argsbarg 4.0.3 → 4.1.0

package/src/parse.test.ts

@@ -20,7 +20,7 @@ import {
 } from "./mcp/tools.ts";
 import { ParseKind, parse, postParseValidate } from "./parse.ts";
 import { cliSchemaJson } from "./schema.ts";
-import { generateSkillBundle } from "./skill/generate.ts";
+import { generatePluginSkillBundle, generateSkillBundle } from "./skill/generate.ts";
 import { cliSkillInstall } from "./skill/install.ts";
 import {
   enumMcpFixture,
@@ -614,7 +614,7 @@ test("cliSchemaExport resolves program key in install notes", () => {
 
   const json = cliSchemaJson(root);
   expect(json).not.toContain("{argsbarg:program}");
-  expect(json).toContain("myapp install --all --yes");
+  expect(json).toContain("myapp install --yes");
 });
 
 test("cliSchemaExport resolves {argsbarg:program} in consumer notes", () => {
@@ -835,7 +835,7 @@ test("cliValidateProgram rejects resource URI matching default schema URI", () =
     },
     commands: [{ key: "x", description: "", handler: () => {} }],
   });
-  expect(() => cliValidateProgram(root)).toThrow(/conflicts with the built-in schema resource/);
+  expect(() => cliValidateProgram(root)).toThrow(/conflicts with built-in schema resource/);
 });
 
 test("cliValidateProgram rejects resource URI matching schemaResourceUri", () => {
@@ -849,7 +849,21 @@ test("cliValidateProgram rejects resource URI matching schemaResourceUri", () =>
     },
     commands: [{ key: "x", description: "", handler: () => {} }],
   });
