@jaybeeuu/agent-cortex 1.39.0 → 1.41.0

package/README.md

@@ -9,8 +9,6 @@ pi, and [Claude Code](https://code.claude.com/docs) (as a plugin).
 ```
 agent-cortex/
 ├── plugin.json               # Copilot plugin manifest
-├── .claude-plugin/
-│   └── marketplace.json      # Claude marketplace (exposes ./claude as the "jaybeeuu" market)
 ├── agents/                   # Canonical agents — composable <name>/ dirs (see agents/README.md)
 │   ├── *.agent.md            #   ralph, ralph-plan, plan, strategy — GENERATED from <name>/ by scripts/build-copilot-agents.mjs
 │   ├── ralph/                #   composable form (shared agent.md + per-harness pi/, copilot/, claude/)
@@ -27,28 +25,26 @@ agent-cortex/
 │   ├── style/                #  style-code, style-tests, style-comms, style-documentation
 │   └── workflow/             #  ralph, run-pipeline-stage, create-task, …
 ├── extensions/               # pi extensions (pi only)
+│   ├── agent-guardrails/     #   behavioural circuit-breakers in the system prompt
 │   ├── agent-modes/          #   switchable agent modes (reads composable agents/)
 │   ├── skill-stats/
 │   └── notify/
-├── pi/                       # Global pi configuration (see below)
-│   └── settings.json
+├── pi/                       # Committed pi config templates (see below)
+│   ├── settings.json
+│   └── keybindings.json
 ├── token-map.json            # canonical tool/path/agent names per harness (install-time token substitution)
 ├── token-map.README.md       # design decisions behind token-map.json
 ├── bin/
 │   ├── agent-cortex.mjs      # CLI entrypoint
 │   └── installers/
 │       ├── copilot.mjs       # shared generator: agent-cortex install copilot + scripts/build-copilot-agents.mjs
-│       └── claude.mjs        # install-time generator + Claude Code registrar (pnpm build:claude = generate-only --output form)
+│       └── claude.mjs        # materialises ~/.agent-cortex/claude + ~/.claude/settings.json, registers with Claude Code (--output <dir> = generate-only)
 ├── scripts/
 │   └── build-copilot-agents.mjs  # thin wrapper over bin/installers/copilot.mjs (regenerates agents/*.agent.md)
-└── claude/                   # Self-contained Claude Code plugin (GENERATED — do not hand-edit)
-    ├── .claude-plugin/
-    │   └── plugin.json
-    ├── .mcp.json             #  MCP servers (context7, github) — hand-authored
-    ├── hooks.json            #  SessionStart + Notification hooks — generated from hooks/claude/
-    ├── hooks/                #  hook scripts (e.g. scripts/notify.mjs) — generated from hooks/claude/
-    ├── agents/               #  composed from agents/<name>/claude/ + copied from agents-native/
-    └── skills/               #  symlinks to the grouped skills/ dirs (29 skills)
+├── claude/                   # Committed Claude user-settings template (settings.json) — merged into ~/.claude/settings.json
+└── claude-extras/            # Hand-authored Claude plugin extras
+    ├── .mcp.json             #  MCP servers (context7, github) — copied into installs
+    └── scripts/              #  statusline-command.sh — copied into installs (executable)
 ```
 
 The same `agents/` and `skills/` power three harnesses (Copilot, pi, Claude Code).
@@ -61,36 +57,45 @@ install-time and build-time output can never diverge) and committed so Copilot C
 The `{{TOOL:...}}` / `{{PATH:...}}` tokens written in agent and skill files are resolved
 per harness at install time from `token-map.json`, the single source of truth for
 canonical tool/path/agent names (see `token-map.README.md` and the `contract` section).
