argsbarg 4.1.1 → 5.0.2

package/src/configure/index.ts

@@ -0,0 +1,298 @@
+/*
+Interactive and automated `configure` command orchestration (agent artifacts and app config).
+*/
+
+import { resolveCapabilities } from "../capabilities.ts";
+import { displayAppConfigPath, runConfigure } from "../config/bootstrap.ts";
+import { resolveInstallPaths } from "../install/paths.ts";
+import { buildInstallPlan, buildUpdatePlan } from "../install/plan.ts";
+import {
+  installErr,
+  installInfo,
+  installOut,
+  printInstallStatus,
+  writeInteractiveInstallIntro,
+} from "../install/status.ts";
+import { resolveEffectiveInstallTargets } from "../install/target-effective.ts";
+import { runTargetPreflight } from "../install/target-plan-build.ts";
+import { INSTALL_TARGETS, installTargetForKey } from "../install/target-registry.ts";
+import { buildDetectedSnapshot, buildTargetPlanContext } from "../install/target-scope.ts";
+import type {
+  CliInstallArtifactKey,
+  InstallAction,
+  InstallActionKind,
+  InstallOpts,
+  TargetPlanContext,
+  UninstallAction,
+} from "../install/target-types.ts";
+import {
+  buildUninstallPlan,
+  skillDirFromUninstallSummary,
+  uninstallSkillDir,
+} from "../install/uninstall.ts";
+import { cliSkillInstall, skillTargetFromActionKind } from "../skill/install.ts";
+import type { CliProgram } from "../types.ts";
+import { artifactPromptLabel, promptTargetAction } from "./prompt.ts";
+
+/** True when interactive `configure` should auto-run the app config wizard. */
+export function appConfigHasEntries(program: CliProgram): boolean {
+  const entries = program.appConfig?.entries;
+  return !!entries && Object.keys(entries).length > 0;
+}
+
+/** Parsed flags for the top-level `configure` built-in. */
+export interface ConfigureOpts {
+  sync?: boolean;
+  removeAll?: boolean;
+  removeConfig?: boolean;
+  status?: boolean;
+  yes?: boolean;
+  dry?: boolean;
+  json?: boolean;
+}
+
+/** Maps raw argv flags into {@link ConfigureOpts}. */
+export function parseConfigureOpts(raw: Record<string, string>): ConfigureOpts {
+  const flag = (name: string) => raw[name] === "1";
+  return {
+    sync: flag("sync"),
+    removeAll: flag("remove-all"),
+    removeConfig: flag("remove-config"),
+    status: flag("status"),
+    yes: flag("yes"),
+    dry: flag("dry"),
+    json: flag("json"),
+  };
+}
+
+/** Returns an error message when configure flags are inconsistent; otherwise null. */
+export function validateConfigureOpts(opts: ConfigureOpts): string | null {
+  const flags = [opts.sync, opts.removeAll, opts.removeConfig, opts.status].filter(Boolean);
+  if (flags.length > 1) {
+    return "Use only one of --sync, --remove-all, --remove-config, or --status.";
+  }
+  if (opts.json) {
+    opts.yes = true;
+  }
+  if ((opts.sync || opts.removeAll || opts.removeConfig) && !opts.yes) {
+    return "--yes is required with --sync, --remove-all, or --remove-config.";
+  }
+  return null;
+}
+
+/** Adapts configure flags to internal install-plan option shape. */
+function configureToInstallOpts(opts: ConfigureOpts): InstallOpts {
+  if (opts.status) {
+    return { status: true, yes: opts.yes, dry: opts.dry, json: opts.json };
+  }
+  if (opts.sync) {
+    return { reinstall: true, yes: true, dry: opts.dry, json: opts.json };
+  }
+  if (opts.removeAll) {
+    return { uninstall: true, all: true, yes: true, dry: opts.dry, json: opts.json };
+  }
+  if (opts.removeConfig) {
+    return { uninstall: true, configure: true, yes: true, dry: opts.dry, json: opts.json };
+  }
+  return { dry: opts.dry, json: opts.json };
+}
+
+/** Installs a skill target and returns changed paths. */
+function runSkillAction(root: CliProgram, kind: InstallActionKind, opts: InstallOpts): string[] {
+  const target = skillTargetFromActionKind(kind);
+  if (!target) return [];
+  return cliSkillInstall(root, target, {
+    global: true,
+    rimraf: true,
+    dry: opts.dry,
+  });
+}
+
+/** Runs install or uninstall actions and collects changed paths. */
+function executePlan(
+  root: CliProgram,
+  actions: Array<InstallAction | UninstallAction>,
+  opts: InstallOpts,
+  showProgress: boolean,
+): string[] {
+  const changed: string[] = [];
+  const paths = resolveInstallPaths(root);
+  for (const action of actions) {
+    if (showProgress) {
+      installInfo(action.message, opts);
+    }
+    if ("kind" in action && action.kind) {
+      const skillTarget = skillTargetFromActionKind(action.kind);
+      if (skillTarget) {
+        changed.push(...runSkillAction(root, action.kind as InstallActionKind, opts));
+        continue;
+      }
+    }
+    if (!("kind" in action) || !action.kind) {
+      const skillDir = skillDirFromUninstallSummary(action.summary, paths);
+      if (skillDir) {
+        changed.push(...uninstallSkillDir(skillDir, !!opts.dry));
+        continue;
+      }
+    }
+    changed.push(...action.run());
+  }
+  return changed;
+}
+
+/** Builds plan context limited to a single artifact key. */
+function buildSingleTargetContext(
+  root: CliProgram,
+  paths: ReturnType<typeof resolveInstallPaths>,
+  detected: ReturnType<typeof buildDetectedSnapshot>,
+  key: CliInstallArtifactKey,
+  mode: "install" | "uninstall",
+  opts: InstallOpts,
+): TargetPlanContext {
+  const effective = resolveEffectiveInstallTargets(root.configure, root);
+  const base = buildTargetPlanContext(root, paths, opts, detected);
+  return {
+    ...base,
+    mode: mode === "install" ? "install-scoped" : "uninstall-scoped",
+    include: (k) => k === key && effective[k].enabled,
+  };
+}
+
+/** Resolves install or uninstall actions for one artifact target. */
+function actionsForTarget(
+  root: CliProgram,
+  paths: ReturnType<typeof resolveInstallPaths>,
+  key: CliInstallArtifactKey,
+  action: "install" | "uninstall",
+  opts: InstallOpts,
+): Array<InstallAction | UninstallAction> {
+  const detected = buildDetectedSnapshot(root, paths);
+  const target = installTargetForKey(key);
+  if (!target) return [];
+  const ctx = buildSingleTargetContext(root, paths, detected, key, action, opts);
+  if (action === "install") {
+    return target.planInstall(ctx);
+  }
+  return target.planUninstall(ctx);
+}
+
+/** Walks enabled targets with per-target prompts (TTY required). */
+async function runInteractiveConfigure(root: CliProgram, opts: ConfigureOpts): Promise<string[]> {
+  if (!process.stdin.isTTY) {
+    throw new Error("Interactive configure requires a TTY. Use flags such as --sync --yes.");
+  }
+
+  writeInteractiveInstallIntro(root);
+  const paths = resolveInstallPaths(root);
+  const detected = buildDetectedSnapshot(root, paths);
+  const effective = resolveEffectiveInstallTargets(root.configure, root);
+  const mutationOpts: InstallOpts = { dry: opts.dry, json: opts.json };
+  const changed: string[] = [];
+
+  for (const target of INSTALL_TARGETS) {
+    if (target.key === "app") continue;
+    if (!effective[target.key].enabled) continue;
+    if (target.key !== "configure" && !target.isAvailable(root, paths)) continue;
+    if (target.key === "configure" && !root.appConfig) continue;
+
+    if (target.key === "configure") {
+      if (!appConfigHasEntries(root)) continue;
+
+      const result = runConfigure(root, { context: "standalone", showHeading: false });
+      if (result.changed) {
+        installOut(`Wrote config: ${displayAppConfigPath(root)}`, mutationOpts);
+        changed.push(displayAppConfigPath(root));
+      }
+      continue;
+    }
+
+    const label = artifactPromptLabel(target.key);
+    const installed = target.detectedForSnapshot(detected);
+
+    const statusHint = installed ? "installed" : "not installed";
+    process.stderr.write(`\n${label} (${statusHint})\n`);
+    const choice = promptTargetAction(label, installed);
+    if (!choice || choice === "skip") continue;
+
+    const actions = actionsForTarget(root, paths, target.key, choice, mutationOpts);
+    if (actions.length === 0) continue;
+
+    const installActions = actions.filter(
+      (a): a is InstallAction =>
+        "kind" in a && typeof a.kind === "string" && a.kind.includes("-mcp"),
+    );
+    if (choice === "install" && resolveCapabilities(root).mcp && installActions.length > 0) {
+      runTargetPreflight(root, paths, mutationOpts, installActions);
+    }
+
+    changed.push(...executePlan(root, actions, mutationOpts, true));
+  }
+
+  return changed;
+}
+
+/** Runs sync, remove, or status modes without per-target prompts. */
+async function runAutomatedConfigure(root: CliProgram, opts: ConfigureOpts): Promise<string[]> {
+  const installOpts = configureToInstallOpts(opts);
+  const paths = resolveInstallPaths(root);
+
+  if (installOpts.status) {
+    printInstallStatus(root, installOpts);
+    return [];
+  }
+
+  let actions: Array<InstallAction | UninstallAction>;
+  if (installOpts.uninstall) {
+    actions = buildUninstallPlan(root, paths, installOpts);
+  } else if (installOpts.reinstall) {
+    actions = buildUpdatePlan(root, paths, installOpts);
+  } else {
+    actions = buildInstallPlan(root, paths, installOpts);
+  }
+
+  const installActions = actions.filter(
+    (a): a is InstallAction => "kind" in a && typeof a.kind === "string" && a.kind.includes("-mcp"),
+  );
+  if (!installOpts.uninstall && resolveCapabilities(root).mcp && installActions.length > 0) {
+    runTargetPreflight(root, paths, installOpts, installActions);
+  }
+
+  return executePlan(root, actions, installOpts, true);
+}
+
+/** Main configure command orchestrator. */
+export async function cliConfigure(
+  root: CliProgram,
+  rawOpts: Record<string, string>,
+): Promise<never> {
+  const opts = parseConfigureOpts(rawOpts);
+  const err = validateConfigureOpts(opts);
+  if (err) {
+    installErr(err);
+    process.exit(1);
+  }
+
+  const isInteractive = !opts.sync && !opts.removeAll && !opts.removeConfig && !opts.status;
+
+  let changed: string[] = [];
+  try {
+    changed = isInteractive
+      ? await runInteractiveConfigure(root, opts)
+      : await runAutomatedConfigure(root, opts);
+  } catch (mutationErr) {
+    installErr(mutationErr instanceof Error ? mutationErr.message : String(mutationErr));
+    process.exit(1);
+  }
+
+  if (opts.json && !opts.status) {
+    process.stdout.write(`${JSON.stringify(changed, null, 2)}\n`);
+    process.exit(0);
+  }
+
+  if (!opts.status && changed.length > 0) {
+    const verb = opts.removeAll || opts.removeConfig ? "Removed" : opts.sync ? "Synced" : "Updated";
+    installOut(`${verb} ${changed.length} file(s).`, configureToInstallOpts(opts));
+  }
+
+  process.exit(0);
+}

