@documentation-robotics/cli 0.2.0 → 0.3.0

package/dist/integrations/claude_code/agents/dr-architect.md

@@ -1,7 +1,7 @@
 ---
 name: dr-architect
 description: Comprehensive Documentation Robotics architect and implementer. Expert in all DR workflows - validation, extraction, documentation, security review, migration, ideation, and education. Intelligent intent-based routing with adaptive autonomy. Single agent that handles everything related to DR models.
-tools: Bash, Read, Edit, Write, Glob, Grep, WebSearch, WebFetch
+tools: Bash, Read, Edit, Write, Glob, Grep, WebSearch, WebFetch, mcp__dr__model_list, mcp__dr__model_show, mcp__dr__model_search, mcp__dr__model_stats, mcp__dr__model_info, mcp__dr__model_trace, mcp__dr__model_validate, mcp__dr__model_export, mcp__dr__model_reload, mcp__dr__changeset_list, mcp__dr__changeset_show, mcp__dr__changeset_create, mcp__dr__changeset_activate, mcp__dr__changeset_deactivate, mcp__dr__changeset_impact, mcp__dr__changeset_brief, mcp__dr__changeset_verify, mcp__dr__changeset_update, mcp__dr__changeset_unstage, mcp__dr__spec_type, mcp__dr__model_add, mcp__dr__model_update, mcp__dr__model_delete, mcp__dr__relationship_add, mcp__dr__relationship_delete, mcp__dr__annotation_list, mcp__dr__annotation_get, mcp__dr__chat_status
 color: orange
 ---
 
@@ -22,11 +22,24 @@ You are the **DR Architect** — a unified expert in Documentation Robotics. You
 
 ## Tools
 
-- **Bash**: DR CLI commands (`dr add`, `dr validate`, `dr changeset`, etc.)
+- **dr MCP tools** (`mcp__dr__*`, when the `dr` MCP server is connected, as it is in the `dr visualize` chat): prefer these to running `dr` through Bash. See **Working through the dr MCP server** below.
+- **Bash**: DR CLI commands (`dr add`, `dr validate`, `dr changeset`, etc.); the fallback when the MCP tools are not available
 - **Read/Glob/Grep**: Read source code and model files
 - **WebSearch/WebFetch**: Research technologies and patterns
 - **Edit/Write**: Model YAML files only (never use for model data — use CLI)
 
+## Working through the dr MCP server
+
+When the `mcp__dr__*` tools are available, plan a change as a staged changeset with them instead of `dr` commands:
+
+1. **Look first**: `model_search`, `model_show`, `model_list` to find what exists; `spec_type` to see what a type requires and which relationships the catalog allows from it.
+2. **Open a changeset**: `changeset_create` with a short name for the change (it activates the new changeset). `changeset_list` / `changeset_activate` resume an existing one.
+3. **Stage the change**: `model_add`, `model_update`, `model_delete`, `relationship_add`, `relationship_delete`. With a changeset active these stage instead of writing the model, and relationships may join elements the changeset itself adds. `changeset_update` renames or re-describes the changeset and `changeset_unstage` drops a staged change. Discarding a changeset is the user's step.
+4. **Pressure-test it**: `changeset_impact` for what the change touches, `changeset_brief` for a review summary. Fix what they surface, then report the brief to the user. Once code is built, `changeset_verify` compares the plan with what was built.
+5. **Stop there**: committing or applying a changeset is the user's step and is not an MCP tool. Tell the user the changeset is ready for review.
+
+Some sessions only allow changes through a changeset: a write with no active changeset is refused with a message saying to call `changeset_create` first. Do that and retry; don't fall back to Bash or to editing files.
+
 ## The 12-Layer Model
 
 ```
@@ -44,7 +57,7 @@ You are the **DR Architect** — a unified expert in Documentation Robotics. You
 12. Testing      — VERIFY (ISP coverage model — 17 entity types)
 ```
 
