@jaybeeuu/agent-cortex 1.39.0 → 1.40.0

package/.agents/skills/style-versioning/SKILL.md

@@ -64,7 +64,7 @@ Fix status bead showing wrong priority after update
 The `release` job in `.github/workflows/ci.yml` handles everything automatically:
 
 1. **Detects new changesets** on main
-2. **Creates a "Version Packages" PR** — the `version` step runs `pnpm version-packages`, which bumps `package.json`, syncs `plugin.json` (via `scripts/sync-plugin-version.sh`), updates `CHANGELOG.md`, and regenerates the committed generated output (`pnpm build:claude`, `pnpm build:copilot`) so the drift gates never fail on a version bump
+2. **Creates a "Version Packages" PR** — the `version` step runs `pnpm version-packages`, which bumps `package.json`, syncs `plugin.json` (via `scripts/sync-plugin-version.sh`), updates `CHANGELOG.md`, and regenerates the committed Copilot output (`pnpm build:copilot`; the Claude plugin is materialised at install time with the package version, so it has no committed output to regenerate) so the drift gates never fail on a version bump
 3. **When "Version Packages" is merged**:
    - Creates a git tag
    - Publishes to npm — `pnpm publish-package` packs with `pnpm pack` and publishes with `npm publish --provenance --access public`. Authenticates via npm Trusted Publishing (OIDC): the release job's `id-token` permission lets npm exchange a GitHub OIDC token for a short-lived npm token at publish time, so no `NPM_TOKEN` secret or `.npmrc` auth config is required — only the one-time npm-side Trusted Publishing setup on npmjs.com (package → Access → Trusted Publishing → GitHub repo `jaybeeuu/agent-cortex` + workflow `.github/workflows/ci.yml`)

package/.github/workflows/ci.yml

@@ -146,7 +146,7 @@ jobs:
         run: pnpm test
 
   claude-plugin-check:
-    name: Claude plugin check
+    name: Claude plugin materialiser check
     needs: setup
     runs-on: ubuntu-latest
     steps:
@@ -175,16 +175,48 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      # `pnpm build:claude` is an alias of `agent-cortex install claude` (both run
-      # bin/installers/claude.mjs), so this drift check proves the committed subtree
-      # equals the installer's output — stale output or hand-edits to generated
-      # files fail the build. The subtree stays committed because the marketplace
-      # install flow reads it straight from the working tree (fresh clone installs
-      # as-is).
-      - name: Check generated Claude plugin is up to date
+      # The claude/ subtree is retired — the installer is the only generator
+      # (plain `agent-cortex install claude` materialises ~/.agent-cortex/claude;
+      # `--output <dir>` is generate-only for tests). There is no committed
+      # output to diff, so this job validates the materialiser itself: it must
+      # produce a complete, structural plugin (generated + hand-authored pieces),
+      # no symlinks, no literal {{TOOL:/{{PATH:/{{SECTION: tokens, and a
+      # plugin.json version tracking the package — exactly what a real install
+      # would ship.
+      - name: Materialise the Claude plugin and run structural checks
         run: |
