@jaybeeuu/agent-cortex 1.40.0 → 1.41.0

package/AGENTS.md

@@ -13,7 +13,7 @@ available in the author's coding sessions.
 
 ```
 agent-cortex/
-├── package.json           # PI package manifest (pi: { extensions, skills })
+├── package.json           # PI package manifest (pi: { extensions, skills, packages })
 ├── plugin.json            # GitHub Copilot plugin manifest — agents, skills, MCP servers
 ├── agents/                # Custom agents — canonical composable <name>/ dirs
 │   ├── *.agent.md         #   generated from <name>/ by scripts/build-copilot-agents.mjs
@@ -34,10 +34,11 @@ agent-cortex/
 │       └── index.ts       # Extension entrypoint
 ├── hooks/                # Canonical Claude Code hooks (hooks.json + scripts — see docs/claude-hooks.md)
 │   └── 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)
+├── claude/               # Committed Claude user-settings template — merged into ~/.claude/settings.json on install
+├── claude-extras/        # Hand-authored Claude plugin extras
 │   ├── .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 })
+└── package.json          # PI package manifest (pi: { extensions, skills, packages })
 ```
 
 ## Versioning
@@ -56,12 +57,18 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
   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.
+- **Share generic tooling helpers in `scripts/lib/`**: tooling code (installers under
+  `bin/installers/`, hooks, other scripts) imports shared utilities from `scripts/lib/`
+  (e.g. `compose-agent.mjs`, `fs.mjs`) rather than redefining them inline.
 
 ## Skill Conventions
 
 - `SKILL.md` must include a YAML front-matter block with `name` and `description`.
 - `description` must be ≤ 1024 characters. First sentence: what it does. Second: "Use when…".
