@bigking67/pi-67 0.10.3 → 0.10.4

package/src/commands/publish-check.mjs

@@ -13,6 +13,10 @@ export async function publishCheckCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "no-remote", "no-pack", "quiet", "strict", "allow-first-publish"],
   });
+  if (options.help) {
+    printPublishCheckHelp();
+    return;
+  }
   const json = ctx.json || options.json;
   const quiet = options.quiet;
   const noRemote = ctx.noRemote || options.noRemote;
@@ -246,6 +250,26 @@ function workflowCheck(file) {
   };
 }
 
+function printPublishCheckHelp() {
+  process.stdout.write(`pi-67 publish-check - verify npm publish readiness
+
+Usage:
+  pi-67 publish-check [--strict] [--json] [--no-remote] [--no-pack]
+
+Options:
+  --strict               Exit non-zero when blockers are present.
+  --json                 Emit machine-readable publish readiness JSON.
+  --no-remote            Skip npm registry/scope/auth remote probes.
+  --no-pack              Skip npm pack dry-run.
+  --quiet                Suppress human output; status is in the exit code.
+  --allow-first-publish  Explicitly allow first-publish local gate probing.
+
+Examples:
+  pi-67 publish-check
+  pi-67 publish-check --strict --no-pack
+`);
+}
+
 function npmAuthCheck(options) {
   if (options.noRemote) return skipped("remote auth check skipped");
   const result = captureCommand("npm", ["whoami"], { timeoutMs: 10000 });

package/src/commands/report.mjs

@@ -7,6 +7,10 @@ export async function reportCommand(ctx, argv) {
     bools: ["dry-run", "no-doctor"],
     strings: ["operation", "output"],
   });
+  if (options.help) {
+    printReportHelp();
+    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];
@@ -18,3 +22,21 @@ export async function reportCommand(ctx, argv) {
     dryRun: false,
   });
 }
+
+function printReportHelp() {
+  process.stdout.write(`pi-67 report - generate pi67-report.json
+
+Usage:
+  pi-67 report [--operation NAME] [--output FILE] [--no-doctor] [--dry-run]
+
+Options:
+  --operation NAME  Operation label to embed in the report.
+  --output FILE     Output path. Defaults to the distro report location.
+  --no-doctor       Skip doctor data collection where supported.
+  --dry-run         Print the script invocation without running it.
+
+Examples:
+  pi-67 report
+  pi-67 report --operation update
+`);
+}

package/src/commands/self-update.mjs

@@ -5,6 +5,10 @@ import { info, pass } from "../lib/output.mjs";
 
 export async function selfUpdateCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["dry-run"] });
+  if (options.help) {
+    printSelfUpdateHelp();
+    return;
+  }
   const pkg = readCliPackageJson();
   const dryRun = ctx.dryRun || options.dryRun;
   runCommand("npm", ["install", "-g", `${pkg.name}@latest`], { dryRun });
@@ -14,3 +18,18 @@ export async function selfUpdateCommand(ctx, argv) {
   }
   pass(`${pkg.name} manager updated. Run \`pi-67 version\` to verify the active PATH entry.`);
 }
+
+function printSelfUpdateHelp() {
+  process.stdout.write(`pi-67 self-update - update the npm manager package
+
+Usage:
+  pi-67 self-update [--dry-run]
+
+Options:
+  --dry-run  Print the npm install command without running it.
+
+Examples:
+  pi-67 self-update --dry-run
+  pi-67 self-update
+`);
+}

package/src/commands/skills.mjs

@@ -1,10 +1,16 @@
 import { parseCommandOptions } from "../lib/args.mjs";