-  expect(() => cliValidateProgram(root)).toThrow(/conflicts with the built-in schema resource/);
+  expect(() => cliValidateProgram(root)).toThrow(/conflicts with built-in schema resource/);
+});
+
+test("cliValidateProgram rejects resource URI matching auto docs topic", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    docs: { enabled: true, topics: { readme: { text: "# r\n" } } },
+    mcpServer: {
+      enabled: true,
+      resources: [{ uri: "app://docs/readme", name: "dup", load: () => "" }],
+    },
+    commands: [{ key: "x", description: "", handler: () => {} }],
+  });
+  expect(() => cliValidateProgram(root)).toThrow(/conflicts with auto docs topic resource/);
 });
 
 test("allMcpResources includes custom resources", () => {
@@ -867,6 +881,20 @@ test("allMcpResources includes custom resources", () => {
   expect(resources.map((r) => r.uri)).toContain("test://x");
 });
 
+test("allMcpResources includes docs topic resources", () => {
+  const root = testProgram({
+    key: "app",
+    description: "",
+    docs: { enabled: true, topics: { readme: { text: "# hi\n" } } },
+    mcpServer: { enabled: true },
+    commands: [{ key: "leaf", description: "", handler: () => {} }],
+  });
+  const resources = allMcpResources(root);
+  expect(resources.map((r) => r.uri)).toContain("app://docs/readme");
+  const readme = resources.find((r) => r.uri === "app://docs/readme");
+  expect(readme?.load()).toBe("# hi\n");
+});
+
 test("applyShellEnv merges PATH and preserves host vars", () => {
   const origPath = process.env.PATH ?? "";
   const origHome = process.env.HOME;
@@ -1096,6 +1124,17 @@ test("install config on non-root node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/install is only supported on the program root/);
 });
 
+test("install.prefix is rejected", () => {
+  const root = {
+    key: "app",
+    version: "0.0.0",
+    description: "",
+    install: { prefix: "/opt/bin" },
+    handler: () => {},
+  } as unknown as CliProgram;
+  expect(() => cliValidateProgram(root)).toThrow(/install\.prefix removed/);
+});
+
 test("generateSkillBundle includes frontmatter and compact command index", () => {
   const bundle = generateSkillBundle(nestedMcpFixture, "cursor");
   expect(bundle.dirName).toBe("nested_ts");
@@ -1116,6 +1155,20 @@ test("generateSkillBundle includes frontmatter and compact command index", () =>
   expect(bundle.referenceMd).not.toContain("```json");
 });
 
+test("generatePluginSkillBundle is MCP routing stub without shell catalog", () => {
+  const bundle = generatePluginSkillBundle(nestedMcpFixture);
+  expect(bundle.dirName).toBe("nested_ts");
+  expect(bundle.skillMd).toMatch(/^---\nname: nested_ts\n/);
+  expect(bundle.skillMd).toContain("MCP toolset");
+  expect(bundle.skillMd).toContain("Server id: `nested_ts`");
+  expect(bundle.skillMd).toContain("nested_ts://schema");
+  expect(bundle.skillMd).toContain("tools/list");
+  expect(bundle.skillMd).not.toContain("Invoke via shell");
+  expect(bundle.skillMd).not.toContain("reference.md");
+  expect(bundle.skillMd).not.toContain("`nested.ts stat owner lookup <path>`");
+  expect(bundle.skillMd).not.toContain("## Commands");
+});
+
 test("cliSkillInstall writes project Cursor skill files", () => {
   const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-"));
   const prev = process.cwd();

package/src/paths/host.ts

@@ -21,20 +21,20 @@ export function expandTilde(path: string): string {
   return path;
 }
 
+/** Display path using `~/` when under the user home directory. */
+export function displayHomePath(absolutePath: string, home = userHome()): string {
+  if (home.length > 0 && absolutePath.startsWith(home)) {
+    return `~${absolutePath.slice(home.length)}`;
+  }
+  return absolutePath;
+}
+
 /** XDG config base directory (`$XDG_CONFIG_HOME` or `~/.config`). */
 export function xdgConfigHome(home = userHome()): string {
   return process.env.XDG_CONFIG_HOME ?? join(home, ".config");
 }
 
-/** Windows `%APPDATA%` (or `~/AppData/Roaming`). */
-export function appDataHome(home = userHome()): string {
-  return process.env.APPDATA ?? join(home, "AppData", "Roaming");
-}
-
-/** OS-appropriate base directory for app config files. */
-export function appConfigHome(home = userHome()): string {
-  if (process.platform === "win32") {
-    return appDataHome(home);
-  }
-  return xdgConfigHome(home);
+/** App config library root (`~/.local/lib`). */
+export function appConfigLibHome(home = userHome()): string {
+  return join(home, ".local", "lib");
 }

package/src/paths/remove-empty-dir.ts

@@ -0,0 +1,13 @@
+import { existsSync, readdirSync, rmdirSync } from "node:fs";
+
+/** Removes a directory when it exists and is empty. Returns true when removed. */
+export function removeEmptyDir(path: string): boolean {
+  if (!existsSync(path)) return false;
+  try {
+    if (readdirSync(path).length > 0) return false;
+    rmdirSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/skill/generate.ts

@@ -4,11 +4,19 @@ This module generates Agent Skills content (SKILL.md + reference.md) from a CLI
 
 import { defaultConfigEntryTitle } from "../config/entry.ts";
 import { generateApiGuide } from "../docs/api-guide.ts";
-import { collectMcpTools, type McpToolDef, sanitizeToolSegment } from "../mcp/tools.ts";
+import {
+  collectMcpTools,
+  type McpToolDef,
+  mcpServerId,
+  resolveMcpSchemaUri,
+  sanitizeToolSegment,
+} from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
 import { CliOptionKind, type CliProgram } from "../types.ts";
+import type { SkillTarget } from "./naming.ts";
+import { skillDirNameForTarget, skillFrontmatterName } from "./naming.ts";
 
-export type SkillTarget = "cursor" | "claude";
+export type { SkillTarget } from "./naming.ts";
 
 export interface SkillBundle {
   dirName: string;
@@ -16,12 +24,28 @@ export interface SkillBundle {
   referenceMd: string;
 }
 
+/** MCP routing skill for Claude Code plugin zips (SKILL.md only). */
+export interface PluginSkillBundle {
+  dirName: string;
+  skillMd: string;
+}
+
 /** Truncates text to maxLen with ellipsis. */
 function truncate(text: string, maxLen: number): string {
   if (text.length <= maxLen) return text;
   return `${text.slice(0, maxLen - 1)}…`;
 }
 
+/** Builds MCP-oriented skill description for Claude plugin YAML frontmatter. */
+function pluginSkillDescription(root: CliProgram): string {
+  const tools = collectMcpTools(root);
+  const paths = tools.map((t) => (t.path.length > 0 ? t.path.join(" ") : root.key));
+  const sample = paths.slice(0, 5).join(", ");
+  const more = paths.length > 5 ? `, and ${paths.length - 5} more` : "";
+  const desc = `Use the ${root.key} MCP toolset (${sample}${more}). Use when the user mentions ${root.key}${paths.length > 0 ? `, ${paths.slice(0, 3).join(", ")}` : ""}, or related tasks.`;
+  return truncate(desc, 1024);
+}
+
 /** Builds third-person skill description for YAML frontmatter. */
 function skillDescription(root: CliProgram): string {
   const tools = collectMcpTools(root);
@@ -81,7 +105,7 @@ function buildConfigurationSection(root: CliProgram): string[] {
 
 /** Builds SKILL.md body for the given target. */
 function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): string {
-  const name = sanitizeToolSegment(root.key);
+  const name = skillFrontmatterName(root.key, target);
   const description = skillDescription(root);
   const tools = collectMcpTools(root);
 
@@ -139,7 +163,7 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
       "Do not install under `~/.cursor/skills-cursor/` (reserved for Cursor built-ins).",
       "",
     );
-  } else {
+  } else if (target === "claude") {
     lines.push(
       "## Claude Code",
       "",
@@ -149,6 +173,18 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
       `- Bundled files in this directory are available via \`\${CLAUDE_SKILL_DIR}\` when the skill runs.`,
       "",
     );
+  } else if (target === "codex") {
+    lines.push(
+      "## Codex",
+      "",
+      `- Global: \`~/.codex/skills/${dirName}/\``,
+      "- Enable skills in `~/.codex/config.toml` if required.",
+      "",
+    );
+  } else if (target === "opencode") {
+    lines.push("## OpenCode", "", `- Global: \`~/.config/opencode/skills/${dirName}/\``, "");
+  } else {
+    lines.push("## OpenClaw", "", `- Global: \`~/.openclaw/skills/${dirName}/\``, "");
   }
 
   return lines.join("\n");
@@ -159,9 +195,57 @@ function buildReferenceMd(root: CliProgram): string {
   return generateApiGuide(root);
 }
 
+/** Builds MCP routing SKILL.md for Claude Code plugin zips. */
+function buildPluginSkillMd(root: CliProgram, dirName: string): string {
+  const name = sanitizeToolSegment(root.key);
+  const description = pluginSkillDescription(root);
+  const serverId = mcpServerId(root);
+  const schemaUri = resolveMcpSchemaUri(root);
+
+  const lines: string[] = [
+    "---",
+    `name: ${name}`,
+    `description: ${description}`,
+    "---",
+    "",
+    `# ${root.key}`,
+    "",
+    root.description,
+    "",
+    "## Execution",
+    "",
+    "This plugin bundles an MCP server. Use MCP tools to fulfill requests.",
+    "",
+    `- Server id: \`${serverId}\` (configured in plugin \`.mcp.json\`)`,
+    "- Tool names and argument shapes come from MCP `tools/list`",
+    `- Full schema: \`${schemaUri}\` (same as \`${root.key} docs schema\`)`,
+    "",
+  ];
+
+  lines.push(...buildConfigurationSection(root));
+
+  lines.push(
+    "## Claude Code plugin",
+    "",
+    `Invoke with \`/${dirName}\` or let Claude auto-match from the description.`,
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+/** Generates MCP routing SKILL.md for Claude Code plugin zips. */
+export function generatePluginSkillBundle(root: CliProgram): PluginSkillBundle {
+  const dirName = sanitizeToolSegment(root.key);
+  return {
+    dirName,
+    skillMd: buildPluginSkillMd(root, dirName),
+  };
+}
+
 /** Generates SKILL.md and reference.md for Cursor or Claude Code. */
 export function generateSkillBundle(root: CliProgram, target: SkillTarget): SkillBundle {
-  const dirName = sanitizeToolSegment(root.key);
+  const dirName = skillDirNameForTarget(root.key, target);
   return {
     dirName,
     skillMd: buildSkillMd(root, target, dirName),

package/src/skill/hint.ts

@@ -58,3 +58,8 @@ export function applySkillBundleHints(
     referenceMd: insertGeneratedHint(referenceMd, hint),
   };
 }
+
+/** Applies bundle hint to plugin SKILL.md (after frontmatter). */
+export function applyPluginSkillHint(program: CliProgram, skillMd: string): string {
+  return insertGeneratedHint(skillMd, skillBundleHint(program), { afterFrontmatter: true });
+}

package/src/skill/install.ts

@@ -5,19 +5,28 @@ import type { CliProgram } from "../types.ts";
 import { generateSkillBundle, type SkillTarget } from "./generate.ts";
 import { applySkillInstallHints } from "./hint.ts";
 
+export { skillDirNameForTarget, skillFrontmatterName, skillSlug } from "./naming.ts";
+
 export interface SkillInstallOpts {
   global?: boolean;
-  /** When true, remove an existing skill directory before writing. */
   rimraf?: boolean;
-  /** When true, skip writes but return paths that would change. */
   dry?: boolean;
 }
 
 function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean): string {
-  const base = global
-    ? join(userHome(), target === "cursor" ? ".cursor" : ".claude", "skills")
-    : join(process.cwd(), target === "cursor" ? ".cursor" : ".claude", "skills");
-  return join(base, dirName);
+  const home = userHome();
+  switch (target) {
+    case "cursor":
+      return join(global ? home : process.cwd(), ".cursor", "skills", dirName);
+    case "claude":
+      return join(global ? home : process.cwd(), ".claude", "skills", dirName);
+    case "codex":
+      return join(global ? home : process.cwd(), ".codex", "skills", dirName);
+    case "opencode":
+      return join(global ? home : process.cwd(), ".config", "opencode", "skills", dirName);
+    case "openclaw":
+      return join(global ? home : process.cwd(), ".openclaw", "skills", dirName);
+  }
 }
 
 /** Writes SKILL.md and reference.md; returns changed file paths. */
@@ -47,3 +56,21 @@ export function cliSkillInstall(
   changed.push(skillPath, refPath);
   return changed;
 }
+
+/** Maps install action kind to skill target. */
+export function skillTargetFromActionKind(kind: string): SkillTarget | undefined {
+  switch (kind) {
+    case "cursor-skill":
+      return "cursor";
+    case "claude-skill":
+      return "claude";
+    case "codex-skill":
+      return "codex";
+    case "opencode-skill":
+      return "opencode";
+    case "openclaw-skill":
+      return "openclaw";
+    default:
+      return undefined;
+  }
+}

package/src/skill/naming.ts

@@ -0,0 +1,28 @@
+/** Agent skill install targets. */
+export type SkillTarget = "cursor" | "claude" | "codex" | "opencode" | "openclaw";
+
+import { sanitizeToolSegment } from "../mcp/tools.ts";
+
+/** Kebab-case skill folder + frontmatter name for agents that require hyphen slugs. */
+export function skillSlug(programKey: string): string {
+  return programKey
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+/** Directory name for a skill target (underscore vs kebab conventions). */
+export function skillDirNameForTarget(programKey: string, target: SkillTarget): string {
+  if (target === "cursor" || target === "claude") {
+    return sanitizeToolSegment(programKey);
+  }
+  return skillSlug(programKey);
+}
+
+/** Frontmatter `name` for SKILL.md by target. */
+export function skillFrontmatterName(programKey: string, target: SkillTarget): string {
+  if (target === "cursor" || target === "claude") {
+    return sanitizeToolSegment(programKey);
+  }
+  return skillSlug(programKey);
+}

package/src/types.ts

@@ -133,6 +133,10 @@ export interface CliMcpBundleConfig {
 export interface CliMcpServerConfig {
   /** When `true`, enables the `mcp` built-in and MCP stdio server. */
   enabled: boolean;
+  /** When `true`, `mcp bundle` writes `dist/<key>.mcpb` for Claude Desktop. Default false. */
+  mcpd?: boolean;
+  /** When `true`, `mcp bundle` also writes `dist/claude-plugin/<name>.zip`. Default false. */
+  claudePlugin?: boolean;
   /** Resource URI for schema export (default: `<sanitized root key>://schema`). */
   schemaResourceUri?: string;
   /**
@@ -224,8 +228,6 @@ export interface CliAppConfigEntry {
  * App configuration block on the program root ({@link CliProgram.appConfig}).
  */
 export interface CliAppConfig {
-  /** Default: `~/.config/<sanitized-key>/config` (or `%APPDATA%/<key>/config` on Windows). */
-  path?: string;
   /** Built-in `config get` / `config set`. Default: enabled when `appConfig` is set. */
   commands?: boolean | { enabled?: boolean; mcpSet?: boolean };
   /** Block JSON Schema (draft-07). When omitted, synthesize all-string schema from `entries`. */
@@ -237,8 +239,15 @@ export interface CliAppConfig {
 export interface CliInstallConfig {
   /** When `false`, hide/disable `install` (default: enabled). */
   enabled?: boolean;
-  /** Default bin directory (default: `~/.local/bin`). Overridden by `INSTALL_PREFIX` env and `--prefix`. */
-  prefix?: string;
+  /**
+   * Default agent integration for full install (`install --all`).
+   * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in `--all`; paired skills excluded.
+   * - `'skill'` when MCP is off (default): skill targets in `--all`; paired MCP excluded.
+   * - `'both'`: install MCP and skill for the same host when both are available.
+   */
+  agentIntegration?: InstallAgentIntegration;
+  /** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
+  targets?: CliInstallTargets;
   /**
    * When set, enables `install --update` on the program root.
    * Should download or locate the latest release binary and return its path.
@@ -246,6 +255,58 @@ export interface CliInstallConfig {
   updateGetLatest?: CliUpdateGetLatest;
 }
 
+/** Agent integration mode for install — MCP vs shell skill per host. */
+export type InstallAgentIntegration = "mcp" | "skill" | "both";
+
+/** Boolean or structured gate for one install artifact. */
+export type InstallTargetSpec =
+  | boolean
+  | {
+      /** When false, artifact is never installed (even with scoped CLI flags). Default true. */
+      enabled?: boolean;
+      /** When true, included in bare `install` / `install --all`. Default varies by key. */
+      includedInAll?: boolean;
+    };
+
+export interface ResolvedInstallTarget {
+  enabled: boolean;
+  includedInAll: boolean;
+}
+
+/** Per-artifact gates for full install/uninstall. See {@link resolveEffectiveInstallTargets}. */
+export interface CliInstallTargets {
+  /** Copy app to `~/.local/bin/<key>`. Default includedInAll true (opt-out). */
+  app?: InstallTargetSpec;
+  /** ChatGPT desktop MCP. Default false. */
+  chatgptMcp?: InstallTargetSpec;
+  /** Claude Code MCP (`~/.claude.json`). Default false. */
+  claudeCodeMcp?: InstallTargetSpec;
+  /** Claude Desktop MCP. Default false. */
+  claudeDesktopMcp?: InstallTargetSpec;
+  /** Claude Code skill. Default false. */
+  claudeSkill?: InstallTargetSpec;
+  /** Codex MCP (`codex mcp add`). Default false. */
+  codexMcp?: InstallTargetSpec;
+  /** Codex skill. Default false. */
+  codexSkill?: InstallTargetSpec;
+  /** Shell completions for detected shells. Default includedInAll true (opt-out). */
+  completions?: InstallTargetSpec;
+  /** App config: wizard on install, file removal on uninstall. Default includedInAll true. */
+  configure?: InstallTargetSpec;
+  /** Cursor MCP. Default false. */
+  cursorMcp?: InstallTargetSpec;
+  /** Cursor skill. Default false. */
+  cursorSkill?: InstallTargetSpec;
+  /** OpenClaw MCP. Default false. */
+  openclawMcp?: InstallTargetSpec;
+  /** OpenClaw skill. Default false. */
+  openclawSkill?: InstallTargetSpec;
+  /** OpenCode MCP. Default false. */
+  opencodeMcp?: InstallTargetSpec;
+  /** OpenCode skill. Default false. */
+  opencodeSkill?: InstallTargetSpec;
+}
+
 /**
  * One bundled documentation topic for the `docs` built-in (program root only).
  */

package/src/validate.ts

@@ -3,8 +3,10 @@ This module validates CLI schemas before execution.
 */
 
 import { reservedCommandNames, resolveCapabilities } from "./capabilities.ts";
+import { reservedDocsTopicResourceUris } from "./docs/mcp-resources.ts";
 import { DOCS_BUILTIN_TOPIC_KEYS } from "./docs/resolve.ts";
 import { validateFormatValue } from "./formats.ts";
+import { AGENT_PAIRS } from "./install/target-registry.ts";
 import { resolveMcpSchemaUri } from "./mcp/tools.ts";
 import {
   type CliLeaf,
@@ -13,6 +15,8 @@ import {
   type CliProgram,
   CliSchemaValidationError,
   CliValueFormat,
+  type InstallAgentIntegration,
+  type InstallTargetSpec,
   isCliLeaf,
   isCliRouter,
 } from "./types.ts";
@@ -104,6 +108,69 @@ function validateConfigBlock(appConfigBlock: import("./types.ts").CliAppConfig):
   }
 }
 
+const PAIR_HOST_LABELS: Record<string, string> = {
+  cursorMcp: "cursor",
+  claudeCodeMcp: "claudeCode",
+  codexMcp: "codex",
+  opencodeMcp: "opencode",
+  openclawMcp: "openclaw",
+};
+
+function installTargetExplicitTruthy(spec: InstallTargetSpec | undefined): boolean {
+  if (spec === undefined || spec === false) return false;
+  if (spec === true) return true;
+  return spec.enabled !== false;
+}
+
+/** Validates `program.install` targets and agentIntegration. */
+function validateInstallConfig(program: CliProgram): void {
+  const install = program.install;
+  if (!install) return;
+
+  if ("prefix" in install) {
+    throw new CliSchemaValidationError(
+      "install.prefix removed; app installs to ~/.local/bin/<key>",
+    );
+  }
+
+  if (!install.targets) return;
+
+  const targets = install.targets;
+  if ("allSkills" in targets || "allMcps" in targets) {
+    throw new CliSchemaValidationError(
+      "install.targets.allSkills/allMcps removed; use agentIntegration and per-key targets",
+    );
+  }
+
+  const integration: InstallAgentIntegration =
+    install.agentIntegration ?? (program.mcpServer?.enabled === true ? "mcp" : "skill");
+
+  for (const [mcpKey, skillKey] of AGENT_PAIRS) {
+    const mcpSpec = targets[mcpKey];
+    const skillSpec = targets[skillKey];
+    const mcpOn = installTargetExplicitTruthy(mcpSpec);
+    const skillOn = installTargetExplicitTruthy(skillSpec);
+    const host = PAIR_HOST_LABELS[mcpKey] ?? mcpKey;
+
+    if (mcpOn && skillOn && integration !== "both") {
+      throw new CliSchemaValidationError(
+        `install.targets: ${host} has both MCP and skill configured; set agentIntegration: 'both' or disable one side`,
+      );
+    }
+
+    if (integration === "skill" && mcpOn) {
+      throw new CliSchemaValidationError(
+        `install.targets.${mcpKey} requires agentIntegration: 'both' when agentIntegration is 'skill'`,
+      );
+    }
+    if (integration === "mcp" && skillOn) {
+      throw new CliSchemaValidationError(
+        `install.targets.${skillKey} requires agentIntegration: 'both' when agentIntegration is 'mcp'`,
+      );
+    }
+  }
+}
+
 /** Validates a program schema. */
 export function cliValidateProgram(program: CliProgram): void {
   if (!program.version || program.version.trim().length === 0) {
@@ -141,6 +208,10 @@ export function cliValidateProgram(program: CliProgram): void {
     }
   }
 
+  if (program.install !== undefined) {
+    validateInstallConfig(program);
+  }
+
   const caps = resolveCapabilities(program);
   const reserved = reservedCommandNames(caps);
 
@@ -209,11 +280,15 @@ function walkNode(node: CliNode, program: CliProgram, isRoot: boolean): void {
 
   if (isRoot && program.mcpServer?.enabled === true && program.mcpServer.resources) {
     const schemaUri = resolveMcpSchemaUri(program);
+    const reserved = new Set([schemaUri, ...reservedDocsTopicResourceUris(program)]);
     const uris = program.mcpServer.resources.map((r) => r.uri);
-    if (uris.includes(schemaUri)) {
-      throw new CliSchemaValidationError(
-        `mcpServer.resources URI '${schemaUri}' conflicts with the built-in schema resource`,
-      );
+    for (const uri of uris) {
+      if (reserved.has(uri)) {
+        const kind = uri === schemaUri ? "built-in schema resource" : "auto docs topic resource";
+        throw new CliSchemaValidationError(
+          `mcpServer.resources URI '${uri}' conflicts with ${kind}`,
+        );
+      }
     }
     if (new Set(uris).size !== uris.length) {
       throw new CliSchemaValidationError("mcpServer.resources URIs must be unique");