@bigking67/pi-67 0.10.3 → 0.10.5

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## [0.10.5]
+
+- Uses `git fetch` plus `git merge --ff-only FETCH_HEAD` in Bash and
+  PowerShell updaters, allowing the updater to inspect incoming changed paths
+  before deciding whether dirty preserved runtime files need temporary cleanup.
+- Keeps dirty runtime config in place without creating a backup when the remote
+  is already current or incoming changed paths do not touch those files.
+- Reports `preserve-in-place-no-backup` from `pi-67 update --check` when a
+  dirty runtime marker is harmless and the remote already matches local HEAD.
+- Updates docs to separate current `~/.pi/pi67/backups/` runtime backups from
+  legacy read-only `~/.pi/agent-backups/` conflict snapshots.
+- Tightens release/smoke gates by checking README version drift, rejecting
+  simulated placeholder final answers, and requiring package metadata smoke
+  cases to include the real package version.
+- Adds `pi-67 xtalpi run` and a Windows PowerShell xtalpi launcher. The stable
+  launcher defaults `PI_OBSERVATIONAL_MEMORY_PASSIVE=true` to keep post-final
+  observational-memory background writes from holding the main task lifecycle
+  open.
+- Bounds `pi skill list` in doctor with POSIX
+  `--skill-list-timeout-seconds` and PowerShell `-SkillListTimeoutSeconds`.
+- Removes legacy `xtalpi-compat` runtime path examples from bootstrap docs.
+
+## [0.10.4]
+
+- Makes all command-level `--help` paths side-effect free, including
+  `pi-67 update --help`, with self-tests proving help output does not create
+  runtime backup directories.
+- Blocks unsafe dirty update plans before the update lifecycle starts, so a
+  blocked `pi-67 update` does not first write a runtime backup.
+- Adds `pi-67 backups prune` and `pi-67 backups archive` for dry-run-first
+  backup retention, with per-kind `--keep-last` semantics.
+- Adds `pi-67 skills plan` and `pi-67 skills diff <name>` for explicit
+  shared-skill drift review without overwriting existing global skills.
+- Adds `pi-67 xtalpi trend`, `pi-67 xtalpi drift`, and `pi-67 xtalpi stress
+  --until-done`; drift defaults to full-suite artifacts to avoid targeted smoke
+  noise.
+- Aligns runtime backup ownership around script-level
+  `pre-update-runtime-*` snapshots while the npm manager owns update planning,
+  locking, and orchestration.
+- Reuses equivalent runtime backups across both `manifest.json` and
+  `backup-manifest.json` formats.
+- Expands Windows CI coverage to Node 22 and Node 24 plus npm manager CLI
+  contract smoke commands.
+
 ## [0.10.3]
 
 - Deduplicates real update/repair runtime backups when preserved config files

package/README.md

@@ -73,14 +73,21 @@ check or repair before trusting the globally installed manager.
 - user-added global skills
 - dirty external repos such as browser67 or design-craft
 
-Before a real `update` or `repair`, the npm manager acquires
-`~/.pi/pi67/locks/update.lock` and snapshots preserved runtime files under
-`~/.pi/pi67/backups/<timestamp>-update/`. This makes the public `npx -y
-@bigking67/pi-67@latest update --repair` path safe even for in-place checkouts
-where `settings.json` is tracked but user-owned.
-If the preserved runtime files are unchanged from the latest same-operation
-backup, the manager reuses that snapshot instead of writing another timestamped
-directory.
+Before a real `update` or `repair`, the npm manager builds the update plan,
+blocks unsafe non-runtime dirty worktrees, and acquires
+`~/.pi/pi67/locks/update.lock`. Runtime config backup/restore is delegated to
+the Bash or PowerShell updater script only when an in-place checkout needs to
+temporarily clear dirty preserved runtime files. The updater fetches first,
+compares incoming `HEAD..FETCH_HEAD` changed paths, and creates a runtime
+snapshot only when the incoming update touches those dirty preserved files.
+Those script-level snapshots live under
+`~/.pi/pi67/backups/pre-update-runtime-*`.
+This keeps `--help`, blocked update plans, already-up-to-date updates,
+non-overlapping incoming updates, and the public `npx -y
+@bigking67/pi-67@latest update --repair` orchestration path free of duplicate
+manager-owned runtime backups. If a backup is actually needed and an identical
+runtime snapshot already exists, the script-level updater reuses it instead of
+writing another timestamped directory.
 
 Runtime backups are first-class CLI state:
 
