argsbarg 3.4.2 → 3.5.0

package/src/builtins/export.ts

@@ -1,12 +1,12 @@
 import { type CliCapabilities, resolveCapabilities } from "../capabilities.ts";
+import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
+import { visibleOptions } from "../hidden.ts";
 import type { CliFallbackMode, CliNode, CliOption, CliPositional, CliProgram } from "../types.ts";
 import { isCliRouter } from "../types.ts";
-import { visibleOptions } from "../hidden.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
-import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 
 /** JSON-safe command node (no handlers). */
 export interface CliSchemaExport {
@@ -55,22 +55,31 @@ function exportBuiltinNode(cmd: CliNode): CliSchemaExport | null {
   return out;
 }
 
+function pushExportedBuiltin(builtins: CliSchemaExport[], cmd: CliNode): void {
+  const node = exportBuiltinNode(cmd);
+  if (node) {
+    builtins.push(node);
+  }
+}
+
 /** Built-in subtrees matching help visibility for `--schema` export. */
-export function exportPresentationBuiltins(program: CliProgram, caps?: CliCapabilities): CliSchemaExport[] {
+export function exportPresentationBuiltins(
+  program: CliProgram,
+  caps?: CliCapabilities,
+): CliSchemaExport[] {
   const resolved = caps ?? resolveCapabilities(program);
-  const builtins: CliSchemaExport[] = [
-    exportBuiltinNode(cliBuiltinCompletionGroup(program))!,
-    exportBuiltinNode(cliBuiltinVersionCommand())!,
-  ];
+  const builtins: CliSchemaExport[] = [];
+  pushExportedBuiltin(builtins, cliBuiltinCompletionGroup(program));
+  pushExportedBuiltin(builtins, cliBuiltinVersionCommand());
   if (resolved.install) {
-    builtins.push(exportBuiltinNode(cliBuiltinInstallCommand(program))!);
+    pushExportedBuiltin(builtins, cliBuiltinInstallCommand(program));
   }
   const docsGroup = cliBuiltinDocsGroupIfEnabled(program);
   if (docsGroup) {
-    builtins.push(exportBuiltinNode(docsGroup)!);
+    pushExportedBuiltin(builtins, docsGroup);
   }
   if (resolved.mcp) {
-    builtins.push(exportBuiltinNode(cliBuiltinMcpCommand(program))!);
+    pushExportedBuiltin(builtins, cliBuiltinMcpCommand(program));
   }
   return builtins;
 }

package/src/builtins/index.ts

@@ -1,10 +1,15 @@
 export { completionBashScript } from "./completion-bash.ts";
-export { completionZshScript } from "./completion-zsh.ts";
 export { completionFishScript } from "./completion-fish.ts";
 export { cliBuiltinCompletionGroup } from "./completion-group.ts";
+export { completionZshScript } from "./completion-zsh.ts";
+export { builtinInterceptRoot, dispatchBuiltin } from "./dispatch.ts";
+export { type CliSchemaExport, exportPresentationBuiltins } from "./export.ts";
 export { cliBuiltinInstallCommand, installBuiltinOptions } from "./install.ts";
 export { cliBuiltinMcpCommand } from "./mcp.ts";
-export { cliParseRoot, cliPresentationRoot, parseBuiltins, presentationBuiltins } from "./presentation.ts";
-export { exportPresentationBuiltins, type CliSchemaExport } from "./export.ts";
-export { dispatchBuiltin, builtinInterceptRoot } from "./dispatch.ts";
+export {
+  cliParseRoot,
+  cliPresentationRoot,
+  parseBuiltins,
+  presentationBuiltins,
+} from "./presentation.ts";
 export { collectScopes, type ScopeRec } from "./scopes.ts";

package/src/builtins/install.ts

@@ -1,5 +1,5 @@
 import { resolveCapabilities } from "../capabilities.ts";
-import { CliProgram, CliOption, CliOptionKind, type CliLeaf } from "../types.ts";
+import { type CliLeaf, type CliOption, CliOptionKind, type CliProgram } from "../types.ts";
 
 /** Install command options (dynamic: `--mcp` only when MCP is enabled). */
 export function installBuiltinOptions(root: CliProgram): CliOption[] {
@@ -42,12 +42,14 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     },
     {
       name: "uninstall",
-      description: "Remove installed artifacts (use --all or scoped flags; skips targets not on disk).",
+      description:
+        "Remove installed artifacts (use --all or scoped flags; skips targets not on disk).",
       kind: CliOptionKind.Presence,
     },
     {
       name: "prefix",
-      description: "Install directory for the binary (default ~/.local/bin; overrides INSTALL_PREFIX).",
+      description:
+        "Install directory for the binary (default ~/.local/bin; overrides INSTALL_PREFIX).",
       kind: CliOptionKind.String,
     },
     {
@@ -67,7 +69,8 @@ export function installBuiltinOptions(root: CliProgram): CliOption[] {
     },
     {
       name: "quiet",
-      description: "Suppress informational output (requires --yes, --json, --reinstall, or --update).",
+      description:
+        "Suppress informational output (requires --yes, --json, --reinstall, or --update).",
       kind: CliOptionKind.Presence,
     },
   ];
@@ -103,11 +106,7 @@ export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
     `  ${app} install --reinstall`,
   ];
   if (resolveCapabilities(root).update) {
-    notesLines.push(
-      "",
-      "Upgrade to latest release:",
-      `  ${app} install --update`,
-    );
+    notesLines.push("", "Upgrade to latest release:", `  ${app} install --update`);
   }
   notesLines.push(
     "",
@@ -122,7 +121,8 @@ export function cliBuiltinInstallCommand(root: CliProgram): CliLeaf {
   );
   return {
     key: "install",
-    description: "Install the binary, shell completions, agent skills, and MCP config to your user environment.",
+    description:
+      "Install the binary, shell completions, agent skills, and MCP config to your user environment.",
     notes: notesLines.join("\n"),
     options: installBuiltinOptions(root),
     handler: () => {},

package/src/builtins/mcp.ts

@@ -1,6 +1,6 @@
 import { resolveCapabilities } from "../capabilities.ts";
 import { docsEnabled } from "../docs/resolve.ts";
-import { type CliLeaf, type CliProgram, type CliRouter, CliFallbackMode } from "../types.ts";
+import { CliFallbackMode, type CliLeaf, type CliProgram, type CliRouter } from "../types.ts";
 
 /** Built-in `mcp` router: bare `myapp mcp` runs stdio (via hidden `serve` fallback); `mcp bundle` packs `.mcpb`. */
 export function cliBuiltinMcpCommand(program: CliProgram): CliRouter {

package/src/builtins/presentation.ts

@@ -1,20 +1,17 @@
 import type { CliCapabilities } from "../capabilities.ts";
 import { resolveCapabilities } from "../capabilities.ts";
+import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 import { presentationNode, visibleOptions } from "../hidden.ts";
 import type { CliLeaf, CliNode, CliProgram, CliRouter } from "../types.ts";
-import { isCliLeaf, isCliRouter } from "../types.ts";
+import { isCliLeaf } from "../types.ts";
 import { cliBuiltinCompletionGroup } from "./completion-group.ts";
 import { cliBuiltinInstallCommand } from "./install.ts";
 import { cliBuiltinMcpCommand } from "./mcp.ts";
 import { cliBuiltinVersionCommand } from "./version.ts";
-import { cliBuiltinDocsGroupIfEnabled } from "../docs/builtin.ts";
 
 /** All built-in command nodes for argv parsing (includes hidden builtins). */
 export function parseBuiltins(program: CliProgram, caps: CliCapabilities): CliNode[] {
-  const builtins: CliNode[] = [
-    cliBuiltinCompletionGroup(program),
-    cliBuiltinVersionCommand(),
-  ];
+  const builtins: CliNode[] = [cliBuiltinCompletionGroup(program), cliBuiltinVersionCommand()];
   if (caps.install) {
     builtins.push(cliBuiltinInstallCommand(program));
   }
@@ -98,10 +95,13 @@ export function cliPresentationRoot(program: CliProgram): CliRouter {
 }
 
 /** Root help notes: consumer `program.notes` plus agent discovery when `docs` is enabled. */
-export function presentationRootNotes(program: CliProgram, caps: CliCapabilities): string | undefined {
+export function presentationRootNotes(
+  program: CliProgram,
+  caps: CliCapabilities,
+): string | undefined {
   const parts: string[] = [];
   if ((program.notes ?? "").trim().length > 0) {
-    parts.push(program.notes!.trim());
+    parts.push((program.notes ?? "").trim());
   }
   if (caps.docs) {
     parts.push(`For AI agents: \`${program.key} docs skill\`.`);

package/src/builtins/scopes.ts

@@ -25,7 +25,7 @@ function walkScopes(cmdPath: string, cmd: CliNode, acc: ScopeRec[]): void {
     wantsFiles: hasPositionalArguments(cmd),
   });
   for (const ch of kids) {
-    const nextPath = cmdPath === "" ? ch.key : cmdPath + "/" + ch.key;
+    const nextPath = cmdPath === "" ? ch.key : `${cmdPath}/${ch.key}`;
     walkScopes(nextPath, ch, acc);
   }
 }

package/src/builtins/version.ts

@@ -1,4 +1,4 @@
-import { type CliLeaf } from "../types.ts";
+import type { CliLeaf } from "../types.ts";
 
 /** Top-level `version` built-in (leaf). */
 export function cliBuiltinVersionCommand(): CliLeaf {

package/src/completion.ts

@@ -3,11 +3,11 @@ Re-export shim — completion emitters and built-in trees live in ./builtins/.
 */
 
 export {
-  completionBashScript,
-  completionZshScript,
-  completionFishScript,
-  cliPresentationRoot,
   cliBuiltinCompletionGroup,
   cliBuiltinInstallCommand,
   cliBuiltinMcpCommand,
+  cliPresentationRoot,
+  completionBashScript,
+  completionFishScript,
+  completionZshScript,
 } from "./builtins/index.ts";

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

@@ -1,8 +1,8 @@
 import { expect, test } from "bun:test";
+import { cliSchemaExport } from "../schema.ts";
 import type { CliProgram } from "../types.ts";
 import { CliOptionKind } from "../types.ts";
 import { generateApiGuide, generateApiGuideBody } from "./api-guide.ts";
-import { cliSchemaExport } from "../schema.ts";
 
 const nestedFixture: CliProgram = {
   key: "nested.ts",
@@ -125,7 +125,7 @@ test("generateApiGuide and cliSchemaExport include leaf outputSchema", () => {
     ],
   };
   const schema = cliSchemaExport(fixture);
-  expect(schema.commands![0]!.outputSchema).toEqual({
+  expect(schema.commands?.[0]?.outputSchema).toEqual({
     type: "object",
     properties: { id: { type: "string" } },
     required: ["id"],

package/src/docs/api-guide.ts

@@ -101,7 +101,7 @@ function renderCommandNode(
     lines.push("#### Options", "");
     lines.push("| Option | Type | Required | Description |");
     lines.push("| --- | --- | --- | --- |");
-    for (const opt of node.options!) {
+    for (const opt of node.options ?? []) {
       lines.push(formatOptionRow(opt));
     }
     lines.push("");
@@ -111,7 +111,7 @@ function renderCommandNode(
     lines.push("#### Positionals", "");
     lines.push("| Argument | Type | Required | Description |");
     lines.push("| --- | --- | --- | --- |");
-    for (const p of node.positionals!) {
+    for (const p of node.positionals ?? []) {
       lines.push(formatPositionalRow(p));
     }
     lines.push("");

package/src/docs/builtin.ts

@@ -1,4 +1,11 @@
-import { CliFallbackMode, CliOptionKind, type CliLeaf, type CliOption, type CliProgram, type CliRouter } from "../types.ts";
+import {
+  CliFallbackMode,
+  type CliLeaf,
+  type CliOption,
+  CliOptionKind,
+  type CliProgram,
+  type CliRouter,
+} from "../types.ts";
 import {
   DOCS_ROUTER_DESCRIPTION,
   docsEffectiveDefaultTopic,
@@ -16,7 +23,11 @@ const DOCS_SAVE_OPTION: CliOption = {
   kind: CliOptionKind.Presence,
 };
 
-function runDocsTopic(program: CliProgram, topic: string, ctx: { hasFlag(name: string): boolean }): void {
+function runDocsTopic(
+  program: CliProgram,
+  topic: string,
+  ctx: { hasFlag(name: string): boolean },
+): void {
   if (ctx.hasFlag("save")) {
     process.stdout.write(`${saveDocsTopic(program, topic)}\n`);
     return;
@@ -43,24 +54,32 @@ function docsRouterNotes(): string {
 
 /** Built-in `docs` router with bundled topic subcommands. */
 export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
-  const docs = program.docs!;
+  const docs = program.docs;
+  if (!docs) {
+    throw new Error("docs not enabled");
+  }
   const leaves: CliLeaf[] = [];
 
   for (const key of docsUserTopicKeys(docs)) {
-    const topic = docs.topics[key]!;
+    const topic = docs.topics[key];
+    if (!topic) {
+      throw new Error(`docs topic missing: ${key}`);
+    }
     leaves.push(docsLeaf(program, key, docsTopicDescription(key, topic.description)));
   }
 
   if (docsIncludesMcpTopic(program)) {
-    leaves.push(
-      docsLeaf(program, "mcp", "Print MCP server setup and tool guidance."),
-    );
+    leaves.push(docsLeaf(program, "mcp", "Print MCP server setup and tool guidance."));
   }
 
   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",
+      "Print a reference agent SKILL, use `install --skill` for optimized.",
+    ),
   );
 
   return {

package/src/docs/docs.test.ts

@@ -1,14 +1,14 @@
-import { describe, expect, test, beforeEach, afterEach } from "bun:test";
+import { afterEach, beforeEach, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
 import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
 import { completionBashScript } from "../completion.ts";
 import { cliInvoke } from "../index.ts";
 import type { CliProgram } from "../types.ts";
 import { cliValidateProgram } from "../validate.ts";
-import { docsEffectiveDefaultTopic } from "./resolve.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
+import { docsEffectiveDefaultTopic } from "./resolve.ts";
 import { saveDocsTopic } from "./save.ts";
 
 let workDir: string;
@@ -64,13 +64,15 @@ test("docs reserved when enabled", () => {
 
 test("docs rejects reserved topic keys", () => {
   const root = docsFixture();
-  root.docs!.topics.schema = { text: "nope" };
+  const docs = root.docs;
+  if (!docs) throw new Error("expected docs fixture");
+  docs.topics.schema = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
-  delete root.docs!.topics.schema;
-  root.docs!.topics.skill = { text: "nope" };
+  delete docs.topics.schema;
+  docs.topics.skill = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
-  delete root.docs!.topics.skill;
-  root.docs!.topics.api = { text: "nope" };
+  delete docs.topics.skill;
+  docs.topics.api = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
 });
 
@@ -127,9 +129,9 @@ test("presentation includes docs subtree", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
   expect(docsNode).toBeDefined();
-  expect(docsNode && "commands" in docsNode && docsNode.commands.some((c) => c.key === "readme")).toBe(
-    true,
-  );
+  expect(
+    docsNode && "commands" in docsNode && docsNode.commands.some((c) => c.key === "readme"),
+  ).toBe(true);
 });
 
 test("docs schema prints JSON", async () => {
@@ -199,6 +201,11 @@ test("generateMcpGuide includes schema URI and install targets", () => {
   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 --bin");
+  expect(guide).toContain("OpenAI Codex");
+  expect(guide).toContain("ChatGPT");
 });
 
 test("docs --save writes topic file", async () => {

package/src/docs/mcp-guide.ts

@@ -1,11 +1,75 @@
-import { collectOptionDefs } from "../parse.ts";
+import { resolveCapabilities } from "../capabilities.ts";
+import { expectedOpenCodeMcpEntry, OPENCODE_CONFIG_SCHEMA } from "../install/mcp-opencode.ts";
 import {
   collectMcpTools,
+  type McpToolDef,
   mcpServerId,
   resolveMcpSchemaUri,
-  type McpToolDef,
 } from "../mcp/tools.ts";
-import { type CliProgram, CliOptionKind } from "../types.ts";
+import { collectOptionDefs } from "../parse.ts";
+import { CliOptionKind, type CliProgram } from "../types.ts";
+
+/** Extra host notes for generated `docs mcp` (manual fallbacks and ChatGPT Connectors). */
+function appendManualHostSetup(lines: string[], root: CliProgram, serverId: string): void {
+  const openCodeEntry = expectedOpenCodeMcpEntry(root);
+
+  lines.push(
+    "| OpenCode | `~/.config/opencode/*` (when `~/.config/opencode` exists) |",
+    "| OpenAI Codex | `~/.codex/config.toml` via `codex mcp add` (when `codex` is on PATH) |",
+    "| ChatGPT desktop | `chatgpt_mcp_config.json` (when ChatGPT app data exists) |",
+    "",
+    "Claude Desktop paths by platform:",
+    "",
+    "- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`",
+    "- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`",
+    "- **Linux:** `~/.config/Claude/claude_desktop_config.json`",
+    "",
+    "ChatGPT desktop JSON (when auto-installed):",
+    "",
+    "- **macOS:** `~/Library/Application Support/ChatGPT/chatgpt_mcp_config.json`",
+    "- **Windows:** `%APPDATA%\\OpenAI\\ChatGPT\\chatgpt_mcp_config.json`",
+    "",
+    "Restart Claude Desktop and ChatGPT desktop after changing their config files.",
+    "",
+    "### Manual fallbacks",
+    "",
+    "**OpenCode** (no `~/.config/opencode` yet):",
+    "",
+    "```json",
+    JSON.stringify(
+      {
+        $schema: OPENCODE_CONFIG_SCHEMA,
+        mcp: { [serverId]: openCodeEntry },
+      },
+      null,
+      2,
+    ),
+    "```",
+    "",
+    "**Codex** (`codex` not on PATH):",
+    "",
+    "```toml",
+    `[mcp_servers.${serverId}]`,
+    `command = "${root.key}"`,
+    'args = ["mcp"]',
+    "```",
+    "",
+    `Or after installing Codex CLI: \`codex mcp add ${serverId} -- ${root.key} mcp\`.`,
+    "",
+    "### ChatGPT web (Connectors)",
+    "",
+    `OpenAI's documented path for **ChatGPT web/desktop** is **Settings → Connectors → Developer mode** with a **remote HTTPS MCP URL** — not local stdio. ChatGPT does not spawn \`${root.key} mcp\` directly.`,
+    "",
+    "For local stdio, bridge and tunnel, then register the HTTPS URL in Connectors:",
+    "",
+    `1. Expose \`${root.key} mcp\` over HTTP (e.g. \`mcp-remote\`).`,
+    "2. Tunnel if needed (ngrok, Cloudflare Tunnel).",
+    "3. Add the public URL as a custom connector.",
+    "",
+    "Desktop `chatgpt_mcp_config.json` is merged when the ChatGPT app is installed; support varies by build. Use Connectors when local JSON is absent or tools do not appear.",
+    "",
+  );
+}
 
 /** Formats one exposed MCP tool for the auto-generated MCP guide. */
 function formatToolLine(root: CliProgram, tool: McpToolDef): string {
@@ -24,23 +88,36 @@ export function generateMcpGuide(root: CliProgram): string {
   const tools = collectMcpTools(root);
   const schemaUri = resolveMcpSchemaUri(root);
   const serverId = mcpServerId(root);
-  const mcp = root.mcpServer!;
+  const mcp = root.mcpServer;
+  if (!mcp) {
+    throw new Error("MCP server not enabled");
+  }
+  const caps = resolveCapabilities(root);
 
   const lines: string[] = [
     `# MCP server (${root.key})`,
     "",
     `${root.key} exposes an MCP server with features similar to the CLI.`,
     "",
-    "## Quick start",
-    "",
-    "```bash",
-    `${root.key} mcp`,
-    "```",
-    "",
-    "## Client setup",
+    "## Installation",
     "",
     "### `install --mcp`",
     "",
+  ];
+
+  if (caps.install) {
+    lines.push(
+      `Install the CLI first so \`${root.key}\` is on your PATH (e.g. \`${root.key} install --bin --yes\` or \`install --all --yes\`). Host configs reference the binary by name.`,
+      "",
+    );
+  } else {
+    lines.push(
+      `The CLI binary \`${root.key}\` must already be on your PATH. Host configs reference it by name.`,
+      "",
+    );
+  }
+
+  lines.push(
     "```bash",
     `${root.key} install --mcp --yes`,
     "```",
@@ -52,18 +129,14 @@ export function generateMcpGuide(root: CliProgram): string {
     "| Cursor | `~/.cursor/mcp.json` (when `~/.cursor` exists) |",
     "| Claude Code | `~/.claude.json` |",
     "| Claude Desktop | `claude_desktop_config.json` (when Claude Desktop app data exists) |",
+  );
+
+  appendManualHostSetup(lines, root, serverId);
+
+  lines.push(
+    "### Manual `mcpServers` entry",
     "",
-    "Claude Desktop paths by platform:",
-    "",
-    "- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`",
-    "- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`",
-    "- **Linux:** `~/.config/Claude/claude_desktop_config.json`",
-    "",
-    "Restart Claude Desktop after changing its config.",
-    "",
-    "### Manual entry",
-    "",
-    "Add under `mcpServers` in the host config:",
+    "For Cursor, Claude, and ChatGPT desktop JSON configs, add under `mcpServers`:",
     "",
     "```json",
     JSON.stringify(
@@ -80,7 +153,15 @@ export function generateMcpGuide(root: CliProgram): string {
     ),
     "```",
     "",
-  ];
+    "## Running directly",
+    "",
+    "Start the stdio MCP server without editing host config:",
+    "",
+    "```bash",
+    `${root.key} mcp`,
+    "```",
+    "",
+  );
 
   if (mcp.shellEnv || mcp.envFile) {
     lines.push("## Environment", "");
@@ -91,7 +172,7 @@ export function generateMcpGuide(root: CliProgram): string {
     }
     if (mcp.envFile) {
       lines.push(
-        "- **`envFile`** — loads `" + mcp.envFile + "` after shell env (overrides for its keys).",
+        `- **\`envFile\`** — loads \`${mcp.envFile}\` after shell env (overrides for its keys).`,
       );
     }
     lines.push("");

package/src/docs/resolve.ts

@@ -1,6 +1,6 @@
-import type { CliDocsConfig, CliProgram } from "../types.ts";
 import { cliSchemaJson } from "../schema.ts";
 import { generateSkillBundle } from "../skill/generate.ts";
+import type { CliDocsConfig, CliProgram } from "../types.ts";
 import { generateApiGuide } from "./api-guide.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
 
@@ -31,7 +31,11 @@ export function docsEffectiveDefaultTopic(docs: CliDocsConfig): string {
   if (keys.length === 0) {
     throw new Error("docs.topics must be non-empty");
   }
-  return keys[0]!;
+  const first = keys[0];
+  if (first === undefined) {
+    throw new Error("docs.topics must be non-empty");
+  }
+  return first;
 }
 
 /** Whether MCP auto-guide topic is included. */
@@ -53,7 +57,10 @@ export function docsTopicDescription(key: string, custom?: string): string {
 
 /** Markdown body for one docs topic key. */
 export function docsTopicText(program: CliProgram, topic: string): string {
-  const docs = program.docs!;
+  const docs = program.docs;
+  if (!docs) {
+    throw new Error("docs not enabled");
+  }
   if (topic === "mcp") {
     if (!docsIncludesMcpTopic(program)) {
       throw new Error("Unknown docs topic 'mcp'.");

package/src/docs/save.ts

@@ -1,8 +1,8 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
 import type { CliProgram } from "../types.ts";
 import { docsTopicContent } from "./resolve.ts";
-import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
 
 /** Relative output directory for `docs --save`. */
 export const DOCS_SAVE_DIR = "docs";
@@ -21,12 +21,20 @@ export function docsSaveGeneratedHint(program: CliProgram, topic: string): strin
 }
 
 /** Inserts save hint without breaking YAML frontmatter (`docs skill`). */
-export function applySaveGeneratedHint(program: CliProgram, topic: string, content: string): string {
+export function applySaveGeneratedHint(
+  program: CliProgram,
+  topic: string,
+  content: string,
+): string {
   if (!docsTopicIsGeneratedByArgsbarg(topic)) {
     return content;
   }
   const hint = docsSaveGeneratedHint(program, topic);
-  return insertGeneratedHint(content, hint, topic === "skill" ? { afterFrontmatter: true } : undefined);
+  return insertGeneratedHint(
+    content,
+    hint,
+    topic === "skill" ? { afterFrontmatter: true } : undefined,
+  );
 }
 
 /** File body for `--save` (hint on argsbarg-generated markdown only). */

package/src/headless.test.ts

@@ -22,28 +22,20 @@ test("shouldRunHeadless is true for MCP and json", () => {
 });
 
 test("shouldRunHeadlessWithPositionals requires positionals in non-tty", () => {
-  expect(
-    shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, [], false, false),
-  ).toBe(false);
-  expect(
-    shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, ["a"], false, false),
-  ).toBe(true);
+  expect(shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, [], false, false)).toBe(
+    false,
+  );
+  expect(shouldRunHeadlessWithPositionals({ invocation: "cli" }, false, ["a"], false, false)).toBe(
+    true,
+  );
 });
 
 test("shouldRunHeadlessWithYes requires yes in non-tty", () => {
   expect(
-    shouldRunHeadlessWithYes(
-      { invocation: "cli" },
-      { yes: true, hasRequiredArgs: true },
-      false,
-    ),
+    shouldRunHeadlessWithYes({ invocation: "cli" }, { yes: true, hasRequiredArgs: true }, false),
   ).toBe(true);
   expect(
-    shouldRunHeadlessWithYes(
-      { invocation: "cli" },
-      { yes: false, hasRequiredArgs: true },
-      false,
-    ),
+    shouldRunHeadlessWithYes({ invocation: "cli" }, { yes: false, hasRequiredArgs: true }, false),
   ).toBe(false);
   expect(
     shouldRunHeadlessWithYes(