@bigking67/pi-67 0.10.2 → 0.10.4

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [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
+  are unchanged from the latest same-operation backup.
+- Deduplicates direct PowerShell `scripts/pi67-update.ps1` dirty runtime-config
+  preservation backups under `~/.pi/pi67/backups/`.
+- Removes the legacy PowerShell updater path that wrote new
+  `~/.pi/agent-backups/pre-update-*` snapshots; runtime preservation now stays
+  under `~/.pi/pi67/backups/`.
+- Avoids writing a theme backup when `pi-67 themes set <name>` is already the
+  active theme.
+
 ## [0.10.2]
 
 - Reads `Manager latest` through the npm registry HTTP API instead of spawning

package/README.md

@@ -73,11 +73,17 @@ 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.
+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 for `git pull --ff-only`. Those
+script-level snapshots live under `~/.pi/pi67/backups/pre-update-runtime-*`.
+This keeps `--help`, blocked update plans, and the public `npx -y
+@bigking67/pi-67@latest update --repair` orchestration path free of duplicate
+manager-owned runtime backups. If 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:
 
@@ -88,15 +94,18 @@ 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
 pre-restore backup before overwriting current local config.
 
 Legacy PowerShell `~/.pi/agent-backups/pre-update-*` directories are read-only
-known-conflict snapshots from older migration paths. They are listed only with
-`--include-legacy` and are intentionally separate from restorable runtime
-backups under `~/.pi/pi67/backups/`.
+known-conflict snapshots from older migration paths; the normal updater no
+longer writes new ones. They are listed only with `--include-legacy` and are
+intentionally separate from restorable runtime backups under
+`~/.pi/pi67/backups/`.
 
 Theme changes are explicit only:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigking67/pi-67",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "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,
@@ -370,6 +434,40 @@ function runUpdateSafetySelfTests() {
     listRuntimeBackups(ctx).some((item) => item.path === lifecycle.backupDir),
     "update lifecycle backups must be listable",
   );
+  const backupCountBeforeDedupe = listRuntimeBackups(ctx).length;
+  const duplicateLifecycle = beginUpdateLifecycle({
+    agentDir,
+    repoRoot: agentDir,
+    stateDir,
+  }, {
+    operation: "test",
+  });
+  assert(duplicateLifecycle.backupSkipped, "unchanged update lifecycle snapshots must be deduplicated");
+  duplicateLifecycle.release();
+  assert(
+    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

@@ -7,6 +7,10 @@ export async function doctorCommand(ctx, argv) {
     bools: ["json", "quiet", "dry-run", "deep-mcp", "strict-shared-skills"],
     strings: ["mcp-timeout-ms"],
   });
+  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];
@@ -19,3 +23,23 @@ export async function doctorCommand(ctx, argv) {
     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.
+  --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
+`);
+}

package/src/commands/install.mjs

@@ -13,6 +13,10 @@ export async function installCommand(ctx, argv) {
     strings: ["repo", "branch"],
     bools: ["dry-run", "yes", "repair"],
   });
+  if (options.help) {
+    printInstallHelp();
+    return;
+  }
   const dryRun = ctx.dryRun || options.dryRun;
   const repo = options.repo || DEFAULT_REPO_URL;
 
@@ -46,3 +50,21 @@ export async function installCommand(ctx, argv) {
   if (!dryRun) writeState(ctx, "install");
   info("Install finished. Run `pi-67 doctor` next.");
 }
+
+function printInstallHelp() {
+  process.stdout.write(`pi-67 install - clone/install pi-67 safely
+
+Usage:
+  pi-67 install [--repo URL] [--branch NAME] [--dry-run] [--repair]
+
+Options:
+  --repo URL      Git repository URL. Defaults to the pi-67 upstream repo.
+  --branch NAME   Clone a specific branch.
+  --dry-run       Print planned writes without changing files.
+  --repair        Force owned asset repair during the installer update phase.
+
+Examples:
+  pi-67 install
+  pi-67 install --dry-run
+`);
+}