# Cortex installation · recipe 1.0.0

Portable, file-based context for an existing coding agent. Two explicit scopes:

- **home:** ecosystem/home coordination, empty project/resource registries,
  START/NOW, tasks/plans/knowledge/journal, operating/bootstrap/session protocols
  and an offline Project Cortex initializer with its adjacent templates.
- **project:** the compact framework for one existing project directory, with
  START/NOW, tasks/plans/knowledge/decisions/journal and scoped instructions.

The frozen framework is Commander Cortex0.1.0 plus Project Cortex0.2.0. Here
"Commander" names a generic coordination role, not a preconfigured computer.
`UPSTREAM.json` records the source and pinned archive SHA-256. `framework.zip` is
the already-public, ecosystem-neutral release, not a copy of an installed Cortex.
The wrapper validates its full source manifest without executing its old installer.

## What this is not

No agent/model installation, credentials, background memory service, transcript
capture, automatic synchronization, permissions, shell aliases, Git setup, discovery
scan or remote control is installed. Framework registries start empty and unknown
identity stays unknown. Reading a document does not grant execution authority.
No private host inventory, user profile, conversation history or secrets are included.

## Prerequisites and target choice

Python3.9+ and a POSIX account. Tested on Linux/Python3.12; macOS and other Python
versions are unverified, Windows is unsupported. An existing coding agent must be
told to read Cortex; native AGENTS.md loading differs between tools and is not
certified by this package. No model request is needed for installation checks.

Ask the owner which scope and exact directory they want. Identify the intended
human/service user, not merely the SSH/sudo management account. The absolute target
must already exist, be owned by that user and have no symlinked path components.
Run without application sudo; root is refused. Create an owner-approved new project
directory separately if needed. Do not assume other installations' paths or policies.

## Inspect and preview

Fetch the versioned ZIP over verified HTTPS, check SHA-256 against the site catalog,
extract into a private directory and inspect README/source/manifests. Never curl-pipe
downloaded code. The archive includes install.py, verify.py, framework.zip and
UPSTREAM.json. Do not invoke the old installer nested inside framework.zip; use this
preview-first wrapper for its preservation/receipt/rollback safeguards.

```sh
python3 install.py --scope home --root /absolute/path/to/your/home
python3 install.py --scope home --root /absolute/path/to/your/home --apply
```

Or for one project:

```sh
python3 install.py --scope project --root /absolute/path/to/project
python3 install.py --scope project --root /absolute/path/to/project --apply
```

The first command in each pair is read-only. `--apply` creates only missing
framework files/directories, privately0700/0600. Existing project/application files,
memory and instructions are never replaced. An existing nonempty `.ai` must be
private with a matching known scope/version; otherwise installation stops for review.
This is not a migration/upgrader. Reapplication preserves learned notes and user edits.

## Existing AGENTS.md is explicit, not overwritten

By default an existing AGENTS.md stays byte-for-byte unchanged. If it does not
already route the agent to Cortex, the verifier reports that missing step. Either
explicitly tell the agent to read START/NOW, merge the route manually, or approve:

```sh
python3 install.py --scope project --root /absolute/path/to/project --merge-agents
python3 install.py --scope project --root /absolute/path/to/project --merge-agents --apply
```

Use home scope for the corresponding home merge. This appends a bounded instruction
block only when routing is absent; existing content/permissions stay intact. It
refuses malformed/duplicate managed markers. No native agent configuration is edited.
Follow the destination's applicable local instructions and publishing/privacy rules.

## Verify as the user, then use

```sh
python3 verify.py --scope home --root /absolute/path/to/your/home --exercise-project-init
python3 verify.py --scope project --root /absolute/path/to/project
```

The normal verifier is read-only. The optional home initializer exercise creates
only a private temporary sample project, checks preview/init/edit preservation and
cleans that fixture. It does not adopt an existing project or change real memory.
If new instructions are preserved rather than merged, resolve the reported route
before calling setup complete. Verification never reads private conversations or
submits a model request.

Start the existing agent from the chosen directory and say:

> Read AGENTS.md, .ai/START.md and .ai/NOW.md, then follow .ai/protocols/operate.md.
> Use bootstrap only for discovery I authorize; keep unknown facts explicit.

Cortex is durable context only when the agent reads and updates those files. Do not
claim that a background memory daemon or automatic cross-tool loading was enabled.

Home scope also places the original offline initializer at
`.ai/tools/project-cortex/cortex.py`, beside `template/`. For authorized future work:

```sh
umask 077
python3 /absolute/home/.ai/tools/project-cortex/cortex.py init /absolute/project --dry-run
python3 /absolute/home/.ai/tools/project-cortex/cortex.py init /absolute/project
```

That original CLI honors the invoking shell's umask; set077 for private new files.
It uses `--dry-run` for preview (unlike the wrapper's default preview)
and preserves existing files. Keep its whole adjacent template directory. It has no
receipt rollback; use this packaged wrapper again if that safeguard is needed.

## Receipts and careful rollback

Private receipts are stored under `$XDG_STATE_HOME/ecosystem-field-guide/cortex-installs/`
(default `~/.local/state/...`). They contain created file hashes and, only for an
approved AGENTS merge, the original AGENTS bytes. Receipts may be private; never
publish or upload them. Existing files and permissions are not broadly backed up,
rewritten, chowned or chmodded.

```sh
python3 install.py --rollback /absolute/path/to/receipt.json
python3 install.py --rollback /absolute/path/to/receipt.json --apply
```

Rollback first checks all installed hashes. It refuses changed/missing files and
new/untracked Cortex notes/projects, rather than deleting or stranding learned
memory. It restores only its own unchanged AGENTS append, removes only its created
files and empty created directories, and retains receipts. If notes have accumulated,
stop and plan a manual preservation/migration with the owner. No force/delete-all
option is provided. Moving an installed home changes embedded root references;
plan that move explicitly instead of treating reinstallation as an upgrade.