-The `claude/` subtree is **generated** by the install-time generator
-(`bin/installers/claude.mjs`). A plain `agent-cortex install claude` regenerates the
-subtree AND registers it with Claude Code by driving the `claude plugin` CLI (marketplace
-add → install → marketplace update → plugin update). `pnpm build:claude` is the pure,
-generate-only alias — it passes `--output claude`, so CI and release drift-checks never
-spawn the claude CLI or touch `~/.claude`. CI regenerates it and checks
-it is never stale:
-
-- **Skills** stay single-source — `claude/skills/<name>` are symlinks into the grouped
-  `skills/<group>/<name>` dirs (Claude discovers skills only one level deep, so the
-  grouping is flattened via links, not copies).
-- **Agents** can't be shared files (the frontmatter formats differ), so `claude/agents/*.md`
-  are composed from the canonical `agents/<name>/` directories' `claude/` harness dirs
+The Claude plugin is **materialised** at install time by `bin/installers/claude.mjs`. A
+plain `agent-cortex install claude` copies the plugin into the home install root
+(`~/.agent-cortex/claude`), writes a marketplace manifest at
+`~/.agent-cortex/.claude-plugin/marketplace.json` exposing it, and registers it with
+Claude Code by driving the `claude plugin` CLI — state-checked and idempotent (a fresh
+install adds the marketplace + installs the plugin; a re-run updates what state says is
+out of date; a repeat install at the same version is a no-op; a missing or pre-v2 CLI
+warns and prints the manual registration commands instead of failing). The generated
+`claude/` plugin subtree is never committed (only the `claude/settings.json` template and
+the hand-authored `claude-extras/` are), so CI validates the materialiser itself — a
+temp-dir install plus structural checks:
+
+- **Skills** stay single-source — the installer copies each `skills/<group>/<name>/` dir
+  flat into `skills/<name>/` (Claude discovers skills only one level deep) with
+  `{{TOOL:...}}` / `{{PATH:...}}` tokens substituted against token-map.json's claude
+  column — no symlinks, so literal tokens never reach Claude.
+- **Agents** can't be shared files (the frontmatter formats differ), so the materialised
+  plugin's `agents/*.md` are composed from the canonical `agents/<name>/` directories' `claude/`
+  harness dirs
   (frontmatter.json + section files), exactly like the Copilot flats are composed from their
   `copilot/` dirs. Claude only loads agents from a plugin's default `agents/` dir, so the plugin
-  root is `claude/` — isolating it from the Copilot `.agent.md` files.
+  ships them at its own root (default `~/.agent-cortex/claude/agents/`) — isolating them from the
+  Copilot `.agent.md` files.
 - **Claude-native agents** that have no Copilot equivalent live in `agents-native/*.md` and are
-  copied verbatim into `claude/agents/`. `ralph` is one: it is reimplemented for Claude around
+  copied verbatim into the materialised plugin's `agents/`. `ralph` is one: it is reimplemented
+  for Claude around
   background workers + an independent review gate (the Copilot Ralph's `task`/`read_agent`
   poll loop has no Claude equivalent), so it can't be mechanically converted.
-- **Manifests** are generated too: `claude/.claude-plugin/plugin.json` (its `version` tracks
-  `package.json`, so it never goes stale) and `claude/hooks.json` (copied from the canonical
+- **Manifests** are generated too: the plugin's `.claude-plugin/plugin.json` (its `version`
+  tracks `package.json`, so it never goes stale) and `hooks.json` (copied from the canonical
   `hooks/claude/hooks.json` source), plus any support files under `hooks/claude/` bundled into
-  `claude/hooks/` so hook commands can reach them via `$CLAUDE_PLUGIN_ROOT`. `claude/.mcp.json`
-  and `claude/scripts/` stay hand-authored. See `docs/claude-hooks.md` for the extension→hook
-  mapping and the rejections (auto-name, skill-stats, subagent, agent-modes).
+  the plugin's `hooks/` so hook commands can reach them via `$CLAUDE_PLUGIN_ROOT`. Hand-authored
+  extras — `.mcp.json` and `scripts/` — are copied into every install from the `claude-extras/`
+  dir, which is their canonical store. See `docs/claude-hooks.md` for the
+  extension→hook mapping and the rejections (auto-name, agent-guardrails, skill-stats, subagent, agent-modes).
 
 Edit the sources (`agents/<name>/` composable dirs, `agents-native/*.md`, `skills/**`,
-`hooks/claude/`, `package.json`), never anything under `claude/` or the generated
-`agents/*.agent.md` files.
+`hooks/claude/`, `claude-extras/`, `package.json`), never the generated
+`agents/*.agent.md` files or anything under the materialised `~/.agent-cortex/claude`.
 
 ## CI
 
@@ -100,6 +105,15 @@ does its own checkout and `pnpm install` rather than sharing build artifacts fro
 the `setup` job — pnpm workspace symlinks don't survive artifact upload/download,
 so artifact sharing would break the workspace resolution that the build depends on.
 