package/src/configure/prompt.ts

@@ -0,0 +1,47 @@
+/*
+TTY prompts for per-target install, skip, or uninstall during interactive `configure`.
+*/
+
+import { readSync } from "node:fs";
+import type { CliInstallArtifactKey } from "../install/target-types.ts";
+
+/** Human-readable labels for each install artifact key in interactive prompts. */
+const LABELS: Record<CliInstallArtifactKey, string> = {
+  app: "App binary",
+  cursorSkill: "Cursor skill",
+  claudeSkill: "Claude skill",
+  codexSkill: "Codex skill",
+  opencodeSkill: "OpenCode skill",
+  openclawSkill: "OpenClaw skill",
+  cursorMcp: "Cursor MCP",
+  claudeCodeMcp: "Claude Code MCP",
+  claudeDesktopMcp: "Claude Desktop MCP",
+  opencodeMcp: "OpenCode MCP",
+  codexMcp: "Codex MCP",
+  openclawMcp: "OpenClaw MCP",
+  chatgptMcp: "ChatGPT desktop MCP",
+  configure: "App config",
+};
+
+/** Returns the prompt label for an install artifact key. */
+export function artifactPromptLabel(key: CliInstallArtifactKey): string {
+  return LABELS[key];
+}
+
+/** User choice from a per-target Y/n or y/N prompt. */
+export type TargetPromptAction = "install" | "skip" | "uninstall";
+
+/** Prompt per target: Y/n when not installed, y/N when installed. */
+export function promptTargetAction(label: string, installed: boolean): TargetPromptAction | null {
+  const hint = installed ? `${label} [y/N]: ` : `${label} [Y/n]: `;
+  process.stderr.write(hint);
+  const buf = Buffer.alloc(256);
+  const n = readSync(0, buf, { length: 256 });
+  const ans = buf.toString("utf8", 0, n).trim().toLowerCase();
+  if (installed) {
+    if (ans === "n") return "uninstall";
+    return "skip";
+  }
+  if (ans === "n") return "skip";
+  return "install";
+}

