@jaybeeuu/agent-cortex 2.6.0 → 2.7.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## 2.7.0
+
+### Minor Changes
+
+- 464c761: Add `ctx update`, which refreshes installed harnesses by re-running their installers. Bare
+  `ctx update` lists every harness with its installed version and the CLI version, then asks which
+  to refresh; a non-interactive shell prints the same table plus the flags and exits non-zero
+  instead of blocking. `ctx update pi claude` refreshes exactly the named harnesses, `ctx update -a`
+  refreshes every harness that is not at the CLI version, and `ctx update -a -f` re-runs every
+  installer regardless of version. The report gives each harness its previous and new version and
+  the artifacts the installer wrote. Selection and reporting are the only additions: every refresh
+  goes through the existing `bin/installers/` entry points, so update-vs-install stays the
+  installer's decision.
+
+### Patch Changes
+
+- bfce679: Add a `housekeeping` pipeline stage that runs after the human merge gate. `create-chores.mjs` now
+  creates a `stage:housekeeping` chore labelled `lifecycle:housekeeping` and blocked behind the
+  `lifecycle:feature-pr` gate bead, so it stays out of `bd ready` until a human merges the PR and
+  closes the gate. A dispatched worker then runs `prune-worktrees.mjs` from the main checkout, retries
+  once on a non-zero exit, and fails the chore without closing it when a closed-bead worktree is still
+  refused. The four existing stages and the gate are unchanged.
+- 8d11154: Ship the skill anatomy doc into both installs. `write-a-skill` and `refactor-skill` read
+  `docs/skills/skill-anatomy.md`, but neither install contained it, so the reference was dead on any
+  machine without the checkout. Both installers now copy the document into the staged tree once per
+  install (`scripts/lib/docs.mjs`), and the skills name it through a new `{{PATH:skill_anatomy}}` entry
+  in `token-map.json`, so the token map stays the single source of the per-harness path. A new test
+  stages both installs and fails when a rendered skill references a repository doc the install does
+  not contain.
+
 ## 2.6.0
 
 ### Minor Changes

package/README.md

@@ -209,6 +209,7 @@ The staged package contains:
 | `package.json` | pi manifest — `keywords: ["pi-package"]`, `pi.extensions` + `pi.skills`; the version tracks the package |
 | `agents/` | composed flat agents (ralph, plan, ralph-plan, strategy) with `{{TOOL:...}}` / `{{PATH:...}}` substituted — the shipped `agent-modes` extension resolves them from the package root |
 | `skills/` | token-substituted skill copies (real files, never symlinks) |
+| `docs/` | the repository documents those skills read (currently `docs/skills/skill-anatomy.md`), copied verbatim once per install so the reference resolves on a machine without the checkout |
 | `extensions/` | copy of the repo `extensions/` tree — imports nothing from pi's runtime except the host-aliased `typebox`, so pi loads it from any directory |
 | `token-map.json` | the token map `agent-modes` reads from the package root |
 | `node_modules/` | the required third-party pi packages and their transitive closure |
@@ -243,9 +244,9 @@ never removes an entry you added. Each report gives the `pi remove` command that
 resolves it, with the resolved path, because `pi remove` resolves a relative
 argument against the current directory.
 
-Re-run `agent-cortex install pi` after every `git pull` to refresh the staged
-package; registration is already in place, so that re-run changes nothing in
-pi's settings. Verify with `pi list` and `pi config` (restart pi to apply).
+Re-run `agent-cortex install pi` (or `agent-cortex update pi`) after every `git pull` to refresh
+the staged package; registration is already in place, so that re-run changes nothing in pi's
+settings. Verify with `pi list` and `pi config` (restart pi to apply).
 
 Refreshing the installed runtime after a release, and trying uncommitted work without
 overwriting it, are recorded in [`docs/dev-loop.md`](docs/dev-loop.md).