-Cross-layer direction: higher layers reference lower layers (e.g., API references Application, Application references Data Model).
+Cross-layer direction follows the predicate, not the layer order (`spec/DESIGN_CHARTER.md`): an API operation `realizes` an application function, an application function `accesses` a data object, an object schema `maps-to` a data-store collection. The relationship catalog is the authority on valid source/predicate/destination triples.
 
 ## Intent Routing
 

package/dist/integrations/claude_code/agents/dr-extractor.md

@@ -269,7 +269,7 @@ Recommendations:
 1. **Use kebab-case for all element IDs**: Element names should be lowercase with hyphens, not spaces or underscores
 2. **Create realistic, meaningful descriptions**: Each element should have a clear description of its purpose
 3. **Every `dr add` must include source metadata**: No exceptions. The test suite enforces `source_files_exist` assertions
-4. **Establish cross-layer references**: Use `dr relationship add` to link API operations to application services, services to business capabilities, etc.
+4. **Establish cross-layer references**: Use `dr relationship add` to link API operations to application services, services to business capabilities, etc. Within reason, every connection the spec models for a type is expected, though not every one will exist. For each element you add, run `dr schema relationship <layer>.<type>` to see what its type can connect to, and add each connection the code shows (calls, imports, handlers, reads and writes). Leave out the ones the code gives no evidence for.
 5. **Run validation after each batch**: Extract ~5 elements, validate immediately, fix issues before continuing
 6. **Flag uncertain mappings**: If an element might be misclassified or its purpose unclear, flag it in the report for manual review
 

package/dist/integrations/claude_code/commands/dr-analyzer.md

