@documentation-robotics/cli 0.2.0 → 0.4.0

package/dist/integrations/claude_code/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "dr",
+  "version": "0.4.0",
+  "description": "Documentation Robotics for Claude Code: the dr MCP server (it serves the project you have open), /dr-plan for planning a change as a staged changeset, the DR layer skills, and the dr-architect and dr-advisor agents. Needs the dr CLI on PATH (npm install -g @documentation-robotics/cli).",
+  "author": {
+    "name": "Documentation Robotics",
+    "url": "https://github.com/tinkermonkey/documentation_robotics"
+  },
+  "homepage": "https://github.com/tinkermonkey/documentation_robotics",
+  "repository": "https://github.com/tinkermonkey/documentation_robotics",
+  "license": "MIT",
+  "keywords": ["architecture", "changesets", "mcp", "planning"],
+  "commands": ["./commands/dr-plan.md"],
+  "agents": [
+    "./plugin-agents/dr-architect.md",
+    "./plugin-agents/dr-advisor.md"
+  ],
+  "mcpServers": {
+    "dr": {
+      "command": "dr",
+      "args": ["mcp"]
+    }
+  }
+}

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, mcp__dr__project_status
 color: orange
 ---
 
@@ -22,11 +22,38 @@ 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__*`): the dr MCP server's tools, when it is connected. 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**: propose a short name for the change and its intent, and confirm both with the user before `changeset_create` (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. When you wire several, use the lists: `model_add` with `elements: [...]` (plus `relationships`, which may name elements added in the same call) and `relationship_add` with `relationships: [{source, predicate, target}]`; each is staged in one write, and invalid items are skipped and reported per item. A planned element with no code yet gets no source fields. `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 (compact; `detail: "full"` only when you need everything). 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.
+
+## Running dr through Bash
+
+When you run `dr` through Bash, run **one `dr` command per Bash call**, and use JSON output (`--json`, or `--format json` where a command takes `--format`) when you need to read the result. Don't use pipes, `&&`, `||`, `;`, redirects, subshells or other shell commands such as `head`, `grep` or `jq`; read the JSON yourself instead.
+
+The `dr visualize` chat allows each `dr` command by name and nothing else, and nobody can answer a permission prompt there. Any extra shell in a call needs approval, so the whole call is denied. To do several things, make several calls.
+
+```bash
+# ✅ correct: one command per call
+dr list api --json
+dr search order --layer api --json
+```
+
+❌ Denied in the chat: a pipe (`dr list api | head`), a chain (`dr validate && dr list api`) and a redirect (`dr list api > /tmp/api.txt`).
+
 ## The 12-Layer Model
 
 ```
@@ -44,7 +71,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

@@ -1,11 +1,17 @@
 ---
 name: dr-extractor
-description: Specialized extraction agent for Documentation Robotics model creation from codebases. Analyzes source code to identify architectural elements across all 13 layers with mandatory source provenance tracking.
+description: "Deprecated: use the codebase_extract MCP tool. Specialized extraction agent for Documentation Robotics model creation from codebases. Analyzes source code to identify architectural elements across all 13 layers with mandatory source provenance tracking."
 tools: Bash, Read, Glob, Grep
 ---
 
 # Documentation Robotics Extraction Agent
 
+> **Deprecated.** The `codebase_extract` tool on the `dr` MCP server replaces this agent. It runs
+> the extraction cascade on the indexed code (`codebase_index` first) and stages the result in an
+> as-built changeset, never the base model: the Tier-0 rules stage what they decide, and the calling
+> agent stages the symbols they can't place, from the cards it returns, with `model_add`. Use it
+> instead of driving `dr add` through Bash. This agent still works but is no longer maintained.
+
 ## Identity
 
 You are the **DR Extractor** — a code analysis specialist focused exclusively on extracting architectural elements from codebases and creating Documentation Robotics model entries. You operate entirely through the `dr add` command line interface, never creating YAML or JSON directly.
@@ -269,7 +275,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-changeset.md

@@ -528,7 +528,8 @@ dr changeset preview                 # Preview staged changes merged with model
 dr changeset create "name"           # Create new changeset
 dr changeset activate <name>         # Activate a changeset (auto-stages changes)
 dr changeset deactivate              # Deactivate the active changeset
-dr changeset commit                  # Commit staged changes to model
+dr changeset commit                  # Commit the active changeset's staged changes to model
+dr changeset commit <name>           # Commit the changeset named (need not be active)
 dr changeset discard                 # Abandon all staged changes
 
 # Export and import