@@ -91,6 +98,8 @@ pi-67 backups inspect <backup-id-or-path>
 pi-67 backups inspect <pre-update-id> --legacy
 pi-67 backups restore --from <backup-id-or-path> --dry-run
 pi-67 backups restore --from <backup-id-or-path> --yes
+pi-67 backups prune --keep-last 10 --dry-run
+pi-67 backups archive --keep-last 10 --older-than 30d --dry-run
 ```
 
 The restore command only restores preserved runtime files and writes a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigking67/pi-67",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "Cross-platform manager CLI for the pi-67 Pi Coding Agent distribution.",
   "type": "module",
   "bin": {

package/scripts/check.mjs

@@ -5,6 +5,7 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { npmLatestVersion, npmPublishTargetStatus, npmRegistryPackageUrl } from "../src/lib/npm-registry.mjs";
 import { commandCandidatesForPlatform } from "../src/lib/shell-runner.mjs";
+import { parseCommandOptions, splitGlobalArgs } from "../src/lib/args.mjs";
 import { readExtensionRegistry, validateExtensionRegistry } from "../src/lib/extension-registry.mjs";
 import { buildPlanDecisions, classifyGitShort } from "../src/lib/update-plan.mjs";
 import {
@@ -29,6 +30,8 @@ for (const file of files.filter((item) => item.endsWith(".json"))) {
   JSON.parse(fs.readFileSync(file, "utf8"));
 }
 await runNpmRegistrySelfTests();
+runArgsSelfTests();
+runCliHelpContractSelfTests();
 runPublishTargetSelfTests();
 runShellRunnerSelfTests();
 runExtensionRegistrySelfTests();
@@ -44,6 +47,67 @@ function walk(dir, files) {
   }
 }
 
+function runArgsSelfTests() {
+  const afterCommandHelp = splitGlobalArgs(["skills", "--help"]);
+  assert(
+    !afterCommandHelp.globals.help && afterCommandHelp.rest.join(" ") === "skills --help",
+    "command-level --help must not be consumed as global help after a command is seen",
+  );
+  const globalHelp = splitGlobalArgs(["--help"]);
+  assert(globalHelp.globals.help && globalHelp.rest.length === 0, "global --help must still be parsed globally");
+  assert(
+    parseCommandOptions(["--help"], { bools: [] }).options.help,
+    "command option parser must accept --help for every command",
+  );
+}
+
+function runCliHelpContractSelfTests() {
+  const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi67-help-contract-"));
+  const home = path.join(tmpRoot, "home");
+  const agentDir = path.join(tmpRoot, "agent");
+  const skillsDir = path.join(tmpRoot, "skills");
+  fs.mkdirSync(home, { recursive: true });
+  fs.mkdirSync(agentDir, { recursive: true });
+  fs.mkdirSync(skillsDir, { recursive: true });
+  const env = { ...process.env, HOME: home, USERPROFILE: home };
+  const globalArgs = ["--agent-dir", agentDir, "--repo-root", root, "--skills-dir", skillsDir];
+  const commands = [
+    ["--help"],
+    ["install", "--help"],
+    ["update", "--help"],
+    ["doctor", "--help"],
+    ["smoke", "--help"],
+    ["status", "--help"],
+    ["report", "--help"],
+    ["version", "--help"],
+    ["xtalpi", "--help"],
+    ["themes", "--help"],
+    ["skills", "--help"],
+    ["extensions", "--help"],
+    ["external", "--help"],
+    ["self-update", "--help"],
+    ["publish-check", "--help"],
+    ["manifest", "--help"],
+    ["backups", "--help"],
+  ];
+  const backupRoot = path.join(home, ".pi", "pi67", "backups");
+  for (const command of commands) {
+    const result = spawnSync(process.execPath, [path.join(root, "bin", "pi-67.mjs"), ...globalArgs, ...command], {
+      cwd: root,
+      env,
+      encoding: "utf8",
+    });
+    assert(result.status === 0, `help command failed: pi-67 ${command.join(" ")}\n${result.stderr || result.stdout}`);
+    assert(!result.stderr.trim(), `help command wrote stderr: pi-67 ${command.join(" ")}\n${result.stderr}`);
+    assert(result.stdout.includes("Usage:"), `help command must print Usage: pi-67 ${command.join(" ")}`);
+  }
+  assert(
+    !fs.existsSync(backupRoot) || fs.readdirSync(backupRoot).length === 0,
+    "help commands must not create runtime backups",
+  );
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+}
+
 function runPublishTargetSelfTests() {
   const unpublished = {
     skipped: false,
@@ -283,6 +347,18 @@ function runUpdatePlanSelfTests() {
     "dirty runtime config alone must not block the distro update plan",
   );
 
+  const dirtyRuntimeRemoteCurrent = decisionsFixture({
+    git: { dirty: true, short: " M settings.json", commit: "abcdef123456" },
+    remote: { ok: true, commit: "abcdef1234567890" },
+  });
+  const currentRemoteAction = buildPlanDecisions(dirtyRuntimeRemoteCurrent).actions.find((item) => item.id === "user-runtime-config");
+  assert(
+    currentRemoteAction?.operation === "preserve-in-place-no-backup" &&
+      currentRemoteAction.createsNewBackup === false &&
+      currentRemoteAction.writes.length === 0,
+    "dirty runtime config must not plan a new backup when the remote already matches local HEAD",
+  );
+
   const dirtyReadme = decisionsFixture({
     git: { dirty: true, short: " M README.md" },
   });
@@ -384,6 +460,26 @@ function runUpdateSafetySelfTests() {
     listRuntimeBackups(ctx).length === backupCountBeforeDedupe,
     "deduplicated update lifecycle snapshots must not create new backup directories",
   );
+  const backupCountBeforeDelegated = listRuntimeBackups(ctx).length;
+  const delegatedLifecycle = beginUpdateLifecycle({
+    agentDir,
+    repoRoot: agentDir,
+    stateDir,
+  }, {
+    operation: "test-delegated",
+    backupRuntime: false,
+  });
+  assert(fs.existsSync(delegatedLifecycle.lockPath), "delegated update lifecycle must still acquire a lock");
+  assert(
+    delegatedLifecycle.backupSkipped && !delegatedLifecycle.backupDir && delegatedLifecycle.backedUp.length === 0,
+    "delegated update lifecycle must skip manager-owned runtime backups",
+  );
+  delegatedLifecycle.release();
+  assert(!fs.existsSync(delegatedLifecycle.lockPath), "delegated update lifecycle must release lock");
+  assert(
+    listRuntimeBackups(ctx).length === backupCountBeforeDelegated,
+    "delegated update lifecycle must not create runtime backup directories",
+  );
   assert(
     inspectRuntimeBackup(ctx, lifecycle.backupDir).fileCount >= 2,
     "update lifecycle backups must be inspectable",

package/src/cli.mjs

@@ -81,15 +81,15 @@ Commands:
   status               Read-only status summary
   report               Generate pi67-report.json
   version              Print manager and distro versions
-  xtalpi               xtalpi health/smoke/capability helpers
+  xtalpi               xtalpi health/smoke/capability/trend/drift/stress helpers
   themes               current/list/doctor/set without update-time overwrite
-  skills               inventory/sync/migrate shared skills
+  skills               inventory/plan/diff/sync/migrate shared skills
   extensions           list/doctor/inspect/plan extension ownership policy
   external             list/install/update/doctor external repos
   self-update          Explicitly update the npm manager package
   publish-check        Verify npm publish readiness and trusted publishing
   manifest             Show managed package/config/theme ownership policy
-  backups              list/inspect/restore preserved runtime backups
+  backups              list/inspect/restore/prune/archive runtime backups
 
 Examples:
   pi-67 install
@@ -101,8 +101,11 @@ Examples:
   pi-67 manifest
   pi-67 manifest --validate
   pi-67 backups list
+  pi-67 backups prune --keep-last 10 --dry-run
   pi-67 extensions doctor
+  pi-67 skills plan
   pi-67 xtalpi smoke --quick
+  pi-67 xtalpi trend
   pi-67 themes current
 `);
 }