package/src/docs/api-guide.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for docs/api-guide module behavior.
+*/
+
 import { expect, test } from "bun:test";
 import { cliSchemaExport } from "../schema.ts";
 import type { CliProgram } from "../types.ts";
@@ -45,6 +49,7 @@ const nestedFixture: CliProgram = {
   ],
 };
 
+/** Tests that generateApiGuideBody matches command section of full API guide. */
 test("generateApiGuideBody matches command section of full API guide", () => {
   const body = generateApiGuideBody(nestedFixture);
   const full = generateApiGuide(nestedFixture);
@@ -53,6 +58,7 @@ test("generateApiGuideBody matches command section of full API guide", () => {
   expect(body).not.toContain("CLI API reference");
 });
 
+/** Tests that generateApiGuide covers the same command keys as cliSchemaExport. */
 test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
   const md = generateApiGuide(nestedFixture);
   const schema = cliSchemaExport(nestedFixture);
@@ -62,6 +68,7 @@ test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
   expect(schema.commands?.map((c) => c.key)).toEqual(["stat"]);
 });
 
+/** Tests that generateApiGuide resolves program key in install notes. */
 test("generateApiGuide resolves program key in install notes", () => {
   const fixture: CliProgram = {
     key: "myapp",
@@ -75,6 +82,7 @@ test("generateApiGuide resolves program key in install notes", () => {
   expect(md).not.toContain("Upgrade to latest release");
 });
 
+/** Tests that generateApiGuide mentions Homebrew upgrade. */
 test("generateApiGuide mentions Homebrew upgrade", () => {
   const fixture: CliProgram = {
     key: "myapp",
@@ -87,6 +95,7 @@ test("generateApiGuide mentions Homebrew upgrade", () => {
   expect(md).not.toContain("install --update");
 });
 
+/** Tests that generateApiGuide resolves {argsbarg:program} in consumer notes. */
 test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
   const fixture: CliProgram = {
     key: "myapp",
@@ -105,6 +114,7 @@ test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
   expect(md).toContain("Invoke `myapp run`.");
 });
 
+/** Tests that generateApiGuide and cliSchemaExport include leaf outputSchema. */
 test("generateApiGuide and cliSchemaExport include leaf outputSchema", () => {
   const fixture: CliProgram = {
     key: "myapp",

package/src/docs/builtin.ts

@@ -1,3 +1,5 @@
+import { docsSkillTopicDescription } from "../builtins/configure-copy.ts";
+import { resolveCapabilities } from "../capabilities.ts";
 import {
   CliFallbackMode,
   type CliLeaf,
@@ -75,11 +77,7 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
   leaves.push(
     docsLeaf(program, "schema", "Print the full command tree as JSON."),
     docsLeaf(program, "api", "Print the full command reference as markdown."),
-    docsLeaf(
-      program,
-      "skill",
-      "Print a reference agent SKILL, use `install --skill` for optimized.",
-    ),
+    docsLeaf(program, "skill", docsSkillTopicDescription(program, resolveCapabilities(program))),
   );
 
   return {

package/src/docs/docs.test.ts

@@ -1,3 +1,7 @@
+/*
+Tests for docs/docs module behavior.
+*/
+
 import { afterEach, beforeEach, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -49,6 +53,7 @@ function docsFixture(mcp = true): CliProgram {
   };
 }
 
+/** Docs reserved when enabled. */
 test("docs reserved when enabled", () => {
   const root: CliProgram = {
     ...docsFixture(),
@@ -63,6 +68,7 @@ test("docs reserved when enabled", () => {
   expect(() => cliValidateProgram(root)).toThrow(/Reserved command name: docs/);
 });
 
+/** Docs rejects reserved topic keys. */
 test("docs rejects reserved topic keys", () => {
   const root = docsFixture();
   const docs = root.docs;
@@ -77,22 +83,26 @@ test("docs rejects reserved topic keys", () => {
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
 });
 
+/** DocsEffectiveDefaultTopic uses first topic key. */
 test("docsEffectiveDefaultTopic uses first topic key", () => {
   expect(docsEffectiveDefaultTopic(docsFixture().docs!)).toBe("readme");
 });
 
+/** Bare docs prints first topic via Cli.invoke. */
 test("bare docs prints first topic via Cli.invoke", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Hello README");
 });
 
+/** Docs readme prints bundled text. */
 test("docs readme prints bundled text", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "readme"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Hello README");
 });
 
+/** Docs defaultTopic override. */
 test("docs defaultTopic override", async () => {
   const root = docsFixture();
   root.docs!.defaultTopic = "arch";
@@ -100,20 +110,23 @@ test("docs defaultTopic override", async () => {
   expect(result.stdout).toContain("Architecture");
 });
 
+/** Docs mcp when MCP enabled. */
 test("docs mcp when MCP enabled", async () => {
   const result = await new Cli(docsFixture(true)).invoke(["docs", "mcp"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("MCP server (myapp)");
   expect(result.stdout).toContain("myapp mcp");
   expect(result.stdout).toContain("claude_desktop_config.json");
-  expect(result.stdout).toContain("install --mcp --yes");
+  expect(result.stdout).toContain("configure --sync --yes");
 });
 
+/** Docs rejects unknown subcommand. */
 test("docs rejects unknown subcommand", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "all"]);
   expect(result.exitCode).not.toBe(0);
 });
 
+/** Docs mcp absent from router when MCP disabled. */
 test("docs mcp absent from router when MCP disabled", async () => {
   const root = docsFixture(false);
   const presentation = cliPresentationRoot(root);
@@ -126,6 +139,7 @@ test("docs mcp absent from router when MCP disabled", async () => {
   expect(result.exitCode).not.toBe(0);
 });
 
+/** Presentation includes docs subtree. */
 test("presentation includes docs subtree", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
@@ -135,6 +149,7 @@ test("presentation includes docs subtree", () => {
   ).toBe(true);
 });
 
+/** Docs schema prints JSON. */
 test("docs schema prints JSON", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "schema"]);
   expect(result.exitCode).toBe(0);
@@ -143,6 +158,7 @@ test("docs schema prints JSON", async () => {
   expect(schema.commands.some((c: { key: string }) => c.key === "run")).toBe(true);
 });
 
+/** Docs api prints markdown reference. */
 test("docs api prints markdown reference", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "api"]);
   expect(result.exitCode).toBe(0);
@@ -152,6 +168,7 @@ test("docs api prints markdown reference", async () => {
   expect(result.stdout).toContain("myapp docs schema");
 });
 
+/** Tests that skipsRequiredAppConfigExit includes docs and config builtins. */
 test("skipsRequiredAppConfigExit includes docs and config builtins", () => {
   const program = {
     ...docsFixture(),
@@ -165,6 +182,7 @@ test("skipsRequiredAppConfigExit includes docs and config builtins", () => {
   expect(skipsRequiredAppConfigExit(["run"], caps)).toBe(false);
 });
 
+/** Docs skill prints Cursor SKILL.md. */
 test("docs skill prints Cursor SKILL.md", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "skill"]);
   expect(result.exitCode).toBe(0);
@@ -176,20 +194,22 @@ test("docs skill prints Cursor SKILL.md", async () => {
   expect(result.stdout).not.toContain("mcp.json");
 });
 
-test("docs skill help recommends install --skill", async () => {
+/** Docs skill help recommends configure. */
+test("docs skill help recommends configure", async () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
   expect(docsNode && "commands" in docsNode).toBe(true);
   if (docsNode && "commands" in docsNode) {
     const skill = docsNode.commands.find((c) => c.key === "skill");
     expect(skill?.description).toContain("reference agent SKILL");
-    expect(skill?.description).toContain("install --skill");
+    expect(skill?.description).toContain("configure");
     expect(skill?.notes).toBeUndefined();
     expect(docsNode.notes).toContain("--save");
     expect(docsNode.notes).not.toContain("install --skill");
   }
 });
 
+/** Presentation includes docs schema and skill. */
 test("presentation includes docs schema and skill", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
@@ -201,6 +221,7 @@ test("presentation includes docs schema and skill", () => {
   }
 });
 
+/** Completions offer docs subcommands. */
 test("completions offer docs subcommands", () => {
   const bash = completionBashScript(cliPresentationRoot(docsFixture()));
   expect(bash).toContain("docs) echo");
@@ -210,19 +231,21 @@ test("completions offer docs subcommands", () => {
   expect(bash).toContain("skill) echo");
 });
 
-test("generateMcpGuide includes schema URI and install targets", () => {
+/** Tests that generateMcpGuide includes schema URI and configure sync. */
+test("generateMcpGuide includes schema URI and configure sync", () => {
   const guide = generateMcpGuide(docsFixture(true));
   expect(guide).toContain("myapp://schema");
   expect(guide).toContain("~/.cursor/mcp.json");
   expect(guide).toContain("claude_desktop_config.json");
   expect(guide).toContain("## Installation");
   expect(guide).toContain("## Running directly");
-  expect(guide).toContain("install --mcp");
+  expect(guide).toContain("configure --sync");
   expect(guide).toContain("brew install myapp");
   expect(guide).toContain("OpenAI Codex");
   expect(guide).toContain("ChatGPT");
 });
 
+/** Docs --save writes topic file. */
 test("docs --save writes topic file", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "readme", "--save"]);
   expect(result.exitCode).toBe(0);
@@ -232,6 +255,7 @@ test("docs --save writes topic file", async () => {
   expect(text).not.toContain("Generated by");
 });
 
+/** Docs api --save prepends generated hint. */
 test("docs api --save prepends generated hint", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "api", "--save"]);
   expect(result.exitCode).toBe(0);
@@ -242,6 +266,7 @@ test("docs api --save prepends generated hint", async () => {
   expect(text).toContain("CLI API reference");
 });
 
+/** Docs skill --save keeps frontmatter first. */
 test("docs skill --save keeps frontmatter first", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "skill", "--save"]);
   expect(result.exitCode).toBe(0);
@@ -252,6 +277,7 @@ test("docs skill --save keeps frontmatter first", async () => {
   expect(text.indexOf(hint)).toBeGreaterThan(text.indexOf("---\n", 4));
 });
 
+/** Docs schema --save writes JSON file. */
 test("docs schema --save writes JSON file", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "schema", "--save"]);
   expect(result.exitCode).toBe(0);
@@ -262,6 +288,7 @@ test("docs schema --save writes JSON file", async () => {
   expect(schema.key).toBe("myapp");
 });
 
+/** Tests that saveDocsTopic returns relative path. */
 test("saveDocsTopic returns relative path", () => {
   const path = saveDocsTopic(docsFixture(), "api");
   expect(path).toBe("docs/api.md");

package/src/docs/mcp-guide.ts

@@ -105,11 +105,11 @@ export function generateMcpGuide(root: CliProgram): string {
     "",
     "## Installation",
     "",
-    "### `install --mcp`",
+    "### `configure`",
     "",
   ];
 
-  if (caps.install) {
+  if (caps.configure) {
     lines.push(
       `Install the CLI first so \`${root.key}\` is on your PATH (e.g. \`brew install ${root.key}\`). Host configs reference the app by name.`,
       "",
@@ -123,7 +123,7 @@ export function generateMcpGuide(root: CliProgram): string {
 
   lines.push(
     "```bash",
-    `${root.key} install --mcp --yes`,
+    `${root.key} configure --sync --yes`,
     "```",
     "",
     "Merges the server entry below into host config when each host is present:",
@@ -177,7 +177,7 @@ export function generateMcpGuide(root: CliProgram): string {
   if (root.appConfig?.entries && Object.keys(root.appConfig.entries).length > 0) {
     lines.push("## Configuration", "");
     lines.push(
-      `Configure before first use in Cursor or Claude Desktop (MCP hosts are non-interactive): \`${root.key} install --configure\`.`,
+      `Configure before first use in Cursor or Claude Desktop (MCP hosts are non-interactive): \`${root.key} configure\`.`,
       "",
       `Default config file: \`${displayAppConfigPath(root)}\` (flat JSON keys).`,
       "",