+The repo commits no generated `claude/` plugin output, so the `claude-plugin-check` job
+validates the Claude plugin **materialiser** instead of diffing a committed mirror:
+it runs `node bin/agent-cortex.mjs install claude --output <tmp dir>` and checks the
+result structurally — `plugin.json` version tracks `package.json`, every generated and
+hand-authored piece is present, no literal `{{TOOL:...}}`/`{{PATH:...}}` tokens survive,
+and no symlinks leak into the copied tree. The Copilot drift check
+(`pnpm build:copilot` + `git diff --exit-code -- 'agents/*.agent.md'`) still guards the
+committed flat agent files.
+
 A separate `changeset-check` job runs only on pull requests and fails any PR that
 touches a versioned path (`extensions/`, `skills/`, `agents/`, `package.json`, or
 `plugin.json`) without a changeset in `.changeset/`. Add one with `pnpm changeset` —
@@ -109,7 +123,9 @@ On pushes to `main`, a `release` job (gated on `lint`, `test`, and
 `claude-plugin-check`) runs changesets to open a `chore: version packages` PR when
 changesets are pending, then publishes to npm once it lands. The version step runs
 `pnpm version-packages` — bumping `package.json`, syncing `plugin.json`, and
-regenerating the committed generated output so the drift gates stay green; the
+regenerating the committed Copilot agent files (the Claude plugin is materialised at
+install time with the package version, so it has no committed output to regenerate)
+so the drift gates stay green; the
 publish step runs `pnpm publish-package` (pack + provenance publish). Publish
 authenticates via npm Trusted Publishing (OIDC) — no npm token or GitHub
 secret is needed, only the one-time npm-side setup on npmjs.com (package →
@@ -118,30 +134,51 @@ are sourced entirely from `main`.
 
 ## Installation
 
-### Symlink as global pi config
-
-This repo's `pi/settings.json` is symlinked to `~/.pi/agent/settings.json`,
-making it the canonical store for personal pi agent configuration:
-
-```sh
-~/.pi/agent/settings.json -> /path/to/agent-cortex/pi/settings.json
-```
-
-All `pi install` / `pi remove` commands write to this file, and changes are
-committed to git. On a fresh machine:
-
-```sh
-git clone https://github.com/jaybeeuu/agent-cortex
-ln -sf "$PWD/agent-cortex/pi/settings.json" ~/.pi/agent/settings.json
-```
+### Pi config files (`settings.json` + `keybindings.json`)
+
+`agent-cortex install pi` materialises `~/.pi/agent/settings.json` and
+`~/.pi/agent/keybindings.json` as real CLI-managed files — the legacy symlinks
+into this repo's `pi/` directory are gone. `pi/settings.json` and
+`pi/keybindings.json` are the committed **templates**; the live files exist only
+on the machine, so re-run the installer after pulling changes.
+
+`settings.json` is merged. The template supplies defaults for keys the live file
+lacks, every value already present in the live file wins, and keys the template
+does not know about are preserved — so personal config (and anything pi itself
+wrote) survives re-install. The one key the CLI owns outright is `packages`: it
+is rebuilt from the template with the repo path entry resolved against the live
+settings file.
+
+Two consequences follow from that precedence:
+
+- **Template changes to non-`packages` keys never reach an existing install.**
+  Because the live value always wins, editing a default in `pi/settings.json`
+  only affects a fresh install (or a manually deleted live file) — edit the live
+  file to adopt a new default.
+- **`pi install npm:<pkg>` entries do not survive re-install.** `packages` is
+  rebuilt from the template, so any `npm:` package pi added to the live file is
+  dropped on the next `agent-cortex install pi`. Declare long-lived packages in
+  the repo template instead.
+
+An unparseable live `settings.json` is warned about and overwritten.
+`keybindings.json` follows a checksum rule: written from the template, refreshed
+when the template changes, and left untouched once you edit it by hand (delete
+it to re-adopt the template).
 
 ### Pi package dependencies
 
-These packages are declared in `pi/settings.json` and auto-installed by pi:
+These packages are declared in the package manifest (`package.json` → `pi.packages`) and
+provisioned by `agent-cortex install pi`, so a clean `~/.pi` gets the tools they provide
+without a manual `pi install`. They are also declared in the template `pi/settings.json`,
+so the materialised `settings.json` registers them with pi.
 
 | Package | Version | Purpose |
 |---|---|---|
-| [`pi-web-access`](https://www.npmjs.com/package/pi-web-access) | 0.10.7 | Web search, URL fetching, GitHub repo access, PDF/YouTube/video analysis |
+| [`pi-web-access`](https://www.npmjs.com/package/pi-web-access) | 0.10.7 | Web search, URL fetching, GitHub repo access, PDF/YouTube/video analysis (`fetch_content`) |
+| [`pi-questions`](https://www.npmjs.com/package/pi-questions) | latest | Structured interactive questions (`ask_questions`) |
+
+Pass `--no-provision` to skip the package install step (e.g. offline machines); a
+missing `pi` CLI or failed install warns and leaves the rest of the install intact.
 
 Desktop notifications are handled by the local `extensions/notify/` extension
 (replaces the former `pi-notify` dependency). It sends an OSC desktop
@@ -159,6 +196,7 @@ composed agents and token-substituted skills into pi's user scope:
 agent-cortex install pi
 # → ~/.pi/agent/agents/<name>.agent.md (ralph, plan, ralph-plan, strategy)
 # → ~/.pi/agent/skills/  (token-substituted skill tree)
+# → ~/.pi/agent/settings.json + keybindings.json (merged from the repo templates)
 ```
 
 Flags:
@@ -166,8 +204,9 @@ Flags:
 | Flag | Meaning |
 | --- | --- |
 | `--dry-run` | Show what would be installed without writing anything |
-| `--output <dir>` | Install into `<dir>/agents` and `<dir>/skills` (default `~/.pi/agent`) |
+| `--output <dir>` | Install into `<dir>/agents`, `<dir>/skills` and the config files (default `~/.pi/agent`) |
 | `--plugin-root <dir>` | Override the plugin root used for `{{PATH:...}}` tokens (default: token-map.json's pi value — use it for checkout or symlinked installs) |
+| `--no-provision` | Skip provisioning the third-party pi packages declared in `package.json` `pi.packages` (default: install them via the `pi` CLI) |
 
 Re-run whenever you pull changes (`git pull` + reinstall, or after `pnpm build:copilot`).
 
@@ -185,32 +224,43 @@ copilot plugin install ./agent-cortex
 
 ### Claude Code plugin (separate)
 
-The Claude plugin is the self-contained `claude/` subtree (manifest at
-`claude/.claude-plugin/plugin.json`), containing **4 agents** (`strategy`, `plan`,
-`ralph-plan`, `ralph`), **29 skills**, `SessionStart` + `Notification` hooks, and 2 MCP servers.
-
-`claude/` is committed (the marketplace install flow reads it straight from the working
-tree, so a fresh clone installs as-is), and rebuilt via the install-time generator if you
-change the sources:
+A plain `agent-cortex install claude` **materialises** the plugin into the home install
+root `~/.agent-cortex/claude` — **4 agents** (`strategy`, `plan`, `ralph-plan`, `ralph`),
+**29 skills** (copied flat per skill, `{{TOOL:...}}` / `{{PATH:...}}` token-substituted — no
+symlinks), `SessionStart` + `Notification` hooks, and 2 MCP servers — writes a marketplace
+manifest at `~/.agent-cortex/.claude-plugin/marketplace.json` exposing `./claude`, and
+registers it with Claude Code, and merges the committed `claude/settings.json` template into
+`~/.claude/settings.json`: the template supplies defaults, personal values win, and the
+installer owns exactly `enabledPlugins` + `extraKnownMarketplaces` — every other key
+(`permissions`, `hooks`, `env`, `statusLine`, unknown keys) is preserved. The only committed
+Claude config is that template plus the hand-authored extras in `claude-extras/`
+(`.mcp.json`, `scripts/`); the plugin subtree is generated at install time — there is nothing
+to drift.
+
+The generate-only `--output <dir>` form is for previewing and CI validation; the
+documented path is the plain install to `~/.agent-cortex/claude`:
 
 ```sh
 pnpm build:copilot   # or: node scripts/build-copilot-agents.mjs (regenerates agents/*.agent.md)
-pnpm build:claude    # or: node bin/agent-cortex.mjs install claude --output claude (generate-only)
-# or the install-time entry (same generator, less typing):
 node bin/agent-cortex.mjs install copilot          # regenerates agents/*.agent.md in place
 node bin/agent-cortex.mjs install copilot --dry-run       # plan only, no writes
 node bin/agent-cortex.mjs install copilot --output /tmp/x # preview the flat files elsewhere
-node bin/agent-cortex.mjs install claude           # regenerates ./claude AND registers it with Claude Code
+node bin/agent-cortex.mjs install claude           # materialises ~/.agent-cortex/claude + marketplace manifest AND registers it with Claude Code (user scope, idempotent)
 node bin/agent-cortex.mjs install claude --dry-run       # plan generation + registration, no writes/spawns
-node bin/agent-cortex.mjs install claude --output /tmp/x # generate only — no registration
+node bin/agent-cortex.mjs install claude --require-register  # fail (non-zero exit) when the claude CLI can't drive registration
+node bin/agent-cortex.mjs install claude --output /tmp/x # generate only (preview/CI) — no marketplace manifest, no registration
 ```
 
 #### Try it for one session
 
+Generate a throwaway plugin and point Claude Code at it — no install or registration
+needed:
+
 ```sh
-claude --plugin-dir /path/to/agent-cortex/claude
+node bin/agent-cortex.mjs install claude --output /tmp/agent-cortex-claude
+claude --plugin-dir /tmp/agent-cortex-claude
 # verify what loaded:
-claude --plugin-dir /path/to/agent-cortex/claude plugin details agent-cortex
+claude --plugin-dir /tmp/agent-cortex-claude plugin details agent-cortex
 ```
 
 `SKILL.md` edits are picked up live in that session; agent, hook, and MCP changes need
@@ -218,24 +268,42 @@ claude --plugin-dir /path/to/agent-cortex/claude plugin details agent-cortex
 
 #### Install persistently (recommended)
 
-The repo ships a marketplace manifest (`.claude-plugin/marketplace.json`) that exposes the
-`claude/` subtree. A plain `agent-cortex install claude` does both halves in one step: it
-regenerates `claude/` and registers the plugin with Claude Code by driving the `claude
-plugin` CLI (marketplace add → install → marketplace update → plugin update), pointing it
-at this checkout's manifest. This requires the `claude` plugin CLI (Claude Code v2+):
+The plain install does both halves in one step: it materialises the plugin into
+`~/.agent-cortex/claude`, writes `~/.agent-cortex/.claude-plugin/marketplace.json` (the
+home install root doubles as the marketplace root — the manifest exposes `./claude`), and
+registers it with Claude Code by driving the `claude plugin` CLI against that root at
+**user scope** (the `claude plugin install` default, so the plugin is available in every
+session — the recommended persistent flow). Registration is idempotent by state, not by
+exit code: `claude plugin marketplace list --json` picks add-vs-update and
+`claude plugin list --json` picks install-vs-update against the materialised version. A
+fresh install adds the marketplace and installs the plugin; a re-run is the update path
+(`marketplace update`, plus `plugin update` only when a newer version is materialised); a
+repeat install at the same version is a true no-op. It requires the `claude` plugin CLI
+(Claude Code v2+): with a missing or pre-v2 CLI the installer warns and prints the manual
+commands below, exiting 0 — `--require-register` makes registration mandatory and fails
+non-zero when it can't run:
 
 ```sh
-git clone https://github.com/jaybeeuu/agent-cortex   # first time (or git pull to update)
-agent-cortex install claude                          # regenerate + register (user scope)
+agent-cortex install claude                          # materialise + register (user scope, idempotent)
+agent-cortex install claude --require-register       # register or fail the install
 ```
 
 `--dry-run` prints the full plan without spawning the claude CLI or writing anything;
-`--output <dir>` regenerates only, with no registration. The equivalent manual registration
-(e.g. on a Claude Code build without the plugin CLI) adds the checkout by **absolute path**
-(a bare `.` is rejected):
+`--output <dir>` generates only, with no marketplace manifest and no registration.
+
+The install also merges the committed `claude/settings.json` template into
+`~/.claude/settings.json` (the settings file Claude Code reads at user scope). The template
+supplies defaults and personal values win; the installer owns exactly `enabledPlugins` +
+`extraKnownMarketplaces`, so `permissions`, `hooks`, `env`, `statusLine` and unknown keys are
+never touched. A legacy symlinked `settings.json` is replaced with a real file rather than
+written through, and `--output` leaves the user's Claude config alone.
+
+The equivalent manual registration adds a marketplace root by **absolute path** (a bare `.` is
+rejected) — the home install root (`~/.agent-cortex`) is the marketplace root written by
+the plain install; the repo checkout ships no manifest:
 
 ```sh
-claude plugin marketplace add /path/to/agent-cortex
+claude plugin marketplace add ~/.agent-cortex              # after a plain install
 claude plugin install agent-cortex@jaybeeuu          # every session (user scope)
 # or, for this project only:
 claude plugin install agent-cortex@jaybeeuu --scope local
@@ -246,17 +314,23 @@ flag, and Ralph is just `claude --agent agent-cortex:ralph`.
 
 #### Update
 
-The marketplace source is your local checkout, so after pulling changes re-run the installer —
-it rebuilds the `claude/` subtree and refreshes the registered plugin (marketplace update →
-plugin update) in one step:
+The plain install re-materialises from the current sources, so after pulling changes
+re-run it — it refreshes the materialised plugin and re-registers whatever the installed
+state says is out of date (`marketplace update`, plus `plugin update` only when a newer
+version is materialised; a repeat install at the same version is a no-op) in one step:
 
 ```sh
 git pull
-agent-cortex install claude                # rebuild + refresh (restart Claude Code to apply)
+agent-cortex install claude                # re-materialise + refresh (restart Claude Code to apply)
 ```
 
-`pnpm build:claude` only regenerates the subtree (no registration), so on its own it won't
-refresh an installed plugin.
+Registration matches the marketplace by **name**, not path: a marketplace previously added
+from a different root is refreshed in place rather than re-pointed at the fresh home
+install. Re-point it with
+`claude plugin marketplace remove jaybeeuu` and re-run the install.
+
+The plain install IS the update — there is no separate build step. (`--output <dir>` only
+generates a preview and never refreshes an installed plugin.)
 
 #### Uninstall
 
@@ -281,7 +355,7 @@ The lean **Ralph** runs as the interactive main agent (not delegated — it must
 receive its workers' completions):
 
 ```sh
-claude --agent agent-cortex:ralph        # (add --plugin-dir .../claude if not installed)
+claude --agent agent-cortex:ralph        # (omitted once installed via agent-cortex install claude; else --plugin-dir ~/.agent-cortex/claude)
 ```
 
 It finds ready beads, spawns parallel background workers (implement → independent review →
@@ -302,7 +376,7 @@ extension→hook audit.
 #### Not ported / follow-ups
 
 - Only `session-start` and `notify` had Claude equivalents (both ported to hooks); the other
-  pi `extensions/` (auto-name, skill-stats, subagent, agent-modes) have none — the audit and
+  pi `extensions/` (auto-name, agent-guardrails, skill-stats, subagent, agent-modes) have none — the audit and
   rejection rationale live in `docs/claude-hooks.md`.
 - Ralph follow-ups: multi-feature epic branches, and a GitHub-trigger routine to auto-resume
   after a PR merge (instead of manual re-invocation).
@@ -313,14 +387,17 @@ extension→hook audit.
 
 Edit the **sources** — the composable `agents/<name>/` directories (shared `agent.md` +
 per-harness frontmatter/sections, auto-composed by `scripts/build-copilot-agents.mjs` and
-the install-time generator `bin/installers/claude.mjs`), `agents-native/*.md` (Claude-only
+`bin/installers/claude.mjs`), `agents-native/*.md` (Claude-only
 agents like `ralph` — the canonical bodies the installer copies verbatim), `skills/**`,
-`hooks/claude/hooks.json` (hook config), and `package.json` (plugin
-version) — then run `pnpm build:claude` (the generate-only alias of `agent-cortex install
-claude --output claude`; run the plain install instead if you also want the plugin
-re-registered with Claude Code). Never hand-edit
-anything under `claude/` except the hand-authored `claude/.mcp.json` and `claude/scripts/`
-files, or the generated `agents/*.agent.md` files, `claude/agents/`, `claude/skills/`,
-`claude/.claude-plugin/plugin.json`, and `claude/hooks.json`. CI runs
-`git diff --exit-code claude/agents/ claude/skills/ claude/.claude-plugin/plugin.json claude/hooks.json`
-and `git diff --exit-code -- 'agents/*.agent.md'` so the generated outputs can never drift.
+`hooks/claude/hooks.json` (hook config), `claude/settings.json` (the user-settings template
+merged into `~/.claude/settings.json`), `claude-extras/` (hand-authored `.mcp.json` and
+`scripts/`), and `package.json` (plugin
+version — picked up at install time) — then run
+`agent-cortex install claude` (re-materialises the home plugin, merges settings, and
+re-registers it; `--output <dir>` generates a preview only). The only committed file under
+`claude/` is the settings template; `~/.agent-cortex/claude` is generated in full
+(`.claude-plugin/plugin.json`, `agents/`, `skills/`, `hooks.json`, `.mcp.json`, `scripts/`)
+so never edit anything under it. The generated `agents/*.agent.md` files are still
+drift-checked by CI (`git diff --exit-code -- 'agents/*.agent.md'`), and CI validates the
+Claude materialiser (structural checks on a temp-dir install) so sources and installer can
+never silently diverge.

package/agents/README.md

@@ -143,8 +143,8 @@ When composing the final agent file for a specific harness:
 2. Replace `{{SECTION:name}}` with content from `<harness>/<name>.md`
 3. `{{TOOL:name}}` and `{{PATH:name}}` are resolved against `token-map.json` — the
    canonical tool/path/agent names per harness. `scripts/lib/compose-agent.mjs` (used by
-   `build:copilot` / `build:claude` and by `bin/installers/pi.mjs`) resolves them when
-   generating the flat files / installing for pi; pi's `agent-modes` extension does the
+   `build:copilot` and by `bin/installers/claude.mjs` / `bin/installers/pi.mjs`) resolves them when
+   generating the flat files / installing for claude and pi; pi's `agent-modes` extension does the
    same at runtime. See the `contract` section of `token-map.json` and
    `token-map.README.md` for the rules.
 
@@ -209,21 +209,24 @@ flat `agents/*.agent.md` files are built from them:
 - `scripts/build-copilot-agents.mjs` (`pnpm build:copilot`) composes `agents/*.agent.md` from
   each agent's `copilot/` harness dir — committed for Copilot CLI, which loads `*.agent.md`
   from `plugin.json`'s `agents: "agents/"` path.
-- `bin/installers/claude.mjs` (plain `agent-cortex install claude` also registers the plugin
-  with Claude Code; `pnpm build:claude` is its generate-only alias, running `install claude
-  --output claude`) composes `claude/agents/*.md` from each agent's `claude/` harness dir (except
-  `ralph`, which ships natively from `agents-native/ralph.md`, copied verbatim).
+- `bin/installers/claude.mjs` (plain `agent-cortex install claude` materialises the plugin
+  into `~/.agent-cortex/claude` and registers it with Claude Code; `--output <dir>` is its
+  generate-only form, used by tests/CI) composes the plugin's
+  `agents/*.md` from each agent's `claude/` harness dir (except `ralph`, which ships natively
+  from `agents-native/ralph.md`, copied verbatim).
 - The pi harness delivers two ways: the `agent-modes` extension composes `agent.md` +
   `pi/frontmatter.json` at runtime against `token-map.json`, and `agent-cortex install pi`
   materialises composed agents + token-substituted skills into `~/.pi/agent` at install
   time (see README "Pi harness agents & skills").
 
-Never edit the generated flat/claude files by hand — edit the composable directory. CI
-regenerates both outputs and fails on drift. Generation is install-time: `claude` ships
+Never edit the generated flat materialised files by hand — edit the composable directory.
+Generation is install-time: `claude` ships
 via `bin/installers/claude.mjs`, the generator behind plain `agent-cortex install claude`
-(which also registers the plugin with Claude Code) and its generate-only `pnpm
-build:claude` alias (`install claude --output claude`) — the committed `claude/` subtree
-is regenerated by it and drift-checked, so it can never be stale; `copilot` ships via
+(which materialises into `~/.agent-cortex/claude`, merges the committed
+`claude/settings.json` into `~/.claude/settings.json`, and registers the plugin with Claude
+Code); the only committed `claude/` file is that settings template (hand-authored extras live
+in `claude-extras/`), and CI validates the materialiser with structural checks on a temp-dir
+install; `copilot` ships via
 `bin/installers/copilot.mjs`, the shared code path behind both `agent-cortex install
 copilot` and `scripts/build-copilot-agents.mjs`; `pi` ships via
 `bin/installers/pi.mjs`, which materialises composed agents + token-substituted skills

package/bin/agent-cortex.mjs

@@ -30,8 +30,12 @@ if (parsed.command === "install") {
 
   if (parsed.harness === "pi") {
     try {
-      const result = installPi({
+      const result = await installPi({
         dryRun: parsed.dryRun ?? false,
+        // Third-party pi packages are only provisioned for a real install:
+        // --output is the generate-only form, --no-provision opts an offline
+        // machine out explicitly.
+        provisionPackages: parsed.output === undefined && !parsed.noProvision,
         warn: () => {}, // warnings surface once in the printed summary
         ...(parsed.output ? { output: parsed.output } : {}),
         ...(parsed.pluginRoot ? { pluginRoot: parsed.pluginRoot } : {}),
@@ -47,21 +51,36 @@ if (parsed.command === "install") {
   process.stdout.write(`Installing agent-cortex for "${parsed.harness}" harness…\n`);
 
   // claude is the first wired harness: a plain `agent-cortex install claude`
-  // regenerates the plugin subtree from the canonical sources (agents/,
-  // agents-native/, skills/, hooks/claude/) via the shared installClaude
-  // generator AND registers it with Claude Code (marketplace add → install →
-  // update) — `pnpm build:claude` is the generate-only alias of this
-  // invocation (it passes `--output claude`), so there is no separate
-  // build-time code path and CI drift-checks never touch ~/.claude.
+  // materialises the plugin into the home install root (~/.agent-cortex/claude)
+  // with copied, token-substituted skills, writes the marketplace manifest at
+  // ~/.agent-cortex/.claude-plugin/marketplace.json, merges the committed
+  // claude/settings.json template into ~/.claude/settings.json (owning only
+  // enabledPlugins + extraKnownMarketplaces), and registers it with Claude Code
+  // (marketplace add → install → update); `--output <dir>` is the generate-only
+  // form (tests/CI validation), and the generated claude/ plugin subtree is
+  // never committed — only the settings template is.
   if (parsed.harness === "claude") {
     // Avoid loading the installer on the help/summary paths and for other harnesses.
     const { installClaude, registerClaude } = await import("./installers/claude.mjs");
     try {
-      installClaude({ output: parsed.output, dryRun: parsed.dryRun });
+      const result = await installClaude({
+        dryRun: parsed.dryRun ?? false,
+        warn: () => {}, // warnings surface once via result.warnings
+        ...(parsed.output ? { output: parsed.output } : {}),
+      });
+      for (const warning of result.warnings) {
+        process.stdout.write(`  ⚠ ${warning}\n`);
+      }
       // Runtime registration happens only for the plain install — `--output`
       // keeps generating only (documented in --help).
       if (parsed.output === undefined) {
-        registerClaude({ dryRun: parsed.dryRun });
+        await registerClaude({
+          root: result.marketplaceRoot,
+          manifest: result.marketplaceManifest,
+          pluginVersion: result.pluginVersion,
+          dryRun: parsed.dryRun ?? false,
+          requireRegister: parsed.requireRegister ?? false,
+        });
       }
       process.exit(0);
     } catch (err) {
@@ -76,7 +95,7 @@ if (parsed.command === "install") {
   if (parsed.harness === "copilot") {
     const { installCopilot } = await import("./installers/copilot.mjs");
     try {
-      installCopilot({ output: parsed.output, dryRun: parsed.dryRun });
+      await installCopilot({ output: parsed.output, dryRun: parsed.dryRun });
       process.exit(0);
     } catch (err) {
       process.stderr.write(`Install failed: ${err.message}\n`);
@@ -93,10 +112,36 @@ function printPiInstall(result) {
     process.stdout.write(`  ✓ ${agent.name}.agent.md → ${agent.filePath}\n`);
   }
   process.stdout.write(`  ✓ Substituted ${result.skills.md} markdown file(s) across ${result.skills.skills} skill(s) → ${result.skills.dir}\n`);
+  printManagedConfig("settings.json", result.settings);
+  printManagedConfig("keybindings.json", result.keybindings);
+  // A dry run installs nothing, so report the plan — otherwise the documented
+  // "show what would be installed" contract prints no packages at all.
+  const packages = result.packages ?? { planned: [], installed: [] };
+  for (const source of result.dryRun ? packages.planned : packages.installed) {
+    process.stdout.write(`  ✓ ${result.dryRun ? "Would install" : "Installed"} pi package ${source}\n`);
+  }
   for (const warning of result.warnings) {
     process.stdout.write(`  ⚠ ${warning}\n`);
   }
   if (result.dryRun) {
     process.stdout.write("(dry-run — nothing written)\n");
   }
+}
+
+/** Report one managed pi config file (settings.json / keybindings.json). */
+function printManagedConfig(label, info) {
+  if (!info) return;
+  if (info.action === "would-remove-symlink") {
+    process.stdout.write(`  → would remove symlink ${info.path} and write ${label}\n`);
+  } else if (info.action === "would-write") {
+    process.stdout.write(`  → would write ${label} → ${info.path}\n`);
+  } else if (info.action === "unchanged") {
+    process.stdout.write(`  · ${label} → ${info.path} (unchanged)\n`);
+  } else if (info.action === "skipped") {
+    process.stdout.write(`  ⚠ ${label} modified after install — left untouched → ${info.path}\n`);
+  } else if (info.action === "removed-symlink") {
+    process.stdout.write(`  ✓ ${label} → ${info.path} (removed legacy symlink)\n`);
+  } else {
+    process.stdout.write(`  ✓ ${label} → ${info.path}\n`);
+  }
 }