-import { inventorySkills, syncSkills } from "../lib/skill-policy.mjs";
-import { CliError, info, keyValue, printJson, section, warn } from "../lib/output.mjs";
+import { diffSkill, inventorySkills, planSkills, syncSkills } from "../lib/skill-policy.mjs";
+import { CliError, info, keyValue, pass, printJson, section, warn } from "../lib/output.mjs";
 
 export async function skillsCommand(ctx, argv) {
   const [sub = "inventory", ...rest] = argv;
+  if (sub === "-h" || sub === "--help" || sub === "help") {
+    printSkillsHelp();
+    return;
+  }
   if (sub === "inventory") return inventory(ctx, rest);
+  if (sub === "plan") return plan(ctx, rest);
+  if (sub === "diff") return diff(ctx, rest);
   if (sub === "sync") return sync(ctx, rest);
   if (sub === "migrate") return migrate(ctx, rest);
   throw new CliError(`unknown skills command: ${sub}`, 2);
@@ -12,6 +18,7 @@ export async function skillsCommand(ctx, argv) {
 
 function inventory(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printSkillsHelp();
   const data = inventorySkills(ctx);
   if (ctx.json || options.json) return printJson(data);
   section("pi-67 shared skills inventory");
@@ -26,9 +33,56 @@ function inventory(ctx, argv) {
   }
 }
 
+function plan(ctx, argv) {
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printSkillsHelp();
+  const data = planSkills(ctx, { names: positionals });
+  if (ctx.json || options.json) return printJson(data);
+  section("pi-67 shared skills plan");
+  keyValue("Source", data.sourceRoot);
+  keyValue("Target", data.skillsDir);
+  keyValue("Selected", data.selected.length === 0 ? "all changed skills" : data.selected.join(", "));
+  keyValue("Missing", data.actions.filter((item) => item.action === "copy-missing").length);
+  keyValue("Conflicts", data.actions.filter((item) => item.action === "preserve-conflict").length);
+  for (const action of data.actions) {
+    const command = action.conflict
+      ? `inspect: pi-67 skills diff ${action.name}; explicit sync: pi-67 skills sync ${action.name} --dry-run`
+      : `sync: pi-67 skills sync ${action.name}`;
+    info(`${action.name}: ${action.action}; ${command}`);
+  }
+  if (data.actions.length === 0) pass("no shared skill action is required");
+}
+
+function diff(ctx, argv) {
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printSkillsHelp();
+  const name = positionals[0];
+  if (!name) throw new CliError("skills diff requires a skill name", 2);
+  const data = diffSkill(ctx, name);
+  if (ctx.json || options.json) return printJson(data);
+  section(`pi-67 shared skill diff: ${name}`);
+  keyValue("Source", data.source);
+  keyValue("Target", data.target);
+  keyValue("Target exists", data.targetExists ? "yes" : "no");
+  keyValue("Identical", data.identical ? "yes" : "no");
+  keyValue("Added files", data.diff.added.length);
+  keyValue("Removed files", data.diff.removed.length);
+  keyValue("Modified files", data.diff.modified.length);
+  for (const file of data.diff.added.slice(0, 20)) info(`added in source: ${file}`);
+  for (const file of data.diff.removed.slice(0, 20)) warn(`missing from source: ${file}`);
+  for (const file of data.diff.modified.slice(0, 20)) info(`modified: ${file}`);
+  const omitted = data.diff.added.length + data.diff.removed.length + data.diff.modified.length - 60;
+  if (omitted > 0) warn(`${omitted} additional file diffs omitted; rerun with --json for full metadata`);
+}
+
 function sync(ctx, argv) {
-  const { options } = parseCommandOptions(argv, { bools: ["json", "dry-run"] });
-  const data = syncSkills(ctx, { dryRun: ctx.dryRun || options.dryRun });
+  const { options, positionals } = parseCommandOptions(argv, { bools: ["json", "dry-run", "yes"] });
+  if (options.help) return printSkillsHelp();
+  const data = syncSkills(ctx, {
+    dryRun: ctx.dryRun || options.dryRun,
+    names: positionals,
+    yes: ctx.yes || options.yes,
+  });
   if (ctx.json || options.json) return printJson(data);
   section("pi-67 shared skills sync");
   for (const action of data.actions) {
@@ -39,6 +93,7 @@ function sync(ctx, argv) {
 
 function migrate(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["dry-run", "json"] });
+  if (options.help) return printSkillsHelp();
   const data = syncSkills(ctx, { dryRun: true });
   data.schema = "pi67.skills-migrate-preview.v1";
   if (ctx.json || options.json) return printJson(data);
@@ -47,3 +102,27 @@ function migrate(ctx, argv) {
   keyValue("Missing", data.summary.missing);
   keyValue("Conflicts", data.summary.conflicts);
 }
+
+function printSkillsHelp() {
+  process.stdout.write(`pi-67 skills - inspect and safely sync shared skills
+
+Usage:
+  pi-67 skills inventory [--json]
+  pi-67 skills plan [skill...] [--json]
+  pi-67 skills diff <skill> [--json]
+  pi-67 skills sync [skill...] [--dry-run] [--yes] [--json]
+  pi-67 skills migrate [--dry-run] [--json]
+
+Safety:
+  Missing skills are copied by default. Existing different global skills are
+  preserved unless you name the skill explicitly and pass --yes. Bulk conflict
+  overwrite is intentionally blocked.
+
+Examples:
+  pi-67 skills inventory
+  pi-67 skills plan
+  pi-67 skills diff lark-doc
+  pi-67 skills sync lark-doc --dry-run
+  pi-67 skills sync lark-doc --yes
+`);
+}

package/src/commands/smoke.mjs

@@ -6,6 +6,10 @@ export async function smokeCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["ci", "quick", "dry-run"],
   });
+  if (options.help) {
+    printSmokeHelp();
+    return;
+  }
   const args = [];
   if (isWindows()) {
     if (options.ci || options.quick) args.push("-Ci");
@@ -16,3 +20,20 @@ export async function smokeCommand(ctx, argv) {
     dryRun: ctx.dryRun || options.dryRun,
   });
 }
+
+function printSmokeHelp() {
+  process.stdout.write(`pi-67 smoke - run repository smoke gates
+
+Usage:
+  pi-67 smoke [--ci|--quick] [--dry-run]
+
+Options:
+  --ci       Run the CI smoke profile.
+  --quick    Alias for the CI smoke profile.
+  --dry-run  Print the script invocation without running it.
+
+Examples:
+  pi-67 smoke
+  pi-67 smoke --ci
+`);
+}

package/src/commands/status.mjs

@@ -6,6 +6,10 @@ export async function statusCommand(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     bools: ["json", "no-remote"],
   });
