@documentation-robotics/cli 0.2.0 → 0.3.0

package/dist/coding-agents/drbot-mcp.js

@@ -0,0 +1,167 @@
+import { existsSync } from "node:fs";
+import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ApiKeyManager } from "../mcp/api-key-manager.js";
+import { CHANGESET_ONLY_ENV } from "../core/changeset-only-guard.js";
+const DR_MCP_SERVER_NAME = "dr", DR_MCP_ROOT_PATH_ENV = "DR_MCP_ROOT_PATH", DR_CLI_ENTRY_ENV = "DR_CLI_ENTRY", DR_MCP_READ_TOOLS = Object.freeze([
+  "model_list",
+  "model_show",
+  "model_search",
+  "model_stats",
+  "model_info",
+  "model_trace",
+  "model_validate",
+  "model_export",
+  "model_reload",
+  "changeset_list",
+  "changeset_show",
+  "changeset_impact",
+  "changeset_brief",
+  "changeset_verify",
+  "spec_type",
+  "annotation_list",
+  "annotation_get",
+  "chat_status"
+]), DR_MCP_CHANGESET_TOOLS = Object.freeze([
+  "changeset_create",
+  "changeset_activate",
+  "changeset_deactivate",
+  "model_add",
+  "model_update",
+  "model_delete",
+  "relationship_add",
+  "relationship_delete",
+  "changeset_update",
+  "changeset_unstage"
+]);
+function drMcpToolRule(tool) {
+  return `mcp__${DR_MCP_SERVER_NAME}__${tool}`;
+}
+function drMcpAllowedTools(mode) {
+  return mode === "danger" ? [] : (mode === "changesets" ? [...DR_MCP_READ_TOOLS, ...DR_MCP_CHANGESET_TOOLS] : [...DR_MCP_READ_TOOLS]).map(drMcpToolRule);
+}
+function resolveDrCommand(env = process.env, exists = existsSync) {
+  const override = env[DR_CLI_ENTRY_ENV];
+  if (override && exists(override))
+    return { command: process.execPath, args: [override] };
+  const bundled = fileURLToPath(new URL("../cli.js", import.meta.url));
+  return exists(bundled) ? { command: process.execPath, args: [bundled] } : { command: "dr", args: [] };
+}
+function buildDrMcpConfig(options) {
+  const env = {
+    DR_MCP_API_KEY: options.apiKey,
+    [DR_MCP_ROOT_PATH_ENV]: options.rootPath,
+    // The key is already in this private config; don't print it into the client's MCP logs.
+    DR_MCP_QUIET_KEY: "1"
+  };
+  return options.changesetOnly && (env[CHANGESET_ONLY_ENV] = "true"), {
+    mcpServers: {
+      [DR_MCP_SERVER_NAME]: {
+        type: "stdio",
+        command: options.drCommand.command,
+        args: [...options.drCommand.args, "mcp"],
+        env
+      }
+    }
+  };
+}
+async function prepareDrMcpLaunch(options) {
+  const keyManager = options.keyManager ?? new ApiKeyManager(), { key } = await keyManager.ensureKey(), config = buildDrMcpConfig({
+    drCommand: options.drCommand ?? resolveDrCommand(),
+    apiKey: key,
+    rootPath: options.rootPath,
+    changesetOnly: options.changesetOnly
+  }), dir = await mkdtemp(join(options.tempRoot ?? tmpdir(), "dr-drbot-mcp-"));
+  let removed = !1;
+  const cleanup = async () => {
+    if (!removed) {
+      removed = !0;
+      try {
+        await rm(dir, { recursive: !0, force: !0 });
+      } catch (error) {
+        console.warn(`[DrBot] Could not remove MCP config directory ${dir}: ${error.message}`);
+      }
+    }
+  };
+  try {
+    await chmod(dir, 448);
+    const configPath = join(dir, "mcp.json");
+    return await writeFile(configPath, JSON.stringify(config, null, 2), {
+      mode: 384
+    }), { configPath, cleanup };
+  } catch (error) {
+    throw await cleanup(), error;
+  }
+}
+function drBotMcpPrompt(mode) {
+  const lines = [
+    `The Documentation Robotics MCP server "${DR_MCP_SERVER_NAME}" is connected for the model this session serves (tools named mcp__${DR_MCP_SERVER_NAME}__*). Prefer these tools to running dr through Bash: model_search/model_show/model_list to look things up, spec_type to check what a type takes and which relationships the catalog allows, changeset_impact and changeset_brief to pressure-test a change.`
+  ];
+  return mode === "changesets" ? lines.push("This session may change the model only through a changeset. Call changeset_create first (it activates the new changeset), then stage changes with model_add, model_update, model_delete, relationship_add and relationship_delete, and review them with changeset_brief. Writes with no active changeset are refused. Never commit or apply a changeset: the user reviews and commits it.") : mode === "read-safe" && lines.push("This session is read-only: answer from the model, and do not try to change it."), lines.join(`
+
+`);
+}
+const DR_ARCHITECT_AGENT = "dr-architect";
+function parseAgentFrontmatterTools(markdown) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(markdown);
+  if (!match)
+    return null;
+  const lines = match[1].split(/\r?\n/), index = lines.findIndex((line) => /^tools\s*:/.test(line));
+  if (index === -1)
+    return null;
+  const unquote = (value) => value.trim().replace(/^["']|["']$/g, "").trim(), inline = lines[index].replace(/^tools\s*:/, "").trim();
+  if (inline)
+    return inline.replace(/^\[|\]$/g, "").split(",").map(unquote).filter(Boolean);
+  const tools = [];
+  for (const line of lines.slice(index + 1)) {
+    const item = /^\s+-\s*(.+)$/.exec(line);
+    if (!item)
+      break;
+    tools.push(unquote(item[1]));
+  }
+  return tools;
+}
+function findInstalledAgentFile(rootPath, homeDir = homedir(), exists = existsSync) {
+  for (const base of [rootPath, homeDir]) {
+    const candidate = join(base, ".claude", "agents", `${DR_ARCHITECT_AGENT}.md`);
+    if (exists(candidate))
+      return candidate;
+  }
+  return null;
+}
+function drMcpToolsForMode(mode) {
+  return mode === "danger" ? [...DR_MCP_READ_TOOLS, ...DR_MCP_CHANGESET_TOOLS].map(drMcpToolRule) : drMcpAllowedTools(mode);
+}
+async function checkInstalledAgentMcpTools(rootPath, mode, homeDir = homedir()) {
+  const path = findInstalledAgentFile(rootPath, homeDir);
+  if (!path)
+    return null;
+  const tools = parseAgentFrontmatterTools(await readFile(path, "utf8"));
+  if (tools === null)
+    return null;
+  const listed = new Set(tools);
+  if (listed.has(`mcp__${DR_MCP_SERVER_NAME}`) || listed.has(`mcp__${DR_MCP_SERVER_NAME}__*`))
+    return null;
+  const required = drMcpToolsForMode(mode), missing = required.filter((rule) => !listed.has(rule));
+  return missing.length === 0 ? null : { path, missing, noneVisible: missing.length === required.length };
+}
+export {
+  DR_ARCHITECT_AGENT,
+  DR_CLI_ENTRY_ENV,
+  DR_MCP_CHANGESET_TOOLS,
+  DR_MCP_READ_TOOLS,
+  DR_MCP_ROOT_PATH_ENV,
+  DR_MCP_SERVER_NAME,
+  buildDrMcpConfig,
+  checkInstalledAgentMcpTools,
+  drBotMcpPrompt,
+  drMcpAllowedTools,
+  drMcpToolRule,
+  findInstalledAgentFile,
+  parseAgentFrontmatterTools,
+  prepareDrMcpLaunch,
+  resolveDrCommand
+};
+//# sourceMappingURL=drbot-mcp.js.map

package/dist/coding-agents/drbot-mcp.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/coding-agents/drbot-mcp.ts"],
+  "sourcesContent": ["/**\n * DrBot on MCP: connect the viewer's chat agent to the dr MCP server.\n *\n * `dr visualize` launches Claude Code as DrBot (server/server.ts). Rather than having the\n * agent shell out to `dr` through Bash, the launch hands Claude Code an MCP config that runs\n * this same dr installation's `dr mcp` over stdio, pointed at the served model, so DrBot plans\n * changes with the change-modeling tools (changeset_create, spec_type, model_add,\n * relationship_add, changeset_brief) the way any other agent does.\n *\n * Authentication: `dr mcp` over stdio requires DR_MCP_API_KEY to match the installation's\n * stored key (mcp/api-key-manager.ts). Over stdio the client supplies both the process and its\n * environment, so a key minted per launch would only be checked against itself; the launch\n * instead resolves the installation key (creating it on first use, as `dr mcp` does) and puts\n * it only in a private temp config file (0600, in a 0700 directory under the OS temp dir),\n * never in the repo, the model directory or the process arguments. The file is removed when the\n * agent process exits.\n *\n * Tolerance: if anything here fails (no key, no temp dir), the caller launches DrBot without\n * MCP and it falls back to the read-safe Bash rules; the failure is logged, not swallowed.\n */\n\nimport { existsSync } from \"node:fs\";\nimport { chmod, mkdtemp, readFile, rm, writeFile } from \"node:fs/promises\";\nimport { homedir, tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { ApiKeyManager } from \"../mcp/api-key-manager.js\";\nimport { CHANGESET_ONLY_ENV } from \"../core/changeset-only-guard.js\";\n\n/** Name the dr MCP server is registered under; Claude Code exposes its tools as mcp__dr__<tool>. */\nexport const DR_MCP_SERVER_NAME = \"dr\";\n\n/** Env var `dr mcp` honours to serve a model from a directory other than its cwd. */\nexport const DR_MCP_ROOT_PATH_ENV = \"DR_MCP_ROOT_PATH\";\n\n/** Env var that overrides the dr CLI entry script DrBot's MCP server runs (tests, custom installs). */\nexport const DR_CLI_ENTRY_ENV = \"DR_CLI_ENTRY\";\n\n/** Tools that only read: allowed in every DrBot mode. */\nexport const DR_MCP_READ_TOOLS: readonly string[] = Object.freeze([\n  \"model_list\",\n  \"model_show\",\n  \"model_search\",\n  \"model_stats\",\n  \"model_info\",\n  \"model_trace\",\n  \"model_validate\",\n  \"model_export\",\n  \"model_reload\",\n  \"changeset_list\",\n  \"changeset_show\",\n  \"changeset_impact\",\n  \"changeset_brief\",\n  \"changeset_verify\",\n  \"spec_type\",\n  \"annotation_list\",\n  \"annotation_get\",\n  \"chat_status\",\n]);\n\n/**\n * Tools added in changeset-only mode (`dr visualize --with-changesets`): open and work in a\n * changeset and stage element and relationship changes. The MCP server runs with\n * DR_CHANGESET_ONLY set, so any of these that would write the base model (no active changeset)\n * is refused there (mcp/changeset-only.ts). changeset_update and changeset_unstage revise the\n * plan. Commit and apply are not MCP tools at all, and changeset_discard (which deletes the\n * staged changes) stays out: abandoning a changeset is the user's call.\n * chat_launch (an agent launching another agent) and the annotation writers stay out.\n */\nexport const DR_MCP_CHANGESET_TOOLS: readonly string[] = Object.freeze([\n  \"changeset_create\",\n  \"changeset_activate\",\n  \"changeset_deactivate\",\n  \"model_add\",\n  \"model_update\",\n  \"model_delete\",\n  \"relationship_add\",\n  \"relationship_delete\",\n  \"changeset_update\",\n  \"changeset_unstage\",\n]);\n\nexport type DrBotMode = \"read-safe\" | \"changesets\" | \"danger\";\n\n/** Claude Code permission rule for one dr MCP tool. */\nexport function drMcpToolRule(tool: string): string {\n  return `mcp__${DR_MCP_SERVER_NAME}__${tool}`;\n}\n\n/** The mcp__dr__* rules DrBot may use without prompting in a mode (danger mode skips permissions). */\nexport function drMcpAllowedTools(mode: DrBotMode): string[] {\n  if (mode === \"danger\") return [];\n  const tools = mode === \"changesets\" ? [...DR_MCP_READ_TOOLS, ...DR_MCP_CHANGESET_TOOLS] : [...DR_MCP_READ_TOOLS];\n  return tools.map(drMcpToolRule);\n}\n\n/** How to run this dr installation: a runtime plus the CLI entry script, or `dr` from PATH. */\nexport interface DrCommand {\n  command: string;\n  args: string[];\n}\n\n/**\n * Resolves the command that runs this same dr installation. The built CLI lives next to this\n * module's parent (dist/coding-agents/ \u2192 dist/cli.js) and runs under whichever runtime is\n * running now; DR_CLI_ENTRY overrides the script. Falls back to `dr` on PATH.\n */\nexport function resolveDrCommand(\n  env: NodeJS.ProcessEnv = process.env,\n  exists: (path: string) => boolean = existsSync\n): DrCommand {\n  const override = env[DR_CLI_ENTRY_ENV];\n  if (override && exists(override)) {\n    return { command: process.execPath, args: [override] };\n  }\n  const bundled = fileURLToPath(new URL(\"../cli.js\", import.meta.url));\n  if (exists(bundled)) {\n    return { command: process.execPath, args: [bundled] };\n  }\n  return { command: \"dr\", args: [] };\n}\n\nexport interface DrMcpConfigOptions {\n  drCommand: DrCommand;\n  apiKey: string;\n  /** Project root of the served model. */\n  rootPath: string;\n  /** Run the server in changeset-only mode (DR_CHANGESET_ONLY=true). */\n  changesetOnly: boolean;\n}\n\n/** The Claude Code MCP config (the --mcp-config file's content) for DrBot's dr server. */\nexport function buildDrMcpConfig(options: DrMcpConfigOptions): {\n  mcpServers: Record<\n    string,\n    {\n      type: \"stdio\";\n      command: string;\n      args: string[];\n      env: Record<string, string>;\n    }\n  >;\n} {\n  const env: Record<string, string> = {\n    DR_MCP_API_KEY: options.apiKey,\n    [DR_MCP_ROOT_PATH_ENV]: options.rootPath,\n    // The key is already in this private config; don't print it into the client's MCP logs.\n    DR_MCP_QUIET_KEY: \"1\",\n  };\n  if (options.changesetOnly) {\n    env[CHANGESET_ONLY_ENV] = \"true\";\n  }\n  return {\n    mcpServers: {\n      [DR_MCP_SERVER_NAME]: {\n        type: \"stdio\",\n        command: options.drCommand.command,\n        args: [...options.drCommand.args, \"mcp\"],\n        env,\n      },\n    },\n  };\n}\n\n/** A written MCP config and the function that removes it again (safe to call more than once). */\nexport interface DrMcpLaunch {\n  configPath: string;\n  cleanup: () => Promise<void>;\n}\n\nexport interface PrepareDrMcpLaunchOptions {\n  rootPath: string;\n  changesetOnly: boolean;\n  keyManager?: Pick<ApiKeyManager, \"ensureKey\">;\n  drCommand?: DrCommand;\n  /** Parent directory for the private config directory; defaults to the OS temp dir. */\n  tempRoot?: string;\n}\n\n/**\n * Writes DrBot's MCP config to a private temp file. Throws on failure; the caller decides to\n * launch without MCP.\n */\nexport async function prepareDrMcpLaunch(options: PrepareDrMcpLaunchOptions): Promise<DrMcpLaunch> {\n  const keyManager = options.keyManager ?? new ApiKeyManager();\n  // No prompt: the server is non-interactive, so a first-time key goes to the default path.\n  const { key } = await keyManager.ensureKey();\n  const config = buildDrMcpConfig({\n    drCommand: options.drCommand ?? resolveDrCommand(),\n    apiKey: key,\n    rootPath: options.rootPath,\n    changesetOnly: options.changesetOnly,\n  });\n\n  const dir = await mkdtemp(join(options.tempRoot ?? tmpdir(), \"dr-drbot-mcp-\"));\n  let removed = false;\n  const cleanup = async () => {\n    if (removed) return;\n    removed = true;\n    try {\n      await rm(dir, { recursive: true, force: true });\n    } catch (error) {\n      console.warn(`[DrBot] Could not remove MCP config directory ${dir}: ${(error as Error).message}`);\n    }\n  };\n\n  try {\n    await chmod(dir, 0o700);\n    const configPath = join(dir, \"mcp.json\");\n    await writeFile(configPath, JSON.stringify(config, null, 2), {\n      mode: 0o600,\n    });\n    return { configPath, cleanup };\n  } catch (error) {\n    await cleanup();\n    throw error;\n  }\n}\n\n/** Appended to DrBot's system prompt when the dr MCP server is connected. */\nexport function drBotMcpPrompt(mode: DrBotMode): string {\n  const lines = [\n    `The Documentation Robotics MCP server \"${DR_MCP_SERVER_NAME}\" is connected for the model this session serves ` +\n      `(tools named mcp__${DR_MCP_SERVER_NAME}__*). Prefer these tools to running dr through Bash: ` +\n      \"model_search/model_show/model_list to look things up, spec_type to check what a type takes and which \" +\n      \"relationships the catalog allows, changeset_impact and changeset_brief to pressure-test a change.\",\n  ];\n  if (mode === \"changesets\") {\n    lines.push(\n      \"This session may change the model only through a changeset. Call changeset_create first (it activates the \" +\n        \"new changeset), then stage changes with model_add, model_update, model_delete, relationship_add and \" +\n        \"relationship_delete, and review them with changeset_brief. Writes with no active changeset are refused. \" +\n        \"Never commit or apply a changeset: the user reviews and commits it.\"\n    );\n  } else if (mode === \"read-safe\") {\n    lines.push(\"This session is read-only: answer from the model, and do not try to change it.\");\n  }\n  return lines.join(\"\\n\\n\");\n}\n\n/** The Claude Code agent DrBot runs as (`claude --agent dr-architect`). */\nexport const DR_ARCHITECT_AGENT = \"dr-architect\";\n\n/**\n * The tool names in an agent file's frontmatter `tools:` field, or null when the file has no\n * `tools:` field (Claude Code then gives the agent every tool, MCP tools included). Accepts the\n * comma-separated form, a flow list (`[a, b]`) and a block list.\n */\nexport function parseAgentFrontmatterTools(markdown: string): string[] | null {\n  const match = /^---\\r?\\n([\\s\\S]*?)\\r?\\n---/.exec(markdown);\n  if (!match) return null;\n  const lines = match[1].split(/\\r?\\n/);\n  const index = lines.findIndex((line) => /^tools\\s*:/.test(line));\n  if (index === -1) return null;\n  const unquote = (value: string) =>\n    value\n      .trim()\n      .replace(/^[\"']|[\"']$/g, \"\")\n      .trim();\n  const inline = lines[index].replace(/^tools\\s*:/, \"\").trim();\n  if (inline) {\n    return inline\n      .replace(/^\\[|\\]$/g, \"\")\n      .split(\",\")\n      .map(unquote)\n      .filter(Boolean);\n  }\n  const tools: string[] = [];\n  for (const line of lines.slice(index + 1)) {\n    const item = /^\\s+-\\s*(.+)$/.exec(line);\n    if (!item) break;\n    tools.push(unquote(item[1]));\n  }\n  return tools;\n}\n\n/**\n * The dr-architect agent file Claude Code loads for a session run in `rootPath`: the project's\n * .claude/agents copy wins over the user's ~/.claude/agents copy. Null when neither exists.\n */\nexport function findInstalledAgentFile(\n  rootPath: string,\n  homeDir: string = homedir(),\n  exists: (path: string) => boolean = existsSync\n): string | null {\n  for (const base of [rootPath, homeDir]) {\n    const candidate = join(base, \".claude\", \"agents\", `${DR_ARCHITECT_AGENT}.md`);\n    if (exists(candidate)) return candidate;\n  }\n  return null;\n}\n\n/** The dr MCP tools a mode uses that the installed dr-architect agent can't see. */\nexport interface AgentMcpToolCheck {\n  /** The agent file that was checked. */\n  path: string;\n  /** The mcp__dr__* rules the mode uses that the agent's `tools:` field leaves out. */\n  missing: string[];\n  /** True when the agent can see none of them (a copy installed before DrBot used MCP). */\n  noneVisible: boolean;\n}\n\n/** Every dr MCP tool DrBot can use in a mode (danger mode may use them all). */\nfunction drMcpToolsForMode(mode: DrBotMode): string[] {\n  return mode === \"danger\"\n    ? [...DR_MCP_READ_TOOLS, ...DR_MCP_CHANGESET_TOOLS].map(drMcpToolRule)\n    : drMcpAllowedTools(mode);\n}\n\n/**\n * Checks that the installed dr-architect agent lists the dr MCP tools DrBot's mode uses. An\n * agent's `tools:` field limits what it can call, so a copy installed before DrBot moved to MCP\n * can't see the server at all, whatever --allowedTools says. Null when there's nothing to report:\n * no agent file found, no `tools:` field, a server-wide `mcp__dr` entry, or every tool listed.\n */\nexport async function checkInstalledAgentMcpTools(\n  rootPath: string,\n  mode: DrBotMode,\n  homeDir: string = homedir()\n): Promise<AgentMcpToolCheck | null> {\n  const path = findInstalledAgentFile(rootPath, homeDir);\n  if (!path) return null;\n  const tools = parseAgentFrontmatterTools(await readFile(path, \"utf8\"));\n  if (tools === null) return null;\n  const listed = new Set(tools);\n  if (listed.has(`mcp__${DR_MCP_SERVER_NAME}`) || listed.has(`mcp__${DR_MCP_SERVER_NAME}__*`)) return null;\n  const required = drMcpToolsForMode(mode);\n  const missing = required.filter((rule) => !listed.has(rule));\n  if (missing.length === 0) return null;\n  return { path, missing, noneVisible: missing.length === required.length };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/commands/add.js

@@ -4,6 +4,7 @@ import { Layer } from "../core/layer.js";
 import { Element } from "../core/element.js";
 import { MutationHandler } from "../core/mutation-handler.js";
 import { validateSourceReferenceOptions, buildSourceReference } from "../utils/source-reference.js";
+import { schemaLookupHint } from "../utils/error-hints.js";
 import { SchemaValidator } from "../validators/schema-validator.js";
 import { getActiveSpan } from "../telemetry/index.js";
 import { generateElementId, generateUUID } from "../utils/id-generator.js";
@@ -36,7 +37,7 @@ async function addCommand(layer, type, name, options) {
     span?.setAttribute("layer.name", layer), span?.setAttribute("element.type", resolvedType), span?.setAttribute("element.id", elementPath), validateSourceReferenceOptions(options);
     let model;
     try {
-      model = await Model.load(options.model || process.cwd(), { layers: [layer] });
+      model = await Model.load(options.model, { layers: [layer] });
     } catch (error) {
       const message = getErrorMessage(error);
       throw message.includes("No DR project") || message.includes("Model not found") ? new ModelNotFoundError() : error;
@@ -78,7 +79,7 @@ async function addCommand(layer, type, name, options) {
         const errorMessages = attrValidation.errors.map((e) => `  ${e.message}`).join(`
 `);
         throw new CLIError(`Element ${elementPath} has invalid attributes:
-${errorMessages}`, ErrorCategory.USER, [`Run "dr schema ${layer} ${type}" to see the required attributes`]);
+${errorMessages}`, ErrorCategory.USER, [schemaLookupHint("cli", layer, resolvedType)]);
       }
     }
     if (layerObj.getElement(elementPath))

package/dist/commands/add.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/commands/add.ts"],
-  "sourcesContent": ["/**\n * Add an element to a layer\n */\n\nimport ansis from \"ansis\";\nimport { Model } from \"../core/model.js\";\nimport { Layer } from \"../core/layer.js\";\nimport { Element } from \"../core/element.js\";\nimport { MutationHandler } from \"../core/mutation-handler.js\";\nimport { validateSourceReferenceOptions, buildSourceReference } from \"../utils/source-reference.js\";\nimport { SchemaValidator } from \"../validators/schema-validator.js\";\nimport { getActiveSpan } from \"../telemetry/index.js\";\nimport { generateElementId, generateUUID } from \"../utils/id-generator.js\";\nimport { getAllLayerIds, isValidLayer } from \"../generated/layer-registry.js\";\nimport { isValidNodeType, getNodeTypesForLayer, normalizeNodeType } from \"../generated/node-types.js\";\nimport {\n  CLIError,\n  ErrorCategory,\n  InvalidJSONError,\n  ModelNotFoundError,\n  findSimilar,\n  formatValidOptions,\n  getErrorMessage,\n  handleError,\n  handleSuccess,\n} from \"../utils/errors.js\";\n\n\nexport interface AddOptions {\n  model?: string;\n  name?: string;\n  description?: string;\n  attributes?: string;\n  sourceFile?: string;\n  sourceSymbol?: string;\n  sourceProvenance?: string;\n  sourceRepoRemote?: string;\n  sourceRepoCommit?: string;\n  verbose?: boolean;\n  debug?: boolean;\n}\n\nexport async function addCommand(\n  layer: string,\n  type: string,\n  name: string,\n  options: AddOptions\n): Promise<void> {\n  try {\n    // Validate layer name\n    if (!isValidLayer(layer)) {\n      const validLayers = getAllLayerIds();\n      const similar = findSimilar(layer, validLayers, 3);\n      const suggestions: string[] = [`Use a valid layer name: ${formatValidOptions(validLayers)}`];\n      if (similar.length > 0) {\n        suggestions.unshift(`Did you mean: ${similar.join(\" or \")}?`);\n      }\n      throw new CLIError(`Unknown layer \"${layer}\"`, ErrorCategory.USER, suggestions, {\n        operation: \"add\",\n        context: `Layer: ${layer}, Type: ${type}, Name: ${name}`,\n      });\n    }\n\n    // Validate element type for this layer\n    if (!isValidNodeType(layer, type)) {\n      const validNodeTypes = getNodeTypesForLayer(layer);\n      const typeNames = validNodeTypes.map((t) => t.type).sort();\n      const similar = findSimilar(type, typeNames, 3);\n      const suggestions: string[] = [`Valid types for ${layer}: ${formatValidOptions(typeNames)}`];\n      if (similar.length > 0) {\n        suggestions.unshift(`Did you mean: ${similar.join(\" or \")}?`);\n      }\n      throw new CLIError(\n        `Invalid element type \"${type}\" for layer \"${layer}\"`,\n        ErrorCategory.USER,\n        suggestions,\n        {\n          operation: \"add\",\n          context: `Layer: ${layer}, Type: ${type}, Name: ${name}`,\n        }\n      );\n    }\n\n    // Resolve abbreviated type names to their canonical spec names\n    // e.g., \"service\" \u2192 \"applicationservice\" for the application layer\n    const resolvedType = normalizeNodeType(layer, type);\n\n    // Generate slug path: {layer}.{resolvedType}.{kebab-name}\n    const elementPath = generateElementId(layer, resolvedType, name);  // slug\n    const elementUUID = generateUUID();                         // UUIDv4\n\n    // Validate the generated slug is non-empty (name may collapse to empty after stripping special chars)\n    const slugPart = elementPath.split(\".\")[2];\n    if (!slugPart) {\n      throw new CLIError(\n        `Cannot generate a valid element ID from name \"${name}\"`,\n        ErrorCategory.USER,\n        [\n          \"Element names must contain at least one letter or digit\",\n          `Generated ID would be: ${elementPath}`,\n        ]\n      );\n    }\n\n    const span = getActiveSpan();\n    span?.setAttribute(\"layer.name\", layer);\n    span?.setAttribute(\"element.type\", resolvedType);\n    span?.setAttribute(\"element.id\", elementPath);\n\n    // Validate source reference options\n    validateSourceReferenceOptions(options);\n\n    // Load model (with error handling for missing models)\n    let model: Model;\n    try {\n      model = await Model.load(options.model || process.cwd(), { layers: [layer] });\n    } catch (error) {\n      const message = getErrorMessage(error);\n      if (message.includes(\"No DR project\") || message.includes(\"Model not found\")) {\n        throw new ModelNotFoundError();\n      }\n      throw error;\n    }\n\n    // Get or create layer\n    let layerObj = await model.getLayer(layer);\n    if (!layerObj) {\n      layerObj = new Layer(layer);\n      model.addLayer(layerObj);\n    }\n\n    // Parse attributes if provided\n    let attributes: Record<string, unknown> = {};\n    if (options.attributes) {\n      try {\n        attributes = JSON.parse(options.attributes);\n      } catch (e) {\n        throw new InvalidJSONError(options.attributes, \"--attributes\");\n      }\n    }\n\n    // Create element in spec-node format\n    // id = UUIDv4 for schema compliance; path = slug for human-readable identifier\n    const element = new Element({\n      id: elementUUID,          // UUIDv4\n      path: elementPath,        // slug: {layer}.{resolvedType}.{kebab-name}\n      spec_node_id: `${layer}.${resolvedType}`,\n      layer_id: layer,\n      type: resolvedType,\n      name: options.name || name,\n      description: options.description,\n      attributes: attributes,\n      metadata: {\n        created_at: new Date().toISOString(),\n        updated_at: new Date().toISOString(),\n        version: 1,\n      },\n      layer, // Set layer so setSourceReference can use it\n    });\n\n\n    // Add source reference if provided\n    const sourceRef = buildSourceReference(options);\n    if (sourceRef) {\n      element.setSourceReference(sourceRef);\n    }\n\n    // Validate element attributes against spec schema before persisting\n    {\n      const schemaValidator = new SchemaValidator();\n      const tempLayer = new Layer(layer);\n      tempLayer.addElement(element);\n      const attrValidation = await schemaValidator.validateLayer(tempLayer);\n      if (!attrValidation.isValid()) {\n        const errorMessages = attrValidation.errors\n          .map((e) => `  ${e.message}`)\n          .join(\"\\n\");\n        throw new CLIError(\n          `Element ${elementPath} has invalid attributes:\\n${errorMessages}`,\n          ErrorCategory.USER,\n          [`Run \"dr schema ${layer} ${type}\" to see the required attributes`]\n        );\n      }\n    }\n\n    // Check if element already exists (look up by path)\n    if (layerObj.getElement(elementPath)) {\n      throw new CLIError(\n        `Element ${elementPath} already exists in ${layer} layer`,\n        ErrorCategory.USER,\n        [\n          `Use \"dr show ${elementPath}\" to view the existing element`,\n          `Use \"dr update ${elementPath}\" to modify it`,\n          `Use \"dr delete ${elementPath}\" to remove it first if you want to recreate it`,\n        ],\n        { operation: \"add\", context: `Duplicate element path` }\n      );\n    }\n\n    // Unified mutation handler for add operation\n    const handler = new MutationHandler(model, elementPath, layer);\n\n    // Execute add through unified path (handles staging and base model consistently)\n    await handler.executeAdd(element, (elem) => {\n      // This mutator is called by executeAdd for base model path only\n      layerObj.addElement(elem);\n    });\n\n    // Determine if operation was staged or applied to base model\n    if (handler.getAfterState()) {\n      // Check if we went through staging path\n      const stagingManager = handler.getStagingManager();\n      const activeChangeset = await stagingManager.getActive();\n      if (activeChangeset && activeChangeset.status === \"staged\") {\n        // Staging path\n        handleSuccess(\n          `Staged element ${ansis.bold(elementPath)} to ${ansis.bold(activeChangeset.name)}`,\n          {\n            elementId: elementPath,\n            layer,\n            type: resolvedType,\n            name: options.name || name,\n            changesetStatus: \"staged\",\n            changeset: activeChangeset.name,\n          },\n          { verbose: options.verbose }\n        );\n      } else {\n        // Base model path\n        handleSuccess(`Added element ${ansis.bold(elementPath)} to ${ansis.bold(layer)} layer`, {\n          elementId: elementPath,\n          layer,\n          type: resolvedType,\n          name: options.name || name,\n          description: options.description || \"(none)\",\n        }, { verbose: true });\n      }\n    }\n  } catch (error) {\n    handleError(error);\n  }\n}\n"],
-  "mappings": "AAIA,OAAO,WAAW;AAClB,SAAS,aAAa;AACtB,SAAS,aAAa;AACtB,SAAS,eAAe;AACxB,SAAS,uBAAuB;AAChC,SAAS,gCAAgC,4BAA4B;AACrE,SAAS,uBAAuB;AAChC,SAAS,qBAAqB;AAC9B,SAAS,mBAAmB,oBAAoB;AAChD,SAAS,gBAAgB,oBAAoB;AAC7C,SAAS,iBAAiB,sBAAsB,yBAAyB;AACzE,SACE,UACA,eACA,kBACA,oBACA,aACA,oBACA,iBACA,aACA,qBACK;AAiBP,eAAsB,WACpB,OACA,MACA,MACA,SAAmB;AAEnB,MAAI;AAEF,QAAI,CAAC,aAAa,KAAK,GAAG;AACxB,YAAM,cAAc,eAAc,GAC5B,UAAU,YAAY,OAAO,aAAa,CAAC,GAC3C,cAAwB,CAAC,2BAA2B,mBAAmB,WAAW,CAAC,EAAE;AAC3F,YAAI,QAAQ,SAAS,KACnB,YAAY,QAAQ,iBAAiB,QAAQ,KAAK,MAAM,CAAC,GAAG,GAExD,IAAI,SAAS,kBAAkB,KAAK,KAAK,cAAc,MAAM,aAAa;QAC9E,WAAW;QACX,SAAS,UAAU,KAAK,WAAW,IAAI,WAAW,IAAI;OACvD;IACH;AAGA,QAAI,CAAC,gBAAgB,OAAO,IAAI,GAAG;AAEjC,YAAM,YADiB,qBAAqB,KAAK,EAChB,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,KAAI,GAClD,UAAU,YAAY,MAAM,WAAW,CAAC,GACxC,cAAwB,CAAC,mBAAmB,KAAK,KAAK,mBAAmB,SAAS,CAAC,EAAE;AAC3F,YAAI,QAAQ,SAAS,KACnB,YAAY,QAAQ,iBAAiB,QAAQ,KAAK,MAAM,CAAC,GAAG,GAExD,IAAI,SACR,yBAAyB,IAAI,gBAAgB,KAAK,KAClD,cAAc,MACd,aACA;QACE,WAAW;QACX,SAAS,UAAU,KAAK,WAAW,IAAI,WAAW,IAAI;OACvD;IAEL;AAIA,UAAM,eAAe,kBAAkB,OAAO,IAAI,GAG5C,cAAc,kBAAkB,OAAO,cAAc,IAAI,GACzD,cAAc,aAAY;AAIhC,QAAI,CADa,YAAY,MAAM,GAAG,EAAE,CAAC;AAEvC,YAAM,IAAI,SACR,iDAAiD,IAAI,KACrD,cAAc,MACd;QACE;QACA,0BAA0B,WAAW;OACtC;AAIL,UAAM,OAAO,cAAa;AAC1B,UAAM,aAAa,cAAc,KAAK,GACtC,MAAM,aAAa,gBAAgB,YAAY,GAC/C,MAAM,aAAa,cAAc,WAAW,GAG5C,+BAA+B,OAAO;AAGtC,QAAI;AACJ,QAAI;AACF,cAAQ,MAAM,MAAM,KAAK,QAAQ,SAAS,QAAQ,IAAG,GAAI,EAAE,QAAQ,CAAC,KAAK,EAAC,CAAE;IAC9E,SAAS,OAAO;AACd,YAAM,UAAU,gBAAgB,KAAK;AACrC,YAAI,QAAQ,SAAS,eAAe,KAAK,QAAQ,SAAS,iBAAiB,IACnE,IAAI,mBAAkB,IAExB;IACR;AAGA,QAAI,WAAW,MAAM,MAAM,SAAS,KAAK;AACzC,IAAK,aACH,WAAW,IAAI,MAAM,KAAK,GAC1B,MAAM,SAAS,QAAQ;AAIzB,QAAI,aAAsC,CAAA;AAC1C,QAAI,QAAQ;AACV,UAAI;AACF,qBAAa,KAAK,MAAM,QAAQ,UAAU;MAC5C,QAAY;AACV,cAAM,IAAI,iBAAiB,QAAQ,YAAY,cAAc;MAC/D;AAKF,UAAM,UAAU,IAAI,QAAQ;MAC1B,IAAI;;MACJ,MAAM;;MACN,cAAc,GAAG,KAAK,IAAI,YAAY;MACtC,UAAU;MACV,MAAM;MACN,MAAM,QAAQ,QAAQ;MACtB,aAAa,QAAQ;MACrB;MACA,UAAU;QACR,aAAY,oBAAI,KAAI,GAAG,YAAW;QAClC,aAAY,oBAAI,KAAI,GAAG,YAAW;QAClC,SAAS;;MAEX;;KACD,GAIK,YAAY,qBAAqB,OAAO;AAC9C,IAAI,aACF,QAAQ,mBAAmB,SAAS;AAItC;AACE,YAAM,kBAAkB,IAAI,gBAAe,GACrC,YAAY,IAAI,MAAM,KAAK;AACjC,gBAAU,WAAW,OAAO;AAC5B,YAAM,iBAAiB,MAAM,gBAAgB,cAAc,SAAS;AACpE,UAAI,CAAC,eAAe,QAAO,GAAI;AAC7B,cAAM,gBAAgB,eAAe,OAClC,IAAI,CAAC,MAAM,KAAK,EAAE,OAAO,EAAE,EAC3B,KAAK;CAAI;AACZ,cAAM,IAAI,SACR,WAAW,WAAW;EAA6B,aAAa,IAChE,cAAc,MACd,CAAC,kBAAkB,KAAK,IAAI,IAAI,kCAAkC,CAAC;MAEvE;IACF;AAGA,QAAI,SAAS,WAAW,WAAW;AACjC,YAAM,IAAI,SACR,WAAW,WAAW,sBAAsB,KAAK,UACjD,cAAc,MACd;QACE,gBAAgB,WAAW;QAC3B,kBAAkB,WAAW;QAC7B,kBAAkB,WAAW;SAE/B,EAAE,WAAW,OAAO,SAAS,yBAAwB,CAAE;AAK3D,UAAM,UAAU,IAAI,gBAAgB,OAAO,aAAa,KAAK;AAS7D,QANA,MAAM,QAAQ,WAAW,SAAS,CAAC,SAAQ;AAEzC,eAAS,WAAW,IAAI;IAC1B,CAAC,GAGG,QAAQ,cAAa,GAAI;AAG3B,YAAM,kBAAkB,MADD,QAAQ,kBAAiB,EACH,UAAS;AACtD,MAAI,mBAAmB,gBAAgB,WAAW,WAEhD,cACE,kBAAkB,MAAM,KAAK,WAAW,CAAC,OAAO,MAAM,KAAK,gBAAgB,IAAI,CAAC,IAChF;QACE,WAAW;QACX;QACA,MAAM;QACN,MAAM,QAAQ,QAAQ;QACtB,iBAAiB;QACjB,WAAW,gBAAgB;SAE7B,EAAE,SAAS,QAAQ,QAAO,CAAE,IAI9B,cAAc,iBAAiB,MAAM,KAAK,WAAW,CAAC,OAAO,MAAM,KAAK,KAAK,CAAC,UAAU;QACtF,WAAW;QACX;QACA,MAAM;QACN,MAAM,QAAQ,QAAQ;QACtB,aAAa,QAAQ,eAAe;SACnC,EAAE,SAAS,GAAI,CAAE;IAExB;EACF,SAAS,OAAO;AACd,gBAAY,KAAK;EACnB;AACF;",
+  "sourcesContent": ["/**\n * Add an element to a layer\n */\n\nimport ansis from \"ansis\";\nimport { Model } from \"../core/model.js\";\nimport { Layer } from \"../core/layer.js\";\nimport { Element } from \"../core/element.js\";\nimport { MutationHandler } from \"../core/mutation-handler.js\";\nimport { validateSourceReferenceOptions, buildSourceReference } from \"../utils/source-reference.js\";\nimport { schemaLookupHint } from \"../utils/error-hints.js\";\nimport { SchemaValidator } from \"../validators/schema-validator.js\";\nimport { getActiveSpan } from \"../telemetry/index.js\";\nimport { generateElementId, generateUUID } from \"../utils/id-generator.js\";\nimport { getAllLayerIds, isValidLayer } from \"../generated/layer-registry.js\";\nimport { isValidNodeType, getNodeTypesForLayer, normalizeNodeType } from \"../generated/node-types.js\";\nimport {\n  CLIError,\n  ErrorCategory,\n  InvalidJSONError,\n  ModelNotFoundError,\n  findSimilar,\n  formatValidOptions,\n  getErrorMessage,\n  handleError,\n  handleSuccess,\n} from \"../utils/errors.js\";\n\n\nexport interface AddOptions {\n  model?: string;\n  name?: string;\n  description?: string;\n  attributes?: string;\n  sourceFile?: string;\n  sourceSymbol?: string;\n  sourceProvenance?: string;\n  sourceRepoRemote?: string;\n  sourceRepoCommit?: string;\n  verbose?: boolean;\n  debug?: boolean;\n}\n\nexport async function addCommand(\n  layer: string,\n  type: string,\n  name: string,\n  options: AddOptions\n): Promise<void> {\n  try {\n    // Validate layer name\n    if (!isValidLayer(layer)) {\n      const validLayers = getAllLayerIds();\n      const similar = findSimilar(layer, validLayers, 3);\n      const suggestions: string[] = [`Use a valid layer name: ${formatValidOptions(validLayers)}`];\n      if (similar.length > 0) {\n        suggestions.unshift(`Did you mean: ${similar.join(\" or \")}?`);\n      }\n      throw new CLIError(`Unknown layer \"${layer}\"`, ErrorCategory.USER, suggestions, {\n        operation: \"add\",\n        context: `Layer: ${layer}, Type: ${type}, Name: ${name}`,\n      });\n    }\n\n    // Validate element type for this layer\n    if (!isValidNodeType(layer, type)) {\n      const validNodeTypes = getNodeTypesForLayer(layer);\n      const typeNames = validNodeTypes.map((t) => t.type).sort();\n      const similar = findSimilar(type, typeNames, 3);\n      const suggestions: string[] = [`Valid types for ${layer}: ${formatValidOptions(typeNames)}`];\n      if (similar.length > 0) {\n        suggestions.unshift(`Did you mean: ${similar.join(\" or \")}?`);\n      }\n      throw new CLIError(\n        `Invalid element type \"${type}\" for layer \"${layer}\"`,\n        ErrorCategory.USER,\n        suggestions,\n        {\n          operation: \"add\",\n          context: `Layer: ${layer}, Type: ${type}, Name: ${name}`,\n        }\n      );\n    }\n\n    // Resolve abbreviated type names to their canonical spec names\n    // e.g., \"service\" \u2192 \"applicationservice\" for the application layer\n    const resolvedType = normalizeNodeType(layer, type);\n\n    // Generate slug path: {layer}.{resolvedType}.{kebab-name}\n    const elementPath = generateElementId(layer, resolvedType, name);  // slug\n    const elementUUID = generateUUID();                         // UUIDv4\n\n    // Validate the generated slug is non-empty (name may collapse to empty after stripping special chars)\n    const slugPart = elementPath.split(\".\")[2];\n    if (!slugPart) {\n      throw new CLIError(\n        `Cannot generate a valid element ID from name \"${name}\"`,\n        ErrorCategory.USER,\n        [\n          \"Element names must contain at least one letter or digit\",\n          `Generated ID would be: ${elementPath}`,\n        ]\n      );\n    }\n\n    const span = getActiveSpan();\n    span?.setAttribute(\"layer.name\", layer);\n    span?.setAttribute(\"element.type\", resolvedType);\n    span?.setAttribute(\"element.id\", elementPath);\n\n    // Validate source reference options\n    validateSourceReferenceOptions(options);\n\n    // Load model (with error handling for missing models)\n    let model: Model;\n    try {\n      model = await Model.load(options.model, { layers: [layer] });\n    } catch (error) {\n      const message = getErrorMessage(error);\n      if (message.includes(\"No DR project\") || message.includes(\"Model not found\")) {\n        throw new ModelNotFoundError();\n      }\n      throw error;\n    }\n\n    // Get or create layer\n    let layerObj = await model.getLayer(layer);\n    if (!layerObj) {\n      layerObj = new Layer(layer);\n      model.addLayer(layerObj);\n    }\n\n    // Parse attributes if provided\n    let attributes: Record<string, unknown> = {};\n    if (options.attributes) {\n      try {\n        attributes = JSON.parse(options.attributes);\n      } catch (e) {\n        throw new InvalidJSONError(options.attributes, \"--attributes\");\n      }\n    }\n\n    // Create element in spec-node format\n    // id = UUIDv4 for schema compliance; path = slug for human-readable identifier\n    const element = new Element({\n      id: elementUUID,          // UUIDv4\n      path: elementPath,        // slug: {layer}.{resolvedType}.{kebab-name}\n      spec_node_id: `${layer}.${resolvedType}`,\n      layer_id: layer,\n      type: resolvedType,\n      name: options.name || name,\n      description: options.description,\n      attributes: attributes,\n      metadata: {\n        created_at: new Date().toISOString(),\n        updated_at: new Date().toISOString(),\n        version: 1,\n      },\n      layer, // Set layer so setSourceReference can use it\n    });\n\n\n    // Add source reference if provided\n    const sourceRef = buildSourceReference(options);\n    if (sourceRef) {\n      element.setSourceReference(sourceRef);\n    }\n\n    // Validate element attributes against spec schema before persisting\n    {\n      const schemaValidator = new SchemaValidator();\n      const tempLayer = new Layer(layer);\n      tempLayer.addElement(element);\n      const attrValidation = await schemaValidator.validateLayer(tempLayer);\n      if (!attrValidation.isValid()) {\n        const errorMessages = attrValidation.errors\n          .map((e) => `  ${e.message}`)\n          .join(\"\\n\");\n        throw new CLIError(\n          `Element ${elementPath} has invalid attributes:\\n${errorMessages}`,\n          ErrorCategory.USER,\n          [schemaLookupHint(\"cli\", layer, resolvedType)]\n        );\n      }\n    }\n\n    // Check if element already exists (look up by path)\n    if (layerObj.getElement(elementPath)) {\n      throw new CLIError(\n        `Element ${elementPath} already exists in ${layer} layer`,\n        ErrorCategory.USER,\n        [\n          `Use \"dr show ${elementPath}\" to view the existing element`,\n          `Use \"dr update ${elementPath}\" to modify it`,\n          `Use \"dr delete ${elementPath}\" to remove it first if you want to recreate it`,\n        ],\n        { operation: \"add\", context: `Duplicate element path` }\n      );\n    }\n\n    // Unified mutation handler for add operation\n    const handler = new MutationHandler(model, elementPath, layer);\n\n    // Execute add through unified path (handles staging and base model consistently)\n    await handler.executeAdd(element, (elem) => {\n      // This mutator is called by executeAdd for base model path only\n      layerObj.addElement(elem);\n    });\n\n    // Determine if operation was staged or applied to base model\n    if (handler.getAfterState()) {\n      // Check if we went through staging path\n      const stagingManager = handler.getStagingManager();\n      const activeChangeset = await stagingManager.getActive();\n      if (activeChangeset && activeChangeset.status === \"staged\") {\n        // Staging path\n        handleSuccess(\n          `Staged element ${ansis.bold(elementPath)} to ${ansis.bold(activeChangeset.name)}`,\n          {\n            elementId: elementPath,\n            layer,\n            type: resolvedType,\n            name: options.name || name,\n            changesetStatus: \"staged\",\n            changeset: activeChangeset.name,\n          },\n          { verbose: options.verbose }\n        );\n      } else {\n        // Base model path\n        handleSuccess(`Added element ${ansis.bold(elementPath)} to ${ansis.bold(layer)} layer`, {\n          elementId: elementPath,\n          layer,\n          type: resolvedType,\n          name: options.name || name,\n          description: options.description || \"(none)\",\n        }, { verbose: true });\n      }\n    }\n  } catch (error) {\n    handleError(error);\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/commands/analyzer.js

@@ -9,6 +9,7 @@ import { CLIError, ModelNotFoundError, ErrorCategory, categorizeError } from "..
 import { findProjectRoot } from "../utils/project-paths.js";
 import { performDiscover } from "./discover-logic.js";
 import { formatVerifyReport } from "../export/verify-formatters.js";
+import { Model } from "../core/model.js";
 function analyzerCommands(program) {
   const analyzer = program.command("analyzer").description("Manage analyzer discovery and indexing");
   analyzer.command("discover").description("Discover and select an analyzer").option("--json", "Output as JSON").option("--reselect", "Force re-selection even if analyzer already selected").addHelpText("after", `
@@ -131,11 +132,16 @@ Examples:
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND, ["Check the analyzer name with `dr analyzer discover`"]);
       const actualProjectRoot = await findProjectRoot();
       let status;
-      if (actualProjectRoot ? status = await backend.status(actualProjectRoot) : status = {
-        detected: await backend.detect(),
-        indexed: !1,
-        fresh: !1
-      }, jsonMode) {
+      if (actualProjectRoot) {
+        const model = await Model.load(actualProjectRoot);
+        status = await backend.status(actualProjectRoot, { codebaseRoot: model.codebaseRoot });
+      } else
+        status = {
+          detected: await backend.detect(),
+          indexed: !1,
+          fresh: !1
+        };
+      if (jsonMode) {
         console.log(JSON.stringify(status, null, 2)), actualProjectRoot && await writeStatus(status, actualProjectRoot, analyzerName);
         return;
       }
@@ -174,8 +180,9 @@ Examples:
           `Visit: ${homepageUrl}`
         ]);
       }
+      const model = await Model.load(projectRoot);
       console.log(`Indexing project with ${analyzerName}...`);
-      const result = await backend.index(projectRoot, { force: options.force });
+      const result = await backend.index(projectRoot, { force: options.force, codebaseRoot: model.codebaseRoot });
       console.log(ansis.green("\u2713 Indexing complete")), console.log(`  Nodes: ${result.node_count}`), console.log(`  Edges: ${result.edge_count}`), console.log(`  Git HEAD: ${result.git_head}`);
     } catch (error) {
       if (error instanceof CLIError || error instanceof ModelNotFoundError)
@@ -205,9 +212,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
-      if (!(await backend.status(projectRoot)).indexed)
+      const model = await Model.load(projectRoot);
+      if (!(await backend.status(projectRoot, { codebaseRoot: model.codebaseRoot })).indexed)
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` to index the project first"]);
-      const endpoints = await backend.endpoints(projectRoot);
+      const endpoints = await backend.endpoints(projectRoot, { codebaseRoot: model.codebaseRoot });
       if (jsonMode) {
         console.log(JSON.stringify(endpoints, null, 2));
         return;
@@ -252,9 +260,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      let services = await backend.services(projectRoot);
+      let services = await backend.services(projectRoot, { codebaseRoot: model.codebaseRoot });
       if (options.layer && (services = services.filter((s) => s.suggested_layer === options.layer)), jsonMode) {
         console.log(JSON.stringify(services, null, 2));
         return;
@@ -298,9 +307,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      const datastores = await backend.datastores(projectRoot);
+      const datastores = await backend.datastores(projectRoot, { codebaseRoot: model.codebaseRoot });
       if (jsonMode) {
         console.log(JSON.stringify(datastores, null, 2));
         return;
@@ -348,9 +358,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      const callers = await backend.callers(projectRoot, qualifiedName, depth);
+      const callers = await backend.callers(projectRoot, qualifiedName, depth, { codebaseRoot: model.codebaseRoot });
       if (jsonMode) {
         console.log(JSON.stringify(callers, null, 2));
         return;
@@ -394,9 +405,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      const callees = await backend.callees(projectRoot, qualifiedName, depth);
+      const callees = await backend.callees(projectRoot, qualifiedName, depth, { codebaseRoot: model.codebaseRoot });
       if (jsonMode) {
         console.log(JSON.stringify(callees, null, 2));
         return;
@@ -441,9 +453,10 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
-      const result = await backend.query(projectRoot, cypher);
+      const result = await backend.query(projectRoot, cypher, { codebaseRoot: model.codebaseRoot });
       options.json, console.log(JSON.stringify(result, null, 2));
     } catch (error) {
       if (error instanceof CLIError || error instanceof ModelNotFoundError)
@@ -493,11 +506,13 @@ Examples:
       const backend = await registry.getAnalyzer(analyzerName);
       if (!backend)
         throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      const model = await Model.load(projectRoot);
       if (!await readIndexMeta(projectRoot, analyzerName))
         throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
       const report = await backend.verify(projectRoot, {
         layers: apiLayers,
-        changesetAware: !0
+        changesetAware: !0,
+        codebaseRoot: model.codebaseRoot
       }), formatted = formatVerifyReport(report, { format });
       if (options.output) {
         const outputPath = path.resolve(options.output);
@@ -511,6 +526,94 @@ Examples:
       const cliError = new CLIError(error instanceof Error ? error.message : String(error), categorizeError(error));
       throw error instanceof Error && (cliError.cause = error), cliError;
     }
+  }), analyzer.command("classify").description("Classify the indexed project's symbols into model layers and types (Tier 0: rules only)").option("--name <n>", "Analyzer name (defaults to active from session.json)").option("--tier0-only", "Apply only the analyzer's Tier-0 rules: no model calls, no network (required for now)").option("--label <labels>", "Comma-separated analyzer labels to classify (default: Class, Interface, Function, Method, Module, Route and every label a rule names)").option("--file <glob>", "Only symbols in files matching this glob").option("--exclude <regex>", "Also leave out files matching this regular expression (build and vendored paths always are)").option("--limit <n>", "Stop after this many symbols").option("--cards", "Include each symbol's full card (source and graph neighbourhood) in JSON output").option("--output <file>", "Write the JSON report to a file").option("--json", "Output as JSON").addHelpText("after", `
+Tier 0 is the first step of the classification cascade (docs/analyzers/CASCADE_DESIGN.md):
+the analyzer's rules decide a symbol's layer and type, reject it as not a model element,
+or narrow its choices for a later tier. Symbols no rule covers are reported as undecided.
+Nothing is written to the model.
+
+Examples:
+  $ dr analyzer classify --tier0-only
+  $ dr analyzer classify --tier0-only --json > tier0.json
+  $ dr analyzer classify --tier0-only --label Class,Method --file "src/main/**"
+  $ dr analyzer classify --tier0-only --cards --output tier0-cards.json`).action(async (options) => {
+    const jsonMode = options.json ?? program.opts().json;
+    try {
+      if (!options.tier0Only)
+        throw new CLIError("Only Tier-0 classification is available so far: pass --tier0-only", ErrorCategory.USER, ["Model-backed classification (Tier 1) needs the per-project opt-in and is not built yet"]);
+      let exclude;
+      if (options.exclude !== void 0)
+        try {
+          exclude = new RegExp(String(options.exclude));
+        } catch (e) {
+          throw new CLIError(`Invalid --exclude regular expression: ${e instanceof Error ? e.message : String(e)}`, ErrorCategory.USER);
+        }
+      let limit;
+      if (options.limit !== void 0 && (limit = Number(options.limit), !Number.isInteger(limit) || limit < 1))
+        throw new CLIError(`--limit must be a positive integer, got '${options.limit}'`, ErrorCategory.USER);
+      const labels = options.label ? String(options.label).split(",").map((l) => l.trim()).filter(Boolean) : void 0;
+      options.cards && !jsonMode && !options.output && console.error(ansis.yellow("--cards only affects JSON output: add --json or --output <file>"));
+      const projectRoot = await findProjectRoot();
+      if (!projectRoot)
+        throw new ModelNotFoundError();
+      let analyzerName = options.name;
+      if (!analyzerName) {
+        const session = await readSession(projectRoot);
+        if (!session)
+          throw new CLIError("No analyzer selected. Run `dr analyzer discover` first.", ErrorCategory.USER);
+        analyzerName = session.active_analyzer;
+      }
+      const registry = AnalyzerRegistry.getInstance();
+      await registry.initialize();
+      const backend = await registry.getAnalyzer(analyzerName);
+      if (!backend)
+        throw new CLIError(`Analyzer not found: ${analyzerName}`, ErrorCategory.NOT_FOUND);
+      if (!backend.classify)
+        throw new CLIError(`The ${analyzerName} analyzer does not support classification`, ErrorCategory.USER);
+      if (!await readIndexMeta(projectRoot, analyzerName))
+        throw new CLIError("Project not indexed", ErrorCategory.USER, ["Run `dr analyzer index` first"]);
+      const model = await Model.load(projectRoot), showProgress = !jsonMode && !options.output && process.stderr.isTTY, report = await backend.classify(projectRoot, {
+        codebaseRoot: model.codebaseRoot,
+        labels,
+        filePattern: options.file,
+        exclude,
+        limit,
+        includeCards: !!options.cards,
+        onProgress: showProgress ? (done, total) => {
+          (done % 50 === 0 || done === total) && process.stderr.write(`\r  ${done}/${total} symbols`), done === total && process.stderr.write(`
+`);
+        } : void 0
+      });
+      if (options.output) {
+        const outputPath = path.resolve(options.output);
+        await fs.writeFile(outputPath, JSON.stringify(report, null, 2) + `
+`, "utf-8"), jsonMode || console.log(ansis.green(`\u2713 Report written to ${outputPath}`));
+      }
+      if (jsonMode) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+      }
+      const { summary } = report, pct = (n) => summary.cards ? `${(100 * n / summary.cards).toFixed(0)}%` : "0%";
+      console.log(""), console.log(ansis.bold(`Tier-0 classification: ${summary.cards} symbols, ${report.rules} rules`)), console.log(ansis.dim("\u2500".repeat(60))), console.log(`  ${ansis.green("decided")}    ${String(summary.decided).padStart(6)}  ${pct(summary.decided)}`), console.log(`  ${ansis.yellow("rejected")}   ${String(summary.rejected).padStart(6)}  ${pct(summary.rejected)}  (not model elements)`), console.log(`  ${ansis.cyan("narrowed")}   ${String(summary.narrowed).padStart(6)}  ${pct(summary.narrowed)}  (choices restricted for Tier 1)`), console.log(`  ${ansis.dim("undecided")}  ${String(summary.undecided).padStart(6)}  ${pct(summary.undecided)}`), summary.no_source && console.log(ansis.yellow(`  ${summary.no_source} symbol(s) had no source, so rules that read the declaration could not apply`));
+      const targets = Object.entries(summary.by_target).sort((a, b) => b[1] - a[1]);
+      if (targets.length) {
+        console.log(""), console.log(ansis.bold("Decided, by type:"));
+        for (const [target, n] of targets)
+          console.log(`  ${target.padEnd(40)} ${String(n).padStart(6)}`);
+      }
+      const rules = Object.entries(summary.by_rule).sort((a, b) => b[1] - a[1]);
+      if (rules.length) {
+        console.log(""), console.log(ansis.bold("Matches, by rule:"));
+        for (const [rule, n] of rules)
+          console.log(`  ${rule.padEnd(40)} ${String(n).padStart(6)}`);
+      }
+      console.log(ansis.dim("\u2500".repeat(60))), console.log(ansis.dim("Per-symbol outcomes: --json or --output <file>")), console.log("");
+    } catch (error) {
+      if (error instanceof CLIError || error instanceof ModelNotFoundError)
+        throw error;
+      const cliError = new CLIError(error instanceof Error ? error.message : String(error), categorizeError(error));
+      throw error instanceof Error && (cliError.cause = error), cliError;
+    }
   });
 }
 export {