@documentation-robotics/cli 0.1.12 → 0.2.0

package/README.md

@@ -264,6 +264,44 @@ dr chat github-copilot                   # Use GitHub Copilot, save as preferenc
 
 **Note**: Chat requires either [Claude Code CLI](https://claude.ai/download) or [GitHub Copilot CLI](https://github.com/github/gh-copilot) to be installed and authenticated. The CLI will auto-detect available clients and prompt you to choose if both are installed. You can also explicitly specify which client to use.
 
+### MCP Server
+
+`dr mcp` starts a [Model Context Protocol](https://modelcontextprotocol.io/) server over stdio, exposing the architecture model (list/show/search/add/update/delete/validate/export/trace elements, changesets, chat) as tools an MCP-aware AI client can call directly.
+
+```bash
+# Start the server (run by your MCP client, not typically by hand)
+dr mcp
+
+# Rotate the API key: generates a new key, overwrites it at the configured
+# storage path, and prints it — without touching the server process
+dr mcp --regenerate-key
+```
+
+**API key**:
+
+- On first launch, `dr mcp` generates a random API key and stores it on disk with `0600` permissions. Interactive sessions are prompted for a storage path; non-interactive launches (the normal case — an MCP client spawning `dr mcp`) default to `~/.dr-mcp-key`.
+- The chosen path is recorded under `mcp.api_key_path` in `~/.dr-config.yaml` (or the path from `DR_CONFIG_PATH`, if set), so subsequent launches reuse the same key without re-prompting.
+- Every launch prints the current key to stderr (never stdout, which carries the MCP protocol) and requires the client to supply it back via the `DR_MCP_API_KEY` environment variable. The connection is rejected if `DR_MCP_API_KEY` is missing or doesn't match.
+- Run `dr mcp --regenerate-key` to rotate the key (e.g. after a suspected leak). This overwrites the key at its existing configured path (or the default path, prompting once if none is configured yet), updates `~/.dr-config.yaml`, prints the new key, and exits without starting the server — no manual deletion of config or key files required.
+
+**Configuring an MCP client**:
+
+Point your MCP client at the `dr` binary and pass the key via `env`:
+
+```json
+{
+  "mcpServers": {
+    "documentation-robotics": {
+      "command": "dr",
+      "args": ["mcp"],
+      "env": {
+        "DR_MCP_API_KEY": "<key printed by dr mcp>"
+      }
+    }
+  }
+}
+```
+
 ## Configuration
 
 ### Model Structure
@@ -289,7 +327,7 @@ your-project/
 │       └── ...
 ```
 
-**Legacy models**: Old projects using `.dr/` directory will auto-migrate changesets to `documentation-robotics/changesets/` on first use.
+**Spec-version migrations**: When the model's spec version is older than the CLI's bundled spec (e.g. after a layer renumbering), run `dr upgrade` to migrate the on-disk model in place — see `MigrationRegistry` in `cli/src/core/migration-registry.ts` for the supported version paths.
 
 ### Specification Reference
 

package/dist/analyzers/verify-engine.js

@@ -1,6 +1,7 @@
 import * as path from "path";
 import { access } from "fs/promises";
 import { Model } from "../core/model.js";
+import { getErrorMessage } from "../utils/errors.js";
 import { IgnoreFileLoader } from "./verify-ignore.js";
 import { SOURCE_CODE_EXT_RE } from "./cbm-analyzer.js";
 class VerifyEngine {
@@ -25,8 +26,8 @@ class VerifyEngine {
     try {
       model = await Model.load(projectRoot);
     } catch (error) {
-      const err = error;
-      throw err.code === "ENOENT" || err.code === "ENOTDIR" ? new Error(`Failed to load DR model at ${projectRoot}: Model directory not found or inaccessible. Please run 'dr init' to initialize the documentation robotics model.`) : new Error(`Failed to load DR model at ${projectRoot}: ${err.message}. Please check that the model directory exists and is accessible.`);
+      const message = getErrorMessage(error);
+      throw message.includes("No DR project") || message.includes("Model not found") || message.includes("no model found") || message.includes("Could not find documentation_robotics") ? new Error(`Failed to load DR model at ${projectRoot}: Model not found. Please run 'dr init' to initialize the documentation robotics model.`) : error;
     }
     const activeChangesetId = model.getActiveChangesetId(), apiLayer = options.changesetAware === !1 ? await model.getBaseLayer("api") : await model.getLayer("api");
     if (!apiLayer)
@@ -129,7 +130,7 @@ Warning: ${emptySymbolCount}/${routes.length} graph route(s) have empty source_s
         file: firstLocation.file,
         symbol: firstLocation.symbol || ""
       });
-      const filePath = path.join(projectRoot, firstLocation.file);
+      const filePath = path.join(model.codebaseRoot, firstLocation.file);
       fileChecks.push(access(filePath).then(() => !0).catch((err) => err.code !== "ENOENT"));
     }
     elementsWithoutSourceRef > 0 && console.warn(`
@@ -143,22 +144,24 @@ Warning: ${elementsWithNonIndexableSource} API model element(s) excluded from dr
   or use dr analyzer endpoints to discover routes automatically.
 `);
     const fileExistsResults = await Promise.all(fileChecks);
-    for (let i = 0; i < elementsToCheck.length; i++)
-      if (fileExistsResults[i]) {
-        const elem = elementsToCheck[i], ignoreReason = IgnoreFileLoader.matches({
-          element_id: elem.path
-        }, "element", ignoreRules);
-        ignoreReason ? ignored.push({
-          id: elem.id,
-          entry_type: "element",
-          reason: ignoreReason
-        }) : inModelOnly.push({
-          id: elem.id,
-          type: "operation",
-          source_file: elem.file,
-          source_symbol: elem.symbol
-        });
-      }
+    for (let i = 0; i < elementsToCheck.length; i++) {
+      const fileExists = fileExistsResults[i], elem = elementsToCheck[i];
+      if (fileExists === !1)
+        continue;
+      const ignoreReason = IgnoreFileLoader.matches({
+        element_id: elem.path
+      }, "element", ignoreRules);
+      ignoreReason ? ignored.push({
+        id: elem.id,
+        entry_type: "element",
+        reason: ignoreReason
+      }) : inModelOnly.push({
+        id: elem.id,
+        type: "operation",
+        source_file: elem.file,
+        source_symbol: elem.symbol
+      });
+    }
     const buckets = {
       matched,
       in_graph_only: inGraphOnly,

package/dist/analyzers/verify-engine.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/analyzers/verify-engine.ts"],
-  "sourcesContent": ["/**\n * Verify Engine - computes verification reports for API endpoints\n *\n * Implements the core algorithm for comparing graph-discovered routes against\n * model-defined operations, supporting dual-index matching and changeset awareness.\n */\n\nimport * as path from \"path\";\nimport { access } from \"fs/promises\";\nimport { Model } from \"../core/model.js\";\nimport type {\n  VerifyReport,\n  VerifyOptions,\n  MatchedEntry,\n  GraphOnlyEntry,\n  ModelOnlyEntry,\n  IgnoredEntry,\n  VerifyBuckets,\n  VerifySummary,\n  IndexMeta,\n  VerifyChangesetContext,\n} from \"./types.js\";\nimport { IgnoreFileLoader } from \"./verify-ignore.js\";\nimport { SOURCE_CODE_EXT_RE } from \"./cbm-analyzer.js\";\n\n/**\n * A discovered route from the graph\n */\nexport interface DiscoveredRoute {\n  id: string;\n  http_method?: string;\n  http_path?: string;\n  handler?: string;\n  source_file?: string;\n  source_symbol?: string;\n}\n\n/**\n * Model element reference extracted from the API layer\n * Contains the minimal set of fields needed for dual-index matching\n */\ninterface ModelElementRef {\n  /** Element ID from the model */\n  id: string;\n  /** Source file path for primary index matching */\n  source_file?: string;\n  /** Source symbol for primary index matching */\n  source_symbol?: string;\n  /** HTTP method for secondary index matching */\n  http_method?: string;\n  /** HTTP path for secondary index matching */\n  http_path?: string;\n}\n\n/**\n * Primary or secondary index entry (holds model element data, not discovered route data)\n */\ninterface IndexEntry {\n  modelEntry: ModelElementRef;\n  key: string;\n}\n\n/**\n * VerifyEngine - computes verification reports for API endpoints\n */\nexport class VerifyEngine {\n  /**\n   * Compute a comprehensive verification report\n   *\n   * Implements the five-step algorithm:\n   * 1. Resolve model view via Model.load() + getActiveChangesetId() + getLayer(\"api\")\n   * 2. Build primary index on source_reference.locations[0].file + \":\" + symbol\n   *    and optional secondary index on http_method + \":\" + http_path\n   * 3. Load ignore rules\n   * 4. Compute four buckets (matched, in_graph_only, in_model_only, ignored)\n   * 5. Assemble VerifyReport\n   *\n   * @param projectRoot Absolute path to the project root\n   * @param routes Array of discovered routes from the graph\n   * @param options Verification options\n   * @returns Comprehensive verification report\n   */\n  async computeReport(\n    projectRoot: string,\n    routes: DiscoveredRoute[],\n    options: VerifyOptions,\n    analyzerName: string = \"codebase-memory-mcp\",\n    indexMeta?: IndexMeta\n  ): Promise<VerifyReport> {\n    // Step 1: Resolve model view\n    let model: Model;\n    try {\n      model = await Model.load(projectRoot);\n    } catch (error) {\n      const err = error as NodeJS.ErrnoException;\n      // Provide helpful error message if model directory is missing or corrupted\n      if (err.code === \"ENOENT\" || err.code === \"ENOTDIR\") {\n        throw new Error(\n          `Failed to load DR model at ${projectRoot}: Model directory not found or inaccessible. ` +\n          `Please run 'dr init' to initialize the documentation robotics model.`\n        );\n      }\n      throw new Error(\n        `Failed to load DR model at ${projectRoot}: ${err.message}. ` +\n        `Please check that the model directory exists and is accessible.`\n      );\n    }\n\n    const activeChangesetId = model.getActiveChangesetId();\n\n    // Use base layer if changesetAware is explicitly false\n    const apiLayer = options.changesetAware === false\n      ? await model.getBaseLayer(\"api\")\n      : await model.getLayer(\"api\");\n\n    if (!apiLayer) {\n      // No API layer found - all routes are in_graph_only\n      return this.assembleReport(\n        projectRoot,\n        model,\n        {\n          matched: [],\n          in_graph_only: routes.map((r) => ({\n            id: r.id,\n            http_method: r.http_method,\n            http_path: r.http_path,\n            source_file: r.source_file || \"\",\n            source_symbol: r.source_symbol || \"\",\n          })),\n          in_model_only: [],\n          ignored: [],\n        },\n        activeChangesetId,\n        options,\n        analyzerName,\n        indexMeta\n      );\n    }\n\n    // Step 2: Build dual-index\n    const primaryIndex = new Map<string, IndexEntry>();\n    const secondaryIndex = new Map<string, IndexEntry>();\n\n    for (const element of apiLayer.elements.values()) {\n      const firstLocation = element.source_reference?.locations?.[0];\n\n      // Primary index: file:symbol\n      if (firstLocation && firstLocation.file) {\n        const symbol = firstLocation.symbol || \"\";\n        const key = `${firstLocation.file}:${symbol}`;\n        primaryIndex.set(key, {\n          modelEntry: {\n            id: element.id,\n            source_file: firstLocation.file,\n            source_symbol: symbol,\n          },\n          key,\n        });\n      }\n\n      // Secondary index: http_method:http_path\n      const attrs = element.attributes as any;\n      if (attrs?.http_method && attrs?.http_path) {\n        const key = `${attrs.http_method}:${attrs.http_path}`;\n        secondaryIndex.set(key, {\n          modelEntry: {\n            id: element.id,\n            http_method: attrs.http_method,\n            http_path: attrs.http_path,\n          },\n          key,\n        });\n      }\n    }\n\n    // Warn if any graph routes have no source_symbol \u2014 they will be skipped by primary-index matching\n    const emptySymbolCount = routes.filter((r) => !r.source_symbol).length;\n    if (emptySymbolCount > 0) {\n      console.warn(\n        `\\nWarning: ${emptySymbolCount}/${routes.length} graph route(s) have empty source_symbol.` +\n        ` Primary-index matching by (source_file, source_symbol) will skip them.\\n` +\n        `  Likely cause: the code graph analyzer did not extract handler function names for this language.\\n` +\n        `  Secondary-index matching (http_method + http_path) requires those attributes on model operations.\\n` +\n        `  To fix: re-index after the analyzer is updated, or manually set http_method/http_path on operations.\\n`\n      );\n    }\n\n    // Step 3: Load ignore rules\n    const ignoreFilePath =\n      options.ignoreFilePath || path.join(projectRoot, \".dr-verify-ignore.yaml\");\n    const ignoreRules = await IgnoreFileLoader.load(ignoreFilePath);\n\n    // Step 4: Compute buckets\n    const matched: MatchedEntry[] = [];\n    const inGraphOnly: GraphOnlyEntry[] = [];\n    const ignored: IgnoredEntry[] = [];\n    const matchedRouteIds = new Set<string>();\n\n    for (const route of routes) {\n      let matchedElement: { id: string } | undefined;\n\n      // Try primary index match\n      if (route.source_file && route.source_symbol) {\n        const key = `${route.source_file}:${route.source_symbol}`;\n        const primaryMatch = primaryIndex.get(key);\n        if (primaryMatch) {\n          matchedElement = primaryMatch.modelEntry;\n        }\n      }\n\n      // Fallback to secondary index match\n      if (!matchedElement && route.http_method && route.http_path) {\n        const key = `${route.http_method}:${route.http_path}`;\n        const secondaryMatch = secondaryIndex.get(key);\n        if (secondaryMatch) {\n          matchedElement = secondaryMatch.modelEntry;\n        }\n      }\n\n      // Check if ignored\n      const ignoreReason = IgnoreFileLoader.matches(\n        {\n          handler: route.handler,\n          path: route.http_path,\n          element_id: route.id,\n        },\n        \"route\",\n        ignoreRules\n      );\n\n      if (ignoreReason) {\n        ignored.push({\n          id: route.id,\n          entry_type: \"route\",\n          reason: ignoreReason,\n        });\n        // Update matchedRouteIds even when ignored to prevent false drift\n        if (matchedElement) {\n          matchedRouteIds.add(matchedElement.id);\n        }\n      } else if (matchedElement) {\n        matched.push({\n          id: matchedElement.id,\n          type: \"operation\",\n          source_file: route.source_file || \"\",\n          source_symbol: route.source_symbol || \"\",\n        });\n        matchedRouteIds.add(matchedElement.id);\n      } else {\n        inGraphOnly.push({\n          id: route.id,\n          http_method: route.http_method,\n          http_path: route.http_path,\n          source_file: route.source_file || \"\",\n          source_symbol: route.source_symbol || \"\",\n        });\n      }\n    }\n\n    // Compute in_model_only: model elements not matched in graph\n    const inModelOnly: ModelOnlyEntry[] = [];\n\n    // Batch file-existence checks\n    const fileChecks: Promise<boolean>[] = [];\n    const elementsToCheck: Array<{ id: string; path: string; file: string; symbol: string }> = [];\n    let elementsWithoutSourceRef = 0;\n    let elementsWithNonIndexableSource = 0;\n\n    for (const element of apiLayer.elements.values()) {\n      if (matchedRouteIds.has(element.id)) {\n        continue; // Already matched\n      }\n\n      const firstLocation = element.source_reference?.locations?.[0];\n\n      if (!firstLocation || !firstLocation.file) {\n        // Skip elements with no source_reference file - they cannot drift since they have no code linkage.\n        // This includes manually-created elements that are documentation-only.\n        elementsWithoutSourceRef++;\n        continue;\n      }\n\n      // CBM only indexes source-code files \u2014 non-code source files (e.g. openapi.yaml)\n      // will never appear in the graph, so including them in drift detection produces false positives.\n      if (!SOURCE_CODE_EXT_RE.test(firstLocation.file)) {\n        elementsWithNonIndexableSource++;\n        continue;\n      }\n\n      elementsToCheck.push({\n        id: element.id,\n        path: element.path,\n        file: firstLocation.file,\n        symbol: firstLocation.symbol || \"\",\n      });\n\n      const filePath = path.join(projectRoot, firstLocation.file);\n      fileChecks.push(\n        access(filePath)\n          .then(() => true)\n          .catch((err: NodeJS.ErrnoException) => {\n            // Only treat ENOENT (file not found) as \"file doesn't exist\"\n            // Other errors (EACCES, EMFILE, etc.) are treated as \"file exists\" to avoid false negatives\n            if (err.code === \"ENOENT\") {\n              return false;\n            }\n            // For permission errors and other issues, assume file exists to be conservative\n            return true;\n          })\n      );\n    }\n\n    if (elementsWithoutSourceRef > 0) {\n      console.warn(\n        `\\nWarning: ${elementsWithoutSourceRef} API model element(s) excluded from drift detection` +\n        ` \u2014 they have no source_reference with a file location.\\n` +\n        `  Drift detection requires a linked source file to compare against the code graph.\\n` +\n        `  Fix: dr update <element-id> --source-file <relative-path> --source-symbol <symbol>\\n` +\n        `  Elements ingested via /dr-map or dr analyzer endpoints are automatically attributed.\\n`\n      );\n    }\n\n    if (elementsWithNonIndexableSource > 0) {\n      console.warn(\n        `\\nWarning: ${elementsWithNonIndexableSource} API model element(s) excluded from drift detection` +\n        ` \u2014 their source files are not indexable source-code files.\\n` +\n        `  Point source_reference to a source-code file (.ts, .js, .py, etc.) for drift detection,\\n` +\n        `  or use dr analyzer endpoints to discover routes automatically.\\n`\n      );\n    }\n\n    // Wait for all file checks. All promises have .catch() handlers that return booleans,\n    // so they will never reject - Promise.all() is safe and simpler than allSettled.\n    const fileExistsResults = await Promise.all(fileChecks);\n\n    // Add to in_model_only only if file exists, then check against ignore rules\n    for (let i = 0; i < elementsToCheck.length; i++) {\n      const fileExists = fileExistsResults[i];\n\n      if (fileExists) {\n        const elem = elementsToCheck[i];\n\n        // Check if element matches any ignore rule\n        // Use element.path (semantic path) instead of elem.id (UUID)\n        const ignoreReason = IgnoreFileLoader.matches(\n          {\n            element_id: elem.path,\n          },\n          \"element\",\n          ignoreRules\n        );\n\n        if (ignoreReason) {\n          ignored.push({\n            id: elem.id,\n            entry_type: \"element\",\n            reason: ignoreReason,\n          });\n        } else {\n          inModelOnly.push({\n            id: elem.id,\n            type: \"operation\",\n            source_file: elem.file,\n            source_symbol: elem.symbol,\n          });\n        }\n      }\n    }\n\n    // Step 5: Assemble report\n    const buckets: VerifyBuckets = {\n      matched,\n      in_graph_only: inGraphOnly,\n      in_model_only: inModelOnly,\n      ignored,\n    };\n\n    return this.assembleReport(\n      projectRoot,\n      model,\n      buckets,\n      activeChangesetId,\n      options,\n      analyzerName,\n      indexMeta,\n      elementsWithoutSourceRef + elementsWithNonIndexableSource\n    );\n  }\n\n  /**\n   * Assemble the final verification report\n   *\n   * @private\n   */\n  private assembleReport(\n    projectRoot: string,\n    model: Model,\n    buckets: VerifyBuckets,\n    activeChangesetId: string | null,\n    options: VerifyOptions,\n    analyzerName: string = \"codebase-memory-mcp\",\n    indexMeta?: IndexMeta,\n    elementsWithoutSourceRef: number = 0\n  ): VerifyReport {\n    const matchedElements = buckets.matched.length;\n    const inModelOnly = buckets.in_model_only.length;\n    const ignoredElements = buckets.ignored.filter((e) => e.entry_type === \"element\").length;\n    const summary: VerifySummary = {\n      matched_count: matchedElements,\n      gap_count: buckets.in_graph_only.length,\n      drift_count: inModelOnly,\n      ignored_count: buckets.ignored.length,\n      total_graph_entries: matchedElements + buckets.in_graph_only.length + buckets.ignored.filter((e) => e.entry_type === \"route\").length,\n      // Count all API layer elements: those that participated in matching plus those\n      // excluded because they lack source_reference (documentation-only elements).\n      total_model_entries: matchedElements + inModelOnly + ignoredElements + elementsWithoutSourceRef,\n      elements_without_source_ref: elementsWithoutSourceRef,\n    };\n\n    // Determine changeset context\n    const changesetAware = options.changesetAware ?? true;\n    const hasActiveChangeset = changesetAware && activeChangesetId !== null;\n\n    // Use analyzer index timestamp if provided, otherwise fall back to model manifest modified time\n    const analyzerIndexedAt = indexMeta?.timestamp || model.manifest.modified;\n\n    // Construct changeset context as discriminated union\n    const changeset_context: VerifyChangesetContext = hasActiveChangeset\n      ? {\n          active_changeset: activeChangesetId,\n          verified_against: \"changeset_view\",\n        }\n      : {\n          active_changeset: null,\n          verified_against: \"base_model\",\n        };\n\n    const hints: string[] = [];\n    if (buckets.in_graph_only.length > 0) {\n      hints.push(\n        \"To close gaps with source attribution, use /dr-map or `dr analyzer endpoints` ingestion \u2014 \"\n        + \"manual `dr add` operations cannot be matched by the verifier.\"\n      );\n    }\n\n    return {\n      generated_at: new Date().toISOString(),\n      project_root: projectRoot,\n      analyzer: analyzerName,\n      analyzer_indexed_at: analyzerIndexedAt,\n      changeset_context,\n      layers_verified: [\"api\"],\n      buckets,\n      summary,\n      ...(hints.length > 0 ? { hints } : {}),\n    };\n  }\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["/**\n * Verify Engine - computes verification reports for API endpoints\n *\n * Implements the core algorithm for comparing graph-discovered routes against\n * model-defined operations, supporting dual-index matching and changeset awareness.\n */\n\nimport * as path from \"path\";\nimport { access } from \"fs/promises\";\nimport { Model } from \"../core/model.js\";\nimport { getErrorMessage } from \"../utils/errors.js\";\nimport type {\n  VerifyReport,\n  VerifyOptions,\n  MatchedEntry,\n  GraphOnlyEntry,\n  ModelOnlyEntry,\n  IgnoredEntry,\n  VerifyBuckets,\n  VerifySummary,\n  IndexMeta,\n  VerifyChangesetContext,\n} from \"./types.js\";\nimport { IgnoreFileLoader } from \"./verify-ignore.js\";\nimport { SOURCE_CODE_EXT_RE } from \"./cbm-analyzer.js\";\n\n/**\n * A discovered route from the graph\n */\nexport interface DiscoveredRoute {\n  id: string;\n  http_method?: string;\n  http_path?: string;\n  handler?: string;\n  source_file?: string;\n  source_symbol?: string;\n}\n\n/**\n * Model element reference extracted from the API layer\n * Contains the minimal set of fields needed for dual-index matching\n */\ninterface ModelElementRef {\n  /** Element ID from the model */\n  id: string;\n  /** Source file path for primary index matching */\n  source_file?: string;\n  /** Source symbol for primary index matching */\n  source_symbol?: string;\n  /** HTTP method for secondary index matching */\n  http_method?: string;\n  /** HTTP path for secondary index matching */\n  http_path?: string;\n}\n\n/**\n * Primary or secondary index entry (holds model element data, not discovered route data)\n */\ninterface IndexEntry {\n  modelEntry: ModelElementRef;\n  key: string;\n}\n\n/**\n * VerifyEngine - computes verification reports for API endpoints\n */\nexport class VerifyEngine {\n  /**\n   * Compute a comprehensive verification report\n   *\n   * Implements the five-step algorithm:\n   * 1. Resolve model view via Model.load() + getActiveChangesetId() + getLayer(\"api\")\n   * 2. Build primary index on source_reference.locations[0].file + \":\" + symbol\n   *    and optional secondary index on http_method + \":\" + http_path\n   * 3. Load ignore rules\n   * 4. Compute four buckets (matched, in_graph_only, in_model_only, ignored)\n   * 5. Assemble VerifyReport\n   *\n   * @param projectRoot Absolute path to the project root\n   * @param routes Array of discovered routes from the graph\n   * @param options Verification options\n   * @returns Comprehensive verification report\n   */\n  async computeReport(\n    projectRoot: string,\n    routes: DiscoveredRoute[],\n    options: VerifyOptions,\n    analyzerName: string = \"codebase-memory-mcp\",\n    indexMeta?: IndexMeta\n  ): Promise<VerifyReport> {\n    // Step 1: Resolve model view\n    let model: Model;\n    try {\n      model = await Model.load(projectRoot);\n    } catch (error) {\n      const message = getErrorMessage(error);\n      // Check for model-not-found errors (matches all 4 error messages from Model.resolveModelPaths)\n      if (\n        message.includes(\"No DR project\") ||\n        message.includes(\"Model not found\") ||\n        message.includes(\"no model found\") ||\n        message.includes(\"Could not find documentation_robotics\")\n      ) {\n        throw new Error(\n          `Failed to load DR model at ${projectRoot}: Model not found. Please run 'dr init' to initialize the documentation robotics model.`\n        );\n      }\n      // Re-throw original error unchanged to preserve stack trace and error type (e.g., YAML parse errors)\n      throw error;\n    }\n\n    const activeChangesetId = model.getActiveChangesetId();\n\n    // Use base layer if changesetAware is explicitly false\n    const apiLayer = options.changesetAware === false\n      ? await model.getBaseLayer(\"api\")\n      : await model.getLayer(\"api\");\n\n    if (!apiLayer) {\n      // No API layer found - all routes are in_graph_only\n      return this.assembleReport(\n        projectRoot,\n        model,\n        {\n          matched: [],\n          in_graph_only: routes.map((r) => ({\n            id: r.id,\n            http_method: r.http_method,\n            http_path: r.http_path,\n            source_file: r.source_file || \"\",\n            source_symbol: r.source_symbol || \"\",\n          })),\n          in_model_only: [],\n          ignored: [],\n        },\n        activeChangesetId,\n        options,\n        analyzerName,\n        indexMeta\n      );\n    }\n\n    // Step 2: Build dual-index\n    const primaryIndex = new Map<string, IndexEntry>();\n    const secondaryIndex = new Map<string, IndexEntry>();\n\n    for (const element of apiLayer.elements.values()) {\n      const firstLocation = element.source_reference?.locations?.[0];\n\n      // Primary index: file:symbol\n      if (firstLocation && firstLocation.file) {\n        const symbol = firstLocation.symbol || \"\";\n        const key = `${firstLocation.file}:${symbol}`;\n        primaryIndex.set(key, {\n          modelEntry: {\n            id: element.id,\n            source_file: firstLocation.file,\n            source_symbol: symbol,\n          },\n          key,\n        });\n      }\n\n      // Secondary index: http_method:http_path\n      const attrs = element.attributes as any;\n      if (attrs?.http_method && attrs?.http_path) {\n        const key = `${attrs.http_method}:${attrs.http_path}`;\n        secondaryIndex.set(key, {\n          modelEntry: {\n            id: element.id,\n            http_method: attrs.http_method,\n            http_path: attrs.http_path,\n          },\n          key,\n        });\n      }\n    }\n\n    // Warn if any graph routes have no source_symbol \u2014 they will be skipped by primary-index matching\n    const emptySymbolCount = routes.filter((r) => !r.source_symbol).length;\n    if (emptySymbolCount > 0) {\n      console.warn(\n        `\\nWarning: ${emptySymbolCount}/${routes.length} graph route(s) have empty source_symbol.` +\n        ` Primary-index matching by (source_file, source_symbol) will skip them.\\n` +\n        `  Likely cause: the code graph analyzer did not extract handler function names for this language.\\n` +\n        `  Secondary-index matching (http_method + http_path) requires those attributes on model operations.\\n` +\n        `  To fix: re-index after the analyzer is updated, or manually set http_method/http_path on operations.\\n`\n      );\n    }\n\n    // Step 3: Load ignore rules\n    const ignoreFilePath =\n      options.ignoreFilePath || path.join(projectRoot, \".dr-verify-ignore.yaml\");\n    const ignoreRules = await IgnoreFileLoader.load(ignoreFilePath);\n\n    // Step 4: Compute buckets\n    const matched: MatchedEntry[] = [];\n    const inGraphOnly: GraphOnlyEntry[] = [];\n    const ignored: IgnoredEntry[] = [];\n    const matchedRouteIds = new Set<string>();\n\n    for (const route of routes) {\n      let matchedElement: { id: string } | undefined;\n\n      // Try primary index match\n      if (route.source_file && route.source_symbol) {\n        const key = `${route.source_file}:${route.source_symbol}`;\n        const primaryMatch = primaryIndex.get(key);\n        if (primaryMatch) {\n          matchedElement = primaryMatch.modelEntry;\n        }\n      }\n\n      // Fallback to secondary index match\n      if (!matchedElement && route.http_method && route.http_path) {\n        const key = `${route.http_method}:${route.http_path}`;\n        const secondaryMatch = secondaryIndex.get(key);\n        if (secondaryMatch) {\n          matchedElement = secondaryMatch.modelEntry;\n        }\n      }\n\n      // Check if ignored\n      const ignoreReason = IgnoreFileLoader.matches(\n        {\n          handler: route.handler,\n          path: route.http_path,\n          element_id: route.id,\n        },\n        \"route\",\n        ignoreRules\n      );\n\n      if (ignoreReason) {\n        ignored.push({\n          id: route.id,\n          entry_type: \"route\",\n          reason: ignoreReason,\n        });\n        // Update matchedRouteIds even when ignored to prevent false drift\n        if (matchedElement) {\n          matchedRouteIds.add(matchedElement.id);\n        }\n      } else if (matchedElement) {\n        matched.push({\n          id: matchedElement.id,\n          type: \"operation\",\n          source_file: route.source_file || \"\",\n          source_symbol: route.source_symbol || \"\",\n        });\n        matchedRouteIds.add(matchedElement.id);\n      } else {\n        inGraphOnly.push({\n          id: route.id,\n          http_method: route.http_method,\n          http_path: route.http_path,\n          source_file: route.source_file || \"\",\n          source_symbol: route.source_symbol || \"\",\n        });\n      }\n    }\n\n    // Compute in_model_only: model elements not matched in graph\n    const inModelOnly: ModelOnlyEntry[] = [];\n\n    // Batch file-existence checks\n    const fileChecks: Promise<boolean>[] = [];\n    const elementsToCheck: Array<{ id: string; path: string; file: string; symbol: string }> = [];\n    let elementsWithoutSourceRef = 0;\n    let elementsWithNonIndexableSource = 0;\n\n    for (const element of apiLayer.elements.values()) {\n      if (matchedRouteIds.has(element.id)) {\n        continue; // Already matched\n      }\n\n      const firstLocation = element.source_reference?.locations?.[0];\n\n      if (!firstLocation || !firstLocation.file) {\n        // Skip elements with no source_reference file - they cannot drift since they have no code linkage.\n        // This includes manually-created elements that are documentation-only.\n        elementsWithoutSourceRef++;\n        continue;\n      }\n\n      // CBM only indexes source-code files \u2014 non-code source files (e.g. openapi.yaml)\n      // will never appear in the graph, so including them in drift detection produces false positives.\n      if (!SOURCE_CODE_EXT_RE.test(firstLocation.file)) {\n        elementsWithNonIndexableSource++;\n        continue;\n      }\n\n      elementsToCheck.push({\n        id: element.id,\n        path: element.path,\n        file: firstLocation.file,\n        symbol: firstLocation.symbol || \"\",\n      });\n\n      const filePath = path.join(model.codebaseRoot, firstLocation.file);\n      fileChecks.push(\n        access(filePath)\n          .then(() => true)\n          .catch((err: NodeJS.ErrnoException) => {\n            // Only treat ENOENT (file not found) as \"file doesn't exist\"\n            // Other errors (EACCES, EMFILE, etc.) are treated as \"file exists\" to avoid false negatives\n            if (err.code === \"ENOENT\") {\n              return false;\n            }\n            // For permission errors and other issues, assume file exists to be conservative\n            return true;\n          })\n      );\n    }\n\n    if (elementsWithoutSourceRef > 0) {\n      console.warn(\n        `\\nWarning: ${elementsWithoutSourceRef} API model element(s) excluded from drift detection` +\n        ` \u2014 they have no source_reference with a file location.\\n` +\n        `  Drift detection requires a linked source file to compare against the code graph.\\n` +\n        `  Fix: dr update <element-id> --source-file <relative-path> --source-symbol <symbol>\\n` +\n        `  Elements ingested via /dr-map or dr analyzer endpoints are automatically attributed.\\n`\n      );\n    }\n\n    if (elementsWithNonIndexableSource > 0) {\n      console.warn(\n        `\\nWarning: ${elementsWithNonIndexableSource} API model element(s) excluded from drift detection` +\n        ` \u2014 their source files are not indexable source-code files.\\n` +\n        `  Point source_reference to a source-code file (.ts, .js, .py, etc.) for drift detection,\\n` +\n        `  or use dr analyzer endpoints to discover routes automatically.\\n`\n      );\n    }\n\n    // Wait for all file checks. All promises have .catch() handlers that return booleans,\n    // so they will never reject - Promise.all() is safe and simpler than allSettled.\n    const fileExistsResults = await Promise.all(fileChecks);\n\n    // Add to in_model_only only if file exists, then check against ignore rules\n    for (let i = 0; i < elementsToCheck.length; i++) {\n      const fileExists = fileExistsResults[i];\n      const elem = elementsToCheck[i];\n\n      // Skip only if file definitively doesn't exist (false).\n      // Process if file exists (true) or if check is unavailable (undefined).\n      if (fileExists === false) {\n        continue;\n      }\n\n      // Check if element matches any ignore rule\n      // Use element.path (semantic path) instead of elem.id (UUID)\n      const ignoreReason = IgnoreFileLoader.matches(\n        {\n          element_id: elem.path,\n        },\n        \"element\",\n        ignoreRules\n      );\n\n      if (ignoreReason) {\n        ignored.push({\n          id: elem.id,\n          entry_type: \"element\",\n          reason: ignoreReason,\n        });\n      } else {\n        inModelOnly.push({\n          id: elem.id,\n          type: \"operation\",\n          source_file: elem.file,\n          source_symbol: elem.symbol,\n        });\n      }\n    }\n\n    // Step 5: Assemble report\n    const buckets: VerifyBuckets = {\n      matched,\n      in_graph_only: inGraphOnly,\n      in_model_only: inModelOnly,\n      ignored,\n    };\n\n    return this.assembleReport(\n      projectRoot,\n      model,\n      buckets,\n      activeChangesetId,\n      options,\n      analyzerName,\n      indexMeta,\n      elementsWithoutSourceRef + elementsWithNonIndexableSource\n    );\n  }\n\n  /**\n   * Assemble the final verification report\n   *\n   * @private\n   */\n  private assembleReport(\n    projectRoot: string,\n    model: Model,\n    buckets: VerifyBuckets,\n    activeChangesetId: string | null,\n    options: VerifyOptions,\n    analyzerName: string = \"codebase-memory-mcp\",\n    indexMeta?: IndexMeta,\n    elementsWithoutSourceRef: number = 0\n  ): VerifyReport {\n    const matchedElements = buckets.matched.length;\n    const inModelOnly = buckets.in_model_only.length;\n    const ignoredElements = buckets.ignored.filter((e) => e.entry_type === \"element\").length;\n    const summary: VerifySummary = {\n      matched_count: matchedElements,\n      gap_count: buckets.in_graph_only.length,\n      drift_count: inModelOnly,\n      ignored_count: buckets.ignored.length,\n      total_graph_entries: matchedElements + buckets.in_graph_only.length + buckets.ignored.filter((e) => e.entry_type === \"route\").length,\n      // Count all API layer elements: those that participated in matching plus those\n      // excluded because they lack source_reference (documentation-only elements).\n      total_model_entries: matchedElements + inModelOnly + ignoredElements + elementsWithoutSourceRef,\n      elements_without_source_ref: elementsWithoutSourceRef,\n    };\n\n    // Determine changeset context\n    const changesetAware = options.changesetAware ?? true;\n    const hasActiveChangeset = changesetAware && activeChangesetId !== null;\n\n    // Use analyzer index timestamp if provided, otherwise fall back to model manifest modified time\n    const analyzerIndexedAt = indexMeta?.timestamp || model.manifest.modified;\n\n    // Construct changeset context as discriminated union\n    const changeset_context: VerifyChangesetContext = hasActiveChangeset\n      ? {\n          active_changeset: activeChangesetId,\n          verified_against: \"changeset_view\",\n        }\n      : {\n          active_changeset: null,\n          verified_against: \"base_model\",\n        };\n\n    const hints: string[] = [];\n    if (buckets.in_graph_only.length > 0) {\n      hints.push(\n        \"To close gaps with source attribution, use /dr-map or `dr analyzer endpoints` ingestion \u2014 \"\n        + \"manual `dr add` operations cannot be matched by the verifier.\"\n      );\n    }\n\n    return {\n      generated_at: new Date().toISOString(),\n      project_root: projectRoot,\n      analyzer: analyzerName,\n      analyzer_indexed_at: analyzerIndexedAt,\n      changeset_context,\n      layers_verified: [\"api\"],\n      buckets,\n      summary,\n      ...(hints.length > 0 ? { hints } : {}),\n    };\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command, CommanderError } from "commander";
 import { setGlobalOptions } from "./utils/globals.js";
+import { installAnsiSuppressor } from "./utils/ansi-suppressor.js";
 import { initCommand } from "./commands/init.js";
 import { addCommand } from "./commands/add.js";
 import { updateCommand } from "./commands/update.js";
@@ -22,6 +23,7 @@ import { chatCommand } from "./commands/chat.js";
 import { upgradeCommand } from "./commands/upgrade.js";
 import { conformanceCommand } from "./commands/conformance.js";
 import { changesetCommands } from "./commands/changeset.js";
+import { farmCommands } from "./commands/farm.js";
 import { claudeCommands } from "./commands/claude.js";
 import { copilotCommands } from "./commands/copilot.js";
 import { analyzerCommands } from "./commands/analyzer.js";
@@ -35,11 +37,13 @@ import { auditSnapshotsCommand } from "./commands/audit-snapshots.js";
 import { repairAttributeCollisionCommand } from "./commands/repair.js";
 import { initTelemetry, startActiveSpan, shutdownTelemetry } from "./telemetry/index.js";
 import { installConsoleInterceptor } from "./telemetry/console-interceptor.js";
-import { getErrorMessage } from "./utils/errors.js";
+import { getErrorMessage, CLIError } from "./utils/errors.js";
+import { getCliVersion } from "./utils/spec-version.js";
 const isTelemetryEnabled = !1, CONSOLE_LOGGING_COMMANDS = /* @__PURE__ */ new Set(["chat", "validate", "import", "export"]);
+process.stdout.isTTY || (process.env.FORCE_COLOR = "0", process.env.NO_COLOR = "1"), installAnsiSuppressor();
 async function extractExitCode(error) {
-  const { CLIError } = await import("./utils/errors.js");
-  if (error instanceof CLIError || error instanceof CommanderError)
+  const { CLIError: CLIError2 } = await import("./utils/errors.js");
+  if (error instanceof CLIError2 || error instanceof CommanderError)
     return error.exitCode;
   if (error && typeof error == "object" && "exitCode" in error) {
     const errorObj = error;
@@ -48,26 +52,28 @@ async function extractExitCode(error) {
   }
   return 1;
 }
-const cliVersion = "0.1.12", program = new Command();
-(process.argv.includes("--version") || process.argv.includes("-V")) && (process.argv = ["node", "dr", "version"]), program.name("dr").description("Documentation Robotics CLI - Architecture Model Management").option("-v, --verbose", "Enable verbose output").option("--debug", "Enable debug mode").exitOverride().showSuggestionAfterError().hook("preAction", async (thisCommand) => {
+const cliVersion = getCliVersion(), program = new Command();
+(process.argv.includes("--version") || process.argv.includes("-V")) && (process.argv = ["node", "dr", "version"]), program.name("dr").description("Documentation Robotics CLI - Architecture Model Management").option("-v, --verbose", "Enable verbose output").option("--debug", "Enable debug mode").option("--json", "Output as JSON (supported on mutating and query commands)").option("--codebase-path <path>", "Override codebase root path (default: resolved from manifest or project root)").exitOverride().showSuggestionAfterError().hook("preAction", async (thisCommand) => {
   const options = thisCommand.opts();
   setGlobalOptions({
     verbose: options.verbose,
-    debug: options.debug
+    debug: options.debug,
+    json: options.json,
+    codebasePath: options.codebasePath
   });
 }), program.command("init [name]").description("Initialize a new architecture model").option("--name <name>", "Model name (overrides positional argument)").option("--author <author>", "Model author").option("--description <desc>", "Model description").addHelpText("after", `
 Examples:
   $ dr init
   $ dr init claudetoreum
   $ dr init "Enterprise Architecture" --author "Team A"
-  $ dr init --name "My Project" --description "13-layer federated model"`).action((name, options) => initCommand({ ...options, name: options.name || name })), program.command("add <layer> <type> <name>").description("Add an element to a layer").option("--name <name>", "Element display name (defaults to the name argument)").option("--description <desc>", "Element description").option("--attributes <json>", "Element type-specific attributes as JSON object").option("--source-file <path>", "Source file path (relative from repository root)").option("--source-symbol <name>", "Symbol name (class, function, variable) in source file").option("--source-provenance <type>", "Provenance type: extracted, manual, inferred, generated").option("--source-repo-remote <url>", "Git remote URL for repository context").option("--source-repo-commit <sha>", "Git commit SHA (40 hex characters) for repository context").addHelpText("after", `
+  $ dr init --name "My Project" --description "13-layer federated model"`).action((name, options) => initCommand({ ...options, name: options.name || name })), program.command("add <layer> <type> <name>").description("Add an element to a layer").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--name <name>", "Element display name (defaults to the name argument)").option("--description <desc>", "Element description").option("--attributes <json>", "Element type-specific attributes as JSON object").option("--source-file <path>", "Source file path (relative from repository root)").option("--source-symbol <name>", "Symbol name (class, function, variable) in source file").option("--source-provenance <type>", "Provenance type: extracted, manual, inferred, generated").option("--source-repo-remote <url>", "Git remote URL for repository context").option("--source-repo-commit <sha>", "Git commit SHA (40 hex characters) for repository context").option("--verbose", "Show detailed output (can also use global -v flag)").addHelpText("after", `
 Examples:
   $ dr add business service "Customer Management"
   $ dr add api operation "Create Customer" --attributes '{"operationId":"createCustomer","summary":"Create a customer","tags":"customers"}'
   $ dr add application component "Customer API" --description "REST API for customer operations"
   $ dr add security policy "Auth Validator" --source-file "src/auth/validator.ts" --source-symbol "validateToken" --source-provenance "extracted"
 
-Note: Element IDs are generated automatically in format {layer}.{type}.{kebab-name}`).action(addCommand), program.command("update <id>").description("Update an element").option("--name <name>", "New element name").option("--description <desc>", "New description").option("--type <new-type>", "Change element type (must be valid for the element's layer; incompatible attributes must be cleaned up manually)").option("--attributes <json>", "Updated type-specific attributes (JSON)").option("--source-file <path>", "Source file path (relative from repository root)").option("--source-symbol <name>", "Symbol name (class, function, variable) in source file").option("--source-provenance <type>", "Provenance type: extracted, manual, inferred, generated").option("--source-repo-remote <url>", "Git remote URL for repository context").option("--source-repo-commit <sha>", "Git commit SHA (40 hex characters) for repository context").option("--clear-source-reference", "Remove source reference from element").addHelpText("after", `
+Note: Element IDs are generated automatically in format {layer}.{type}.{kebab-name}`).action((layer, type, name, options) => addCommand(layer, type, name, { ...options, verbose: options.verbose ?? program.opts().verbose })), program.command("update <id>").description("Update an element").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--name <name>", "New element name").option("--description <desc>", "New description").option("--type <new-type>", "Change element type (must be valid for the element's layer; incompatible attributes must be cleaned up manually)").option("--attributes <json>", "Updated type-specific attributes (JSON)").option("--source-file <path>", "Source file path (relative from repository root)").option("--source-symbol <name>", "Symbol name (class, function, variable) in source file").option("--source-provenance <type>", "Provenance type: extracted, manual, inferred, generated").option("--source-repo-remote <url>", "Git remote URL for repository context").option("--source-repo-commit <sha>", "Git commit SHA (40 hex characters) for repository context").option("--clear-source-reference", "Remove source reference from element").option("--verbose", "Show detailed output (can also use global -v flag)").addHelpText("after", `
 Note: Changes are written immediately to model files.
 To track changes for review, activate a changeset first:
   $ dr changeset activate my-changeset
@@ -76,13 +82,13 @@ Examples:
   $ dr update api-endpoint-create-customer --name "Create Customer (v2)"
   $ dr update business-service-order --description "Updated description"
   $ dr update application-applicationfunction-process-orders --type applicationservice
-  $ dr update security-policy-auth --source-file "src/auth/policy.ts" --source-provenance "extracted"`).action(updateCommand), program.command("delete <id>").description("Delete an element").option("--force", "Skip dependency checks (confirmation is also skipped in non-TTY environments)").option("--cascade", "Remove dependent elements automatically").option("--dry-run", "Show what would be removed without actually removing").addHelpText("after", `
+  $ dr update security-policy-auth --source-file "src/auth/policy.ts" --source-provenance "extracted"`).action((id, options) => updateCommand(id, { ...options, verbose: options.verbose ?? program.opts().verbose })), program.command("delete <id>").description("Delete an element").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--force", "Skip dependency checks (confirmation is also skipped in non-TTY environments)").option("--cascade", "Remove dependent elements automatically").option("--dry-run", "Show what would be removed without actually removing").option("--verbose", "Show detailed output (can also use global -v flag)").addHelpText("after", `
 Examples:
   $ dr delete api-endpoint-old-endpoint
   $ dr delete api-endpoint-old-endpoint --force
   $ dr delete api-endpoint-old-endpoint --cascade
   $ dr delete api-endpoint-old-endpoint --dry-run
-  $ dr delete api-endpoint-old-endpoint --cascade --dry-run`).action(deleteCommand), program.command("show <id>").description("Display element details").option("--model <path>", "Path to model root (contains model/manifest.yaml)").addHelpText("after", `
+  $ dr delete api-endpoint-old-endpoint --cascade --dry-run`).action((id, options) => deleteCommand(id, { ...options, verbose: options.verbose ?? program.opts().verbose })), program.command("show <id>").description("Display element details").option("--model <path>", "Path to model root (contains model/manifest.yaml)").addHelpText("after", `
 Examples:
   $ dr show api-endpoint-create-customer
   $ dr show business-service-order-mgmt`).action((id, options) => showCommand(id, options)), program.command("list [layer]").description("List elements in a layer (or all layers if omitted)").option("--type <type>", "Filter by element type").option("--json", "Output as JSON").option("--model <path>", "Path to model root (contains model/manifest.yaml)").addHelpText("after", `
@@ -91,12 +97,12 @@ Examples:
   $ dr list api
   $ dr list business --type businessservice
   $ dr list api --json
-  $ dr list --json`).action(listCommand), program.command("search <query>").description("Search for elements by name or ID").option("--layer <layer>", "Limit search to specific layer").option("--type <type>", "Filter by element type").option("--source-file <path>", "Find elements referencing a source file (takes precedence over pattern matching)").option("--json", "Output as JSON").addHelpText("after", `
+  $ dr list --json`).action((layer, options) => listCommand(layer, { ...options, json: options.json ?? program.opts().json })), program.command("search <query>").description("Search for elements by name or ID").option("--layer <layer>", "Limit search to specific layer").option("--type <type>", "Filter by element type").option("--source-file <path>", "Find elements referencing a source file (takes precedence over pattern matching)").option("--json", "Output as JSON").addHelpText("after", `
 Examples:
   $ dr search customer
   $ dr search "order processing" --layer business
   $ dr search create-* --type endpoint
-  $ dr search "" --source-file src/api/customer.ts`).action(searchCommand), program.command("validate").description("Validate the architecture model").option("--layers <layers...>", "Specific layers to validate").option("--strict", "Treat warnings as errors").option("--verbose", "Show detailed validation output with relationship breakdown").option("--quiet", "Show minimal output").option("--output <path>", "Export validation report to file (JSON or Markdown)").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--orphans", "Show only orphaned elements grouped by layer with relationship suggestions").option("--all", "Run all validations (default behavior)").option("--markdown", "Validate markdown structure").option("--schemas", "Validate JSON schemas").option("--schema", "Validate JSON schemas (alias for --schemas)").option("--relationships", "Validate relationships").option("--structure", "Validate documentation structure").option("--naming", "Validate naming conventions").option("--references", "Validate cross-layer references").addHelpText("after", `
+  $ dr search "" --source-file src/api/customer.ts`).action((query, options) => searchCommand(query, { ...options, json: options.json ?? program.opts().json })), program.command("validate").description("Validate the architecture model").option("--layers <layers...>", "Specific layers to validate").option("--strict", "Treat warnings as errors").option("--verbose", "Show detailed validation output with relationship breakdown").option("--quiet", "Show minimal output").option("--output <path>", "Export validation report to file (JSON or Markdown)").option("--model <path>", "Path to model root (contains model/manifest.yaml)").option("--orphans", "Show only orphaned elements grouped by layer with relationship suggestions").option("--all", "Run all validations (default behavior)").option("--markdown", "Validate markdown structure").option("--schemas", "Validate JSON schemas").option("--schema", "Validate JSON schemas (alias for --schemas)").option("--relationships", "Validate relationships").option("--structure", "Validate documentation structure").option("--naming", "Validate naming conventions").option("--references", "Validate cross-layer references").option("--scope <scope>", "Validation scope: 'local' (default) or 'composed' for cross-model validation").option("--model-path <mapping...>", "Override filesystem path for external model (format: model-name=/path/to/project-root, can be repeated)").addHelpText("after", `
 Examples:
   $ dr validate
   $ dr validate --all --strict
@@ -108,7 +114,11 @@ Examples:
   $ dr validate --relationships
   $ dr validate --layers business api
   $ dr validate --orphans
-  $ dr validate --orphans --output orphans.json`).action(validateCommand), program.command("export <format>").description("Export the architecture model to various formats").option("--output <path>", "Output file path (default: print to stdout)").option("--layers <layers...>", "Specific layers to export").option("--model <path>", "Path to model root directory or manifest.yaml file").option("--include-sources", "Include source file paths in PlantUML diagrams as notes").addHelpText("after", `
+  $ dr validate --orphans --output orphans.json
+  $ dr validate --scope composed --model-path auth-service=/path/to/auth-service-repo
+  $ dr validate --scope composed --model-path auth-service=/path/to/auth-service-repo --model-path payment-service=/path/to/payment-repo
+
+Note: When using --model-path, pass the project root (where documentation-robotics/model/ is located).`).action(validateCommand), program.command("export <format>").description("Export the architecture model to various formats").option("--output <path>", "Output file path (default: print to stdout)").option("--layers <layers...>", "Specific layers to export").option("--model <path>", "Path to model root directory or manifest.yaml file").option("--include-sources", "Include source file paths in PlantUML diagrams as notes").addHelpText("after", `
 Supported formats:
   archimate    Export to ArchiMate XML (layers 1, 2, 5, 6)
   openapi      Export to OpenAPI 3.0 specification (layer 7)
@@ -233,9 +243,9 @@ Examples:
   $ dr repair:attribute-collision --apply             # Restore every recoverable value
   $ dr repair:attribute-collision --format json --output report.json`).action((options) => repairAttributeCollisionCommand(options));
 const relationshipGroup = program.command("relationship").description("Relationship operations");
-relationshipCommands(relationshipGroup);
+relationshipCommands(relationshipGroup, program);
 const elementGroup = program.command("element").description("Element operations");
-elementCommands(elementGroup), schemaCommands(program), catalogCommands(program), docsCommands(program), program.command("trace <elementId>").description("Trace dependencies for an element").option("--direction <dir>", "Trace direction: up (dependencies), down (dependents), both (default)").option("--depth <num>", "Maximum traversal depth").option("--metrics", "Show graph and element metrics").option("--model <path>", "Path to model root (contains model/manifest.yaml)").addHelpText("after", `
+elementCommands(elementGroup, program), schemaCommands(program), catalogCommands(program), docsCommands(program), program.command("trace <elementId>").description("Trace dependencies for an element").option("--direction <dir>", "Trace direction: up (dependencies), down (dependents), both (default)").option("--depth <num>", "Maximum traversal depth").option("--metrics", "Show graph and element metrics").option("--model <path>", "Path to model root (contains model/manifest.yaml)").addHelpText("after", `
 Examples:
   $ dr trace api-endpoint-create-customer
   $ dr trace business-service-order --direction down --metrics
@@ -256,9 +266,15 @@ Examples:
   $ dr visualize --with-danger
   $ dr visualize --viewer-path ./dist/embedded/dr-viewer-bundle
 
-The --with-danger flag enables dangerous mode for chat functionality:
-  - Claude Code: --dangerously-skip-permissions
-  - GitHub Copilot: --allow-all-tools
+Default mode (read-safe permissions) enables:
+  - Running 'dr' CLI commands to query the architecture model
+  - Reading the codebase
+  - Reading the documentation-robotics/ model folder
+  - Reading the .dr/ configuration folder
+
+Dangerous mode (--with-danger) enables unrestricted access:
+  - Claude Code: --dangerously-skip-permissions (full tool access)
+  - GitHub Copilot: --allow-all-tools (full tool access)
 
 The --viewer-path option allows loading a local build of the web UI:
   - Point to a directory containing index.html and supporting files
@@ -274,6 +290,58 @@ The --viewer-path option allows loading a local build of the web UI:
     withDanger: options.withDanger,
     viewerPath: options.viewerPath
   });
+}), program.command("mcp").description("Start MCP server for AI assistant integration").option("--regenerate-key", "Generate a new MCP API key, overwrite it at the configured storage path, and print it (does not start the server)").option("--transport <type>", "Transport type: stdio or http (default: stdio)", "stdio").option("--port <number>", "Port for HTTP transport (default: 3100, only meaningful with --transport http)", "3100").option("--host <address>", "Host address for HTTP transport (default: 127.0.0.1, only meaningful with --transport http)", "127.0.0.1").addHelpText("after", `
+Examples:
+
+Stdio transport (default):
+  $ dr mcp
+
+HTTP transport:
+  $ dr mcp --transport http                    # HTTP on localhost:3100
+  $ dr mcp --transport http --port 8200        # HTTP on custom port
+  $ dr mcp --transport http --host 0.0.0.0 --port 3100  # Listen on all interfaces
+
+Key management:
+  $ dr mcp --regenerate-key                    # Generate new API key
+
+Initial Setup:
+On first launch, generates an API key and asks where to store it (interactive
+sessions only; non-interactive launches default to ~/.dr-mcp-key). The key is
+printed to stderr on every launch and must be supplied via environment variable.
+
+Stdio Configuration:
+For stdio transport, supply the key via environment variable:
+
+  {
+    "command": "dr",
+    "args": ["mcp"],
+    "env": { "DR_MCP_API_KEY": "<your-api-key>" }
+  }
+
+HTTP Configuration:
+For HTTP transport, include the API key as a Bearer token in the Authorization header:
+
+  {
+    "url": "http://localhost:3100/mcp",
+    "headers": {
+      "Authorization": "Bearer <your-api-key>"
+    }
+  }
+
+Use --regenerate-key to rotate the key (e.g. after a suspected leak) without
+manually deleting the stored key file or config.`).action(async (options) => {
+  const { mcpCommand } = await import("./commands/mcp.js"), transport = options.transport.toLowerCase();
+  if (transport !== "stdio" && transport !== "http")
+    throw new CLIError(`Invalid transport: ${transport}. Allowed values: stdio, http`, 1);
+  const port = parseInt(options.port, 10);
+  if (!Number.isFinite(port) || port < 1 || port > 65535)
+    throw new CLIError(`Invalid port: ${options.port}. Must be a number between 1 and 65535`, 1);
+  await mcpCommand({
+    regenerateKey: options.regenerateKey,
+    transport,
+    port,
+    host: options.host
+  });
 }), program.command("chat [client] [withDanger]").description("Interactive chat with AI about the architecture model").addHelpText("after", `
 Arguments:
   client      Optional AI client to use: "claude-code" or "github-copilot"
@@ -287,9 +355,15 @@ Examples:
   $ dr chat claude-code with-danger   # Use Claude Code with dangerous mode
   $ dr chat github-copilot with-danger # Use GitHub Copilot with dangerous mode
 
-Dangerous mode enables:
-  - Claude Code: --dangerously-skip-permissions
-  - GitHub Copilot: --allow-all-tools
+Default mode (read-safe permissions) enables:
+  - Running 'dr' CLI commands to query the architecture model
+  - Reading the codebase
+  - Reading the documentation-robotics/ model folder
+  - Reading the .dr/ configuration folder
+
+Dangerous mode (--with-danger) enables unrestricted access:
+  - Claude Code: --dangerously-skip-permissions (full tool access)
+  - GitHub Copilot: --allow-all-tools (full tool access)
 
 This launches an interactive chat interface where you can ask AI questions
 about your architecture model. Supports Claude Code CLI and GitHub Copilot CLI.
@@ -322,10 +396,10 @@ Examples:
   $ dr conformance --verbose`).action(async (options) => {
   await conformanceCommand({
     layers: options.layers,
-    json: options.json,
+    json: options.json ?? program.opts().json,
     verbose: options.verbose ?? program.opts().verbose
   });
-}), changesetCommands(program), claudeCommands(program), copilotCommands(program), analyzerCommands(program), (async () => {
+}), changesetCommands(program), farmCommands(program), claudeCommands(program), copilotCommands(program), analyzerCommands(program), (async () => {
   let exitCode = 0;
   try {
     if (isTelemetryEnabled) {
@@ -346,8 +420,8 @@ Examples:
             // SpanStatusCode.ERROR
             message: getErrorMessage(error)
           }));
-          const { CLIError } = await import("./utils/errors.js");
-          error instanceof CommanderError || (error instanceof CLIError ? console.error(error.format()) : error instanceof Error ? console.error(error.message) : console.error(String(error))), exitCode = await extractExitCode(error);
+          const { CLIError: CLIError2 } = await import("./utils/errors.js"), { isJson } = await import("./utils/globals.js");
+          error instanceof CommanderError || (error instanceof CLIError2 ? isJson() || console.error(error.format()) : error instanceof Error ? console.error(error.message) : console.error(String(error))), exitCode = await extractExitCode(error);
         }
       }, {
         "cli.command": commandName,
@@ -359,8 +433,8 @@ Examples:
       try {
         await program.parseAsync(process.argv);
       } catch (error) {
-        const { CLIError } = await import("./utils/errors.js");
-        error instanceof CommanderError || (error instanceof CLIError ? console.error(error.format()) : error instanceof Error ? console.error(error.message) : console.error(String(error)));
+        const { CLIError: CLIError2 } = await import("./utils/errors.js"), { isJson } = await import("./utils/globals.js");
+        error instanceof CommanderError || (error instanceof CLIError2 ? isJson() || console.error(error.format()) : error instanceof Error ? console.error(error.message) : console.error(String(error)));
         const exitCodeFromError = await extractExitCode(error);
         process.exit(exitCodeFromError);
       }