-          pnpm build:claude
-          git diff --exit-code claude/agents/ claude/skills/ claude/.claude-plugin/plugin.json claude/hooks.json claude/hooks/
+          set -euo pipefail
+          OUT="$RUNNER_TEMP/claude-plugin-check"
+          node bin/agent-cortex.mjs install claude --output "$OUT"
+
+          # structure: generated + hand-authored pieces all present
+          test -f "$OUT/.claude-plugin/plugin.json"
+          test -f "$OUT/agents/plan.md"
+          test -f "$OUT/agents/ralph.md"
+          test -f "$OUT/skills/tdd/SKILL.md"
+          test -f "$OUT/hooks.json"
+          test -f "$OUT/hooks/scripts/notify.mjs"
+          test -f "$OUT/.mcp.json"
+          test -f "$OUT/scripts/statusline-command.sh"
+
+          # flat-copy guarantee: no symlinks in the materialised tree
+          if [ -n "$(find "$OUT" -type l)" ]; then
+            echo "::error::symlinks found in materialised Claude plugin"
+            exit 1
+          fi
+
+          # token substitution: no literal tokens survive materialisation
+          TOKENS=$(grep -rlE '\{\{(TOOL|PATH|SECTION):' "$OUT" || true)
+          if [ -n "$TOKENS" ]; then
+            echo "::error::literal substitution tokens in materialised Claude plugin:"
+            echo "$TOKENS"
+            exit 1
+          fi
+
+          # plugin version tracks the package (never stale)
+          PKG_VERSION=$(node -p "require('./package.json').version")
+          PLUGIN_VERSION=$(node -p "require('$OUT/.claude-plugin/plugin.json').version")
+          test "$PKG_VERSION" = "$PLUGIN_VERSION"
 
       - name: Check generated Copilot agent files are up to date
         run: |
@@ -239,10 +271,11 @@ jobs:
           # the string is split by argStringToArray on whitespace (single quotes
           # survive literally), so each must be a single unquoted command token
           # that runs a pnpm script. version-packages bumps versions, syncs
-          # plugin.json, THEN regenerates the committed generated output
-          # (build:claude writes claude/.claude-plugin/plugin.json with the NEW
-          # version, build:copilot re-derives agents/*.agent.md) before the action
-          # commits, so the Version Packages PR always passes the drift gates.
+          # plugin.json, THEN regenerates the committed Copilot output
+          # (build:copilot re-derives agents/*.agent.md; the Claude plugin is
+          # materialised at install time with the package version, so nothing
+          # committed needs regenerating) before the action commits, so the
+          # Version Packages PR always passes the drift gates.
           version: pnpm version-packages
           publish: pnpm publish-package
           commit: "chore: version packages"

package/AGENTS.md

@@ -33,7 +33,10 @@ agent-cortex/
 │       ├── README.md      # Installation & usage
 │       └── index.ts       # Extension entrypoint
 ├── hooks/                # Canonical Claude Code hooks (hooks.json + scripts — see docs/claude-hooks.md)
