agent-skillboard 0.1.1 → 0.2.1

package/src/cli.mjs

@@ -1,11 +1,15 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, isAbsolute } from "node:path";
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 import {
   activateSkill,
   addHarness,
   addSkill,
+  addSkillVariant,
   addWorkflow,
+  approveSkillVariant,
   auditSources,
   blockSkill,
   canUseSkill,
@@ -13,6 +17,7 @@ import {
   detectInstallOutput,
   doctorProject,
   explainSkill,
+  forkSkillVariant,
   importSource,
   installGuardHook,
   impactDisable,
@@ -26,6 +31,7 @@ import {
   preferSkill,
   quarantineSkill,
   removeSkill,
+  resetSkillVariant,
   reconcileWorkspace,
   refreshAgentInventory,
   refreshSourcePins,
@@ -38,7 +44,9 @@ import {
   rolloutPlan,
   rolloutReport,
   rolloutRollback,
+  routeSkill,
   verifySources,
+  variantLifecycleStatus,
   writeLockfile
 } from "./index.mjs";
 // SIZE_OK: src/cli.mjs is pre-existing command-router debt; brief behavior delegates to src/brief-cli.mjs and hook planning delegates through src/hook-plan.mjs until a broader router split.
@@ -49,21 +57,65 @@ import { planGuardHookInstall } from "./control.mjs";
 import { writeCheckedConfig } from "./control/config-write.mjs";
 import { runInitCommand, runUninstallCommand } from "./lifecycle-cli.mjs";
 
+const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
 const APPLY_ACTION_VALUE_OPTIONS = new Set(["workflow", "dir", "config", "skills", "out", "skillboard-bin"]);
-
-export async function main(argv, stdout, stderr) {
+const COMMAND_USAGE = new Map([
+  ["uninstall", ["uninstall [--dir <path>] [--dry-run] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]"]],
+  [
+    "inventory",
+    [
+      "inventory refresh [--dir <path>] [--config <path>] [--scan-root <dir>[,<dir>]] [--dry-run] [--json]",
+      "inventory detect --unit <id> --config <path> [--install-output <path>] [--config-file a,b] [--source <value>] [--kind <kind>] [--scope <scope>] [--dry-run] [--json]"
+    ]
+  ],
+  ["sources", ["sources refresh [--dir <path>] [--config <path>] [--unit <id>[,<id>]] [--cache-dir <dir>] [--dry-run] [--json]"]],
+  ["import", ["import --profile <id-or-path> --source-root <dir> [--profile-dirs a,b] [--out <path>]", "import --profile <id-or-path> --source-root <dir> --config <path> --merge [--replace] [--dry-run]"]],
+  ["scan", ["scan --config <path>"]],
+  ["check", ["check --config <path> --skills <dir>"]],
+  ["list", ["list [skills|workflows|harnesses|install-units] --config <path> --skills <dir> [--workflow <name>] [--json]"]],
+  ["explain", ["explain <skill-id> --config <path> --skills <dir> [--json]"]],
+  ["can-use", ["can-use <skill-id> --workflow <name> --config <path> --skills <dir> [--json]"]],
+  ["audit", ["audit sources --config <path> --skills <dir> [--verify] [--json]"]],
+  ["rollout", ["rollout [audit|plan|apply|rollback|report] [--dir <path>] [--config <path>] [--skills <dir>] [--transaction <id>] [--json]"]],
+  ["hook", ["hook install --workflow <name> --config <path> --skills <dir> [--out <path>] [--skillboard-bin <path>] [--dry-run] [--json]"]],
+  ["lock", ["lock write --config <path> --skills <dir> [--out <path>] [--replace] [--allow-unverified] [--json]"]],
+  ["review", ["review install-unit <unit-id> [--trust-level trusted|reviewed|unreviewed|blocked] --config <path> --skills <dir> [--dry-run] [--json]"]],
+  ["add", ["add skill <skill-id> --path <relative-skill-path> --config <path> --skills <dir> [--status <status>] [--invocation <mode>] [--exposure <exposure>] [--category <name>] [--workflow <name>] [--dry-run] [--json]", "add workflow <workflow-name> --harness <harness-name> --config <path> --skills <dir> [--skill <id>[,<id>]] [--harness-status <status>] [--require-existing-harness] [--dry-run] [--json]", "add harness <harness-name> --config <path> --skills <dir> [--status <status>] [--command <cmd>[,<cmd>]] [--dry-run] [--json]"]],
+  ["variant", ["variant add <variant-id> --from <base-id> --capability <name> --workflow <name> --config <path> --skills <dir> [--path <relative-skill-path>] [--mode manual-only|router-only|workflow-auto] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]", "variant fork <variant-id> --from <base-id> --capability <name> --workflow <name> --path <relative-skill-path> --config <path> --skills <dir> [--adapted-for <label>] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]", "variant status <variant-id> --config <path> --skills <dir> [--json]", "variant approve <variant-id> --config <path> --skills <dir> [--mode manual-only|router-only|workflow-auto] [--dry-run] [--json]", "variant reset <variant-id> --to-base|--to-approved --config <path> --skills <dir> [--yes] [--dry-run] [--mode manual-only|router-only|workflow-auto] [--json]"]],
+  ["activate", ["activate <skill-id> --workflow <name> [--mode manual-only|router-only|workflow-auto] --config <path> --skills <dir> [--dry-run] [--json]"]],
+  ["block", ["block <skill-id> --workflow <name> --config <path> --skills <dir> [--dry-run] [--json]"]],
+  ["quarantine", ["quarantine <skill-id> --config <path> --skills <dir> [--dry-run] [--json]"]],
+  ["prefer", ["prefer <skill-id> --workflow <name> --capability <name> --config <path> --skills <dir> [--dry-run] [--json]"]],
+  ["remove", ["remove skill <skill-id> --config <path> --skills <dir> [--force] [--dry-run] [--json]"]],
+  ["dashboard", ["dashboard --config <path> --skills <dir> [--out <path>]"]],
+  ["reconcile", ["reconcile --config <path> --skills <dir> [--actual-harnesses a,b] [--out <path>]"]],
+  ["impact", ["impact disable <skill-id> --config <path> --skills <dir> [--out <path>] [--json]"]]
+]);
+
+if (process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  process.exitCode = await main(process.argv.slice(2), process.stdout, process.stderr);
+}
+
+export async function main(argv, stdout, stderr) {
   try {
     return await run(argv, stdout, stderr);
   } catch (error) {
     stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
-    return 1;
+    return Number.isInteger(error?.exitCode) ? error.exitCode : 1;
   }
 }
 
-async function run(argv, stdout, stderr) {
-  const command = argv[0] ?? "help";
-  const options = parseOptions(argv.slice(1));
-  switch (command) {
+async function run(argv, stdout, stderr) {
+  const command = argv[0] ?? "help";
+  const commandArgs = argv.slice(1);
+  const options = parseOptions(commandArgs);
+  const help = selectedHelpText(command, commandArgs, options);
+  if (help !== null) {
+    stdout.write(help);
+    return 0;
+  }
+  switch (command) {
     case "init":
       return await runInitCommand(options, stdout);
     case "uninstall":
@@ -92,6 +144,8 @@ async function run(argv, stdout, stderr) {
       return await list(argv.slice(1), options, stdout);
     case "explain":
       return await explain(argv.slice(1), options, stdout);
+    case "route":
+      return await route(argv.slice(1), options, stdout);
     case "can-use":
       return await canUse(argv.slice(1), options, stdout);
     case "guard":
@@ -110,6 +164,8 @@ async function run(argv, stdout, stderr) {
       return await activate(argv.slice(1), options, stdout);
     case "add":
       return await add(argv.slice(1), options, stdout);
+    case "variant":
+      return await variant(argv.slice(1), options, stdout);
     case "block":
       return await block(argv.slice(1), options, stdout);
     case "quarantine":
@@ -124,17 +180,34 @@ async function run(argv, stdout, stderr) {
       return await reconcile(options, stdout);
     case "impact":
       return await impact(argv.slice(1), options, stdout);
-    case "help":
-    case "--help":
-    case "-h":
-      stdout.write(helpText());
-      return 0;
-    default:
-      stderr.write(`Unknown command: ${command}\n`);
-      stdout.write(helpText());
-      return 1;
-  }
-}
+    case "help":
+    case "--help":
+    case "-h":
+      stdout.write(helpText());
+      return 0;
+    case "--version":
+    case "-v":
+      stdout.write(`${VERSION}\n`);
+      return 0;
+    default:
+      stderr.write(`Unknown command: ${command}\nRun skillboard help for usage.\n`);
+      return 1;
+  }
+}
+
+function selectedHelpText(command, args, options) {
+  if (command === "help") {
+    const topic = positionalArgs(args)[0];
+    return topic === undefined ? helpText() : commandHelpText(topic) ?? helpText();
+  }
+  if (command === "--help" || command === "-h") {
+    return helpText();
+  }
+  if (options.get("help") === "true" || args.includes("-h")) {
+    return commandHelpText(command);
+  }
+  return null;
+}
 
 async function importProfile(options, stdout) {
   const profileRef = options.get("profile");
@@ -326,6 +399,25 @@ async function explain(argv, options, stdout) {
   return 0;
 }
 
+async function route(argv, options, stdout) {
+  const intent = positionalArgs(argv).join(" ").trim();
+  const workflow = options.get("workflow");
+  if (intent.length === 0 || workflow === undefined) {
+    throw new Error("Usage: skillboard route <intent> --workflow <name>");
+  }
+  const config = configPath(options);
+  const skills = skillsRoot(options);
+  const workspace = await loadWorkspace({ configPath: config, skillsRoot: skills });
+  const result = routeSkill(workspace, {
+    intent,
+    workflow,
+    configPath: config,
+    skillsRoot: skills
+  });
+  writeOutput(stdout, result, options, () => renderRoute(result));
+  return 0;
+}
+
 async function canUse(argv, options, stdout) {
   const skillId = positionalArgs(argv)[0];
   const workflow = options.get("workflow");
@@ -578,6 +670,219 @@ async function addHarnessCommand(args, options, stdout) {
   return 0;
 }
 
+async function variant(argv, options, stdout) {
+  try {
+    return await runVariant(argv, options, stdout);
+  } catch (error) {
+    const payload = variantErrorPayload(error);
+    if (options.get("json") === "true") {
+      stdout.write(`${JSON.stringify({ ok: false, error: payload.error }, null, 2)}\n`);
+      return payload.exitCode;
+    }
+    throw Object.assign(new Error(payload.error.message), { exitCode: payload.exitCode });
+  }
+}
+
+async function runVariant(argv, options, stdout) {
+  const args = positionalArgs(argv);
+  const subcommand = args[0];
+  if (subcommand === "add") {
+    return await variantAddCommand(args, options, stdout);
+  }
+  if (subcommand === "fork") {
+    return await variantForkCommand(args, options, stdout);
+  }
+  if (subcommand === "status") {
+    return await variantStatusCommand(args, options, stdout);
+  }
+  if (subcommand === "approve") {
+    return await variantApproveCommand(args, options, stdout);
+  }
+  if (subcommand === "reset") {
+    return await variantResetCommand(args, options, stdout);
+  }
+  throw new VariantCliError("unknown_variant_subcommand", `Unknown variant subcommand: ${subcommand ?? "<missing>"}`, 2);
+}
+
+async function variantAddCommand(args, options, stdout) {
+  const variantId = args[1];
+  const baseId = options.get("from");
+  const capability = options.get("capability");
+  const workflow = options.get("workflow");
+  if (variantId === undefined || baseId === undefined || capability === undefined || workflow === undefined) {
+    throw new VariantCliError("usage_error", variantAddUsage(), 2);
+  }
+  const result = await addSkillVariant({
+    variantId,
+    baseId,
+    capability,
+    workflow,
+    path: options.get("path"),
+    mode: options.get("mode"),
+    category: options.get("category"),
+    ownerInstallUnit: options.get("owner-install-unit"),
+    configPath: configPath(options),
+    skillsRoot: skillsRoot(options),
+    dryRun: options.get("dry-run") === "true"
+  });
+  writeControlResult(stdout, result, options);
+  return 0;
+}
+
+async function variantForkCommand(args, options, stdout) {
+  const variantId = args[1];
+  const baseId = options.get("from");
+  const capability = options.get("capability");
+  const workflow = options.get("workflow");
+  if (variantId === undefined || baseId === undefined || capability === undefined || workflow === undefined || options.get("path") === undefined) {
+    throw new VariantCliError("usage_error", variantForkUsage(), 2);
+  }
+  const result = await forkSkillVariant({
+    variantId,
+    baseId,
+    capability,
+    workflow,
+    path: options.get("path"),
+    adaptedFor: options.get("adapted-for"),
+    category: options.get("category"),
+    ownerInstallUnit: options.get("owner-install-unit"),
+    configPath: configPath(options),
+    skillsRoot: skillsRoot(options),
+    dryRun: options.get("dry-run") === "true"
+  });
+  writeLifecycleResult(stdout, result, options);
+  return 0;
+}
+
+async function variantStatusCommand(args, options, stdout) {
+  const variantId = args[1];
+  if (variantId === undefined) {
+    throw new VariantCliError("usage_error", "Usage: skillboard variant status <variant-id> --config <path> --skills <dir> [--json]", 2);
+  }
+  const result = await variantLifecycleStatus({ variantId, configPath: configPath(options), skillsRoot: skillsRoot(options) });
+  writeOutput(stdout, result, options, () => renderVariantStatus(result));
+  return 0;
+}
+
+async function variantApproveCommand(args, options, stdout) {
+  const variantId = args[1];
+  if (variantId === undefined) {
+    throw new VariantCliError("usage_error", "Usage: skillboard variant approve <variant-id> --config <path> --skills <dir> [--mode manual-only|router-only|workflow-auto] [--dry-run] [--json]", 2);
+  }
+  const result = await approveSkillVariant({
+    variantId,
+    mode: options.get("mode"),
+    configPath: configPath(options),
+    skillsRoot: skillsRoot(options),
+    dryRun: options.get("dry-run") === "true"
+  });
+  writeLifecycleResult(stdout, result, options);
+  return 0;
+}
+
+async function variantResetCommand(args, options, stdout) {
+  const variantId = args[1];
+  if (variantId === undefined) {
+    throw new VariantCliError("usage_error", "Usage: skillboard variant reset <variant-id> --to-base|--to-approved --config <path> --skills <dir> [--yes] [--dry-run] [--mode manual-only|router-only|workflow-auto] [--json]", 2);
+  }
+  const result = await resetSkillVariant({
+    variantId,
+    toBase: options.get("to-base") === "true",
+    toApproved: options.get("to-approved") === "true",
+    mode: options.get("mode"),
+    yes: options.get("yes") === "true",
+    dryRun: options.get("dry-run") === "true",
+    configPath: configPath(options),
+    skillsRoot: skillsRoot(options)
+  });
+  writeLifecycleResult(stdout, result, options);
+  return 0;
+}
+
+function variantAddUsage() {
+  return "Usage: skillboard variant add <variant-id> --from <base-id> --capability <name> --workflow <name> --config <path> --skills <dir> [--path <relative-skill-path>] [--mode manual-only|router-only|workflow-auto] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]";
+}
+
+function variantForkUsage() {
+  return "Usage: skillboard variant fork <variant-id> --from <base-id> --capability <name> --workflow <name> --path <relative-skill-path> --config <path> --skills <dir> [--adapted-for <label>] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]";
+}
+
+class VariantCliError extends Error {
+  constructor(code, message, exitCode) {
+    super(message);
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+}
+
+function variantErrorPayload(error) {
+  if (error instanceof VariantCliError) {
+    return { exitCode: error.exitCode, error: { code: error.code, message: error.message } };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  if (
+    message.startsWith("Usage:")
+    || message.includes("requires exactly one of --to-base or --to-approved")
+    || message.includes("requires --mode manual-only")
+  ) {
+    return { exitCode: 2, error: { code: "usage_error", message } };
+  }
+  if (message.includes("requires --yes")) {
+    return { exitCode: 1, error: { code: "confirmation_required", message } };
+  }
+  if (message.toLowerCase().includes("snapshot")) {
+    return { exitCode: 1, error: { code: "snapshot_error", message } };
+  }
+  if (message.toLowerCase().includes("symlink") || message.toLowerCase().includes("path")) {
+    return { exitCode: 1, error: { code: "path_error", message } };
+  }
+  return { exitCode: 1, error: { code: "lifecycle_error", message } };
+}
+
+function writeLifecycleResult(stdout, result, options) {
+  const warnings = result.warnings ?? result.policy?.warnings ?? [];
+  if (options.get("json") === "true") {
+    stdout.write(`${JSON.stringify({
+      message: result.message,
+      dryRun: result.dryRun,
+      changed: result.changed,
+      plan: result.plan,
+      filePlan: result.filePlan ?? [],
+      skill: result.skill,
+      variant: result.variant,
+      warnings
+    }, null, 2)}\n`);
+    return;
+  }
+  stdout.write(`${result.dryRun ? "Dry run: " : ""}${result.message}\n`);
+  stdout.write(renderChangePlan(result.plan));
+  stdout.write(renderFilePlan(result.filePlan ?? []));
+  if (warnings.length > 0) {
+    stdout.write(`${warnings.join("\n")}\n`);
+  }
+}
+
+function renderFilePlan(filePlan) {
+  if (filePlan.length === 0) {
+    return "File operations: none\n";
+  }
+  return `File operations:\n${filePlan.map((item) => `- ${item.operation ?? "write"} ${item.path ?? item.target ?? "unknown"}`).join("\n")}\n`;
+}
+
+function renderVariantStatus(result) {
+  return [
+    `Variant ${result.skill}: ${result.computedStatus}`,
+    `Live digest: ${result.liveDigest ?? "missing"}`,
+    `Base digest: ${result.baseDigest}`,
+    `Approved digest: ${result.approvedDigest ?? "none"}`,
+    `Live file: ${result.files.live.path}`,
+    `Base snapshot: ${result.files.baseSnapshot.path}`,
+    `Approved snapshot: ${result.files.approvedSnapshot?.path ?? "none"}`,
+    `Warnings: ${result.warnings.length === 0 ? "none" : result.warnings.join("; ")}`,
+    ""
+  ].join("\n");
+}
+
 async function block(argv, options, stdout) {
   const skillId = positionalArgs(argv)[0];
   const workflow = options.get("workflow");
@@ -702,13 +1007,24 @@ function renderImpact(result) {
     "",
     `- Found: \`${result.exists}\``,
     `- Risk: ${result.risk}`,
-    `- Affected workflows: ${formatList(result.affectedWorkflows)}`,
-    `- Affected required outputs: ${formatList(result.affectedOutputs)}`,
-    `- Alternatives: ${formatList(result.alternatives)}`,
-    ""
-  ].join("\n");
-}
-
+    `- Affected workflows: ${formatList(result.affectedWorkflows)}`,
+    `- Affected required outputs: ${formatList(result.affectedOutputs)}`,
+    `- Alternatives: ${formatList(result.alternatives)}`,
+    `- Conflicting skills: ${formatList(result.conflictingSkills ?? [])}`,
+    `- Active conflicts: ${formatActiveConflicts(result.activeConflicts ?? [])}`,
+    ""
+  ].join("\n");
+}
+
+function formatActiveConflicts(entries) {
+  if (entries.length === 0) {
+    return "none";
+  }
+  return entries
+    .map((entry) => `\`${entry.workflow}:${entry.skill}<->${entry.conflictingSkill}\``)
+    .join(", ");
+}
+
 function configPath(options) {
   return options.get("config") ?? "skillboard.config.yaml";
 }
@@ -1012,6 +1328,63 @@ function renderCanUse(result) {
   return lines.join("\n");
 }
 
+function renderRoute(result) {
+  const lines = [
+    `Intent: ${result.intent}`,
+    `Workflow: ${result.workflow}`,
+    `Match source: ${result.match_source}`,
+    `Matched capability: ${result.matched_capability ?? "none"}`,
+    `Matched skill: ${result.matched_skill ?? "none"}`,
+    `Confidence: ${result.confidence}`,
+    `Why: ${result.recommendation_reason}`,
+    `Matched terms: ${formatList(result.matched_terms)}`,
+    `Recommended skill: ${result.recommended_skill ?? "none"}`,
+    `Fallback skills: ${formatList(result.fallback_skills)}`
+  ];
+  if ((result.route_candidates ?? []).length > 0) {
+    lines.push("Route candidates:");
+    for (const candidate of result.route_candidates) {
+      lines.push(`- ${candidate.skill} (${routeCandidateStatus(candidate)})`);
+      if (!candidate.guard_allowed && candidate.guard_reasons.length > 0) {
+        lines.push(`  - ${candidate.guard_reasons[0]}`);
+      }
+    }
+  }
+  if (result.guard_command !== null) {
+    lines.push(`Guard: ${result.guard_command}`);
+  }
+  if (result.usage_disclosure !== null && result.usage_disclosure !== undefined) {
+    lines.push(`Disclosure: run the guard automatically, state at the start that ${result.recommended_skill} is being used, and state at completion that it was used. No extra user approval is needed when the guard allows it.`);
+    lines.push(`Say before use: "${result.usage_disclosure.start_message}"`);
+    lines.push(`Say after completion: "${result.usage_disclosure.finish_message}"`);
+  }
+  if (result.post_use_policy_suggestion !== null && result.post_use_policy_suggestion !== undefined) {
+    const suggestion = result.post_use_policy_suggestion;
+    lines.push(`After completion: ${routeAfterUsePromptText(suggestion.question)}`);
+    lines.push(`Policy command after confirmation: ${suggestion.suggested_policy.command_hint}`);
+  }
+  if (result.matched_capability === null) {
+    lines.push("Possible skills:");
+    for (const skill of result.possible_skills.slice(0, 5)) {
+      lines.push(`- ${skill.id} (${skill.category ?? "uncategorized"}, allowed=${skill.allowed})`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function routeCandidateStatus(candidate) {
+  return [
+    candidate.role,
+    candidate.selected ? "selected" : null,
+    candidate.guard_allowed ? "allowed" : "denied"
+  ].filter((value) => value !== null).join(", ");
+}
+
+function routeAfterUsePromptText(question) {
+  return question.replace(/^Should I /u, "ask whether to ").replace(/\?$/u, ".");
+}
+
 function renderSourceAudit(result) {
   const lines = [
     `Source audit: ${result.ok ? "passed" : "failed"}`,
@@ -1123,9 +1496,10 @@ function renderCounts(counts) {
 
 function helpText() {
   return [
-    "SkillBoard - workflow-scoped agent skill policy",
+    "SkillBoard - AI-mediated workflow-scoped skill policy",
+    "Version: see skillboard --version",
     "",
-    "Commands:",
+    "AI/automation operations:",
     "  init [--dir <path>] [--scan-root <dir>[,<dir>]] [--no-scan-installed]",
     "  uninstall [--dir <path>] [--dry-run] [--remove-config|--reset-config] [--remove-reports] [--remove-hooks] [--keep-empty-dirs]",
     "  inventory refresh [--dir <path>] [--config <path>] [--scan-root <dir>[,<dir>]] [--dry-run] [--json]",
@@ -1133,7 +1507,7 @@ function helpText() {
     "  sources refresh [--dir <path>] [--config <path>] [--unit <id>[,<id>]] [--cache-dir <dir>] [--dry-run] [--json]",
     "  doctor [--dir <path>] [--config <path>] [--skills <dir>] [--verify] [--strict] [--summary] [--json]",
     "  status [--dir <path>] [--config <path>] [--skills <dir>] [--verify] [--strict] [--summary] [--json]",
-    "  brief [--workflow <name>] [--dir <path>] [--config <path>] [--skills <dir>] [--include-actions] [--verbose] [--json]",
+    "  brief [--workflow <name>] [--intent <request>] [--dir <path>] [--config <path>] [--skills <dir>] [--include-actions] [--verbose] [--json]",
     "  apply-action <action-id> [--workflow <name>] [--dir <path>] [--config <path>] [--skills <dir>] [--dry-run] [--yes] [--allow-destructive] [--json]",
     "  import --profile <id-or-path> --source-root <dir> [--profile-dirs a,b] [--out <path>]",
     "  import --profile <id-or-path> --source-root <dir> --config <path> --merge [--replace] [--dry-run]",
@@ -1141,6 +1515,7 @@ function helpText() {
     "  check --config <path> --skills <dir>",
     "  list [skills|workflows|harnesses|install-units] --config <path> --skills <dir> [--workflow <name>] [--json]",
     "  explain <skill-id> --config <path> --skills <dir> [--json]",
+    "  route <intent> --workflow <name> --config <path> --skills <dir> [--json]",
     "  can-use <skill-id> --workflow <name> --config <path> --skills <dir> [--json]",
     "  guard use <skill-id> --workflow <name> --config <path> --skills <dir> [--json]",
     "  audit sources --config <path> --skills <dir> [--verify] [--json]",
@@ -1151,6 +1526,11 @@ function helpText() {
     "  add skill <skill-id> --path <relative-skill-path> --config <path> --skills <dir> [--status <status>] [--invocation <mode>] [--exposure <exposure>] [--category <name>] [--workflow <name>] [--dry-run] [--json]",
     "  add workflow <workflow-name> --harness <harness-name> --config <path> --skills <dir> [--skill <id>[,<id>]] [--harness-status <status>] [--require-existing-harness] [--dry-run] [--json]",
     "  add harness <harness-name> --config <path> --skills <dir> [--status <status>] [--command <cmd>[,<cmd>]] [--dry-run] [--json]",
+    "  variant add <variant-id> --from <base-id> --capability <name> --workflow <name> --config <path> --skills <dir> [--path <relative-skill-path>] [--mode manual-only|router-only|workflow-auto] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]",
+    "  variant fork <variant-id> --from <base-id> --capability <name> --workflow <name> --path <relative-skill-path> --config <path> --skills <dir> [--adapted-for <label>] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]",
+    "  variant status <variant-id> --config <path> --skills <dir> [--json]",
+    "  variant approve <variant-id> --config <path> --skills <dir> [--mode manual-only|router-only|workflow-auto] [--dry-run] [--json]",
+    "  variant reset <variant-id> --to-base|--to-approved --config <path> --skills <dir> [--yes] [--dry-run] [--mode manual-only|router-only|workflow-auto] [--json]",
     "  activate <skill-id> --workflow <name> [--mode manual-only|router-only|workflow-auto] --config <path> --skills <dir> [--dry-run] [--json]",
     "  block <skill-id> --workflow <name> --config <path> --skills <dir> [--dry-run] [--json]",
     "  quarantine <skill-id> --config <path> --skills <dir> [--dry-run] [--json]",
@@ -1160,12 +1540,187 @@ function helpText() {
     "  reconcile --config <path> --skills <dir> [--actual-harnesses a,b] [--out <path>]",
     "  impact disable <skill-id> --config <path> --skills <dir> [--out <path>] [--json]",
     "",
-    "Approval loop:",
-    "  Run skillboard brief --json --config <path> --skills <dir> [--workflow <name>] [--include-actions].",
-    "  Pick one current action id from the brief and ask the user for confirmation.",
-    "  Apply with skillboard apply-action <action-id> --config <path> --skills <dir> [--workflow <name>] --yes --json.",
-    "  Read the returned post-apply brief, then run skillboard guard use before invocation.",
+    "AI/automation control loop:",
+    "  Goal: preserve SkillBoard as a non-blocking AI skill routing control plane; see docs/ai-skill-routing-goal.md.",
+    "  Development loop: observe → route → work → explain briefly → ask after → remember policy.",
+    "  For an already-allowed skill, disclose the selected skill at start and completion; do not ask for another approval.",
+    "  Translate a user's skill request into the current brief: skillboard brief --json --config <path> --skills <dir> [--workflow <name>] [--intent <request>] [--include-actions].",
+    "  If a policy-changing action is needed, pick one current action id from that brief and ask the user for one confirmation.",
+    "  Apply one current action with skillboard apply-action <action-id> --config <path> --skills <dir> [--workflow <name>] --yes --json.",
+    "  Read the returned post-apply brief, then run skillboard guard use automatically before invocation.",
     "  apply-action re-resolves current actions; do not use cached/stale ids, multiple actions, or raw action-card shell text as the primary apply path.",
     ""
   ].join("\n");
 }
+
+function commandHelpText(command) {
+  if (command === "brief") {
+    return briefHelpText();
+  }
+  if (command === "init") {
+    return initHelpText();
+  }
+  if (command === "doctor" || command === "status") {
+    return doctorHelpText();
+  }
+  if (command === "route") {
+    return routeHelpText();
+  }
+  if (command === "guard") {
+    return guardHelpText();
+  }
+  if (command === "apply-action") {
+    return applyActionHelpText();
+  }
+  const usage = COMMAND_USAGE.get(command);
+  return usage === undefined ? null : genericCommandHelpText(usage);
+}
+
+function genericCommandHelpText(usageLines) {
+  return [
+    ...usageLines.map((line) => `Usage: skillboard ${line}`),
+    "",
+    "This help is read-only. It does not load config or change project files.",
+    "Run skillboard help for the full command catalog.",
+    ""
+  ].join("\n");
+}
+
+function initHelpText() {
+  return [
+    "Usage: skillboard init [--dir <path>] [--scan-root <dir>[,<dir>]] [--no-scan-installed]",
+    "",
+    "Creates the local SkillBoard control files for a project.",
+    "Use it once per project before asking the AI which skills it can use.",
+    "",
+    "Options:",
+    "  --dir <path>              Project root to initialize; defaults to the current directory.",
+    "  --scan-root <dir>[,<dir>] Add extra skill roots to scan during setup.",
+    "  --no-scan-installed       Create the files without scanning installed agent skills.",
+    "",
+    "What changes:",
+    "  Writes skillboard.config.yaml, skills/, .skillboard/, AGENTS.md, and CLAUDE.md as needed.",
+    "  Imports trusted user-local skills as on-request skills.",
+    "  Keeps runtime, plugin, system, and external skills quarantined until reviewed.",
+    "",
+    "Next:",
+    "  Run skillboard doctor --summary.",
+    "  Ask your AI: \"What skills can you use in this project?\"",
+    ""
+  ].join("\n");
+}
+
+function doctorHelpText() {
+  return [
+    "Usage: skillboard doctor [--dir <path>] [--config <path>] [--skills <dir>] [--verify] [--strict] [--summary] [--json]",
+    "",
+    "Checks whether a SkillBoard project is ready to use.",
+    "The status command is an alias for doctor.",
+    "",
+    "Options:",
+    "  --dir <path>       Project root to check; defaults to the current directory.",
+    "  --config <path>    Use a specific skillboard.config.yaml.",
+    "  --skills <dir>     Use a specific skills directory.",
+    "  --verify           Verify local source/cache digests when available.",
+    "  --strict           Return a failing exit code for review-needed safe mode.",
+    "  --summary          Print a short human summary.",
+    "  --json             Print an agent-readable payload.",
+    "",
+    "Use this after init and before trusting new skill sources.",
+    ""
+  ].join("\n");
+}
+
+function briefHelpText() {
+  return [
+    "Usage: skillboard brief [--workflow <name>] [--intent <request>] [--dir <path>] [--config <path>] [--skills <dir>] [--include-actions] [--verbose] [--json]",
+    "",
+    "Reads the current SkillBoard brief without changing project files.",
+    "Use it when a user asks what skills the AI can use, which skill fits a request, or what needs approval.",
+    "",
+    "Options:",
+    "  --workflow <name>     Evaluate one workflow.",
+    "  --intent <request>    Add a natural-language request so SkillBoard can suggest a skill.",
+    "  --dir <path>          Use a project root; defaults to the current directory.",
+    "  --config <path>       Use a specific skillboard.config.yaml.",
+    "  --skills <dir>        Use a specific skills directory.",
+    "  --include-actions     Include current action ids in JSON output.",
+    "  --verbose             Show full lists instead of compact previews.",
+    "  --json                Print an agent-readable payload.",
+    "",
+    "AI use:",
+    "  Read this before answering availability questions.",
+    "  Run skillboard guard use <skill-id> --workflow <name> before invoking a skill.",
+    "  If guard allows use, disclose the skill at the start and completion; do not ask for another approval.",
+    "  If a policy change is needed, ask the user to approve one current action id from this brief.",
+    ""
+  ].join("\n");
+}
+
+function routeHelpText() {
+  return [
+    "Usage: skillboard route <intent> --workflow <name> [--config <path>] [--skills <dir>] [--json]",
+    "",
+    "Suggests the best currently allowed skill for a user request.",
+    "Use it when the AI needs a skill recommendation without changing policy.",
+    "",
+    "Options:",
+    "  <intent>           Natural-language request, such as \"write tests first\".",
+    "  --workflow <name>  Workflow to route within.",
+    "  --config <path>    Use a specific skillboard.config.yaml.",
+    "  --skills <dir>     Use a specific skills directory.",
+    "  --json             Print an agent-readable payload.",
+    "",
+    "AI use:",
+    "  If a skill is recommended, run the guard before invoking it.",
+    "  If no skill matches, ask a clarifying question instead of guessing.",
+    ""
+  ].join("\n");
+}
+
+function guardHelpText() {
+  return [
+    "Usage: skillboard guard use <skill-id> --workflow <name> [--config <path>] [--skills <dir>] [--json]",
+    "",
+    "Checks whether one skill may be used right now.",
+    "Run this immediately before the AI invokes a skill.",
+    "",
+    "Options:",
+    "  use                Guard a skill invocation.",
+    "  <skill-id>         Skill id to check.",
+    "  --workflow <name>  Workflow that will use the skill.",
+    "  --config <path>    Use a specific skillboard.config.yaml.",
+    "  --skills <dir>     Use a specific skills directory.",
+    "  --json             Print an agent-readable payload.",
+    "",
+    "AI use:",
+    "  If allowed, disclose the skill at the start and completion.",
+    "  If denied, do not invoke the skill. Explain the reason or ask for the needed policy change.",
+    ""
+  ].join("\n");
+}
+
+function applyActionHelpText() {
+  return [
+    "Usage: skillboard apply-action <action-id> [--workflow <name>] [--dir <path>] [--config <path>] [--skills <dir>] [--dry-run] [--yes] [--allow-destructive] [--json]",
+    "",
+    "Applies one current action id from the latest brief.",
+    "Use it only after the user confirms a policy-changing action.",
+    "",
+    "Options:",
+    "  <action-id>             One action id from the current brief.",
+    "  --workflow <name>       Workflow for workflow-scoped actions.",
+    "  --dir <path>            Project root; defaults to the current directory.",
+    "  --config <path>         Use a specific skillboard.config.yaml.",
+    "  --skills <dir>          Use a specific skills directory.",
+    "  --dry-run               Preview the action without writing changes.",
+    "  --yes                   Apply the action after user confirmation.",
+    "  --allow-destructive     Permit destructive reset or cleanup actions.",
+    "  --json                  Print an agent-readable payload.",
+    "",
+    "AI use:",
+    "  Apply exactly one current action id.",
+    "  Read the returned post-apply brief before making another availability decision.",
+    ""
+  ].join("\n");
+}