@@ -0,0 +1,565 @@
+---
+description: Discover, install, index, and query code analyzers. Supports graph-based analysis of your codebase with dual-root awareness (metadata root may differ from source code root).
+argument-hint: "[discover|status|index|endpoints|services|datastores|callers|callees|query|verify] [options]"
+---
+
+# Code Analyzer Management
+
+Discover, install, and manage code analyzers that scan your codebase and build a code graph for verification and querying. These commands respect the configured codebase root, allowing metadata (model) and source code to reside in separate directories.
+
+## Overview
+
+Analyzers are optional but powerful: they enable verification of your architecture model against actual code, detection of missing or drifted elements, and deep code querying. The DR CLI currently supports **Codebase Memory** (CBM), a graph-based analyzer.
+
+## Key Concept: Dual-Root Architecture
+
+Your Documentation Robotics project has two roots:
+
+- **Model Root** (project root): The directory that **contains** your `documentation-robotics/` folder (manifest, changesets, layers live under `documentation-robotics/model/`)
+- **Codebase Root**: Where your actual source code is located
+
+These can be the **same directory** (typical case) or **different directories** (useful for monorepos, federated architectures, or farms).
+
+### Resolution Priority
+
+When you run analyzer commands, the codebase root is resolved in this order:
+
+1. **`--codebase-path` CLI flag** — Global option that overrides all other resolution methods
+2. **`manifest.codebase_path`** — Path relative to the model root, i.e. the directory that contains `documentation-robotics/`, **not** the `documentation-robotics/model/` folder the manifest sits in (configured in `documentation-robotics/model/manifest.yaml`; an absolute path also works)
+3. **Farm auto-resolution** — If your model is inside a farm, resolved from farm configuration
+4. **Default** — Uses the model root itself
+
+**Example Resolution:**
+
+```
+Model root:    /workspace/my-app-model/           (contains documentation-robotics/model/manifest.yaml)
+Codebase root: /workspace/my-app/                 (source code lives here)
+
+Configure in /workspace/my-app-model/documentation-robotics/model/manifest.yaml:
+  codebase_path: ../my-app
+
+Resolved as /workspace/my-app-model/../my-app = /workspace/my-app
+
+Monorepo variant: model root /workspace/monorepo/, code in /workspace/monorepo/services/api/
+  codebase_path: services/api
+
+Or configure via farm (auto-detected if model is in a farm)
+```
+
+### Important: Re-indexing After Update
+
+If you have a pre-existing CBM project entry that was indexed under the old (incorrect) model root, you need to re-index after enabling the dual-root configuration:
+
+```bash
+# After configuring codebase_path in manifest.yaml:
+dr analyzer index --force
+```
+
+This ensures the analyzer indexes the correct codebase root.
+
+---
+
+## Commands
+
+### discover — Discover and Select Analyzer
+
+Scan for installed analyzers and select the one to use for your project.
+
+```bash
+dr analyzer discover [--json] [--reselect]
+```
+
+**Options:**
+
+- `--json` — Output discovery results as JSON (includes installed count, available analyzers, selected analyzer)
+- `--reselect` — Force re-selection even if an analyzer is already selected
+
+**Output:**
+
+- Interactive mode: Prompts to select from installed analyzers
+- JSON mode: Returns list of discovered analyzers with installation status
+- Result: Saves selection to `.dr/analyzers/session.json` (project root)
+
+**Examples:**
+
+```bash
+# Interactive discovery and selection
+dr analyzer discover
+
+# Non-interactive discovery (auto-selects first installed)
+dr analyzer discover --json
+
+# Force re-selection
+dr analyzer discover --reselect
+```
+
+---
+
+### status — Check Analyzer Status
+
+Report on analyzer detection and project index state.
+
+```bash
+dr analyzer status [--name <analyzer>] [--json]
+```
+
+**Options:**
+
+- `--name <analyzer>` — Specific analyzer name (default: active analyzer from session)
+- `--json` — Output status as JSON
+
+**Status Fields:**
+
+- `detected.installed` — Whether analyzer is installed
+- `detected.binary_path` — Path to analyzer binary (if installed)
+- `detected.version` — Analyzer version
+- `detected.mcp_registered` — Whether analyzer is registered as an MCP server
+- `detected.contract_ok` — Whether contract validation passed
+- `indexed` — Whether project has been indexed
+- `fresh` — Whether index is current (not stale)
+- `last_indexed` — Timestamp of last indexing
+
+**Important:** Status respects the dual-root configuration — it checks the codebase root for index status, not the model root.
+
+**Examples:**
+
+```bash
+# Check active analyzer
+dr analyzer status
+
+# Check specific analyzer
+dr analyzer status --name cbm
+
+# JSON output
+dr analyzer status --json
+```
+
+---
+
+### index — Index Project with Analyzer
+
+Build the code graph by scanning the codebase. Respects the configured codebase root.
+
+```bash
+dr analyzer index [--name <analyzer>] [--force]
+```
+
+**Options:**
+
+- `--name <analyzer>` — Specific analyzer name (default: active analyzer from session)
+- `--force` — Force re-indexing even if index is current
+
+**Output:**
+
+- Indexing progress
+- Node count (code entities discovered)
+- Edge count (relationships discovered)
+- Git HEAD (commit hash of indexed code)
+
+**Codebase Root Resolution:**
+
+When indexing, the analyzer:
+
+1. Locates your model root
+2. Resolves the codebase root using the priority order (see "Dual-Root Architecture")
+3. Scans the codebase root for code
+4. Stores index metadata in `.dr/analyzers/` at the model root
+
+**Important for Dual-Root Users:**
+
+If you recently configured `manifest.codebase_path`, re-index with `--force`:
+
+```bash
+# After updating manifest.codebase_path
+dr analyzer index --force
+```
+
+**Examples:**
+
+```bash
+# Index with active analyzer
+dr analyzer index
+
+# Force re-index
+dr analyzer index --force
+
+# Index with specific analyzer
+dr analyzer index --name cbm
+```
+
+---
+
+### endpoints — List Discovered API Endpoints
+
+Query the indexed code graph for discovered API endpoints.
+
+```bash
+dr analyzer endpoints [--name <analyzer>] [--json]
+```
+
+**Options:**
+
+- `--name <analyzer>` — Specific analyzer name (default: active)
+- `--json` — Output as JSON
+
+**Output Columns:**
+
+- Method (HTTP verb)
+- Path (URL route)
+- Name (suggested element name)
+- ID Fragment (suggested element ID suffix)
+- Symbol (source code symbol)
+- Confidence (high/medium/low)
+- File (source file path)
+
+**Examples:**
+
+```bash
+# List endpoints
+dr analyzer endpoints
+
+# JSON output
+dr analyzer endpoints --json
+
+# Specific analyzer
+dr analyzer endpoints --name cbm
+```
+
+---
+
+### services — Query for Services/Components
+
+Discover application services and components from the indexed code.
+
+```bash
+dr analyzer services [--name <analyzer>] [--layer <layer>] [--json]
+```
+
+**Options:**
+
+- `--name <analyzer>` — Specific analyzer name (default: active)
+- `--layer <layer>` — Filter by suggested layer (e.g., application)
+- `--json` — Output as JSON
+
+**Output Columns:**
+
+- Name
+- Layer (suggested layer)
+- Type (suggested element type)
+- Symbol (source code symbol)
+- Confidence (high/medium/low)
+- File (source file)
+
+**Examples:**
+
+```bash
+# List all services
+dr analyzer services
+
+# Filter by layer
+dr analyzer services --layer application
+
+# JSON output
+dr analyzer services --json
+```
+
+---
+
+### datastores — Query for Databases
+
+Discover data stores and databases inferred from code (database libraries, ORMs, migrations).
+
+```bash
+dr analyzer datastores [--name <analyzer>] [--json]
+```
+
+**Options:**
+
+- `--name <analyzer>` — Specific analyzer name (default: active)
+- `--json` — Output as JSON
+
+**Output:**
+
+For each datastore:
+
+- Name (inferred)
+- Source evidence (files and patterns)
+- Notes (if available)
+
+**Examples:**
+
+```bash
+# List datastores
+dr analyzer datastores
+
+# JSON output
+dr analyzer datastores --json
+```
+
+---
+
+### callers — Trace Callers of a Symbol
+
+Find all functions or methods that call a specific symbol.
+
+```bash
+dr analyzer callers <qualified-name> [--name <analyzer>] [--depth <n>] [--json]
+```
+
+**Arguments:**
+
+- `<qualified-name>` — Fully-qualified name of the target symbol (e.g., `com.example.Service.handleRequest`)
+
+**Options:**
+
+- `--name <analyzer>` — Specific analyzer name (default: active)
+- `--depth <n>` — Maximum traversal depth (default: 3, max: 10)
+- `--json` — Output as JSON
+
+**Output:**
+
+For each caller:
+
+- Qualified name
+- Source file
+- Source symbol
+- Depth (distance in call graph)
+- Edge type (direct call, inheritance, etc.)
+
+**Examples:**
+
+```bash
+# Find callers of a method
+dr analyzer callers com.example.Service.handleRequest
+
+# Deeper traversal
+dr analyzer callers com.example.Service.handleRequest --depth 5
+
+# JSON output
+dr analyzer callers com.example.Service.handleRequest --json
+```
+
+---
+
+### callees — Trace Callees of a Symbol
+
+Find all functions or methods called by a specific symbol.
+
+```bash
+dr analyzer callees <qualified-name> [--name <analyzer>] [--depth <n>] [--json]
+```
+
+**Arguments:**
+
+- `<qualified-name>` — Fully-qualified name of the target symbol
+
+**Options:**
+
+- `--name <analyzer>` — Specific analyzer name (default: active)
+- `--depth <n>` — Maximum traversal depth (default: 3, max: 10)
+- `--json` — Output as JSON
+
+**Output:**
+
+For each callee:
+
+- Qualified name
+- Source file
+- Source symbol
+- Depth (distance in call graph)
+- Edge type (direct call, inheritance, etc.)
+
+**Examples:**
+
+```bash
+# Find methods called by a handler
+dr analyzer callees com.example.Service.handleRequest
+
+# Deeper traversal
+dr analyzer callees com.example.Service.handleRequest --depth 5
+```
+
+---
+
+### query — Execute Raw Graph Query
+
+Advanced: Execute a raw query (Cypher) against the analyzer's graph. Use when standard commands don't meet your needs.
+
+```bash
+dr analyzer query "<cypher>" [--name <analyzer>]
+```
+
+**Arguments:**
+
+- `<cypher>` — Cypher query string (note: backend-specific, currently supports Cypher for graph analyzers)
+
+**Options:**
+
+- `--name <analyzer>` — Specific analyzer name (default: active)
+
+**Output:**
+
+Always JSON format. Query results depend on the query itself.
+
+**Warning:**
+
+This is an advanced escape hatch. Query syntax and result format depend on the analyzer backend. Use standard commands when possible.
+
+**Examples:**
+
+```bash
+# Find all services
+dr analyzer query "MATCH (n:Service) RETURN n.name"
+
+# Count nodes
+dr analyzer query "MATCH (n) RETURN count(n)"
+
+# Find nodes with specific property
+dr analyzer query "MATCH (n) WHERE n.name CONTAINS 'order' RETURN n"
+```
+
+---
+
+### verify — Verify Model Against Code Graph
+
+Cross-reference your model against discovered code routes. Reports matched, graph-only (suspected gaps), and model-only (possible drift) entries.
+
+```bash
+dr analyzer verify [--name <analyzer>] [--layer <layer>...] [--json | --format <format>] [--output <path>]
+```
+
+**Options:**
+
+- `--name <analyzer>` — Specific analyzer name (default: active)
+- `--layer <layer>` — Layer(s) to verify (default: api; v1 only supports api)
+- `--json` — Output as JSON (legacy shorthand equivalent to `--format json`)
+- `--format <format>` — Output format: text (default), json, markdown
+- `--output <path>` — Write report to file (format inferred from extension)
+
+**Note on `--json` and `--format`**: If both flags are provided, `--json` takes precedence and a warning is issued. Use `--format` for consistency with other tools.
+
+**Output Buckets:**
+
+- **Matched**: Graph routes that exist in model ✓
+- **Graph-Only**: Code routes not in model (suspected gaps) ⚠
+- **Model-Only**: Model operations not in code (possible drift) ?
+
+**Report Fields:**
+
+- Summary counts (matched, gaps, drift, ignored)
+- Changeset context (which version verified)
+- Detailed buckets with source information
+
+**Examples:**
+
+```bash
+# Verify to console
+dr analyzer verify
+
+# JSON output
+dr analyzer verify --json
+
+# Save markdown report
+dr analyzer verify --output verify.md
+
+# Save JSON report
+dr analyzer verify --output verify.json
+```
+
+For detailed verification workflow and reconciliation options, see `/dr-verify` command reference.
+
+---
+
+## Configuration
+
+### Setting the Codebase Root
+
+**Option 1: Via manifest.yaml** (recommended for persistent configuration)
+
+```yaml
+# documentation-robotics/model/manifest.yaml
+version: 0.1.0
+schema: documentation-robotics-v1
+---
+codebase_path: ../my-app # Relative to the directory that contains documentation-robotics/
+```
+
+Then re-index:
+
+```bash
+dr analyzer index --force
+```
+
+**Option 2: Via Farm Configuration** (if model is in a farm)
+
+Farm auto-resolves the codebase root. See your farm's configuration for details.
+
+---
+
+## Troubleshooting
+
+### Problem: "Project not indexed"
+
+**Solution:**
+
+```bash
+dr analyzer index
+```
+
+### Problem: "No analyzer selected"
+
+**Solution:**
+
+```bash
+dr analyzer discover
+# Then select an analyzer
+```
+
+### Problem: "Analyzer not installed"
+
+**Solution:**
+
+1. Run `dr analyzer discover` to see installation instructions
+2. Follow the links to install the analyzer for your platform
+3. Run `dr analyzer index` to index your codebase
+
+### Problem: Index is Stale
+
+**Solution:**
+
+```bash
+dr analyzer index --force
+```
+
+### Problem: Dual-Root Configuration Not Recognized
+
+After updating `manifest.codebase_path`, analyzer commands may still read from the old root. Re-index:
+
+```bash
+dr analyzer index --force
+```
+
+The analyzer cache must be rebuilt at the correct codebase root.
+
+---
+
+## Related Commands
+
+- `/dr-verify` — Interactive verification workflow against indexed code
+- `/dr-map` — Extract architecture model from codebase (consumes analyzer pre-briefs)
+- `/dr-validate` — Validate model integrity
+- `dr show <element-id>` — Inspect element details
+- `dr add <layer> <type> <name>` — Manually add elements
+
+---
+
+## Advanced: Integration with Claude Code
+
+When running DR commands in Claude Code, the analyzer integration enables:
+
+1. **Pre-briefs**: `/dr-map` consumes analyzer results to accelerate extraction
+2. **Verification**: `/dr-verify` cross-references model against code
+3. **Querying**: Direct code graph access via `dr analyzer query`
+4. **Codebase Memory**: Shared cache of analyzer results across commands
+
+Dual-root awareness ensures all these operations work correctly whether metadata and source are co-located or separate.

