@jaybeeuu/agent-cortex 2.6.0 → 2.8.0

package/agents/ralph/pi/wake.md

@@ -46,30 +46,25 @@ Initialize `.agent-cortex/ralph/state.json` as `{ "timerShellId": null, "infligh
 - **inflight[].agentId** — the ID `task` returned for that worker; it is the argument `wait_for_agents` takes, the identifier for a `read_agent` fallback, and the key the completion is correlated to its bead.
 - **timerShellId** — stays `null` on PI forever: the blocking wait replaces a poll timer, so nothing is ever recorded there.
 
-### Log flush
-
-Flush new log lines as part of handling each wait result — that is when the loop wakes, and a worker's final lines arrive with the completion. Run this procedure each time `wait_for_agents` returns (or whenever a new agent is dispatched):
-
-1. **Query in-flight beads**: read `inflight` from `state.json`. Each entry has a `parentId` and `logLine`.
-2. For each in-flight entry, read new lines from its log file:
-   ```bash
-   tail -n +<logLine> .agent-cortex/ralph/ralph-<parentId>.log 2>/dev/null
-   ```
-3. For each entry that has new lines:
-   - **Post a chat summary** of new key events (stage transitions and notable events — not every line verbatim). Format:
-     ```
-     📋 [parent-id] <title>
-        coding → verifying  (or whatever transition)
-        Tests: 12 passed, 0 failed
-     ```
-   - Update `logLine` in `state.json` for that entry.
-4. If no entry had new lines, post nothing — do not spam the chat with empty polls.
+### Reading the trail
+
+There is no log file and nothing to flush. A worker appends its own checkpoints to its bead with
+`trail-entry.mjs`, so progress is read from the bead itself when a wait returns:
+
+```bash
+bd show <chore-id>              # entries: Outcome, Evidence, What is left
+bd provenance log <chore-id>    # refs: git-sha, branch, pr, work-id
+```
+
+Read each completed worker's bead once, post a chat summary of what is new — the stage transition,
+the test and lint results, the close reason — and post nothing when nothing new arrived. Nothing in
+`state.json` needs a bookmark, because the trail is not a stream to follow.
 
 ### Wait loop lifecycle
 
 - **Dispatch-and-wait** — during initialization, dispatch up to 5 AFK chore subagents with `task` (or an expansion worker for a chore-less AFK bead) and hold their agent IDs (recorded in `state.json`'s `inflight` list; expansion entries carry `kind: "expand"` and `choreId: null`).
 - **Wait** — call `wait_for_agents` with the agent IDs of every in-flight agent, stage worker or expansion worker (`timeout` defaults to 120s). The tool blocks until at least one finishes. For each completed agent:
-  1. Flush its log tail if it has new lines (see _Log flush_ above) to surface progress to chat.
+  1. Read its bead trail (see _Reading the trail_ above) to surface progress to chat.
   2. Apply the shared completion handling described under _Completion arrival_ above.
   3. Drop the completed agent ID from the wait set.
 - **Repeat** — dispatch replacements for completed work (up to 5 in flight), add their new IDs to the wait set, and call `wait_for_agents` again with the remaining + new IDs. A completed expansion leaves a slot to fill with its parent's newly ready `stage:code` chore.
@@ -86,4 +81,4 @@ Nothing to kill: stopping means simply **stop calling `wait_for_agents`**. There
 - **Always** keep a `wait_for_agents` call outstanding while agents are in-flight — stage workers and expansion workers alike. Never let running agent work stall without a wait active.
 - **Never** re-dispatch an agent that is merely STILL RUNNING — wait again on the same ID.
 - **Never** start `sleep` / background timer loops for completion detection on PI — `wait_for_agents` replaces them, and there is nothing to kill on HITL Pause.
-- **Never** post empty poll updates to chat — only surface new log content.
+- **Never** post empty poll updates to chat — only surface what a bead actually reports.

package/bin/agent-cortex.mjs

@@ -1,14 +1,26 @@
 #!/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";
+import { readFile, realpath } from "node:fs/promises";
+import { runSelfUpdate } from "../lib/self-update.mjs";
 import { installPi, registerPi, sweepLegacyPiUserDirs } from "./installers/pi.mjs";
 
 /** @typedef {import("./installers/pi.mjs").InstallPiResult} InstallPiResult */
@@ -90,50 +102,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 +182,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;
   }
 }
 
@@ -192,6 +280,24 @@ function printPiSweep({ removed }) {
   }
 }
 
+if (parsed.command === "self-update") {
+  if (parsed.optionError) {
+    process.stderr.write(`${parsed.optionError}\n`);
+    process.exit(1);
+  }
+  try {
+    // The real path follows the global bin shim into the layout of the manager
+    // that installed this copy, which is what identifies the owner. Taking it
+    // from this file's own URL keeps detection on the running entry point, not
+    // on the cwd or on PATH.
+    const entryPoint = await realpath(fileURLToPath(import.meta.url));
+    process.exitCode = await runSelfUpdate({ entryPoint, programName, check: parsed.check ?? false });
+  } catch (err) {
+    process.stderr.write(`${/** @type {Error} */ (err).message}\n`);
+    process.exit(1);
+  }
+}
+
 if (parsed.command === "migrate") {
   if (parsed.optionError) {
     process.stderr.write(`${parsed.optionError}\n`);
@@ -217,6 +323,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,