argsbarg 6.1.2 → 6.1.3

package/src/docs/{api-guide.test.ts → cli-guide.test.ts}

@@ -1,18 +1,18 @@
 /*
-Tests for docs/api-guide module behavior.
+Tests for docs/cli-guide module behavior.
 */
 
 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 "~/core/schema.ts";
+import type { CliProgram } from "~/core/types.ts";
+import { CliOptionKind } from "~/core/types.ts";
+import { generateCliGuide, generateCliGuideBody } from "./cli-guide.ts";
 
 const nestedFixture: CliProgram = {
   key: "nested.ts",
   version: "1.0.0",
   description: "Nested groups demo.",
-  docs: { enabled: true, topics: { readme: { text: "# readme\n" } } },
+  docs: { topics: { readme: { text: "# readme\n" } } },
   commands: [
     {
       key: "stat",
@@ -49,16 +49,16 @@ const nestedFixture: CliProgram = {
   ],
 };
 
-test("generateApiGuideBody matches command section of full API guide", () => {
-  const body = generateApiGuideBody(nestedFixture);
-  const full = generateApiGuide(nestedFixture);
+test("generateCliGuideBody matches command section of full API guide", () => {
+  const body = generateCliGuideBody(nestedFixture);
+  const full = generateCliGuide(nestedFixture);
   expect(full).toContain(body.trimEnd());
   expect(body).toContain("## `nested.ts stat`");
   expect(body).not.toContain("CLI API reference");
 });
 
-test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
-  const md = generateApiGuide(nestedFixture);
+test("generateCliGuide covers the same command keys as cliSchemaExport", () => {
+  const md = generateCliGuide(nestedFixture);
   const schema = cliSchemaExport(nestedFixture);
   expect(md).toContain("`nested.ts stat owner lookup`");
   expect(md).toContain("`--user-name` (`-u`)");
@@ -66,34 +66,34 @@ test("generateApiGuide covers the same command keys as cliSchemaExport", () => {
   expect(schema.commands?.map((c) => c.key)).toEqual(["stat"]);
 });
 
-test("generateApiGuide configure notes point to README not brew install", () => {
+test("generateCliGuide configure notes point to README not brew install", () => {
   const fixture: CliProgram = {
     key: "myapp",
     version: "1.0.0",
     description: "Demo app.",
     commands: [{ key: "run", description: "Run.", handler: () => {} }],
   };
-  const md = generateApiGuide(fixture);
+  const md = generateCliGuide(fixture);
   expect(md).not.toContain("{argsbarg:program}");
   expect(md).toContain("README");
   expect(md).not.toContain("brew install <tap>");
   expect(md).not.toContain("Upgrade to latest release");
 });
 
-test("generateApiGuide mentions Homebrew upgrade", () => {
+test("generateCliGuide mentions Homebrew upgrade", () => {
   const fixture: CliProgram = {
     key: "myapp",
     version: "1.0.0",
     description: "Demo app.",
     commands: [{ key: "run", description: "Run.", handler: () => {} }],
   };
-  const md = generateApiGuide(fixture);
+  const md = generateCliGuide(fixture);
   expect(md).toContain("brew upgrade");
   expect(md).not.toContain("install --update");
 });
 
-/** Tests that generateApiGuide resolves {argsbarg:program} in consumer notes. */
-test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
+/** Tests that generateCliGuide resolves {argsbarg:program} in consumer notes. */
+test("generateCliGuide resolves {argsbarg:program} in consumer notes", () => {
   const fixture: CliProgram = {
     key: "myapp",
     version: "1.0.0",
@@ -107,12 +107,12 @@ test("generateApiGuide resolves {argsbarg:program} in consumer notes", () => {
       },
     ],
   };
-  const md = generateApiGuide(fixture);
+  const md = generateCliGuide(fixture);
   expect(md).toContain("Invoke `myapp run`.");
 });
 
-/** Tests that generateApiGuide and cliSchemaExport include leaf outputSchema. */
-test("generateApiGuide and cliSchemaExport include leaf outputSchema", () => {
+/** Tests that generateCliGuide and cliSchemaExport include leaf outputSchema. */
+test("generateCliGuide and cliSchemaExport include leaf outputSchema", () => {
   const fixture: CliProgram = {
     key: "myapp",
     version: "1.0.0",
@@ -136,7 +136,7 @@ test("generateApiGuide and cliSchemaExport include leaf outputSchema", () => {
     properties: { id: { type: "string" } },
     required: ["id"],
   });
-  const md = generateApiGuide(fixture);
+  const md = generateCliGuide(fixture);
   expect(md).toContain("#### Output");
   expect(md).toContain('"id"');
   expect(md).toContain('"type": "string"');

package/src/docs/{api-guide.ts → cli-guide.ts}

@@ -1,8 +1,14 @@
-import type { CliSchemaExport } from "../builtins/export.ts";
-import { cliPositionalLabel, cliResolveNotes } from "../help.ts";
-import { cliSchemaExport } from "../schema.ts";
-import type { CliOption, CliPositional, CliProgram } from "../types.ts";
-import { CliFallbackMode, CliOptionKind } from "../types.ts";
+import type { CliSchemaExport } from "~/builtins/export.ts";
+import { cliSchemaExport } from "~/core/schema.ts";
+import type { CliOption, CliPositional, CliProgram } from "~/core/types.ts";
+import { CliFallbackMode, CliOptionKind } from "~/core/types.ts";
+import { cliPositionalLabel, cliResolveNotes } from "~/help.ts";
+
+/** Options for {@link generateCliGuideBody} and {@link generateCliGuide}. */
+export interface CliGuideBodyOptions {
+  /** Omit embedded outputSchema JSON; point to `docs cli-schema` instead (skill reference). */
+  compact?: boolean;
+}
 
 /** CLI invocation path as a single string (`myapp stat owner lookup`). */
 function commandPath(rootKey: string, path: string[]): string {
@@ -66,7 +72,7 @@ function formatNotesBlockquote(notes: string, appKey: string): string {
     .join("\n");
 }
 
-/** Markdown section for leaf outputSchema (docs api / skill reference). */
+/** Markdown section for leaf outputSchema (docs cli / skill reference). */
 function formatOutputSchemaSection(schema: Record<string, unknown>): string[] {
   return [
     "#### Output",
@@ -89,8 +95,19 @@ function fallbackLine(node: CliSchemaExport): string | null {
   return `**Default subcommand:** \`${node.fallbackCommand}\` (\`${mode}\`)`;
 }
 
+/** Compact outputSchema pointer instead of inlined JSON. */
+function formatOutputSchemaPointer(rootKey: string): string[] {
+  return ["#### Output", "", `See \`${rootKey} docs cli-schema\` for outputSchema when set.`, ""];
+}
+
 /** Renders one command node and recurses into subcommands. */
-function renderCommandNode(rootKey: string, path: string[], node: CliSchemaExport, lines: string[]): void {
+function renderCommandNode(
+  rootKey: string,
+  path: string[],
+  node: CliSchemaExport,
+  lines: string[],
+  opts: CliGuideBodyOptions,
+): void {
   const level = Math.min(path.length + 2, 6);
   const heading = "#".repeat(level);
   const cmd = commandPath(rootKey, path);
@@ -106,7 +123,15 @@ function renderCommandNode(rootKey: string, path: string[], node: CliSchemaExpor
     lines.push(fb, "");
   }
 
-  if ((node.options ?? []).length > 0) {
+  const isJsonStyleLeaf =
+    opts.compact &&
+    (node.options ?? []).length === 0 &&
+    (node.positionals ?? []).length === 0 &&
+    !node.commands?.length;
+
+  if (isJsonStyleLeaf) {
+    lines.push(`Input shape: see \`${rootKey} docs cli-schema\`.`, "");
+  } else if ((node.options ?? []).length > 0) {
     lines.push("#### Options", "");
     lines.push("| Option | Type | Required | Format / default | Description |");
     lines.push("| --- | --- | --- | --- | --- |");
@@ -127,7 +152,11 @@ function renderCommandNode(rootKey: string, path: string[], node: CliSchemaExpor
   }
 
   if (node.outputSchema !== undefined) {
-    lines.push(...formatOutputSchemaSection(node.outputSchema));
+    if (opts.compact) {
+      lines.push(...formatOutputSchemaPointer(rootKey));
+    } else {
+      lines.push(...formatOutputSchemaSection(node.outputSchema));
+    }
   }
 
   const children = node.commands ?? [];
@@ -140,20 +169,20 @@ function renderCommandNode(rootKey: string, path: string[], node: CliSchemaExpor
   }
 
   for (const child of children) {
-    renderCommandNode(rootKey, [...path, child.key], child, lines);
+    renderCommandNode(rootKey, [...path, child.key], child, lines, opts);
   }
 }
 
-/** Command-tree markdown shared by `docs api` and generated agent skills (no API doc header). */
-export function generateApiGuideBody(program: CliProgram): string {
+/** Command-tree markdown shared by `docs cli` and generated agent skills (no API doc header). */
+export function generateCliGuideBody(program: CliProgram, opts: CliGuideBodyOptions = {}): string {
   const schema = cliSchemaExport(program);
   const lines: string[] = [];
-  renderCommandNode(program.key, [], schema, lines);
+  renderCommandNode(program.key, [], schema, lines, opts);
   return `${lines.join("\n").trimEnd()}\n`;
 }
 
-/** Generates markdown API reference from the same export as `docs cli-schema`. */
-export function generateApiGuide(program: CliProgram): string {
+/** Generates markdown CLI reference from the same export as `docs cli-schema`. */
+export function generateCliGuide(program: CliProgram, opts: CliGuideBodyOptions = {}): string {
   const schema = cliSchemaExport(program);
   const lines: string[] = [
     `# ${program.key} — CLI API reference`,
@@ -168,6 +197,6 @@ export function generateApiGuide(program: CliProgram): string {
     lines.push(formatNotesBlockquote(schema.notes, program.key), "");
   }
 
-  lines.push(generateApiGuideBody(program).trimEnd(), "");
+  lines.push(generateCliGuideBody(program, opts).trimEnd(), "");
   return `${lines.join("\n").trimEnd()}\n`;
 }

package/src/docs/docs.test.ts

@@ -6,14 +6,15 @@ import { afterEach, beforeEach, expect, test } from "bun:test";
 import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { completionBashScript } from "../builtins/index.ts";
-import { cliPresentationRoot } from "../builtins/presentation.ts";
-import { resolveCapabilities, skipsRequiredAppConfigExit } from "../capabilities.ts";
-import { Cli } from "../index.ts";
-import type { CliProgram } from "../types.ts";
-import { cliValidateProgram } from "../validate.ts";
+import { completionBashScript } from "~/builtins";
+import { cliPresentationRoot } from "~/builtins/presentation.ts";
+import { ParseKind, parse } from "~/core/parse.ts";
+import type { CliProgram } from "~/core/types.ts";
+import { cliValidateProgram } from "~/core/validate.ts";
+import { cliHelpRender } from "~/help.ts";
+import { Cli } from "~/index";
+import { resolveCapabilities, skipsRequiredAppConfigExit } from "~/runtime/capabilities.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
-import { docsEffectiveDefaultTopic } from "./resolve.ts";
 import { saveDocsTopic } from "./save.ts";
 
 let workDir: string;
@@ -37,7 +38,6 @@ function docsFixture(mcp = true): CliProgram {
     description: "Demo app.",
     mcpServer: mcp ? { enabled: true } : undefined,
     docs: {
-      enabled: true,
       topics: {
         readme: { text: "# Hello README\n" },
         arch: { text: "# Architecture\n", description: "Contributor notes." },
@@ -72,16 +72,16 @@ test("docs reserved when enabled", () => {
 test("docs rejects reserved topic keys", () => {
   const root = docsFixture();
   const docs = root.docs;
-  if (!docs) throw new Error("expected docs fixture");
+  if (!docs?.topics) throw new Error("expected docs fixture");
   docs.topics["cli-schema"] = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
   delete docs.topics["cli-schema"];
   docs.topics.skill = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
   delete docs.topics.skill;
-  docs.topics.api = { text: "nope" };
+  docs.topics.cli = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
-  delete docs.topics.api;
+  delete docs.topics.cli;
   docs.topics.openapi = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
   delete docs.topics.openapi;
@@ -89,14 +89,57 @@ test("docs rejects reserved topic keys", () => {
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
 });
 
-test("docsEffectiveDefaultTopic uses first topic key", () => {
-  expect(docsEffectiveDefaultTopic(docsFixture().docs!)).toBe("readme");
+test("docs enabled by default without docs block", () => {
+  const root: CliProgram = {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo.",
+    commands: [{ key: "run", description: "Run.", handler: () => {} }],
+  };
+  expect(resolveCapabilities(root).docs).toBe(true);
+  cliValidateProgram(root);
 });
 
-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");
+test("docs opt-out allows user command named docs", () => {
+  const root: CliProgram = {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo.",
+    docs: { enabled: false },
+    commands: [
+      {
+        key: "docs",
+        description: "Custom docs.",
+        handler: () => {},
+      },
+    ],
+  };
+  expect(resolveCapabilities(root).docs).toBe(false);
+  cliValidateProgram(root);
+});
+
+test("built-in docs work without topics", async () => {
+  const root: CliProgram = {
+    key: "myapp",
+    version: "1.0.0",
+    description: "Demo.",
+    commands: [{ key: "run", description: "Run.", handler: () => {} }],
+  };
+  const cliRef = await new Cli(root).invoke(["docs", "cli"]);
+  expect(cliRef.exitCode).toBe(0);
+  expect(cliRef.stdout).toContain("CLI API reference");
+  const skill = await new Cli(root).invoke(["docs", "skill"]);
+  expect(skill.exitCode).toBe(0);
+  expect(skill.stdout).toContain("name: myapp");
+});
+
+test("bare docs shows router help", () => {
+  const root = cliPresentationRoot(docsFixture());
+  const pr = parse(root, ["docs"]);
+  expect(pr.kind).toBe(ParseKind.Help);
+  const help = cliHelpRender(root, pr.helpPath, false);
+  expect(help).toContain("cli");
+  expect(help).not.toContain("Hello README");
 });
 
 test("docs readme prints bundled text", async () => {
@@ -104,14 +147,6 @@ test("docs readme prints bundled text", async () => {
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("Hello README");
 });
-
-test("docs defaultTopic override", async () => {
-  const root = docsFixture();
-  root.docs!.defaultTopic = "arch";
-  const result = await new Cli(root).invoke(["docs"]);
-  expect(result.stdout).toContain("Architecture");
-});
-
 test("docs mcp when MCP enabled", async () => {
   const result = await new Cli(docsFixture(true)).invoke(["docs", "mcp"]);
   expect(result.exitCode).toBe(0);
@@ -140,7 +175,7 @@ test("docs mcp absent from router when MCP disabled", async () => {
 
 test("docs http when API enabled", async () => {
   const root = docsFixture(true);
-  root.apiServer = { enabled: true };
+  root.httpServer = { enabled: true };
   cliValidateProgram(root);
   const result = await new Cli(root).invoke(["docs", "http"]);
   expect(result.exitCode).toBe(0);
@@ -163,7 +198,7 @@ test("docs http absent from router when API disabled", async () => {
 
 test("docs openapi when API enabled", async () => {
   const root = docsFixture(true);
-  root.apiServer = { enabled: true };
+  root.httpServer = { enabled: true };
   cliValidateProgram(root);
   const result = await new Cli(root).invoke(["docs", "openapi"]);
   expect(result.exitCode).toBe(0);
@@ -193,8 +228,8 @@ test("docs cli-schema prints JSON", async () => {
   expect(schema.commands.some((c: { key: string }) => c.key === "run")).toBe(true);
 });
 
-test("docs api prints markdown reference", async () => {
-  const result = await new Cli(docsFixture()).invoke(["docs", "api"]);
+test("docs cli prints markdown reference", async () => {
+  const result = await new Cli(docsFixture()).invoke(["docs", "cli"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout).toContain("# myapp — CLI API reference");
   expect(result.stdout).toContain("## `myapp run`");
@@ -210,7 +245,7 @@ test("skipsRequiredAppConfigExit includes docs and config builtins", () => {
     },
   };
   const caps = resolveCapabilities(program);
-  expect(skipsRequiredAppConfigExit(["docs", "api"], caps)).toBe(true);
+  expect(skipsRequiredAppConfigExit(["docs", "cli"], caps)).toBe(true);
   expect(skipsRequiredAppConfigExit(["configure", "get"], caps)).toBe(true);
   expect(skipsRequiredAppConfigExit(["run"], caps)).toBe(false);
 });
@@ -247,7 +282,7 @@ test("presentation includes docs cli-schema and skill", () => {
   expect(docsNode && "commands" in docsNode).toBe(true);
   if (docsNode && "commands" in docsNode) {
     expect(docsNode.commands.some((c) => c.key === "cli-schema")).toBe(true);
-    expect(docsNode.commands.some((c) => c.key === "api")).toBe(true);
+    expect(docsNode.commands.some((c) => c.key === "cli")).toBe(true);
     expect(docsNode.commands.some((c) => c.key === "skill")).toBe(true);
   }
 });
@@ -257,7 +292,7 @@ test("completions offer docs subcommands", () => {
   expect(bash).toContain("docs) echo");
   expect(bash).toContain("readme) echo");
   expect(bash).toContain("cli-schema) echo");
-  expect(bash).toContain("api) echo");
+  expect(bash).toContain("cli) echo");
   expect(bash).toContain("skill) echo");
 });
 
@@ -283,11 +318,11 @@ test("docs --save writes topic file", async () => {
   expect(text).not.toContain("Generated by");
 });
 
-test("docs api --save prepends generated hint", async () => {
-  const result = await new Cli(docsFixture()).invoke(["docs", "api", "--save"]);
+test("docs cli --save prepends generated hint", async () => {
+  const result = await new Cli(docsFixture()).invoke(["docs", "cli", "--save"]);
   expect(result.exitCode).toBe(0);
-  const text = readFileSync(join(workDir, "docs/api.md"), "utf8");
-  expect(text.startsWith("<!-- Generated by myapp docs api --save; do not edit. -->\n\n")).toBe(true);
+  const text = readFileSync(join(workDir, "docs/cli.md"), "utf8");
+  expect(text.startsWith("<!-- Generated by myapp docs cli --save; do not edit. -->\n\n")).toBe(true);
   expect(text).toContain("CLI API reference");
 });
 
@@ -313,7 +348,7 @@ test("docs cli-schema --save writes JSON file", async () => {
 
 test("docs openapi --save writes JSON file", async () => {
   const root = docsFixture(true);
-  root.apiServer = { enabled: true };
+  root.httpServer = { enabled: true };
   const result = await new Cli(root).invoke(["docs", "openapi", "--save"]);
   expect(result.exitCode).toBe(0);
   expect(result.stdout.trim()).toBe("docs/openapi.json");
@@ -324,9 +359,9 @@ test("docs openapi --save writes JSON file", async () => {
 });
 
 test("saveDocsTopic returns relative path", () => {
-  const path = saveDocsTopic(docsFixture(), "api");
-  expect(path).toBe("docs/api.md");
-  const text = readFileSync(join(workDir, "docs/api.md"), "utf8");
-  expect(text).toContain("<!-- Generated by myapp docs api --save; do not edit. -->");
+  const path = saveDocsTopic(docsFixture(), "cli");
+  expect(path).toBe("docs/cli.md");
+  const text = readFileSync(join(workDir, "docs/cli.md"), "utf8");
+  expect(text).toContain("<!-- Generated by myapp docs cli --save; do not edit. -->");
   expect(text).toContain("CLI API reference");
 });

package/src/docs/http-guide.ts

@@ -1,15 +1,15 @@
-import { resolveApiListenAddress } from "../api/server.ts";
-import { defaultConfigEntryTitle } from "../config/entry.ts";
-import { displayAppConfigPath } from "../config/file.ts";
-import { collectMcpTools, type McpToolDef } from "../mcp/tools.ts";
-import { collectOptionDefs } from "../parse.ts";
-import { CliOptionKind, type CliProgram } from "../types.ts";
+import { defaultConfigEntryTitle } from "~/config/entry.ts";
+import { displayAppConfigPath } from "~/config/file.ts";
+import { collectOptionDefs } from "~/core/parse.ts";
+import { CliOptionKind, type CliProgram } from "~/core/types.ts";
+import { collectHttpRoutes } from "~/http/routes.ts";
+import { resolveHttpListenAddress } from "~/http/server.ts";
 
-/** Formats one exposed tool for the auto-generated HTTP guide. */
-function formatToolLine(root: CliProgram, tool: McpToolDef): string {
-  const cliPath = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
-  let line = `- \`${tool.apiName}\` (MCP: \`${tool.name}\`, CLI: \`${cliPath}\`) — ${tool.description}`;
-  const opts = collectOptionDefs(root, tool.path);
+/** Formats one HTTP route for the auto-generated HTTP guide. */
+function formatRouteLine(root: CliProgram, route: ReturnType<typeof collectHttpRoutes>[number]): string {
+  const cliPath = route.commandPath.join(" ");
+  let line = `- \`${route.method} ${route.openApiPath}\` (CLI: \`${root.key} ${cliPath}\`) — ${route.leaf.description}`;
+  const opts = collectOptionDefs(root, route.commandPath);
   const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
   if (flags.length > 0) {
     line += ` (flags: ${flags.join(", ")})`;
@@ -19,27 +19,27 @@ function formatToolLine(root: CliProgram, tool: McpToolDef): string {
 
 /** Generates the auto `docs http` markdown guide from schema and API config. */
 export function generateHttpGuide(root: CliProgram): string {
-  const api = root.apiServer;
+  const api = root.httpServer;
   if (!api) {
     throw new Error("HTTP API server not enabled");
   }
 
-  const tools = collectMcpTools(root);
-  const { hostname, port } = resolveApiListenAddress(root);
+  const routes = collectHttpRoutes(root);
+  const { hostname, port } = resolveHttpListenAddress(root);
   const baseUrl = `http://${hostname}:${port}`;
 
   const lines: string[] = [
     `# HTTP API (${root.key})`,
     "",
-    `${root.key} exposes the same callable tools over HTTP as MCP.`,
+    `${root.key} exposes user commands over HTTP REST routes derived from the CLI tree.`,
     "",
     "## Running",
     "",
     "```bash",
-    `${root.key} api`,
+    `${root.key} http`,
     "```",
     "",
-    `Listens on **${baseUrl}** by default (\`apiServer.host\` / \`apiServer.port\`).`,
+    `Listens on **${baseUrl}** by default (\`httpServer.host\` / \`httpServer.port\`).`,
     "",
     "Bind is localhost-only in v0 — use a reverse proxy for remote access.",
     "",
@@ -47,27 +47,30 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     "| Method | Path | Purpose |",
     "| --- | --- | --- |",
-    "| `GET` | `/health` | Liveness check |",
-    "| `GET` | `/openapi.json` | OpenAPI 3.1 document (tool paths and request shapes) |",
+    "| `GET` | `/health` or `/health/live` | Liveness check |",
+    "| `GET` | `/health/ready` | Readiness (config + `program.readiness`) |",
+    "| `GET` | `/openapi.json` | OpenAPI 3.1 REST paths |",
     "| `GET` | `/openapi-browser` | Interactive Scalar API reference |",
-    "| `POST` | `/tools/:name` | Invoke with flat JSON args object in the body |",
+    "| `*` | `/api/...` | Invoke user commands (method per route) |",
     "| `OPTIONS` | `*` | CORS preflight |",
     "",
-    "Replace `{tool-key}` below with a path segment from `openapi.json` (`paths` keys are `/tools/{tool-key}`). Match body keys to that tool's `requestBody` schema in the spec.",
+    "Discover paths from `openapi.json` (`/api/...`). Query binds options; POST/PUT/PATCH body binds options and `inputSchema` fields.",
     "",
     "## Examples",
     "",
     "```bash",
     `curl -s ${baseUrl}/health`,
+    `curl -s ${baseUrl}/health/ready`,
     `curl -s ${baseUrl}/openapi.json`,
-    `curl -s -X POST ${baseUrl}/tools/{tool-key} \\`,
+    `curl -s ${baseUrl}/api/workspaces`,
+    `curl -s -X POST ${baseUrl}/api/workspaces \\`,
     '  -H "content-type: application/json" \\',
-    "  -d '{...}'",
+    `  -d '{"name":"qa2"}'`,
     "```",
     "",
     "## Responses",
     "",
-    "Success (`200`): raw response body (JSON object, string, or binary). No `{ ok, stdout }` envelope.",
+    "Success: status from handler → `http.successStatus` → method default (GET 200, POST 201, DELETE 204).",
     "",
     "Handlers must use `ctx.respond()` or return a value for API/MCP tool calls.",
     "",
@@ -92,29 +95,29 @@ export function generateHttpGuide(root: CliProgram): string {
     lines.push("");
   }
 
-  lines.push("## Exposed tools", "");
+  lines.push("## REST routes", "");
 
-  if (tools.length === 0) {
-    lines.push("(No tools exposed.)", "");
+  if (routes.length === 0) {
+    lines.push("(No routes exposed.)", "");
   } else {
-    for (const tool of tools) {
-      lines.push(formatToolLine(root, tool));
+    for (const route of routes) {
+      lines.push(formatRouteLine(root, route));
     }
     lines.push("");
   }
 
   lines.push(
-    "## Tool arguments",
+    "## Request bodies",
     "",
-    "POST bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
+    "POST/PUT/PATCH bodies are a flat JSON object keyed by long option and positional names (hyphenated option names are valid keys).",
     "",
-    `For HTTP clients, use **\`GET /openapi.json\`** (or **\`GET /openapi-browser\`**) for per-tool request shapes — each \`POST /tools/{name}\` path has a \`requestBody\` schema.`,
+    `For HTTP clients, use **\`GET /openapi.json\`** (or **\`GET /openapi-browser\`**) for per-route request shapes.`,
     "",
     "Varargs positionals accept a JSON array of strings (not a comma-separated string).",
     "Options with `format: comma-list` accept a comma-separated string or JSON array.",
     "Options with a schema `default` are applied when omitted.",
     "",
-    `Shell invocation reference: \`${root.key} docs api\`. Full CLI tree JSON: \`${root.key} docs cli-schema\`.`,
+    `Shell invocation reference: \`${root.key} docs cli\`. Full CLI tree JSON: \`${root.key} docs cli-schema\`.`,
     "",
     "## OpenAPI",
     "",
@@ -124,7 +127,7 @@ export function generateHttpGuide(root: CliProgram): string {
     `- **Fetch** — \`curl -s ${baseUrl}/openapi.json\``,
     `- **Save offline** — \`${root.key} docs openapi --save\` → \`./docs/openapi.json\` (or \`just docgen\` in app repos)`,
     "",
-    "Use the spec to discover tool names (`paths`) and request/response shapes before calling `POST /tools/:name`.",
+    "Use the spec to discover REST paths and request/response shapes before calling `/api/...`.",
     "",
   );
 

package/src/docs/mcp-guide.ts

@@ -1,12 +1,12 @@
-import { resolveCapabilities } from "../capabilities.ts";
-import { defaultConfigEntryTitle } from "../config/entry.ts";
-import { displayAppConfigPath } from "../config/file.ts";
-import { expectedOpenCodeMcpEntry, OPENCODE_CONFIG_SCHEMA } from "../install/mcp-opencode.ts";
-import { collectMcpTools, type McpToolDef, mcpServerId, resolveMcpSchemaUri } from "../mcp/tools.ts";
-import { collectOptionDefs } from "../parse.ts";
-import { CliOptionKind, type CliProgram } from "../types.ts";
+import { defaultConfigEntryTitle } from "~/config/entry.ts";
+import { displayAppConfigPath } from "~/config/file.ts";
+import { expectedOpenCodeMcpEntry, OPENCODE_CONFIG_SCHEMA } from "~/configure/artifacts/mcp-opencode.ts";
+import { collectOptionDefs } from "~/core/parse.ts";
+import { CliOptionKind, type CliProgram } from "~/core/types.ts";
+import { collectMcpTools, type McpToolDef, mcpServerId, resolveMcpSchemaUri } from "~/mcp/tools.ts";
+import { resolveCapabilities } from "~/runtime/capabilities.ts";
 import { resolveDocsTopicResourceUri } from "./mcp-resources.ts";
-import { docsEnabled, docsUserTopicKeys } from "./resolve.ts";
+import { docsEnabled, docsUserTopicKeys, resolveDocsConfig } from "./resolve.ts";
 
 /** Extra host notes for generated `docs mcp` (manual fallbacks and ChatGPT Connectors). */
 function appendManualHostSetup(lines: string[], root: CliProgram, serverId: string): void {
@@ -205,12 +205,10 @@ export function generateMcpGuide(root: CliProgram): string {
     `| Schema resource | \`${schemaUri}\` — same JSON as \`${root.key} docs cli-schema\` |`,
   );
   if (docsEnabled(root)) {
-    const docs = root.docs;
-    if (docs) {
-      for (const key of docsUserTopicKeys(docs)) {
-        const uri = resolveDocsTopicResourceUri(root, key);
-        lines.push(`| Docs topic \`${key}\` | \`${uri}\` — same markdown as \`${root.key} docs ${key}\` |`);
-      }
+    const docs = resolveDocsConfig(root);
+    for (const key of docsUserTopicKeys(docs)) {
+      const uri = resolveDocsTopicResourceUri(root, key);
+      lines.push(`| Docs topic \`${key}\` | \`${uri}\` — same markdown as \`${root.key} docs ${key}\` |`);
     }
   }
   lines.push("", "## Exposed tools", "");