package/dist/integrations/claude_code/commands/dr-map.md

@@ -246,6 +246,19 @@ Proceed with extraction?
 
 The extraction workflow can consult the dr-analyzer if one is installed and active.
 
+**Important: Dual-Root Configuration**
+
+If your codebase root (source code location) differs from your model root (metadata location):
+
+1. Ensure `codebase_path` is configured in `documentation-robotics/model/manifest.yaml`
+2. If you recently changed `codebase_path`, re-index before extraction:
+
+   ```bash
+   dr analyzer index --force
+   ```
+
+See [dr-analyzer.md](dr-analyzer.md) for complete dual-root setup instructions.
+
 **Check analyzer status:**
 
 Run the following command and save the result (it will guide the extraction agent):

package/dist/integrations/claude_code/commands/dr-plan.md

@@ -0,0 +1,40 @@
+---
+description: Plan a change as a staged DR changeset through the dr MCP server, pressure-test it, build from its brief, and verify the build. The human commits it in the PR.
+argument-hint: "<the change to plan, in plain words>"
+---
+
+# Plan a Change
+
+Plan `$ARGUMENTS` as a staged DR changeset instead of a prose plan.
+
+## Instructions for Claude Code
+
+Follow the `dr_change_planning` skill (`.claude/skills/dr_change_planning/SKILL.md`) for this change.
+In short:
+
+1. **Frame**: `changeset_create` with a kebab-case name and the change's intent as the description
+   (or `changeset_activate` an existing one). Find or stage the goal, requirement or feature it
+   serves.
+2. **Orient**: `model_search`, `model_show`, `model_trace` for what exists; `spec_type` for each
+   type you will add. Within reason, every connection the spec models for a type is expected,
+   though not every one will exist.
+3. **Draft**: `model_add` / `model_update` / `model_delete` / `relationship_add` /
+   `relationship_delete` across every layer the change reaches. `model_update` with
+   `attributePatch` to change one attribute; `changeset_unstage` to back out (`source` or `target`
+   alone drops every staged connection at that end).
+4. **Pressure-test**: `changeset_brief` and `changeset_impact`. Answer each gap by staging what is
+   missing, or accept it and say why in an annotation or the description. Steps 3 and 4 repeat:
+   stage a little, then pass the brief's `revisionToken` back as `since` to see what changed, work
+   through `unwired`, and walk `changeset_impact` with `from` set to what you just added.
+5. **Review**: show the human the brief and ask them to review it in `dr visualize`. Read
+   `annotation_list`, reply, revise. Wait for agreement before building.
+6. **Build** from the brief. Commit only the plan's own changeset directory
+   (`documentation-robotics/changesets/<id>/`) on the branch with the code; keep `.active` and the
+   as-built changeset out of the commit.
+7. **Verify**: stage an `<name>-as-built` changeset from the diff, then `changeset_verify` the plan
+   against it. Fix what diverges, in the code or in the plan.
+8. **Land**: the human commits the changeset in the PR. Never commit, apply or discard the plan
+   yourself.
+
+If the `dr` MCP tools are not available, say so and point the user to
+`integrations/claude_code/docs/MCP_SERVER.md`.