package/src/commands/backups.mjs

@@ -1,4 +1,6 @@
 import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
 import { parseCommandOptions } from "../lib/args.mjs";
 import {
   inspectLegacyConflictBackup,
@@ -14,6 +16,8 @@ export async function backupsCommand(ctx, argv) {
   if (subcommand === "list") return listCommand(ctx, argv.slice(1));
   if (subcommand === "inspect") return inspectCommand(ctx, argv.slice(1));
   if (subcommand === "restore") return restoreCommand(ctx, argv.slice(1));
+  if (subcommand === "prune") return pruneCommand(ctx, argv.slice(1));
+  if (subcommand === "archive") return archiveCommand(ctx, argv.slice(1));
   if (subcommand === "-h" || subcommand === "--help" || subcommand === "help") {
     printBackupsHelp();
     return;
@@ -25,6 +29,7 @@ function listCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "include-legacy"],
   });
+  if (options.help) return printBackupsHelp();
   const backups = listRuntimeBackups(ctx);
   const legacyConflictBackups = listLegacyConflictBackups(ctx);
   if (ctx.json || options.json) {
@@ -62,6 +67,7 @@ function inspectCommand(ctx, argv) {
   const { options, positionals } = parseCommandOptions(argv, {
     bools: ["json", "legacy"],
   });
+  if (options.help) return printBackupsHelp();
   const backup = options.legacy ? inspectLegacyConflictBackup(ctx, positionals[0]) : inspectRuntimeBackup(ctx, positionals[0]);
   if (ctx.json || options.json) {
     printJson({
@@ -96,6 +102,7 @@ function restoreCommand(ctx, argv) {
     strings: ["from"],
     bools: ["json", "dry-run", "yes"],
   });
+  if (options.help) return printBackupsHelp();
   const dryRun = ctx.dryRun || options.dryRun;
   if (!options.from) {
     throw new CliError("backups restore requires --from <backup-id-or-path>", 2);
@@ -128,13 +135,186 @@ function restoreCommand(ctx, argv) {
   }
 }
 
+function pruneCommand(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    strings: ["keep-last", "older-than"],
+    bools: ["json", "dry-run", "yes", "include-legacy"],
+  });
+  if (options.help) return printBackupsHelp();
+  const dryRun = ctx.dryRun || options.dryRun;
+  const plan = buildRetentionPlan(ctx, options);
+  if (!dryRun && !(ctx.yes || options.yes)) {
+    throw new CliError("backups prune deletes backup directories; rerun with --dry-run or --yes", 2);
+  }
+  if (!dryRun) {
+    for (const item of plan.selected) {
+      fs.rmSync(item.path, { recursive: true, force: true });
+    }
+  }
+  const result = {
+    schema: "pi67.backups-prune.v1",
+    createdAt: new Date().toISOString(),
+    dryRun,
+    selector: plan.selector,
+    selected: plan.selected,
+    kept: plan.kept,
+    deleted: dryRun ? [] : plan.selected,
+  };
+  if (ctx.json || options.json) return printJson(result);
+  section("pi-67 backups prune");
+  keyValue("Dry run", dryRun ? "yes" : "no");
+  keyValue("Selected", result.selected.length);
+  keyValue("Kept", result.kept.length);
+  for (const item of result.selected) {
+    warn(`${dryRun ? "would delete" : "deleted"} ${item.kind}: ${item.id}`);
+  }
+  if (result.selected.length === 0) pass("no backups matched the retention selector");
+}
+
+function archiveCommand(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    strings: ["keep-last", "older-than", "to"],
+    bools: ["json", "dry-run", "yes", "include-legacy"],
+  });
+  if (options.help) return printBackupsHelp();
+  const dryRun = ctx.dryRun || options.dryRun;
+  const plan = buildRetentionPlan(ctx, options);
+  const archiveRoot = path.resolve(expandTilde(options.to || path.join(ctx.stateDir, "backups-archive")));
+  if (!dryRun && !(ctx.yes || options.yes)) {
+    throw new CliError("backups archive moves backup directories; rerun with --dry-run or --yes", 2);
+  }
+  const archived = [];
+  if (!dryRun) {
+    fs.mkdirSync(archiveRoot, { recursive: true, mode: 0o700 });
+    for (const item of plan.selected) {
+      const targetRoot = path.join(archiveRoot, item.kind);
+      fs.mkdirSync(targetRoot, { recursive: true, mode: 0o700 });
+      const target = uniqueArchivePath(path.join(targetRoot, item.id));
+      moveDirectorySync(item.path, target);
+      archived.push({ ...item, archivedPath: target });
+    }
+  }
+  const result = {
+    schema: "pi67.backups-archive.v1",
+    createdAt: new Date().toISOString(),
+    dryRun,
+    archiveRoot,
+    selector: plan.selector,
+    selected: plan.selected,
+    kept: plan.kept,
+    archived: dryRun ? [] : archived,
+  };
+  if (ctx.json || options.json) return printJson(result);
+  section("pi-67 backups archive");
+  keyValue("Dry run", dryRun ? "yes" : "no");
+  keyValue("Archive root", archiveRoot);
+  keyValue("Selected", result.selected.length);
+  for (const item of result.selected) {
+    info(`${dryRun ? "would archive" : "archived"} ${item.kind}: ${item.id}`);
+  }
+  if (result.selected.length === 0) pass("no backups matched the retention selector");
+}
+
+function buildRetentionPlan(ctx, options) {
+  const keepLast = parseOptionalNonNegativeInt(options.keepLast, "--keep-last");
+  const olderThanMs = parseDurationMs(options.olderThan, "--older-than");
+  if (keepLast === undefined && olderThanMs === undefined) {
+    throw new CliError("backups retention requires --keep-last N and/or --older-than Nd|Nh|Nm", 2);
+  }
+  const now = Date.now();
+  const runtime = listRuntimeBackups(ctx).map((item) => ({ ...item, kind: "runtime" }));
+  const legacy = options.includeLegacy
+    ? listLegacyConflictBackups(ctx).map((item) => ({ ...item, kind: "legacy" }))
+    : [];
+  const all = [...runtime, ...legacy].sort((left, right) => backupTime(right) - backupTime(left));
+  const rankByKind = new Map();
+  const selected = [];
+  const kept = [];
+  for (const item of all) {
+    const rank = rankByKind.get(item.kind) || 0;
+    rankByKind.set(item.kind, rank + 1);
+    const keptByCount = keepLast !== undefined && rank < keepLast;
+    const oldEnough = olderThanMs === undefined || now - backupTime(item) >= olderThanMs;
+    if (!keptByCount && oldEnough) selected.push(item);
+    else kept.push(item);
+  }
+  return {
+    selector: {
+      keepLast: keepLast ?? null,
+      olderThan: options.olderThan || "",
+      includeLegacy: Boolean(options.includeLegacy),
+    },
+    selected,
+    kept,
+  };
+}
+
+function parseOptionalNonNegativeInt(value, name) {
+  if (value === undefined) return undefined;
+  const number = Number(value);
+  if (!Number.isInteger(number) || number < 0) {
+    throw new CliError(`${name} must be a non-negative integer`, 2);
+  }
+  return number;
+}
+
+function parseDurationMs(value, name) {
+  if (value === undefined) return undefined;
+  const match = /^(\d+)(m|h|d)$/i.exec(String(value).trim());
+  if (!match) throw new CliError(`${name} must look like 30d, 12h, or 90m`, 2);
+  const amount = Number(match[1]);
+  const unit = match[2].toLowerCase();
+  const multiplier = unit === "d" ? 24 * 60 * 60 * 1000 : unit === "h" ? 60 * 60 * 1000 : 60 * 1000;
+  return amount * multiplier;
+}
+
+function backupTime(item) {
+  const parsed = Date.parse(item.createdAt || "");
+  if (Number.isFinite(parsed)) return parsed;
+  try {
+    return fs.statSync(item.path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function uniqueArchivePath(candidate) {
+  if (!fs.existsSync(candidate)) return candidate;
+  for (let index = 1; index < 1000; index += 1) {
+    const next = `${candidate}.${index}`;
+    if (!fs.existsSync(next)) return next;
+  }
+  throw new CliError(`could not allocate archive path for ${candidate}`, 1);
+}
+
+function expandTilde(input) {
+  if (input === "~") return os.homedir();
+  if (input.startsWith("~/") || input.startsWith("~\\")) {
+    return path.join(os.homedir(), input.slice(2));
+  }
+  return input;
+}
+
+function moveDirectorySync(source, target) {
+  try {
+    fs.renameSync(source, target);
+    return;
+  } catch (error) {
+    if (error.code !== "EXDEV") throw error;
+  }
+  fs.cpSync(source, target, { recursive: true, force: false, errorOnExist: true });
+  fs.rmSync(source, { recursive: true, force: true });
+}
+
 function printBackupsHelp() {
-  process.stdout.write(`pi-67 backups - inspect and restore preserved runtime backups
+  process.stdout.write(`pi-67 backups - inspect, restore, prune, and archive runtime backups
 
 Usage:
   pi-67 backups list [--include-legacy] [--json]
   pi-67 backups inspect <backup-id-or-path> [--legacy] [--json]
   pi-67 backups restore --from <backup-id-or-path> [--dry-run] [--yes] [--json]
+  pi-67 backups prune --keep-last N [--older-than 30d] [--include-legacy] [--dry-run|--yes] [--json]
+  pi-67 backups archive --keep-last N [--older-than 30d] [--to DIR] [--include-legacy] [--dry-run|--yes] [--json]
 
 Examples:
   pi-67 backups list
@@ -143,5 +323,11 @@ Examples:
   pi-67 backups inspect pre-update-20260707-235901 --legacy
   pi-67 backups restore --from 20260707T120000Z-update --dry-run
   pi-67 backups restore --from 20260707T120000Z-update --yes
+  pi-67 backups prune --keep-last 10 --dry-run
+  pi-67 backups archive --keep-last 10 --older-than 30d --dry-run
+
+Retention:
+  --keep-last is applied per backup kind. Legacy backups are ignored unless
+  --include-legacy is provided. prune/archive require --dry-run or --yes.
 `);
 }

package/src/commands/doctor.mjs

@@ -5,8 +5,12 @@ import { isWindows } from "../lib/platform.mjs";
 export async function doctorCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "quiet", "dry-run", "deep-mcp", "strict-shared-skills"],
-    strings: ["mcp-timeout-ms"],
+    strings: ["mcp-timeout-ms", "skill-list-timeout-seconds"],
   });
+  if (options.help) {
+    printDoctorHelp();
+    return;
+  }
   const args = isWindows()
     ? ["-AgentDir", ctx.agentDir, "-RepoRoot", ctx.repoRoot, "-SkillsDir", ctx.skillsDir]
     : ["--agent-dir", ctx.agentDir, "--repo-root", ctx.repoRoot, "--skills-dir", ctx.skillsDir];
@@ -15,7 +19,32 @@ export async function doctorCommand(ctx, argv) {
   if (options.strictSharedSkills) args.push(isWindows() ? "-StrictSharedSkills" : "--strict-shared-skills");
   if (!isWindows() && options.deepMcp) args.push("--deep-mcp");
   if (!isWindows() && options.mcpTimeoutMs) args.push("--mcp-timeout-ms", options.mcpTimeoutMs);
+  if (options.skillListTimeoutSeconds) {
+    args.push(isWindows() ? "-SkillListTimeoutSeconds" : "--skill-list-timeout-seconds", options.skillListTimeoutSeconds);
+  }
   runDistroScript(ctx, { sh: "pi67-doctor.sh", ps1: "pi67-doctor.ps1" }, args, {
     dryRun: ctx.dryRun || options.dryRun,
   });
 }
+
+function printDoctorHelp() {
+  process.stdout.write(`pi-67 doctor - run readiness diagnostics
+
+Usage:
+  pi-67 doctor [--json] [--quiet] [--deep-mcp] [--strict-shared-skills]
+
+Options:
+  --json                  Emit machine-readable diagnostics.
+  --quiet                 Reduce human output where supported.
+  --deep-mcp              Run deeper MCP probes on POSIX platforms.
+  --mcp-timeout-ms N      Timeout for deep MCP probes on POSIX platforms.
+  --skill-list-timeout-seconds N
+                          Timeout for pi skill list on POSIX platforms.
+  --strict-shared-skills  Treat differing shared skills as blocking.
+  --dry-run               Print the script invocation without running it.
+
+Examples:
+  pi-67 doctor
+  pi-67 doctor --json
+`);
+}

package/src/commands/extensions.mjs

@@ -20,6 +20,7 @@ export async function extensionsCommand(ctx, argv) {
 
 function list(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printExtensionsHelp();
   const manifest = buildDistroManifest(ctx);
   const data = {
     schema: "pi67.extensions-list.v1",
@@ -41,6 +42,7 @@ async function doctor(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "strict-shared-skills", "no-remote"],
   });
+  if (options.help) return printExtensionsHelp();
   const manifest = buildDistroManifest(ctx);
   const validation = validateExtensionRegistry(manifest.extensionRegistry, {
     manifest,
@@ -94,6 +96,7 @@ async function doctor(ctx, argv) {
 
 function inspect(ctx, argv) {
   const { options, positionals } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printExtensionsHelp();
   const id = positionals[0];
   if (!id) throw new CliError("extensions inspect requires an extension id", 2);
   const manifest = buildDistroManifest(ctx);
@@ -124,6 +127,7 @@ async function plan(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "strict-shared-skills", "no-remote"],
   });
+  if (options.help) return printExtensionsHelp();
   const updatePlan = await buildUpdatePlan(ctx, {
     noRemote: ctx.noRemote || options.noRemote,
     strictSharedSkills: options.strictSharedSkills,
@@ -144,7 +148,8 @@ async function plan(ctx, argv) {
 }
 
 function updateHint(_ctx, argv) {
-  const { positionals } = parseCommandOptions(argv, { bools: ["dry-run"] });
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["dry-run"] });
+  if (options.help) return printExtensionsHelp();
   const id = positionals[0] || "<id>";
   throw new CliError(
     [

package/src/commands/external.mjs

@@ -4,6 +4,10 @@ import { CliError, info, keyValue, printJson, section, warn } from "../lib/outpu
 
 export async function externalCommand(ctx, argv) {
   const [sub = "list", ...rest] = argv;
+  if (sub === "-h" || sub === "--help" || sub === "help") {
+    printExternalHelp();
+    return;
+  }
   if (sub === "list") return list(ctx, rest);
   if (sub === "install") return install(ctx, rest);
   if (sub === "update") return update(ctx, rest);
@@ -13,6 +17,7 @@ export async function externalCommand(ctx, argv) {
 
 function list(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printExternalHelp();
   const data = { schema: "pi67.external-list.v1", repos: listExternal(ctx) };
   if (ctx.json || options.json) return printJson(data);
   section("pi-67 external repos");
@@ -23,6 +28,7 @@ function list(ctx, argv) {
 
 function install(ctx, argv) {
   const { options, positionals } = parseCommandOptions(argv, { bools: ["json", "dry-run"] });
+  if (options.help) return printExternalHelp();
   const name = positionals[0];
   assertExternalName(name);
   const data = installExternal(ctx, name, { dryRun: ctx.dryRun || options.dryRun });
@@ -32,6 +38,7 @@ function install(ctx, argv) {
 
 function update(ctx, argv) {
   const { options, positionals } = parseCommandOptions(argv, { bools: ["json", "dry-run"] });
+  if (options.help) return printExternalHelp();
   const name = positionals[0];
   assertExternalName(name);
   const data = updateExternal(ctx, name, { dryRun: ctx.dryRun || options.dryRun });
@@ -41,6 +48,7 @@ function update(ctx, argv) {
 
 function doctor(ctx, argv) {
   const { options, positionals } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printExternalHelp();
   const name = positionals[0];
   assertExternalName(name);
   const data = externalStatus(ctx, name);
@@ -61,3 +69,23 @@ function assertExternalName(name) {
   if (!name) throw new CliError(`external repo name required. Available: ${Object.keys(EXTERNAL_REPOS).join(", ")}`, 2);
   if (!EXTERNAL_REPOS[name]) throw new CliError(`unknown external repo: ${name}`, 2);
 }
+
+function printExternalHelp() {
+  process.stdout.write(`pi-67 external - manage external companion repositories
+
+Usage:
+  pi-67 external list [--json]
+  pi-67 external install <browser67|design-craft> [--dry-run] [--json]
+  pi-67 external update <browser67|design-craft> [--dry-run] [--json]
+  pi-67 external doctor <browser67|design-craft> [--json]
+
+Safety:
+  External repos are explicit opt-in. Dirty external repos block update instead
+  of being overwritten.
+
+Examples:
+  pi-67 external list
+  pi-67 external install browser67 --dry-run
+  pi-67 external doctor design-craft
+`);
+}