+  if (options.help) {
+    printStatusHelp();
+    return;
+  }
   const plan = await buildUpdatePlan(ctx, { noRemote: ctx.noRemote || options.noRemote });
   if (ctx.json || options.json) {
     printJson(plan);
@@ -19,3 +23,19 @@ export async function statusCommand(ctx, argv) {
   keyValue("Theme", plan.settings.theme || "unset");
   keyValue("Shared skills", `${plan.skills.identical} ok, ${plan.skills.missing} missing, ${plan.skills.conflicts} conflicts`);
 }
+
+function printStatusHelp() {
+  process.stdout.write(`pi-67 status - read-only status summary
+
+Usage:
+  pi-67 status [--json] [--no-remote]
+
+Options:
+  --json       Emit the full update-plan status JSON.
+  --no-remote  Skip remote git/npm registry checks.
+
+Examples:
+  pi-67 status
+  pi-67 status --json --no-remote
+`);
+}

package/src/commands/themes.mjs

@@ -7,6 +7,10 @@ import { CliError, keyValue, printJson, section, pass, fail, info } from "../lib
 
 export async function themesCommand(ctx, argv) {
   const [sub = "current", ...rest] = argv;
+  if (sub === "-h" || sub === "--help" || sub === "help") {
+    printThemesHelp();
+    return;
+  }
   if (sub === "current") return current(ctx, rest);
   if (sub === "list") return list(ctx, rest);
   if (sub === "doctor") return doctor(ctx, rest);
@@ -16,6 +20,7 @@ export async function themesCommand(ctx, argv) {
 
 function current(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printThemesHelp();
   const value = currentTheme(ctx);
   const data = {
     schema: "pi67.theme-current.v1",
@@ -29,6 +34,7 @@ function current(ctx, argv) {
 
 function list(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printThemesHelp();
   const themes = listThemes(ctx);
   if (ctx.json || options.json) return printJson({ schema: "pi67.theme-list.v1", themes });
   section("Available themes");
@@ -37,6 +43,7 @@ function list(ctx, argv) {
 
 function doctor(ctx, argv) {
   const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) return printThemesHelp();
   const theme = currentTheme(ctx);
   const installed = theme ? hasTheme(ctx, theme) : false;
   const data = { schema: "pi67.theme-doctor.v1", theme, installed };
@@ -48,6 +55,7 @@ function doctor(ctx, argv) {
 
 function setTheme(ctx, argv) {
   const { options, positionals } = parseCommandOptions(argv, { bools: ["force", "dry-run"] });
+  if (options.help) return printThemesHelp();
   const name = positionals[0];
   if (!name) throw new CliError("themes set requires a theme name", 2);
   if (!options.force && !hasTheme(ctx, name)) {
@@ -71,3 +79,24 @@ function setTheme(ctx, argv) {
   pass(`theme set: ${previous || "unset"} -> ${name}`);
   info(`Preserved runtime backup: ${backupDir}`);
 }
+
+function printThemesHelp() {
+  process.stdout.write(`pi-67 themes - inspect and explicitly set themes
+
+Usage:
+  pi-67 themes current [--json]
+  pi-67 themes list [--json]
+  pi-67 themes doctor [--json]
+  pi-67 themes set <name> [--force] [--dry-run]
+
+Safety:
+  Updates install theme assets but never change the selected theme. Only
+  \`pi-67 themes set <name>\` changes settings.json, and it writes a runtime
+  backup first unless --dry-run is used.
+
+Examples:
+  pi-67 themes current
+  pi-67 themes list
+  pi-67 themes set gruvbox-dark --dry-run
+`);
+}

package/src/commands/update.mjs

@@ -1,6 +1,6 @@
 import { parseCommandOptions } from "../lib/args.mjs";
 import { buildUpdatePlan } from "../lib/update-plan.mjs";
-import { printJson, section, keyValue, pass, warn, info } from "../lib/output.mjs";
+import { CliError, printJson, section, keyValue, pass, warn, info } from "../lib/output.mjs";
 import { runDistroScript } from "../lib/distro-scripts.mjs";
 import { isWindows } from "../lib/platform.mjs";
 import { runCommand } from "../lib/shell-runner.mjs";
@@ -24,6 +24,10 @@ export async function updateCommand(ctx, argv) {
       "strict-shared-skills",
     ],
   });
+  if (options.help) {
+    printUpdateHelp();
+    return;
+  }
   const dryRun = ctx.dryRun || options.dryRun;
   const json = ctx.json || options.json;
   if (options.check) {
@@ -43,10 +47,12 @@ export async function updateCommand(ctx, argv) {
     noRemote: ctx.noRemote || options.noRemote,
     strictSharedSkills: options.strictSharedSkills,
   });
+  assertPlanCanProceed(plan, { allowDirty: options.allowDirty });
   const lifecycle = beginUpdateLifecycle(ctx, {
     operation: options.repair ? "repair" : "update",
     dryRun,
     plan,
+    backupRuntime: false,
   });
   if (!dryRun && lifecycle.backedUp.length > 0) {
     info(`Preserved runtime backup: ${lifecycle.backupDir}`);
@@ -86,6 +92,12 @@ function buildBashUpdateArgs(ctx, options, dryRun) {
   return args;
 }
 
+function assertPlanCanProceed(plan, options = {}) {
+  if (options.allowDirty || !plan.blocked?.length) return;
+  for (const item of plan.blocked) warn(`${item.id}: ${item.reason}`);
+  throw new CliError("pi-67 update is blocked; run `pi-67 update --check` for the full plan or rerun with --allow-dirty if you accept the risk", 2);
+}
+
 function buildWindowsUpdateArgs(ctx, options, dryRun) {
   const args = ["-AgentDir", ctx.agentDir, "-RepoRoot", ctx.repoRoot, "-SkillsDir", ctx.skillsDir];
   if (dryRun) args.push("-DryRun");
@@ -138,3 +150,37 @@ function printPlan(plan) {
   for (const item of plan.recommendations) info(item);
   if (!plan.git?.dirty) pass("update check completed without local dirty blocker");
 }
+
+function printUpdateHelp() {
+  process.stdout.write(`pi-67 update - update pi-67 safely
+
+Usage:
+  pi-67 update [--repair] [--dry-run] [--no-remote] [--no-npm]
+  pi-67 update --check [--json] [--no-remote]
+
+Options:
+  --check                 Print the read-only update plan and exit.
+  --repair                Re-run owned asset/config repair during update.
+  --dry-run               Print planned script actions without changing files.
+  --no-remote             Skip remote git/npm registry checks where supported.
+  --no-npm                Skip npm package sync in the distro updater.
+  --allow-dirty           Let the script-level updater handle non-runtime dirty files.
+  --strict-shared-skills  Treat differing shared skills as blocking.
+  --include-pi            Also run upstream \`pi update --all\` when paired with --yes.
+  --include-external      Report explicit external repo update commands.
+  --all                   Alias for --include-pi --include-external.
+  --yes                   Confirm explicit opt-in actions.
+  --json                  Emit JSON for --check.
+
+Safety:
+  Runtime config backup/restore is owned by the platform updater script when
+  preserved runtime files are dirty. The npm manager owns the update lock and
+  never creates a runtime backup for --help or a blocked update plan.
+
+Examples:
+  pi-67 update --check
+  pi-67 update --check --json --no-remote
+  pi-67 update
+  pi-67 update --repair
+`);
+}

package/src/commands/version.mjs

@@ -4,10 +4,16 @@ import { currentTheme } from "../lib/theme-policy.mjs";
 import { keyValue, printJson } from "../lib/output.mjs";
 import { platformName } from "../lib/platform.mjs";
 import { readCliPackageJson, readTextIfExists } from "../lib/paths.mjs";
+import { parseCommandOptions } from "../lib/args.mjs";
 import path from "node:path";
 
 export async function versionCommand(ctx, argv) {
-  const json = ctx.json || argv.includes("--json");
+  const { options } = parseCommandOptions(argv, { bools: ["json"] });
+  if (options.help) {
+    printVersionHelp();
+    return;
+  }
+  const json = ctx.json || options.json;
   const pkg = readCliPackageJson();
   const git = gitStatus(ctx.repoRoot);
   const pi = captureCommand("pi", ["--version"]);
@@ -49,3 +55,18 @@ export async function versionCommand(ctx, argv) {
   keyValue("agentDir", data.paths.agentDir);
   keyValue("theme", data.theme || "unset");
 }
+
+function printVersionHelp() {
+  process.stdout.write(`pi-67 version - print manager and distro versions
+
+Usage:
+  pi-67 version [--json]
+
+Options:
+  --json  Emit machine-readable version metadata.
+
+Examples:
+  pi-67 version
+  pi-67 version --json
+`);
+}

package/src/commands/xtalpi.mjs

@@ -6,17 +6,25 @@ import { CliError } from "../lib/output.mjs";
 
 export async function xtalpiCommand(ctx, argv) {
   const [sub = "health", ...rest] = argv;
+  if (sub === "-h" || sub === "--help" || sub === "help") {
+    printXtalpiHelp();
+    return;
+  }
   if (sub === "health") return health(ctx, rest);
   if (sub === "smoke") return smoke(ctx, rest);
   if (sub === "capability") return capability(ctx, rest);
+  if (sub === "trend") return trend(ctx, rest);
+  if (sub === "drift") return drift(ctx, rest);
+  if (sub === "stress") return stress(ctx, rest);
   throw new CliError(`unknown xtalpi command: ${sub}`, 2);
 }
 
 function health(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     strings: ["model", "provider", "timeout-ms", "attempts"],
-    bools: ["dry-run"],
+    bools: ["dry-run", "json"],
   });
+  if (options.help) return printXtalpiHelp();
   const args = [scriptPath(ctx, "pi67-xtalpi-provider-health.mjs"), "--agent-dir", ctx.agentDir];
   if (options.provider) args.push("--provider", options.provider);
   if (options.model) args.push("--model", options.model);
@@ -30,6 +38,7 @@ function smoke(ctx, argv) {
     strings: ["case", "profile"],
     bools: ["quick", "extension-low-risk", "extension-expanded", "self-test", "dry-run"],
   });
+  if (options.help) return printXtalpiHelp();
   if (isWindows()) {
     const pwsh = findPowerShell();
     if (!pwsh) throw new CliError("PowerShell executable not found");
@@ -50,8 +59,9 @@ function smoke(ctx, argv) {
 function capability(ctx, argv) {
   const { options } = parseCommandOptions(argv, {
     strings: ["model", "provider", "timeout-ms"],
-    bools: ["dry-run", "self-test"],
+    bools: ["dry-run", "self-test", "json"],
   });
+  if (options.help) return printXtalpiHelp();
   const args = [scriptPath(ctx, "pi67-xtalpi-provider-capability-probe.mjs"), "--agent-dir", ctx.agentDir];
   if (options.selfTest) args.push("--self-test");
   if (options.provider) args.push("--provider", options.provider);
@@ -60,6 +70,46 @@ function capability(ctx, argv) {
   runCommand("node", args, { cwd: ctx.repoRoot, dryRun: ctx.dryRun || options.dryRun });
 }
 
+function trend(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    strings: ["limit", "profile", "out-dir"],
+    bools: ["json", "dry-run"],
+  });
+  if (options.help) return printXtalpiHelp();
+  const limit = options.limit || "3";
+  const args = [scriptPath(ctx, "pi67-xtalpi-pi-tools-debug-summary.sh"), "--trend-gate", limit];
+  if (options.profile) args.push("--profile", options.profile);
+  else args.push("--profile", "full-suite-strict");
+  if (ctx.json || options.json) args.push("--json");
+  if (options.outDir) args.push(options.outDir);
+  runCommand("bash", args, { cwd: ctx.repoRoot, dryRun: ctx.dryRun || options.dryRun });
+}
+
+function drift(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    strings: ["limit", "run-kind", "out-dir"],
+    bools: ["json", "dry-run"],
+  });
+  if (options.help) return printXtalpiHelp();
+  const limit = options.limit || "10";
+  const args = [scriptPath(ctx, "pi67-xtalpi-pi-tools-debug-summary.sh"), "--drift", limit];
+  args.push("--run-kind", options.runKind || "full-suite");
+  if (ctx.json || options.json) args.push("--json");
+  if (options.outDir) args.push(options.outDir);
+  runCommand("bash", args, { cwd: ctx.repoRoot, dryRun: ctx.dryRun || options.dryRun });
+}
+
+function stress(ctx, argv) {
+  const { options } = parseCommandOptions(argv, {
+    strings: ["case", "profile"],
+    bools: ["until-done", "dry-run"],
+  });
+  if (options.help) return printXtalpiHelp();
+  const smokeCase = options.untilDone ? "until-done-continuation" : options.case;
+  if (smokeCase) return smoke(ctx, ["--case", smokeCase, ...(options.dryRun ? ["--dry-run"] : [])]);
+  return smoke(ctx, ["--profile", options.profile || "full-suite", ...(options.dryRun ? ["--dry-run"] : [])]);
+}
+
 function profileFromOptions(options) {
   if (options.profile) return options.profile;
   if (options.extensionLowRisk) return "extension-low-risk";
@@ -67,3 +117,32 @@ function profileFromOptions(options) {
   if (options.quick) return "quick";
   return "quick";
 }
+
+function printXtalpiHelp() {
+  process.stdout.write(`pi-67 xtalpi - xtalpi health, smoke, and artifact helpers
+
+Usage:
+  pi-67 xtalpi health [--provider ID] [--model NAME] [--timeout-ms N] [--attempts N]
+  pi-67 xtalpi smoke [--quick|--extension-low-risk|--extension-expanded|--profile NAME]
+  pi-67 xtalpi smoke --case NAME
+  pi-67 xtalpi capability [--self-test] [--provider ID] [--model NAME]
+  pi-67 xtalpi trend [--limit N] [--profile NAME] [--json] [--out-dir DIR]
+  pi-67 xtalpi drift [--limit N] [--run-kind LIST] [--json] [--out-dir DIR]
+  pi-67 xtalpi stress --until-done
+
+Notes:
+  xtalpi-pi-tools treats xtalpi as plain chat-completions transport. Pi local
+  code owns tool protocol parsing, validation, repair, retry classification,
+  tool execution, and smoke gates.
+  xtalpi drift defaults to --run-kind full-suite so targeted one-off smoke
+  artifacts do not create expected case-set drift noise.
+
+Examples:
+  pi-67 xtalpi health
+  pi-67 xtalpi smoke --quick
+  pi-67 xtalpi smoke --case until-done-continuation
+  pi-67 xtalpi trend --json
+  pi-67 xtalpi drift --json
+  pi-67 xtalpi stress --until-done
+`);
+}

package/src/lib/args.mjs

@@ -6,14 +6,20 @@ const BOOL_GLOBALS = new Set(["json", "dry-run", "yes", "help", "no-remote"]);
 export function splitGlobalArgs(argv) {
   const globals = {};
   const rest = [];
+  let commandSeen = false;
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
+    if (commandSeen) {
+      rest.push(arg);
+      continue;
+    }
     if (arg === "-h") {
       globals.help = true;
       continue;
     }
     if (!arg.startsWith("--")) {
       rest.push(arg);
+      commandSeen = true;
       continue;
     }
 
@@ -48,7 +54,7 @@ export function parseCommandOptions(argv, spec = {}) {
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
-    if (arg === "-h") {
+    if (arg === "-h" || arg === "--help") {
       options.help = true;
       continue;
     }