cadre-ai 0.0.0 → 1.0.0

package/README.md

@@ -1,3 +1,124 @@
-# cadre-ai
+# Cadre
 
-Bootstrap package for configuring npm trusted publishing.
+![Cadre logo](../docs/public/cadre-logo.png)
+
+**Measure twice, code once.**
+
+Cadre is a context-driven development harness for AI coding agents. It combines
+spec-first tracks, Beads-backed durable task memory, review gates, team boards,
+parallel worker orchestration, and mono/polyrepo delivery into one packet-owned
+workflow.
+
+Public docs: [https://cadre-docs.pages.dev/](https://cadre-docs.pages.dev/)
+
+## What Cadre Provides
+
+- **Structured work:** setup, new track, implementation, review, ship/land,
+  archive, release, handoff, refresh, revise, validate, flag, and formula flows.
+- **Persistent memory:** Beads stores task graph, dependencies, notes, handoffs,
+  and resume evidence; agents access it through Cadre packets.
+- **Team safety:** ownership, advisory leases, collision scans, review queues,
+  shared sync, and compact MCP dashboard resources.
+- **Polyglot intelligence:** repo maps, dependency graphs, test impact,
+  workspace diagnostics, LSP setup, warm LSP review, and async job artifacts.
+- **Two agent surfaces:** Claude Code and OpenAI Codex plugins are thin MCP
+  entrypoints. The global `cadre-mcp` runtime owns the skill contract,
+  protocols, references, templates, and packet tools.
+
+## Install
+
+Install Beads first; setup requires the `bd` CLI to be available.
+
+```bash
+npm install -g @beads/bd
+bd --version
+```
+
+Install Cadre from npm and let the CLI wire detected clients:
+
+```bash
+npm install -g cadre-ai
+cadre install
+cadre doctor
+```
+
+## Use
+
+In a target project, activate the Cadre skill and ask for the workflow you need:
+
+```text
+$cadre
+cadre-setup
+cadre-newtrack "Add OAuth login"
+cadre-implement
+cadre-review
+cadre-ship
+```
+
+Cadre workflows are packet-owned. The agent verifies Cadre MCP, passes a
+per-call `root`, and lets the runtime perform state reads/writes, Beads work,
+parallel worker state, provider evidence write-back, and shared sync. Do not
+maintain Cadre state by hand.
+
+## Setup Outputs
+
+`cadre-setup` writes the project control plane:
+
+- `cadre/product.json` plus generated `cadre/product.md`
+- `cadre/product_guidelines.json` plus generated `cadre/product_guidelines.md`
+- `cadre/tech-stack.json`
+- `cadre/workflow.json` plus generated `cadre/workflow.md`
+- `cadre/tracks.json` as the generated track index
+- `cadre/patterns.jsonl` plus generated `cadre/patterns.md`
+- `cadre/config.json`
+- `cadre/beads.json`
+- `cadre/styleguides/*.json` plus generated `cadre/code_styleguides/*.md`
+- optional `cadre/repos.json` for polyrepo topology
+- optional `cadre/lsp.json` for LSP recommendations
+
+Setup also initializes Beads, can configure shared-sync merge attributes, and
+can scaffold hosted CI checks when requested.
+
+## Team And Repo Modes
+
+Cadre supports monorepos and polyrepo control repos. For teams, use shared sync
+so ownership, leases, review state, blockers, and available work are visible to
+everyone. Product code publication still happens through ship/land workflows;
+shared sync is for the Cadre control plane.
+
+Compact MCP resources provide bounded views for larger teams:
+
+- team board and next actions
+- review queue and handoff inbox
+- quality gate and parallel worker state
+- repo topology, repo map, workspace diagnostics, test impact, and LSP status
+- provider action plans and async job results
+
+## Harness Development
+
+This repository is the Cadre harness/package repo. Runtime sources live in
+`src/`, master skill/protocol sources live in `skills/cadre/`, references live
+in `scripts/agent-refs/`, and templates live in `templates/`.
+
+Run package commands from the repository root:
+
+```bash
+pnpm --filter cadre-ai generate
+pnpm --filter cadre-ai check
+```
+
+Generated plugin bundles under `.agents/`, `.claude/`, and `plugins/` are
+rebuilt from master sources. They contain only platform manifests, MCP config,
+and `SKILL.md`; the embedded MCP runtime is built under `scripts/`.
+
+Public documentation lives in the repo-root `docs/` Next.js app. Markdown page
+source is in `docs/content/`:
+
+- [Documentation Home](../docs/content/overview.md)
+- [Getting Started](../docs/content/getting-started.md)
+- [How Cadre Works](../docs/content/how-cadre-works.md)
+- [Workflows](../docs/content/workflows.md)
+- [Architecture](../docs/content/architecture.md)
+- [Team And Polyrepo](../docs/content/team-and-polyrepo.md)
+- [Parallel Execution](../docs/content/parallel-execution.md)
+- [Troubleshooting](../docs/content/troubleshooting.md)

package/package.json

@@ -1,21 +1,63 @@
 {
   "name": "cadre-ai",
-  "version": "0.0.0",
-  "description": "Bootstrap package for configuring npm trusted publishing. Use a real release version for installation.",
-  "license": "Apache-2.0",
+  "version": "1.0.0",
+  "description": "MCP-first Cadre workflows for context-driven development.",
+  "author": {
+    "name": "Vishal Kumar",
+    "url": "https://github.com/vishal-kr-barnwal"
+  },
+  "homepage": "https://cadre-docs.pages.dev/",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/vishal-kr-barnwal/cadre.git",
+    "url": "https://github.com/vishal-kr-barnwal/cadre.git",
     "directory": "harness"
   },
+  "license": "Apache-2.0",
+  "keywords": [
+    "cadre",
+    "cadre-ai",
+    "context-driven-development",
+    "mcp",
+    "codex",
+    "claude",
+    "beads"
+  ],
+  "type": "commonjs",
+  "packageManager": "pnpm@11.4.0",
+  "main": "scripts/cadre-core.js",
   "bin": {
-    "cadre": "index.js",
-    "cadre-ai": "index.js",
-    "cadre-mcp": "index.js"
+    "cadre": "scripts/cadre-cli.js",
+    "cadre-ai": "scripts/cadre-cli.js",
+    "cadre-lsp-setup": "scripts/cadre-lsp-setup.js",
+    "cadre-lsp-review": "scripts/cadre-lsp-review.js",
+    "cadre-mcp": "scripts/mcp/cadre-server.js"
   },
   "files": [
-    "index.js",
+    "LICENSE",
     "README.md",
-    "LICENSE"
-  ]
+    "scripts/cadre-cli.js",
+    "scripts/cadre-core.js",
+    "scripts/cadre-job-runner.js",
+    "scripts/cadre-lsp-daemon.js",
+    "scripts/cadre-lsp-review.js",
+    "scripts/cadre-lsp-setup.js",
+    "scripts/mcp/cadre-server.js"
+  ],
+  "scripts": {
+    "build": "node scripts/build-runtime.mjs",
+    "build:runtime": "node scripts/build-runtime.mjs",
+    "generate": "bash scripts/generate-skills.sh",
+    "check": "pnpm check:typecheck && pnpm check:runtime && pnpm check:generated && pnpm check:test",
+    "check:typecheck": "pnpm typecheck",
+    "check:runtime": "pnpm build:runtime",
+    "check:generated": "bash scripts/generate-skills.sh --check",
+    "check:test": "pnpm test",
+    "test": "node --test scripts/source-architecture.test.js scripts/cadre-core.test.js scripts/cadre-cli.test.js scripts/mcp/cadre-server.test.js scripts/protocol-packet-only.test.js && node scripts/cadre-team-scale-sim.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.4",
+    "esbuild": "^0.25.5",
+    "typescript": "^5.8.3"
+  }
 }