@@ -408,8 +409,9 @@ from a different root is refreshed in place rather than re-pointed at the fresh
 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.)
+The plain install IS the update — there is no separate build step, and `agent-cortex update claude`
+is the same materialise-and-register run selected by name. (`--output <dir>` only generates a
+preview and never refreshes an installed plugin.)
 
 #### Uninstall
 
@@ -474,7 +476,7 @@ 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/`)
+(`.claude-plugin/plugin.json`, `agents/`, `skills/`, `docs/`, `hooks.json`, `.mcp.json`, `scripts/`)
 so never edit anything under it. CI validates the Claude materialiser (structural checks on
 a temp-dir install) so sources and installer can never silently diverge.
 
@@ -502,6 +504,42 @@ Only plain release versions are compared, so a prerelease on either side also re
 The command is read-only: it stats and reads those manifests, and never installs, writes, or
 reaches the network.
 
+## Refreshing installed harnesses (`agent-cortex update`)
+
+`agent-cortex update` re-runs a harness installer and reports what changed. It installs nothing
+itself: every refresh goes through the same path as `agent-cortex install <harness>`, so update and
+install can never disagree about what is out of date.
+
+```sh
+agent-cortex update                 # list the harnesses, then ask which to refresh
+agent-cortex update pi claude       # refresh exactly these, no prompt
+agent-cortex update -a              # refresh every harness not at the CLI version
+agent-cortex update -a -f           # re-run every installer regardless of version
+```
+
+The prompt lists every supported harness with its installed version, the CLI version, and a status
+marker (`current`, `stale`, `ahead`, `unknown`, or `missing`) — the data `agent-cortex version`
+reports, plus a row for a harness with no install. Answer with row numbers counted from the top
+row, `a` for every harness, or blank to cancel.
+
+A harness named on the command line always refreshes, whatever version it reports, and takes
+precedence over `-a`. `-a` refreshes every harness that does not report `current`, so an
+uninstalled, stale, ahead, or unreadable harness is refreshed. `-f` requires `-a`: alone it says
+nothing about which harnesses to touch. An unknown name fails before any installer runs.
+
+A shell that is not a terminal cannot answer the prompt, so a bare `agent-cortex update` there
+prints the same table plus the flags above and exits non-zero — a script can never mistake
+"nothing chosen" for "nothing to do".
+
+The report gives each refreshed harness its previous version, its new version, and the artifacts
+the installer wrote; harnesses already at the CLI version are listed as skipped. A harness's new
+version is read back from the manifest its installer wrote, so a refresh that failed to
+materialise reports `unknown` rather than claiming the CLI version.
+
+This refreshes the installs, not the CLI. Bump the global package first
+(`pnpm add -g @jaybeeuu/agent-cortex@latest`), then update the harnesses — see
+[`docs/dev-loop.md`](docs/dev-loop.md).
+
 ## Migrating a beads workspace
 
 `agent-cortex migrate` brings the `.beads` workspace it runs in — any repo, not just this

package/agents/ralph/agent.md

@@ -21,7 +21,7 @@ Each pipeline stage is a separate **chore bead**, pre-created by `create-chores.
 - **Single-feature epics** (epic has exactly one feature task child): skip the epic branch entirely. The feature branch (`feature/<parent-id>`) is based directly from `origin/main`. The HITL PR targets `main` directly. No epic PR is required.
 - **Multi-feature epics** (epic has two or more feature task children): each epic runs on `epic/<epic-id>` (base: `origin/main`, never local `main`). Each feature branch is based from its epic branch. Completed features PR into `epic/<epic-id>`; the completed epic PRs into `main`.
 - Each parent feature task runs on `feature/<parent-id>` in `.agent-cortex/worktrees/<parent-id>`.