-│   └── claude/           #   generated into claude/hooks.json + claude/hooks/ by bin/installers/claude.mjs
+│   └── claude/           #   generated into the plugin's hooks.json + hooks/ by bin/installers/claude.mjs
+├── claude-extras/        # Hand-authored Claude plugin extras (no committed claude/ output)
+│   ├── .mcp.json         # MCP servers (context7, github) — copied into installs
+│   └── scripts/          # statusline-command.sh — copied into installs (executable)
 └── package.json          # PI package manifest (pi: { extensions, skills })
 ```
 
@@ -47,6 +50,13 @@ See the `style-versioning` skill for the full workflow.
 
 Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
 
+## Coding Conventions
+
+- **Never block the main thread**: no `*Sync` functions (`readFileSync`, `spawnSync`, …).
+  Tooling code in `bin/`, `scripts/`, `lib/`, `hooks/`, and `test/` must be async —
+  enforced by `scripts/check-no-sync.mjs` (runs via `pnpm lint`). Skill-owned
+  scripts (`skills/*/scripts`) and `extensions/` are the remaining sync surfaces.
+
 ## Skill Conventions
 
 - `SKILL.md` must include a YAML front-matter block with `name` and `description`.
@@ -66,10 +76,14 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
   from the canonical directories by the shared `bin/installers/copilot.mjs` code path behind both
   `agent-cortex install copilot` and `scripts/build-copilot-agents.mjs` (thin wrapper), and
   committed for Copilot CLI (plugin.json `agents: "agents/"` scans for `*.agent.md`); never edit
-  them by hand. The `claude/` subtree is generated by the install-time generator
-  `bin/installers/claude.mjs` (a plain `agent-cortex install claude` also registers the plugin
-  with Claude Code via the `claude plugin` CLI; `pnpm build:claude` is the generate-only alias,
-  running `agent-cortex install claude --output claude`; `ralph`
+  them by hand. The Claude plugin is materialised by the install-time generator
+  `bin/installers/claude.mjs`: a plain `agent-cortex install claude` copies it into
+  `~/.agent-cortex/claude` (skills copied flat with `{{TOOL:...}}`/`{{PATH:...}}` substituted,
+  never symlinked), writes the marketplace manifest at
+  `~/.agent-cortex/.claude-plugin/marketplace.json`, and registers it with Claude Code via the
+  `claude plugin` CLI; the repo commits no `claude/` output — hand-authored plugin
+  extras live in `claude-extras/` (`.mcp.json`, `scripts/`), and `--output <dir>` is the
+  generate-only form (tests/CI materialiser checks); `ralph`
   is authored natively in `agents-native/` and copied verbatim; the other agents compose from their
   `claude/` harness dirs).
 - Keep orchestration logic in the agent file; extract shared per-task workflow into a skill

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.40.0
+
+### Minor Changes
+
+- 1b6b8b8: `agent-cortex install claude` now materialises the plugin: home-scoped install into `~/.agent-cortex/claude`, copied (token-substituted, no symlinks) skills, marketplace manifest, and automatic registration with Claude Code. Installer toolchain is fully async (no `*Sync` — never block the main thread), enforced by a `check-no-sync` lint scanner.
+- 65119b8: Map `ask_user` → `ask_questions` (pi-questions package) and `skill` → `read` in the pi column of token-map.json: pi agent modes regain interactive questioning (`ask_questions`) instead of dropping the tool with a startup warning, and skill references resolve to reading their SKILL.md. Notes and docs updated to record that `ask_questions` is provided by the pi-questions package.
+- 1b6b8b8: Retire the committed `claude/` plugin subtree: `agent-cortex install claude` into `~/.agent-cortex/claude` (with automatic marketplace registration) is now the only way to build the Claude Code plugin. Hand-authored extras moved to `claude-extras/`, the `build:claude` script is removed, and CI validates the installer instead of diffing committed output.
+
+### Patch Changes
+
+- fcb16d7: Fix grill-with-docs failing to load: quote the front-matter description so skill parsers accept it.
+
 ## 1.39.0
 
 ### Minor Changes

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/)
@@ -38,17 +36,12 @@ agent-cortex/
 │   ├── 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 + registers with Claude Code (--output <dir> = generate-only form)
 ├── 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-extras/            # Hand-authored Claude plugin extras (no committed claude/ output)
+    ├── .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 +54,44 @@ 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 repo commits
+no `claude/` output (hand-authored extras live in `claude-extras/`), 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, 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 +101,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/` 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 +119,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 →
@@ -185,32 +197,39 @@ 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.
+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. The repo commits no `claude/` output: hand-authored extras
+(`.mcp.json`, `scripts/`) are served from `claude-extras/`, and everything else is generated
+at install time — there is nothing to drift.
 
-`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:
+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 +237,34 @@ 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
+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 +275,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 +316,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 →
@@ -313,14 +348,16 @@ 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-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 and re-registers it;
+`--output <dir>` generates a preview only). There is no committed
+`claude/` output to hand-edit or regenerate: `~/.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,22 @@ 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` and registers the plugin with Claude
+Code); the repo commits no `claude/` output (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,7 +30,7 @@ if (parsed.command === "install") {
 
   if (parsed.harness === "pi") {
     try {
-      const result = installPi({
+      const result = await installPi({
         dryRun: parsed.dryRun ?? false,
         warn: () => {}, // warnings surface once in the printed summary
         ...(parsed.output ? { output: parsed.output } : {}),
@@ -47,21 +47,34 @@ 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, and registers it with
+  // Claude Code (marketplace add → install → update); `--output <dir>` is the
+  // generate-only form (tests/CI validation), and there is no committed claude/
+  // subtree in the repo anymore.
   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 +89,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`);