package/scripts/cadre-cli.js

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+// AUTO-GENERATED by pnpm build from src/*.ts -- do not edit by hand.
+// Edit TypeScript sources under src/ instead.
+const __CADRE_SKILL_SHIM__ = "---\nname: cadre\ndescription: |\n  Context-driven development methodology for organized, spec-first coding. Use when:\n  - Project has a `cadre/` directory\n  - User mentions specs, plans, tracks, or context-driven development\n  - Files like `cadre/tracks.json`, `cadre/product.json`, or `cadre/workflow.json` exist\n  - User asks about project status, implementation progress, or track management\n  - User wants to organize development work with TDD practices\n  - User asks for a `cadre-*` workflow (setup, newtrack, implement, status, revert, validate, flag, revise, review, ship, land, archive, release, handoff, refresh, formula, artifacts)\n  - User mentions documentation is outdated or wants to sync context with codebase changes\n  - Project is a polyrepo control repo (`cadre/repos.json` with mode \"polyrepo\") spanning git-submodule product repos\n\n  Interoperable across Claude Code and OpenAI Codex.\n  Integrates with Beads for persistent task memory across sessions.\n---\n\n# Cadre Skill Shim\n\nCadre MCP is required for every Cadre workflow. Before acting, verify the MCP\nruntime with `cadre_project` using `{\"action\":\"ping\"}`. If Cadre MCP tools or\nresources are unavailable, halt and ask the user to install, enable, or restart\nthe Cadre plugin.\n\nLoad `cadre://skill-contract` for the authoritative `cadre.skill.v1` contract.\nUse `cadre://workflow-protocols` to discover workflow protocol resources, then\nload `cadre://workflow-protocol?workflow=<name>` for the active workflow.\nReferences and template inventory are also MCP-served through Cadre resources.\n";
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli/install.ts
+var import_node_fs = __toESM(require("node:fs"));
+var import_node_os = __toESM(require("node:os"));
+var import_node_path = __toESM(require("node:path"));
+var import_node_child_process = require("node:child_process");
+var PACKAGE_PLUGIN_NAME = "cadre";
+var PACKAGE_DISPLAY_NAME = "Cadre";
+function usage() {
+  return [
+    "Cadre CLI",
+    "",
+    "Usage:",
+    "  cadre install [--target codex|claude|all] [--scope user|project|local] [--dry-run] [--check] [--force] [--yes]",
+    "  cadre doctor",
+    "  cadre help"
+  ].join("\n");
+}
+function parseInstall(argv) {
+  const parsed = {
+    target: "auto",
+    scope: "user",
+    dryRun: false,
+    check: false,
+    force: false,
+    yes: false,
+    cadreHome: process.env.CADRE_HOME || import_node_path.default.join(import_node_os.default.homedir(), ".cadre")
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--dry-run") parsed.dryRun = true;
+    else if (arg === "--check") parsed.check = true;
+    else if (arg === "--force") parsed.force = true;
+    else if (arg === "--yes" || arg === "-y") parsed.yes = true;
+    else if (arg === "--target") {
+      const value = argv[index + 1];
+      if (value !== "codex" && value !== "claude" && value !== "all") throw new Error("--target must be codex, claude, or all");
+      parsed.target = value;
+      index += 1;
+    } else if (arg === "--scope") {
+      const value = argv[index + 1];
+      if (value !== "user" && value !== "project" && value !== "local") throw new Error("--scope must be user, project, or local");
+      parsed.scope = value;
+      index += 1;
+    } else if (arg === "--home") {
+      const value = argv[index + 1];
+      if (!value) throw new Error("--home requires a path");
+      parsed.cadreHome = import_node_path.default.resolve(value);
+      index += 1;
+    } else {
+      throw new Error(`Unknown install option: ${arg}`);
+    }
+  }
+  return parsed;
+}
+function runtimePaths() {
+  const runtimeRoot = import_node_path.default.resolve(__dirname, "..");
+  return {
+    runtimeRoot,
+    nodePath: process.execPath,
+    mcpServer: import_node_path.default.join(runtimeRoot, "scripts", "mcp", "cadre-server.js")
+  };
+}
+function commandExists(command) {
+  const result = (0, import_node_child_process.spawnSync)(process.platform === "win32" ? "where" : "command", process.platform === "win32" ? [command] : ["-v", command], {
+    encoding: "utf8",
+    shell: process.platform !== "win32",
+    stdio: "ignore"
+  });
+  return result.status === 0;
+}
+function selectedTargets(options) {
+  if (options.target === "codex" || options.target === "claude") return [options.target];
+  if (options.target === "all") return ["codex", "claude"];
+  return ["codex", "claude"].filter((target) => commandExists(target));
+}
+function targetPaths(home, target) {
+  const pluginRoot = import_node_path.default.join(home, "plugins", target, PACKAGE_PLUGIN_NAME);
+  const marketplaceRoot = import_node_path.default.join(home, "marketplaces", target);
+  return {
+    pluginRoot,
+    marketplaceRoot,
+    marketplaceFile: target === "codex" ? import_node_path.default.join(marketplaceRoot, ".agents", "plugins", "marketplace.json") : import_node_path.default.join(marketplaceRoot, ".claude-plugin", "marketplace.json")
+  };
+}
+function readPackageMetadata(runtimeRoot) {
+  try {
+    const json = JSON.parse(import_node_fs.default.readFileSync(import_node_path.default.join(runtimeRoot, "package.json"), "utf8"));
+    return {
+      version: typeof json.version === "string" ? json.version : "0.0.0",
+      description: typeof json.description === "string" ? json.description : "MCP-first Cadre workflows.",
+      homepage: typeof json.homepage === "string" ? json.homepage : "https://cadre-docs.pages.dev/",
+      repository: typeof json.repository === "string" ? json.repository : "https://github.com/vishal-kr-barnwal/cadre",
+      license: typeof json.license === "string" ? json.license : "Apache-2.0"
+    };
+  } catch {
+    return {
+      version: "0.0.0",
+      description: "MCP-first Cadre workflows.",
+      homepage: "https://cadre-docs.pages.dev/",
+      repository: "https://github.com/vishal-kr-barnwal/cadre",
+      license: "Apache-2.0"
+    };
+  }
+}
+function pluginManifest(target, runtime) {
+  const metadata = readPackageMetadata(runtime.runtimeRoot);
+  const base = {
+    name: PACKAGE_PLUGIN_NAME,
+    version: metadata.version,
+    description: metadata.description,
+    author: { name: "Vishal Kumar", url: "https://github.com/vishal-kr-barnwal" },
+    homepage: metadata.homepage,
+    repository: metadata.repository,
+    license: metadata.license,
+    keywords: ["cadre", "context-driven-development", "skills", "beads", "mcp"],
+    skills: "./skills/"
+  };
+  if (target === "claude") {
+    return { ...base, displayName: PACKAGE_DISPLAY_NAME, mcpServers: "./mcp-config.json" };
+  }
+  return {
+    ...base,
+    mcpServers: "./.mcp.json",
+    interface: {
+      displayName: PACKAGE_DISPLAY_NAME,
+      shortDescription: "MCP-first planning, tracks, reviews, and packet tools.",
+      longDescription: "Cadre packages context-driven development workflows for Codex through one global MCP runtime.",
+      developerName: "Vishal Kumar",
+      category: "Productivity",
+      capabilities: ["Read", "Write", "Interactive"],
+      defaultPrompt: ["Set up this repo with Cadre.", "Show Cadre team status.", "Review the current Cadre track."],
+      brandColor: "#10A37F"
+    }
+  };
+}
+function mcpConfig(runtime) {
+  return {
+    mcpServers: {
+      cadre: {
+        command: runtime.nodePath,
+        args: [runtime.mcpServer],
+        cwd: runtime.runtimeRoot
+      }
+    }
+  };
+}
+function marketplace(target, pluginRoot, runtime) {
+  const metadata = readPackageMetadata(runtime.runtimeRoot);
+  if (target === "codex") {
+    return {
+      name: PACKAGE_PLUGIN_NAME,
+      interface: { displayName: PACKAGE_DISPLAY_NAME },
+      plugins: [{
+        name: PACKAGE_PLUGIN_NAME,
+        source: { source: "local", path: pluginRoot },
+        policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
+        category: "Productivity"
+      }]
+    };
+  }
+  return {
+    name: PACKAGE_PLUGIN_NAME,
+    owner: { name: "Vishal Kumar" },
+    description: "Cadre MCP-first workflows for Claude Code.",
+    plugins: [{
+      name: PACKAGE_PLUGIN_NAME,
+      source: pluginRoot,
+      description: metadata.description,
+      version: metadata.version,
+      author: { name: "Vishal Kumar" },
+      category: "productivity",
+      tags: ["cadre", "skills", "mcp", "context-driven-development"]
+    }]
+  };
+}
+function writeJson(file, value) {
+  import_node_fs.default.mkdirSync(import_node_path.default.dirname(file), { recursive: true });
+  import_node_fs.default.writeFileSync(file, `${JSON.stringify(value, null, 2)}
+`);
+}
+function writeText(file, text) {
+  import_node_fs.default.mkdirSync(import_node_path.default.dirname(file), { recursive: true });
+  import_node_fs.default.writeFileSync(file, text.endsWith("\n") ? text : `${text}
+`);
+}
+function writeThinPlugin(target, paths, runtime, skillShim) {
+  import_node_fs.default.rmSync(paths.pluginRoot, { recursive: true, force: true });
+  writeText(import_node_path.default.join(paths.pluginRoot, "skills", "cadre", "SKILL.md"), skillShim);
+  if (target === "codex") {
+    writeJson(import_node_path.default.join(paths.pluginRoot, ".codex-plugin", "plugin.json"), pluginManifest(target, runtime));
+    writeJson(import_node_path.default.join(paths.pluginRoot, ".mcp.json"), mcpConfig(runtime));
+  } else {
+    writeJson(import_node_path.default.join(paths.pluginRoot, ".claude-plugin", "plugin.json"), pluginManifest(target, runtime));
+    writeJson(import_node_path.default.join(paths.pluginRoot, "mcp-config.json"), mcpConfig(runtime));
+  }
+  writeJson(paths.marketplaceFile, marketplace(target, paths.pluginRoot, runtime));
+}
+function installCommands(target, paths, scope) {
+  if (target === "codex") {
+    return [
+      { command: "codex", args: ["plugin", "marketplace", "add", paths.marketplaceRoot] },
+      { command: "codex", args: ["plugin", "add", "cadre@cadre"] }
+    ];
+  }
+  return [
+    { command: "claude", args: ["plugin", "marketplace", "add", "--scope", scope, paths.marketplaceRoot] },
+    { command: "claude", args: ["plugin", "install", "--scope", scope, "cadre@cadre"] }
+  ];
+}
+function runCommand(plan) {
+  const result = (0, import_node_child_process.spawnSync)(plan.command, plan.args, { encoding: "utf8" });
+  return { ok: result.status === 0, status: result.status, stderr: result.stderr || "" };
+}
+function assertNoThinPluginPayload(paths) {
+  const forbidden = ["assets", "agents", "scripts"].filter((name) => import_node_fs.default.existsSync(import_node_path.default.join(paths.pluginRoot, name)));
+  return forbidden.map((name) => `${paths.pluginRoot}/${name}`);
+}
+function pingMcp(runtime) {
+  if (!import_node_fs.default.existsSync(runtime.mcpServer)) return { ok: false, reason: `missing MCP server: ${runtime.mcpServer}` };
+  const request = {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "tools/call",
+    params: { name: "cadre_project", arguments: { action: "ping" } }
+  };
+  const result = (0, import_node_child_process.spawnSync)(runtime.nodePath, [runtime.mcpServer], {
+    cwd: runtime.runtimeRoot,
+    input: `${JSON.stringify(request)}
+`,
+    encoding: "utf8",
+    timeout: 3e3
+  });
+  if (result.status !== 0 && !result.stdout.trim()) return { ok: false, reason: result.stderr || `MCP exited with ${result.status}` };
+  const line = result.stdout.split(/\r?\n/).find((entry) => entry.trim());
+  if (!line) return { ok: false, reason: "MCP returned no JSON-RPC response" };
+  try {
+    const parsed = JSON.parse(line);
+    if (parsed.error) return { ok: false, reason: parsed.error.message || "MCP returned an error" };
+    const text = parsed.result?.content?.[0]?.text;
+    const body = text ? JSON.parse(text) : null;
+    return body?.data?.ok === true ? { ok: true } : { ok: false, reason: "MCP ping did not return ok:true" };
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+}
+function checkTarget(target, paths, runtime) {
+  const errors = [];
+  const skill = import_node_path.default.join(paths.pluginRoot, "skills", "cadre", "SKILL.md");
+  if (!import_node_fs.default.existsSync(skill)) errors.push(`missing ${skill}`);
+  const manifest = target === "codex" ? import_node_path.default.join(paths.pluginRoot, ".codex-plugin", "plugin.json") : import_node_path.default.join(paths.pluginRoot, ".claude-plugin", "plugin.json");
+  const mcp = target === "codex" ? import_node_path.default.join(paths.pluginRoot, ".mcp.json") : import_node_path.default.join(paths.pluginRoot, "mcp-config.json");
+  if (!import_node_fs.default.existsSync(manifest)) errors.push(`missing ${manifest}`);
+  if (!import_node_fs.default.existsSync(mcp)) errors.push(`missing ${mcp}`);
+  errors.push(...assertNoThinPluginPayload(paths).map((entry) => `thin plugin contains forbidden payload ${entry}`));
+  if (import_node_fs.default.existsSync(mcp)) {
+    const config = JSON.parse(import_node_fs.default.readFileSync(mcp, "utf8"));
+    const server = config.mcpServers?.cadre;
+    if (server?.command !== runtime.nodePath) errors.push(`${mcp} does not point at the current Node runtime`);
+    if (server?.args?.[0] !== runtime.mcpServer) errors.push(`${mcp} does not point at ${runtime.mcpServer}`);
+    if (server?.cwd !== runtime.runtimeRoot) errors.push(`${mcp} has wrong cwd`);
+  }
+  return errors;
+}
+function printPlan(target, paths, commands) {
+  process.stdout.write(`Cadre ${target} plugin: ${paths.pluginRoot}
+`);
+  process.stdout.write(`Cadre ${target} marketplace: ${paths.marketplaceRoot}
+`);
+  for (const command of commands) process.stdout.write(`Would run: ${command.command} ${command.args.join(" ")}
+`);
+}
+function runInstall(argv, context) {
+  const options = parseInstall(argv);
+  const runtime = runtimePaths();
+  const targets = selectedTargets(options);
+  if (targets.length === 0) {
+    process.stderr.write("No supported client detected. Install Codex or Claude, or pass --target codex|claude.\n");
+    return 1;
+  }
+  const ping = pingMcp(runtime);
+  if (!ping.ok) {
+    process.stderr.write(`Cadre MCP check failed: ${ping.reason}
+`);
+    return 1;
+  }
+  let ok = true;
+  for (const target of targets) {
+    const paths = targetPaths(options.cadreHome, target);
+    const commands = installCommands(target, paths, options.scope);
+    if (options.dryRun) {
+      printPlan(target, paths, commands);
+      continue;
+    }
+    if (!options.check) writeThinPlugin(target, paths, runtime, context.skillShim);
+    const errors = checkTarget(target, paths, runtime);
+    if (errors.length > 0) {
+      ok = false;
+      for (const error of errors) process.stderr.write(`${error}
+`);
+      continue;
+    }
+    if (options.check) {
+      process.stdout.write(`Cadre ${target} plugin is installed and points at ${runtime.mcpServer}
+`);
+      continue;
+    }
+    if (!commandExists(target)) {
+      ok = false;
+      process.stderr.write(`${target} command not found; plugin files were written but native registration was skipped.
+`);
+      continue;
+    }
+    for (const command of commands) {
+      const result = runCommand(command);
+      if (!result.ok) {
+        ok = false;
+        process.stderr.write(`${command.command} ${command.args.join(" ")} failed: ${result.stderr}
+`);
+      }
+    }
+    if (ok) process.stdout.write(`Installed Cadre ${target} plugin through ${paths.marketplaceRoot}
+`);
+  }
+  return ok ? 0 : 1;
+}
+function runDoctor() {
+  const runtime = runtimePaths();
+  const ping = pingMcp(runtime);
+  const checks = [
+    `package root: ${runtime.runtimeRoot}`,
+    `node: ${runtime.nodePath}`,
+    `cadre-mcp: ${runtime.mcpServer}`,
+    `mcp ping: ${ping.ok ? "ok" : `failed (${ping.reason})`}`
+  ];
+  process.stdout.write(`${checks.join("\n")}
+`);
+  return ping.ok ? 0 : 1;
+}
+async function runCli(argv, context) {
+  const command = argv[0] || "help";
+  let code = 0;
+  if (command === "install") code = runInstall(argv.slice(1), context);
+  else if (command === "doctor") code = runDoctor();
+  else if (command === "help" || command === "--help" || command === "-h") process.stdout.write(`${usage()}
+`);
+  else {
+    process.stderr.write(`${usage()}
+`);
+    code = 1;
+  }
+  if (code !== 0) process.exit(code);
+}
+
+// src/cli.ts
+runCli(process.argv.slice(2), {
+  skillShim: typeof __CADRE_SKILL_SHIM__ === "string" ? __CADRE_SKILL_SHIM__ : ""
+}).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}
+`);
+  process.exit(1);
+});