-- Each implemented bead owns a child HITL PR-gate task bead (`lifecycle:feature-pr`, blocked by its own `document` chore) for PR review/merge.
+- Each implemented bead owns a child HITL PR-gate task bead (`lifecycle:feature-pr`, blocked by its own `document` chore) for PR review/merge, plus a `stage:housekeeping` chore blocked behind that gate.
 - Completed features must be reviewed by PR merge from the agent branch (`feature/<parent-id>`) into its base (epic branch for multi-feature epics, `main` for single-feature epics), then the HITL PR task bead must be closed by a human before Ralph continues feature scheduling.
 - Completed multi-feature epics must be reviewed by PR merge into `main`.
 
@@ -93,11 +93,13 @@ A ready `execution:afk` task bead with no `stage:*` chore children has nothing t
    { "kind": "expand", "choreId": null, "parentId": "<parent-id>", "title": "<parent title>", "agentId": "<agent-id>", "logLine": 1 }
    ```
    That entry is what keeps it in the wait set and makes its completion attributable to the parent.
-4. The worker reports the returned mapping — `code`, `verify`, `review`, `document`, `featurePrReview` — and closes nothing. It emits **no** `---REPORT---` block and owns no bead, so there is nothing to parse and no close to confirm.
+4. The worker reports the returned mapping — `code`, `verify`, `review`, `document`, `housekeeping`, `featurePrReview` — and closes nothing. It emits **no** `---REPORT---` block and owns no bead, so there is nothing to parse and no close to confirm.
 5. Its completion means the parent now has a `stage:*` chain: the event loop's next `bd ready -l execution:afk` pass picks up the `stage:code` chore (event loop step 7).
 
 **Expansion completion contract.** An expansion worker is dispatched like a stage worker but is not one: no chore claim, no `---REPORT---`, no leaf-bead close. Handle its completion with the expansion branch in event-loop step 3, which confirms the chain exists (`bd children <parent-id> --json | grep -c '"stage:'` prints one match per stage chore — the gate carries `lifecycle:feature-pr` and is not counted) and dispatches the ready `stage:code` chore. A count below the stage total in `pipeline.json` is a partial chain, whose missing stages never arrive, so re-dispatch the expansion instead of dispatching on. If the parent still has no `stage:*` children the expansion failed: surface the worker's output in chat, record the parent for the shutdown summary, and re-dispatch the expansion — `create-chores.mjs` is idempotent, so a second run adopts the chores that exist, creates only the missing ones, and reports the whole mapping. Either way, create nothing and close nothing yourself.
 
+**Housekeeping chore.** One stage runs outside the pipeline's ordering: `stage:housekeeping`, labelled `lifecycle:housekeeping` and blocked behind the PR gate bead, so it becomes ready only after a human merges the PR and closes the gate. Dispatch it with the **main checkout** as cwd — not the feature worktree — because the worktree it removes can be the parent's own. The worker runs `prune-worktrees.mjs`, retries once on a non-zero exit (exit `1` is normal: an open bead counts as survival), and then decides from the per-worktree report. It fails the chore and leaves it **open** when a `closed-bead` worktree is still `refused`; a `kept` or `refused` entry for an open bead is a normal report. Never close a chore over a worktree the script did not remove.
+
 **Never expand an existing bead by running `create-task`** (or any other command that creates a bead). `create-task` creates a bead first and expands second, so running it for an existing bead leaves a **second parent** beside the original, which stays chore-less and never gets dispatched. `create-chores.mjs` expands a bead that already exists; it never creates parents.
 
 ---

package/bin/agent-cortex.mjs

@@ -1,11 +1,22 @@
 #!/usr/bin/env node
 
-import { parseArgs, buildHelpText, resolveProgramName, validateHarness } from "../lib/cli.mjs";
+import { parseArgs, buildHelpText, resolveProgramName, validateHarness, SUPPORTED_HARNESSES } from "../lib/cli.mjs";
 import {
   collectVersionReport,
+  collectHarnessStatus,
   formatVersionReport,
   serialiseVersionReport,
 } from "../lib/harness-versions.mjs";
+import {
+  describeClaudeArtifacts,
+  describePiArtifacts,
+  formatHarnessTable,
+  formatUpdateFlags,
+  formatUpdateReport,
+  promptHarnessSelection,
+  runUpdate,
+  selectHarnesses,
+} from "../lib/harness-update.mjs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readFile } from "node:fs/promises";
@@ -90,50 +101,76 @@ if (parsed.command === "install") {
     process.exit(1);
   }
 
-  if (parsed.harness === "pi") {
+  try {
+    await installHarness(/** @type {"pi" | "claude"} */ (parsed.harness), {
+      dryRun: parsed.dryRun ?? false,
+      ...(parsed.output ? { output: parsed.output } : {}),
+      ...(parsed.pluginRoot ? { pluginRoot: parsed.pluginRoot } : {}),
+      requireRegister: parsed.requireRegister ?? false,
+    });
+  } catch (err) {
+    process.stderr.write(`Install failed: ${/** @type {Error} */ (err).message}\n`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (parsed.command === "update") {
+  process.exitCode = await runUpdateCommand(parsed, programName);
+}
+
+/**
+ * Run one harness's installer and, for a plain install, its registration.
+ * `install <harness>` and `update` both come through here, so update-vs-install
+ * stays the installer's decision and neither command grows a second install path.
+ * @param {"pi" | "claude"} harness
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun]
+ * @param {string} [options.output]
+ * @param {string} [options.pluginRoot]
+ * @param {boolean} [options.requireRegister]
+ * @returns {Promise<string[]>} What the installer wrote, for the update report
+ */
+async function installHarness(harness, { dryRun = false, output, pluginRoot, requireRegister = false } = {}) {
+  if (harness === "pi") {
     // A plain `agent-cortex install pi` stages the package into the home
     // install root (~/.agent-cortex/pi) and registers that directory with pi
     // through pi's own `pi install` (idempotent by state: a re-run is a no-op
     // update); `--output <dir>` is the stage-only form (tests/CI) and prints
     // the registration command instead.
-    try {
-      const result = await installPi({
-        dryRun: parsed.dryRun ?? false,
-        warn: () => {}, // warnings surface once in the printed summary
-        ...(parsed.output ? { output: parsed.output } : {}),
-        ...(parsed.pluginRoot ? { pluginRoot: parsed.pluginRoot } : {}),
+    const result = await installPi({
+      dryRun,
+      warn: () => {}, // warnings surface once in the printed summary
+      ...(output ? { output } : {}),
+      ...(pluginRoot ? { pluginRoot } : {}),
+    });
+    printPiInstall(result);
+    if (output === undefined) {
+      const registration = await registerPi({
+        output: result.output,
+        dryRun,
+        requireRegister,
+        warn: (msg) => process.stdout.write(`  ⚠ ${msg}\n`),
       });
-      printPiInstall(result);
-      if (parsed.output === undefined) {
-        const registration = await registerPi({
-          output: result.output,
-          dryRun: parsed.dryRun ?? false,
-          requireRegister: parsed.requireRegister ?? false,
-          warn: (msg) => process.stdout.write(`  ⚠ ${msg}\n`),
-        });
-        // The old installer's rendered copies are only stale once the staged
-        // package is what pi loads — and nothing is deleted on a dry run. The
-        // flag is passed through as well, so the sweep's own guarantee does not
-        // depend on this guard staying in place.
-        if (registration.registered && !(parsed.dryRun ?? false)) {
-          printPiSweep(
-            await sweepLegacyPiUserDirs({
-              piUserDir: dirname(registration.settingsPath),
-              dryRun: parsed.dryRun ?? false,
-            }),
-          );
-        }
-      } else {
-        process.stdout.write(`  → register it with pi: pi install ${result.output}\n`);
+      // The old installer's rendered copies are only stale once the staged
+      // package is what pi loads — and nothing is deleted on a dry run. The
+      // flag is passed through as well, so the sweep's own guarantee does not
+      // depend on this guard staying in place.
+      if (registration.registered && !dryRun) {
+        printPiSweep(
+          await sweepLegacyPiUserDirs({
+            piUserDir: dirname(registration.settingsPath),
+            dryRun,
+          }),
+        );
       }
-    } catch (err) {
-      process.stderr.write(`Install failed: ${/** @type {Error} */ (err).message}\n`);
-      process.exit(1);
+    } else {
+      process.stdout.write(`  → register it with pi: pi install ${result.output}\n`);
     }
-    process.exit(0);
+    return describePiArtifacts(result);
   }
 
-  process.stdout.write(`Installing agent-cortex for "${parsed.harness}" harness…\n`);
+  process.stdout.write(`Installing agent-cortex for "${harness}" harness…\n`);
 
   // claude is the first wired harness: a plain `agent-cortex install claude`
   // materialises the plugin into the home install root (~/.agent-cortex/claude)
@@ -144,40 +181,90 @@ if (parsed.command === "install") {
   // (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 {
-      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`);
+
+  // Avoid loading the installer on the help/summary paths and for other harnesses.
+  const { installClaude, registerClaude } = await import("./installers/claude.mjs");
+  const result = await installClaude({
+    dryRun,
+    warn: () => {}, // warnings surface once via result.warnings
+    ...(output ? { 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 (output === undefined) {
+    await registerClaude({
+      // A default install always materialises the marketplace manifest; the
+      // generate-only form (--output) is the only path where it is null, and
+      // this branch is not that path.
+      root: /** @type {string} */ (result.marketplaceRoot),
+      manifest: /** @type {object} */ (result.marketplaceManifest),
+      pluginVersion: result.pluginVersion,
+      // The enablement check reads the same file this install just merged:
+      // a plugin Claude Code does not enable loads nothing.
+      ...(result.settings ? { settingsPath: result.settings.path } : {}),
+      dryRun,
+      requireRegister,
+    });
+  }
+  return describeClaudeArtifacts(result);
+}
+
+/**
+ * `ctx update`: choose the harnesses, refresh each through its installer, report
+ * what changed. Every write happens inside `installHarness`'s call into the
+ * harness installer — this command adds selection and reporting only.
+ * @param {import("../lib/cli.mjs").ParsedArgs} parsed
+ * @param {string} programName
+ * @returns {Promise<number>} The exit code
+ */
+async function runUpdateCommand(parsed, programName) {
+  if (parsed.optionError) {
+    process.stderr.write(`${parsed.optionError}\n`);
+    return 1;
+  }
+  try {
+    const cliVersion = await readPackageVersion();
+    const statuses = await collectHarnessStatus({ cli: cliVersion });
+    const all = parsed.all ?? false;
+    let harnesses = parsed.harnesses ?? [];
+
+    // Bare `ctx update` asks; a non-interactive shell gets the same table plus
+    // the flags that select without a prompt, and a non-zero exit so a script
+    // never mistakes "nothing chosen" for "nothing to do".
+    if (harnesses.length === 0 && !all) {
+      if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+        process.stdout.write(`${formatHarnessTable(statuses)}\n\n${formatUpdateFlags(programName)}\n`);
+        return 1;
       }
-      // Runtime registration happens only for the plain install — `--output`
-      // keeps generating only (documented in --help).
-      if (parsed.output === undefined) {
-        await registerClaude({
-          // A default install always materialises the marketplace manifest; the
-          // generate-only form (--output) is the only path where it is null, and
-          // this branch is not that path.
-          root: /** @type {string} */ (result.marketplaceRoot),
-          manifest: /** @type {object} */ (result.marketplaceManifest),
-          pluginVersion: result.pluginVersion,
-          // The enablement check reads the same file this install just merged:
-          // a plugin Claude Code does not enable loads nothing.
-          ...(result.settings ? { settingsPath: result.settings.path } : {}),
-          dryRun: parsed.dryRun ?? false,
-          requireRegister: parsed.requireRegister ?? false,
-        });
+      harnesses = await promptHarnessSelection({ statuses });
+      if (harnesses.length === 0) {
+        process.stdout.write("No harness selected; nothing updated.\n");
+        return 0;
       }
-      process.exit(0);
-    } catch (err) {
-      process.stderr.write(`Install failed: ${/** @type {Error} */ (err).message}\n`);
-      process.exit(1);
     }
+
+    const plan = selectHarnesses({ statuses, harnesses, all, force: parsed.force ?? false });
+    if (plan.unknown.length > 0) {
+      const names = plan.unknown.map((name) => `"${name}"`).join(", ");
+      process.stderr.write(
+        `Unknown harness ${names}. Supported harnesses: ${SUPPORTED_HARNESSES.join(", ")}\nRun "${programName} --help" for usage.\n`,
+      );
+      return 1;
+    }
+
+    const entries = await runUpdate({
+      cli: cliVersion,
+      targets: plan.targets,
+      refresh: (harness) => installHarness(/** @type {"pi" | "claude"} */ (harness), {}),
+    });
+    process.stdout.write(`${formatUpdateReport({ cli: cliVersion, entries, skipped: plan.skipped })}\n`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`Update failed: ${/** @type {Error} */ (err).message}\n`);
+    return 1;
   }
 }
 
@@ -217,6 +304,9 @@ 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`);
+  if (result.docs.files.length > 0) {
+    process.stdout.write(`  ✓ Copied ${result.docs.files.length} doc(s) → ${result.docs.dir}\n`);
+  }
   process.stdout.write(`  ✓ Copied ${result.extensions.files} extension file(s) → ${result.extensions.dir}\n`);
   for (const name of result.packages.bundled) {
     process.stdout.write(`  ✓ Bundled pi package ${name} → ${join(result.packages.dir, name)}\n`);

package/bin/installers/claude.mjs

@@ -22,6 +22,12 @@
 //                                           layout (scripts/lib/skill-links.mjs),
 //                                           so a grouped-tree handoff still
 //                                           resolves in the plugin.
+//   <output>/docs/...                       documents the skills read after
+//                                           install (docs/skills/skill-anatomy.md),
+//                                           copied verbatim once per install — a
+//                                           skill names them by {{PATH:key}}, so
+//                                           the token map decides both location
+//                                           and shipment
 //   <output>/hooks.json + hooks/<scripts>   from hooks/claude/ (support files
 //                                           referenced via ${CLAUDE_PLUGIN_ROOT})
 //   <output>/.mcp.json + scripts/           hand-authored extras copied from
@@ -67,6 +73,7 @@ import { join, dirname, basename, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { composeAgent, loadTokenMap, substituteTokens } from "../../scripts/lib/compose-agent.mjs";
+import { installDocs } from "../../scripts/lib/docs.mjs";
 import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
 import { flattenSkillLinks } from "../../scripts/lib/skill-links.mjs";
 
@@ -633,6 +640,26 @@ async function isSymlink(filePath) {
   }
 }
 
+/**
+ * Result of generating (or planning) the Claude Code plugin.
+ * @typedef {object} InstallClaudeResult
+ * @property {string} output
+ * @property {string | null} marketplaceRoot
+ * @property {string | null} manifestPath
+ * @property {object | null} marketplaceManifest
+ * @property {string[]} agents
+ * @property {{ names: string[], md: number, files: number, dir: string }} skills
+ * @property {{ files: string[], dir: string }} docs
+ * @property {boolean} hooks
+ * @property {string[]} hookFiles
+ * @property {string[]} handAuthored
+ * @property {{ path: string, action: string, removedSymlink: boolean } | null} settings
+ * @property {{ path: string, action: string, removedSymlink: boolean } | null} instructions
+ * @property {string} pluginVersion
+ * @property {string[]} warnings
+ * @property {boolean} dryRun
+ */
+
 /**
  * Generate the Claude Code plugin subtree.
  *
@@ -654,13 +681,7 @@ async function isSymlink(filePath) {
  *                                       explicitly materialises the section even
  *                                       with --output — the test/CI seam.
  * @param {(msg: string) => void} [options.warn] Warning sink, also collected in `warnings`.
- * @returns {Promise<{ output: string, marketplaceRoot: string|null, manifestPath: string|null,
- *             marketplaceManifest: object|null, agents: string[],
- *             skills: {names: string[], md: number, files: number, dir: string},
- *             hooks: boolean, hookFiles: string[], handAuthored: string[],
- *             settings: {path: string, action: string, removedSymlink: boolean}|null,
- *             instructions: {path: string, action: string, removedSymlink: boolean}|null,
- *             pluginVersion: string, warnings: string[], dryRun: boolean }>}
+ * @returns {Promise<InstallClaudeResult>}
  */
 export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = false, pluginRoot, settingsPath, instructionsPath, warn = DEFAULT_WARN } = {}) {
   const tokenMap = await loadTokenMap(root);
@@ -690,7 +711,7 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
   // or a tmp dir, never claude-extras/, but clearing the output first would
   // still destroy sources if they ever collided). They are re-copied fresh in
   // the write phase. In dry-run nothing is cleaned or written.
-  const cleanable = ["agents", "skills", ".claude-plugin", "hooks", "scripts", "hooks.json", ".mcp.json"];
+  const cleanable = ["agents", "skills", "docs", ".claude-plugin", "hooks", "scripts", "hooks.json", ".mcp.json"];
   const handAuthored = await buildHandAuthored(root);
 
   // Regenerate the plugin children (removes stale output from earlier flows,
@@ -721,6 +742,7 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
   const agents = await buildAgents(root);
   const skillOut = join(out, "skills");
   const skills = await buildSkills(root, skillOut, { dryRun, pluginRoot: rootPlugin, tokenMap, warn: warnSink });
+  const docs = await installDocs({ root, output: out, dryRun, tokenMap });
   const pluginJson = await buildPluginJson(root);
   const hooksSrc = join(root, "hooks", "claude", "hooks.json");
   const hooksJson = (await isFile(hooksSrc)) ? await readFile(hooksSrc, "utf-8") : null;
@@ -735,6 +757,7 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
     pluginVersion: JSON.parse(pluginJson).version,
     agents: agents.files.map((f) => f.file.replace(/\.md$/, "")),
     skills: { names: skills.names, md: skills.md, files: skills.files, dir: skillOut },
+    docs,
     hooks: hooksJson !== null,
     hookFiles: hookFiles.map((f) => f.rel),
     handAuthored: handAuthored.map((f) => f.rel),
@@ -748,6 +771,7 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
     console.log(`DRY-RUN — would generate into ${out}, no files written:`);
     console.log(`  agents: ${summary.agents.join(", ")}`);
     console.log(`  skills: ${summary.skills.names.length} copied → ${skillOut}/<name>/ (token-substituted)`);
+    if (docs.files.length) console.log(`  docs: ${docs.files.join(", ")} → ${docs.dir}/ (verbatim copies)`);
     console.log(`  .claude-plugin/plugin.json (version ${JSON.parse(pluginJson).version})`);
     if (isDefaultInstall && manifestPath) {
       console.log(`  marketplace manifest → ${manifestPath} (plugin agent-cortex @ ./${basename(out)})`);
@@ -778,6 +802,7 @@ export async function installClaude({ root = PACKAGE_ROOT, output, dryRun = fals
   console.log(
     `Copied ${summary.skills.names.length} skill(s) → ${skillOut}/<name>/ (token-substituted, no symlinks)`,
   );
+  if (docs.files.length) console.log(`Copied ${docs.files.length} doc(s) → ${docs.dir}/ (verbatim)`);
 
   await mkdir(join(out, ".claude-plugin"), { recursive: true });
   await writeFile(join(out, ".claude-plugin", "plugin.json"), pluginJson);

package/bin/installers/pi.mjs

@@ -22,6 +22,11 @@
 //                                    <extension>/../../agents, i.e. this dir
 //   <output>/skills/<group>/<name>/  token-substituted skill copies — real
 //                                    files, never symlinks
+//   <output>/docs/...                documents the skills read after install
+//                                    (docs/skills/skill-anatomy.md), copied
+//                                    verbatim once per install — a skill names
+//                                    them by {{PATH:key}}, so the token map
+//                                    decides both location and shipment
 //   <output>/extensions/             copy of the repo extensions/ tree (loaded
 //                                    by pi's package discovery)
 //   <output>/token-map.json          the map agent-modes reads from the package
@@ -115,6 +120,7 @@ import { join, dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { composeAgent, loadTokenMap, substituteTokens, translateToolList } from "../../scripts/lib/compose-agent.mjs";
+import { installDocs } from "../../scripts/lib/docs.mjs";
 import { isDirectory, isFile } from "../../scripts/lib/fs.mjs";
 
 const PI = "pi";
@@ -141,6 +147,7 @@ const PI = "pi";
  * @property {string} output
  * @property {{ name: string, filePath: string }[]} agents
  * @property {{ skills: number, md: number, files: number, dir: string }} skills
+ * @property {{ files: string[], dir: string }} docs
  * @property {{ files: number, dir: string }} extensions
  * @property {{ dir: string, bundled: string[], staged: string[], resources: PackageResources }} packages
  * @property {{ path: string, manifest: PiManifest }} manifest
@@ -181,7 +188,7 @@ const STAGED_NAME = "@jaybeeuu/agent-cortex-pi";
 // before every write so re-staging cannot leave stale copies behind (a skill
 // deleted in the repo, a package dropped from the manifest). Anything else in
 // the output directory is left alone.
-const OWNED_CHILDREN = ["package.json", "token-map.json", "agents", "skills", "extensions", "node_modules"];
+const OWNED_CHILDREN = ["package.json", "token-map.json", "agents", "skills", "docs", "extensions", "node_modules"];
 
 const GENERATED_MARKER =
   "GENERATED by `agent-cortex install pi` — DO NOT EDIT; re-run the installer to update.";
@@ -242,6 +249,7 @@ const DEFAULT_LEGACY_SWEEP_RECORD = join(homedir(), ".agent-cortex", "legacy-swe
  * @param {(msg: string) => void} [options.warn] Warning sink, also collected in `warnings`
  * @returns {Promise<{ output: string, agents: {name: string, filePath: string}[],
  *             skills: {skills: number, md: number, files: number, dir: string},
+ *             docs: {files: string[], dir: string},
  *             extensions: {files: number, dir: string},
  *             packages: {dir: string, bundled: string[], staged: string[], resources: {extensions: string[], skills: string[]}},
  *             manifest: {path: string, manifest: PiManifest},
@@ -285,6 +293,7 @@ export async function installPi(options = {}) {
 
   const agents = await installAgents({ root, agentsDir: join(output, "agents"), dryRun, pluginRoot, tokenMap, warn });
   const skills = await installSkills({ root, skillsDir: join(output, "skills"), dryRun, pluginRoot, tokenMap, warn });
+  const docs = await installDocs({ root, output, dryRun, tokenMap });
   const extensions = await installExtensions({ root, output, dryRun });
   const tokenMapFile = await installTokenMap({ output, tokenMap, dryRun });
   const packages = await stagePiPackages({ dependencies, output, resolvePackage, dryRun, warn });
@@ -301,6 +310,7 @@ export async function installPi(options = {}) {
     output,
     agents,
     skills,
+    docs,
     extensions,
     packages,
     manifest,