-- Keep `SKILL.md` under ~100 lines. Overflow into `REFERENCE.md` for rarely-needed detail.
+- Keep `SKILL.md` near the ~150-line target in `docs/skills/skill-anatomy.md`, overflowing into
+  purpose-named support files (`REFERENCE.md`, `EXAMPLES.md`, `FORMAT.md`). `style-tests`
+  deliberately sits at the top of that range rather than splitting — its principles must load
+  automatically with the skill.
 - Add utility scripts to `scripts/` when an operation is deterministic and would otherwise be
   regenerated each time (e.g. install scripts, scanners).
 - Skill names use kebab-case and are grouped by prefix where related (e.g. `review-security`,
@@ -80,10 +87,13 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
   `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`
+  `~/.agent-cortex/.claude-plugin/marketplace.json`, merges the committed `claude/settings.json`
+  template into `~/.claude/settings.json`, and registers it with Claude Code via the
+  `claude plugin` CLI. The settings merge preserves personal config: the CLI owns exactly
+  `enabledPlugins` + `extraKnownMarketplaces`, and every other key is left untouched. Only
+  that settings template is committed under `claude/` — the generated plugin subtree is not;
+  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
@@ -96,6 +106,9 @@ Generated automatically by changesets. Do not edit `CHANGELOG.md` manually.
 - Extensions are auto-discovered when the repo is installed as a PI package via `pi install`.
 - Keep extensions lightweight: no internal LLM calls. Extensions observe events and provide
   commands — they should not add token overhead.
+- Register CLI flags from the extension factory (load time), never from a `session_start`
+  handler: PI matches parsed CLI flags against the extensions loaded at startup, so late
+  registration makes the flag fail with `Unknown option`.
 - Extensions that persist data should write to `~/.pi/agent-cortex/` (global, cross-project)
   and tag records with the project path for per-project slicing.
 - PI extensions with Claude Code equivalents are ported to `hooks/claude/`; the port/reject

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 1.41.0
+
+### Minor Changes
+
+- a6b1929: `agent-cortex install pi` now materialises the pi config files as real CLI-managed files, replacing the legacy symlinks into the repo's `pi/` directory. `settings.json` is merged — the committed template supplies defaults, values already present (personal config and anything pi wrote) win, and the CLI owns the `packages` list with the repo path entry resolved against the settings file — so personal config survives re-install. `keybindings.json` is written from the template, refreshed when the template changes, and left alone once edited by hand. The generated header lives in a top-level `"//"` key because pi parses both files with a bare `JSON.parse`. `--dry-run` prints the plan (including "would remove symlink …") and `--output <dir>` keeps the generate-only semantics. Two caveats: because the live value wins, a changed default in the committed template only reaches fresh installs (edit the live file to adopt it); and `packages` is rebuilt from the template, so any `npm:` package added to the live file with `pi install npm:<pkg>` is dropped on the next install — declare long-lived packages in the repo template. An unparseable live `settings.json` is warned about and overwritten.
+- d6ac5a5: Provision the pi packages agent-cortex needs (pi-questions for `ask_questions`, pi-web-access for `fetch_content`) on `agent-cortex install pi`. The package manifest now declares them under `pi.packages`, the installer installs any that the pi user scope is missing via the pi CLI (idempotent, warns and continues on failure), and `--no-provision` opts an offline machine out. The token-map `ask_user` / `web_fetch` mappings are no longer no-ops on a clean `~/.pi`.
+- daa77c8: Encode test-quality rules into `style-tests`: the full agreed principle set (behaviour over
+  implementation, mocking only at external edges, module-boundary units, realistic
+  LocalStack/TestContainers integration, test independence, CI-only truth, spec-by-test, and
+  more), a blanket ban on asserting the static contents of a file (config, markdown, terraform,
+  snapshots) with the behaviour-not-inventory distinction, and test-data construction rules —
+  inline data, no shared mutable top-level fixtures, and small configurable factories over
+  repeated full literals. The content-assertion ban and the test-data rules land as red-flag rows
+  plus verification-checklist items. `style-tests/SKILL.md` deliberately occupies the full
+  ~150-line `SKILL.md` budget so the principles load automatically, rather than splitting into
+  `REFERENCE.md`.
+
+### Patch Changes
+
+- 3e2d149: Add the `agent-guardrails` pi extension: it appends behavioural circuit-breakers to the PI
+  system prompt once per user prompt — two-strikes retry limits, explicit check-in triggers, and
+  atomic-change discipline (first slice of `docs/ideas/improve-pi-system-prompt.md`).
+- a6b1929: The bundled `agent-modes` pi extension now registers its `--agent <name>` CLI flag while the extension loads, instead of from its `session_start` handler. PI validates parsed CLI flags against the extensions present at startup, so the late registration meant `pi --agent <name>` failed with `Unknown option: --agent`. Registration is extracted into a `registerAgentFlag(pi, agents)` helper called directly by the extension factory.
+- a6b1929: Materialise `~/.claude/settings.json` from a new committed `claude/settings.json` template when
+  `agent-cortex install claude` runs (parity with the pi installer's merge-keep-personal contract).
+  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 file is replaced with a real file,
+  `--dry-run` plans without writing, and `--output <dir>` leaves the user's Claude config alone.
+- 140d9d4: Add a deterministic classifier to the `classify-bead` skill
+  (`skills/planning/classify-bead/scripts/classify-bead.mjs`). One command resolves an
+  existing `implementation-type` label, the legacy `## Type` field, then conservative
+  heuristic signals, and applies the label itself; only beads with no deterministic signal
+  escalate to the rubric subagent. `create-task` and `write-a-prd` now run the classifier
+  before spawning a subagent, and `--audit` reports the deterministic-vs-rubric split
+  over recent beads.
+- e055123: Extract the generic async `isFile`/`isDirectory` stat wrappers into a shared `scripts/lib/fs.mjs` and import them from the claude, copilot, and pi installers instead of redefining them inline.
+- 720d678: Add a milestone-notes discipline to the `run-pipeline-stage` skill: the stage-runner prompt and
+  SKILL.md now instruct agents to append a short checkpoint to the bead's notes (`bd update <id>
+--append-notes`) at stage start and at each milestone, so a fresh session can resume from
+  `bd show <id>` alone if the original session dies mid-stage.
+- 515b75e: Document why the pi installer's substituted skills are the sole pi skill source (the local pi/settings.json packages filter `{ source, "skills": [] }` keeps raw package skills out) and update pi/settings.json to the current runtime config (models, packages, compaction, TUI prefs).
+- 11f9a36: Add a class-over-factory rule to `style-code`: when a module holds mutable state and exposes
+  methods that transform or manage it, model it as a class with public methods and native
+  `#private` fields rather than a factory function returning a closure of methods (TypeScript's
+  `private` modifier is compile-time only). Existing functional guidance for stateless components,
+  hooks, and pure transforms is unchanged.
+
 ## 1.40.0
 
 ### Minor Changes

package/README.md

@@ -25,21 +25,24 @@ 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        # materialises ~/.agent-cortex/claude + registers with Claude Code (--output <dir> = generate-only 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-extras/            # Hand-authored Claude plugin extras (no committed claude/ output)
+├── 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)
 ```
@@ -61,9 +64,10 @@ plain `agent-cortex install claude` copies the plugin into the home install root
 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:
+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
@@ -87,7 +91,7 @@ materialiser itself — a temp-dir install plus structural checks:
   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).
+  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/`, `claude-extras/`, `package.json`), never the generated
@@ -101,7 +105,7 @@ 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
+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
@@ -130,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
@@ -171,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:
@@ -178,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`).
 
@@ -202,9 +229,13 @@ root `~/.agent-cortex/claude` — **4 agents** (`strategy`, `plan`, `ralph-plan`
 **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.
+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`:
@@ -258,8 +289,16 @@ agent-cortex install claude --require-register       # register or fail the inst
 ```
 
 `--dry-run` prints the full plan without spawning the claude CLI or writing anything;
-`--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
+`--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:
 
@@ -337,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).
@@ -350,12 +389,13 @@ Edit the **sources** — the composable `agents/<name>/` directories (shared `ag
 per-harness frontmatter/sections, auto-composed by `scripts/build-copilot-agents.mjs` and
 `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), `claude-extras/` (hand-authored `.mcp.json` and
+`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 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
+`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

package/agents/README.md

@@ -222,9 +222,11 @@ flat `agents/*.agent.md` files are built from them:
 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 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
+(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

@@ -32,6 +32,10 @@ if (parsed.command === "install") {
     try {
       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 } : {}),
@@ -49,10 +53,12 @@ if (parsed.command === "install") {
   // claude is the first wired harness: a plain `agent-cortex install 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.
+  // ~/.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");
@@ -106,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`);
+  }
 }