@documentation-robotics/cli 0.1.13 → 0.3.0

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

@@ -29,9 +29,9 @@ full set of spec-defined schemas — intra-layer and cross-layer alike.
 
 Relationships require the full model to be visible before wiring can begin:
 
-- A `ux.librarycomponent.renders.ux.view` relationship can't be created until both
+- A `ux.view.composes.ux.componentinstance` relationship can't be created until both
   the source and target UX elements exist
-- Cross-layer relationships (e.g., `business.businessservice --[delivers-value]--> motivation.value`)
+- Cross-layer relationships (e.g., `business.businessservice --[delivers]--> motivation.value`)
   can't be wired until both layers are populated
 - Re-running `/dr-relate` after adding more layers is cheap — no nodes are re-created
 
@@ -303,16 +303,16 @@ Build a relationship map that includes both intra-layer and cross-layer schemas:
 
 ```
 ux layer relationship map (intra-layer):
-  ux.librarycomponent →[renders]→ ux.view
-  ux.librarycomponent →[extends]→ ux.librarycomponent
-  ux.view             →[contains]→ ux.widget
+  ux.view              →[composes]→ ux.componentinstance
+  ux.componentinstance →[realizes]→ ux.librarycomponent
+  ux.librarycomponent  →[specializes]→ ux.librarycomponent
   ux.view             →[handles]→ ux.event
   ux.widget           →[triggers]→ ux.event
   ... (123 total intra-layer schemas in ux)
 
 application layer cross-layer schemas:
   application.applicationprocess →[realizes]→ business.businessprocess
-  application.applicationservice →[delivers-value]→ motivation.value
+  application.applicationservice →[delivers]→ motivation.value
   application.applicationservice →[references]→ apm.traceconfiguration
   ...
 ```
@@ -343,8 +343,8 @@ For each populated layer (in the order they appear in the model):
      - Element names and descriptions
      - Source provenance files (if elements share the same source file, a relationship
        is likely)
-     - Domain semantics of the predicate (e.g., `renders` implies a parent component
-       rendering a child view)
+     - Domain semantics of the predicate (e.g., `composes` implies a parent view
+       placing a child component)
 
 3. For warranted pairs, create the relationship:
 
@@ -378,20 +378,20 @@ For each populated layer (in the order they appear in the model):
 
 **Intra-layer relationship priorities by layer:**
 
-| Layer       | High-value predicates to look for                           |
-| ----------- | ----------------------------------------------------------- |
-| ux          | renders, contains, handles, extends, triggers, navigates-to |
-| navigation  | routes-to, contains, links-to, guards                       |
-| api         | service-of, extends, depends-on, produces, consumes         |
-| data-model  | extends, references, contains                               |
-| data-store  | stores, partitions, indexes                                 |
-| application | depends-on, orchestrates, delegates-to                      |
-| technology  | depends-on, runs-on, extends                                |
-| security    | protects, requires, grants, scopes                          |
-| apm         | monitors, aggregates, triggers                              |
-| testing     | tests, covers, depends-on                                   |
-| business    | realizes, depends-on, triggers, supports                    |
-| motivation  | supports, influences, realizes, fulfills                    |
+| Layer       | High-value predicates to look for                                         |
+| ----------- | ------------------------------------------------------------------------- |
+| ux          | composes, realizes, applies, binds-to, uses, triggers, navigates-to       |
+| navigation  | navigates-to, flows-to, protects, evaluates, composes, accesses           |
+| api         | composes, references, specializes, governs, realizes, serves              |
+| data-model  | composes, references, specializes, maps-to                                |
+| data-store  | composes, accesses, references, triggers, derives-from                    |
+| application | depends-on, orchestrates, delegates-to                                    |
+| technology  | composes, assigned-to, realizes, serves, connects, depends-on             |
+| security    | aggregates, composes, authorizes, mandates, mitigates, generates, governs |
+| apm         | aggregates, composes, flows-to, references, monitors                      |
+| testing     | composes, references, validates, aggregates, covers, tests                |
+| business    | realizes, depends-on, triggers, supports                                  |
+| motivation  | realizes, aggregates, specializes, influence, associated-with, constrains |
 
 ---
 
@@ -424,79 +424,89 @@ The table below lists every cross-layer layer pair and the predicates defined in
 Run `dr schema relationship <element-type>` for the exact source/destination node types
 within each pair — this table shows the predicate vocabulary, not individual type combinations.
 
-| Source Layer | Target Layer | Predicates                                                                                                  |
-| ------------ | ------------ | ----------------------------------------------------------------------------------------------------------- |
-| api          | apm          | references                                                                                                  |
-| api          | application  | realizes, references, serves, triggers, uses                                                                |
-| api          | business     | maps-to, realizes, references, serves, triggers                                                             |
-| api          | data-store   | maps-to                                                                                                     |
-| api          | motivation   | realizes, satisfies, serves                                                                                 |
-| api          | security     | implements, maps-to, references, requires, satisfies                                                        |
-| api          | technology   | depends-on, uses                                                                                            |
-| apm          | api          | monitors, references                                                                                        |
-| apm          | application  | maps-to, monitors                                                                                           |
-| apm          | business     | maps-to, monitors, serves                                                                                   |
-| apm          | data-model   | monitors, references                                                                                        |
-| apm          | data-store   | accesses, depends-on, monitors, serves                                                                      |
-| apm          | motivation   | maps-to, realizes, satisfies                                                                                |
-| apm          | navigation   | monitors, references                                                                                        |
-| apm          | security     | monitors, references, satisfies                                                                             |
-| apm          | technology   | depends-on, monitors                                                                                        |
-| apm          | ux           | monitors, references                                                                                        |
-| application  | apm          | references                                                                                                  |
-| application  | business     | accesses, realizes, serves, triggers                                                                        |
-| application  | motivation   | delivers-value, realizes, satisfies, serves                                                                 |
-| application  | security     | accesses, constrained-by, exposes, implements, mitigates, requires                                          |
-| business     | application  | aggregates, references                                                                                      |
-| business     | motivation   | delivers-value, realizes, satisfies, serves                                                                 |
-| business     | security     | constrained-by                                                                                              |
-| data-model   | api          | maps-to, realizes, serves                                                                                   |
-| data-model   | application  | maps-to, realizes, references, serves                                                                       |
-| data-model   | business     | realizes, references, serves                                                                                |
-| data-model   | data-store   | maps-to                                                                                                     |
-| data-model   | motivation   | realizes, satisfies                                                                                         |
-| data-model   | security     | references, requires, satisfies                                                                             |
-| data-model   | technology   | depends-on, maps-to, uses                                                                                   |
-| data-store   | api          | maps-to, realizes, serves                                                                                   |
-| data-store   | application  | implements, serves, triggers                                                                                |
-| data-store   | business     | realizes, satisfies, serves, triggers                                                                       |
-| data-store   | motivation   | satisfies                                                                                                   |
-| data-store   | security     | implements, requires, satisfies                                                                             |
-| data-store   | technology   | depends-on, uses                                                                                            |
-| navigation   | api          | accesses, maps-to, references, requires, uses                                                               |
-| navigation   | application  | accesses, depends-on, lazy-loads, realizes, references, resolves-with, triggers, uses                       |
-| navigation   | business     | maps-to, realizes, references, serves, triggers                                                             |
-| navigation   | data-model   | accesses, maps-to, references, uses                                                                         |
-| navigation   | data-store   | accesses, depends-on, uses                                                                                  |
-| navigation   | motivation   | realizes, satisfies                                                                                         |
-| navigation   | security     | accesses, implements, references, requires, satisfies                                                       |
-| navigation   | technology   | depends-on, uses                                                                                            |
-| navigation   | ux           | accesses, maps-to, triggers, uses                                                                           |
-| security     | business     | constrains, governs, maps-to, protects, references, targets                                                 |
-| security     | motivation   | implements, maps-to, realizes, satisfies                                                                    |
-| technology   | application  | realizes, serves                                                                                            |
-| technology   | business     | realizes, serves                                                                                            |
-| technology   | motivation   | implements, realizes, satisfies, serves                                                                     |
-| technology   | security     | accesses, implements, mitigates, realizes, satisfies                                                        |
-| testing      | api          | accesses, covers, references, tests, validates                                                              |
-| testing      | apm          | references, tests                                                                                           |
-| testing      | application  | covers, tests                                                                                               |
-| testing      | business     | covers, references, tests                                                                                   |
-| testing      | data-model   | covers, references, tests                                                                                   |
-| testing      | data-store   | accesses, references, tests                                                                                 |
-| testing      | motivation   | constrained-by, fulfills-requirements, governed-by-principles, measures-outcome, references, supports-goals |
-| testing      | navigation   | covers, references, tests                                                                                   |
-| testing      | security     | covers, references, tests, validates                                                                        |
-| testing      | technology   | references, requires, tests                                                                                 |
-| testing      | ux           | covers, maps-to, tests                                                                                      |
-| ux           | api          | accesses, maps-to, triggers, uses                                                                           |
-| ux           | application  | accesses, realizes, serves, triggers, uses                                                                  |
-| ux           | business     | maps-to, realizes, serves, triggers                                                                         |
-| ux           | data-model   | maps-to, references                                                                                         |
-| ux           | data-store   | accesses, maps-to, triggers                                                                                 |
-| ux           | motivation   | maps-to, realizes, satisfies, serves                                                                        |
-| ux           | security     | references, requires, satisfies                                                                             |
-| ux           | technology   | depends-on, requires, uses                                                                                  |
+| Source Layer | Target Layer | Predicates                                                             |
+| ------------ | ------------ | ---------------------------------------------------------------------- |
+| api          | application  | realizes, references, serves, triggers, uses                           |
+| api          | motivation   | satisfies, supports                                                    |
+| api          | navigation   | serves                                                                 |
+| api          | product      | exposes                                                                |
+| api          | security     | realizes, references, requires, satisfies                              |
+| api          | technology   | depends-on                                                             |
+| apm          | api          | monitors, references                                                   |
+| apm          | application  | maps-to, monitors                                                      |
+| apm          | business     | monitors                                                               |
+| apm          | data-model   | monitors, references                                                   |
+| apm          | data-store   | accesses, monitors                                                     |
+| apm          | motivation   | measures-outcome, satisfies                                            |
+| apm          | navigation   | monitors, references                                                   |
+| apm          | security     | monitors, references, satisfies                                        |
+| apm          | technology   | monitors, references                                                   |
+| apm          | ux           | monitors, references                                                   |
+| application  | apm          | references                                                             |
+| application  | business     | accesses, realizes, serves, triggers                                   |
+| application  | data-model   | accesses                                                               |
+| application  | data-store   | accesses                                                               |
+| application  | motivation   | delivers, realizes, satisfies                                          |
+| application  | product      | realizes                                                               |
+| application  | security     | accesses, constrained-by, exposes, realizes, requires                  |
+| business     | application  | references                                                             |
+| business     | motivation   | delivers, realizes, references, satisfies, supports                    |
+| business     | security     | constrained-by                                                         |
+| data-model   | api          | maps-to                                                                |
+| data-model   | application  | realizes                                                               |
+| data-model   | business     | realizes                                                               |
+| data-model   | data-store   | maps-to                                                                |
+| data-model   | motivation   | satisfies                                                              |
+| data-model   | security     | references, requires, satisfies                                        |
+| data-model   | technology   | maps-to                                                                |
+| data-store   | api          | maps-to, serves                                                        |
+| data-store   | application  | realizes, serves, triggers                                             |
+| data-store   | business     | realizes, satisfies                                                    |
+| data-store   | motivation   | satisfies                                                              |
+| data-store   | security     | realizes, references, requires, satisfies                              |
+| data-store   | technology   | depends-on                                                             |
+| navigation   | api          | maps-to, references, requires, uses                                    |
+| navigation   | application  | accesses, depends-on, lazy-loads, realizes, references, triggers, uses |
+| navigation   | business     | references                                                             |
+| navigation   | data-model   | accesses, maps-to, references                                          |
+| navigation   | motivation   | satisfies                                                              |
+| navigation   | product      | realizes                                                               |
+| navigation   | security     | accesses, realizes, references, requires, satisfies                    |
+| navigation   | technology   | depends-on                                                             |
+| navigation   | ux           | maps-to, triggers, uses                                                |
+| product      | business     | realizes, references                                                   |
+| product      | motivation   | delivers, references, satisfies, supports                              |
+| security     | business     | constrains, governs, protects, references, targets                     |
+| security     | motivation   | realizes, references, satisfies                                        |
+| technology   | api          | serves                                                                 |
+| technology   | apm          | serves                                                                 |
+| technology   | application  | realizes, serves                                                       |
+| technology   | data-store   | serves                                                                 |
+| technology   | motivation   | realizes, satisfies                                                    |
+| technology   | navigation   | serves                                                                 |
+| technology   | product      | realizes                                                               |
+| technology   | security     | accesses, realizes, satisfies                                          |
+| technology   | ux           | serves                                                                 |
+| testing      | api          | covers, references, tests                                              |
+| testing      | apm          | tests                                                                  |
+| testing      | application  | covers, tests                                                          |
+| testing      | business     | covers, tests                                                          |
+| testing      | data-model   | covers, references, tests                                              |
+| testing      | data-store   | accesses, covers, tests                                                |
+| testing      | motivation   | measures-outcome, satisfies, supports                                  |
+| testing      | navigation   | covers, tests                                                          |
+| testing      | product      | covers, tests                                                          |
+| testing      | security     | covers, tests                                                          |
+| testing      | technology   | covers, references, requires                                           |
+| testing      | ux           | covers, references, tests                                              |
+| ux           | api          | maps-to, references, triggers                                          |
+| ux           | application  | realizes, triggers                                                     |
+| ux           | business     | references, serves                                                     |
+| ux           | data-model   | maps-to, references                                                    |
+| ux           | motivation   | satisfies, supports                                                    |
+| ux           | product      | realizes                                                               |
+| ux           | security     | references, requires, satisfies                                        |
+| ux           | technology   | depends-on                                                             |
 
 > **API→Application traceability pattern**
 >
@@ -644,7 +654,7 @@ Log the failure and continue. At the end of the pass, surface skipped pairs:
 Skipped relationships (not in spec):
   ux.view.dashboard-view →[contains]→ ux.widget.sidebar
     Reason: ux.view.contains.ux.widget is not a defined relationship schema
-    Suggestion: Valid predicates for ux.view: renders, handles, triggers
+    Suggestion: Valid predicates for ux.view: composes, applies, binds-to, uses
 ```
 
 ### Element not found

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

@@ -16,7 +16,19 @@ Cross-reference the Documentation Robotics model against an external code analyz
    - **Graph-only**: Routes discovered in the code but missing from the model (suspected gaps) ⚠
    - **Model-only**: Operations in the model but not discovered in the code (possible drift) ?
 
-4. Offers actionable next steps: add missing routes, remove orphaned operations, or ignore entries
+4. Checks matched elements for connections the spec models but the model lacks, and looks for
+   evidence of each in the analyzer's graph and the code
+5. Offers actionable next steps: add missing routes and connections, remove orphaned operations, or
+   ignore entries
+
+## Important: Dual-Root Configuration
+
+The verification process respects your project's dual-root configuration. If your codebase root (source code location) differs from your model root (metadata location), ensure:
+
+1. **Configure in manifest**: Set `codebase_path` in `documentation-robotics/model/manifest.yaml` if needed
+2. **Re-index if needed**: If you recently updated `codebase_path`, run `dr analyzer index --force` before verifying
+
+See [dr-analyzer.md](dr-analyzer.md) for complete dual-root documentation.
 
 ## Usage
 
@@ -348,7 +360,38 @@ ignore:
     match: "model_only"
 ```
 
-### Step 7: Status and Next Steps
+### Step 7: Check for Missing Connections
+
+Matching elements is half the check. Within reason, every connection the spec models for a type is
+expected, though not every one will exist. Look for the ones the model has not captured:
+
+1. **Pick the elements.** The matched elements, plus the ones you added in Step 5. With a changeset
+   active, the elements it adds or changes.
+2. **Ask the spec what each type can connect to:** `dr schema relationship <layer>.<type>` lists
+   the triples the catalog defines from that type (over MCP, `spec_type` lists both directions).
+   Incoming ones are covered when you check the element at the other end.
+3. **Compare with the model:** `dr show <element-id>` lists the relationships the element has.
+   Every triple the spec models that the element lacks is a candidate.
+4. **Look for evidence of each candidate, in this order:**
+   - the analyzer's graph: `dr analyzer callers <symbol>` / `dr analyzer callees <symbol>` for the
+     element's source symbol, or `dr analyzer query` for HTTP calls, imports and handlers between
+     the element's file and the other element's file
+   - the code at the element's source file and symbol
+5. **Act on what you find.**
+   - Evidence found: offer the relationship with the evidence, for example
+     `dr relationship add <source-id> <target-id> --predicate <predicate>`. Say what the evidence is
+     ("`createOrder` calls `OrderRepository.save`").
+   - No evidence: don't add it. The catalog says a connection can exist, not that it does here.
+
+**Report the result in its own section:**
+
+```
+Missing connections: N candidates checked, X with evidence (offered), Y without evidence (left out).
+```
+
+List each one with evidence: the triple, the two elements, and where the evidence is.
+
+### Step 8: Status and Next Steps
 
 **After processing all buckets, summarize:**
 

package/dist/integrations/claude_code/docs/END_TO_END_WALKTHROUGH.md

@@ -168,6 +168,18 @@ If you select [y], the analyzer is installed and ready.
 
 **What this does:** Scans your codebase and builds an indexed code graph for later verification.
 
+**Important: If Your Codebase is in a Different Directory**
+
+If your source code lives in a different directory than your model (common in monorepos), configure it first:
+
+**In `documentation-robotics/model/manifest.yaml`:**
+
+```yaml
+codebase_path: src # Relative to the directory that contains documentation-robotics/
+```
+
+Then proceed with indexing.
+
 **Command:**
 
 ```bash
@@ -206,6 +218,8 @@ Ready for extraction with /dr-map
 
 **Then proceed to Step 3** with the analyzer installed. This enables `/dr-verify` for gap and drift detection.
 
+For complete analyzer documentation including dual-root configuration, see [dr-analyzer.md](../commands/dr-analyzer.md).
+
 ---
 
 ### Option B: Without Code Analyzer (Faster, Manual-First Approach)

package/dist/integrations/claude_code/docs/MCP_SERVER.md

@@ -0,0 +1,79 @@
+---
+title: DR MCP Server
+description: Configure an MCP client to connect to the Documentation Robotics MCP server
+---
+
+# Documentation Robotics MCP Server
+
+`dr mcp` runs the CLI as a [Model Context Protocol](https://modelcontextprotocol.io/) server over stdio, exposing model tools (list/show/search/add/update/delete/validate/export/trace elements, changesets, chat, annotations) to any MCP-aware AI client — Claude Code included.
+
+Annotation tools (`annotation_list`, `annotation_get`, `annotation_create`, `annotation_update`, `annotation_delete`, `annotation_reply`) mirror the capabilities of the REST server's `/api/annotations/*` endpoints. Unlike the REST server's in-memory, per-process annotation store, the MCP tools persist annotations to `documentation-robotics/annotations/` on disk, so they survive across MCP sessions.
+
+## Tools
+
+| Group                    | Tools                                                                                                                                                              |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Read the model           | `model_list`, `model_show`, `model_search`, `model_trace`, `model_stats`, `model_info`, `model_validate`, `model_export`, `model_reload`                           |
+| Change the model         | `model_add`, `model_update`, `model_delete`, `relationship_add`, `relationship_delete`                                                                             |
+| Look up the spec         | `spec_type`                                                                                                                                                        |
+| Changesets               | `changeset_list`, `changeset_show`, `changeset_create`, `changeset_activate`, `changeset_deactivate`, `changeset_update`, `changeset_unstage`, `changeset_discard` |
+| Pressure-test and verify | `changeset_brief`, `changeset_impact`, `changeset_verify`                                                                                                          |
+| Annotations              | `annotation_list`, `annotation_get`, `annotation_create`, `annotation_update`, `annotation_delete`, `annotation_reply`                                             |
+| Chat                     | `chat_launch`, `chat_status`                                                                                                                                       |
+
+With a changeset active, the "change the model" tools stage into it, and the read tools show the model as the changeset leaves it. Committing or applying a changeset is not a tool: the human does that in the viewer or with `dr changeset commit`. `changeset_discard` deletes staged changes for good, so it needs the changeset named explicitly (id or name) and `confirm: true`.
+
+To plan a change with these tools, use `/dr-plan` (or the `dr_change_planning` skill). The design is in [`docs/CHANGE_MODELING.md`](../../../docs/CHANGE_MODELING.md).
+
+## Environment
+
+| Variable            | Effect                                                                                                                                                                                        |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DR_MCP_API_KEY`    | Required. The key `dr mcp` prints on start.                                                                                                                                                   |
+| `DR_MCP_ROOT_PATH`  | Serve the model at this path instead of the working directory. An unusable path is reported on stderr and the server keeps its own directory.                                                 |
+| `DR_CHANGESET_ONLY` | `true`/`1`/`yes`/`on` refuses model writes unless a staged changeset is active (an unrecognised value also turns it on, with a warning). DrBot sets it with `dr visualize --with-changesets`. |
+
+## Configuring Claude Code
+
+Add an entry to your project's `.mcp.json` (or the equivalent global MCP config). Name the server `dr`: the DR agents and DrBot refer to its tools as `mcp__dr__<tool>`.
+
+```json
+{
+  "mcpServers": {
+    "dr": {
+      "command": "dr",
+      "args": ["mcp"],
+      "env": {
+        "DR_MCP_API_KEY": "<key printed by dr mcp>"
+      }
+    }
+  }
+}
+```
+
+Other MCP clients follow the same shape: a `command`/`args` pair that launches `dr mcp`, plus `DR_MCP_API_KEY` in `env`.
+
+## Getting the API key
+
+Run `dr mcp` once from a terminal — it generates an API key on first launch (prompting for a storage path interactively, defaulting to `~/.dr-mcp-key` otherwise) and prints it to stderr on every launch:
+
+```
+$ dr mcp
+Generated new MCP API key, stored at /home/you/.dr-mcp-key
+MCP API key: dr-mcp-<random>
+Documentation Robotics MCP server ready (stdio)
+```
+
+Copy that key into the client config's `DR_MCP_API_KEY`. The server rejects the connection if the key is missing or doesn't match.
+
+## Rotating the key
+
+If a key leaks or you just want a fresh one, run:
+
+```bash
+dr mcp --regenerate-key
+```
+
+This overwrites the key at its existing storage path, updates `~/.dr-config.yaml`, and prints the new key — no manual deletion of files required. Update `DR_MCP_API_KEY` in every client config after rotating.
+
+See [cli/README.md](../../../cli/README.md#mcp-server) for the full command reference.

package/dist/integrations/claude_code/docs/QUICK_START.md

@@ -185,6 +185,34 @@ dr analyzer index
 - **Pre-Briefs:** Analyzer provides summaries of endpoints, services, datastores that `/dr-map` uses for high-confidence extraction
 - **Three Buckets:** Verification shows **matched** (good), **graph-only** (gaps), **model-only** (drift)
 - **Interactive Reconciliation:** `/dr-verify` prompts you to add gaps or remove drift one by one
+- **Dual-Root Architecture:** Your model (metadata) and codebase (source code) can be in different directories. Configure via `codebase_path` in `manifest.yaml` if needed (relative to the directory that contains `documentation-robotics/`).
+
+---
+
+## Special Setup: Dual-Root Configuration
+
+If your source code and model are in **separate directories** (common in monorepos), configure the codebase root:
+
+**In `documentation-robotics/model/manifest.yaml`:**
+
+```yaml
+version: 0.1.0
+schema: documentation-robotics-v1
+---
+codebase_path: src # Relative to the directory that contains documentation-robotics/
+```
+
+`codebase_path` is resolved against the model root: the directory that **contains** `documentation-robotics/`, not the `documentation-robotics/model/` folder the manifest sits in. So `src` points at `<model-root>/src`, and a sibling checkout at `<model-root>/../my-app` is `codebase_path: ../my-app`.
+
+**Then re-index:**
+
+```bash
+dr analyzer index --force
+```
+
+**Don't have separate directories?** No action needed — DR defaults to the model directory.
+
+For complete details, see [dr-analyzer.md dual-root documentation](../commands/dr-analyzer.md).
 
 ---
 
@@ -231,14 +259,15 @@ Ready for export/sharing
 
 ## Troubleshooting Quick Fixes
 
-| Problem             | Solution                                                       |
-| ------------------- | -------------------------------------------------------------- |
-| "No analyzer"       | `dr analyzer discover` then pick one                           |
-| "Not indexed"       | `dr analyzer index` to build graph                             |
-| "Index stale"       | `dr analyzer index` to refresh                                 |
-| "Many gaps"         | `/dr-map ./src --layers api` to re-extract                     |
-| "Validation errors" | `dr validate --strict` to see details, then `/dr-model` to fix |
-| "Lost in process"   | Read `END_TO_END_WALKTHROUGH.md` for detailed guide            |
+| Problem             | Solution                                                               |
+| ------------------- | ---------------------------------------------------------------------- |
+| "No analyzer"       | `dr analyzer discover` then pick one                                   |
+| "Not indexed"       | `dr analyzer index` to build graph                                     |
+| "Index stale"       | `dr analyzer index` to refresh                                         |
+| "Many gaps"         | `/dr-map ./src --layers api` to re-extract                             |
+| "Wrong codebase"    | Set `codebase_path` in manifest.yaml, then `dr analyzer index --force` |
+| "Validation errors" | `dr validate --strict` to see details, then `/dr-model` to fix         |
+| "Lost in process"   | Read `END_TO_END_WALKTHROUGH.md` for detailed guide                    |
 
 ---
 

package/dist/integrations/claude_code/docs/README.md

@@ -50,6 +50,16 @@ The comprehensive manual walkthrough covering every step from fresh project thro
 
 ### Command Reference
 
+- **[dr-plan.md](../commands/dr-plan.md)** — Plan a change as a staged changeset over the `dr` MCP server
+  - Frame, draft, pressure-test (`changeset_brief`, `changeset_impact`), review, build, verify
+  - The human commits the changeset in the PR
+
+- **[dr-analyzer.md](../commands/dr-analyzer.md)** — Discover, install, and manage code analyzers
+  - Dual-root architecture (separate metadata and codebase roots)
+  - Index and query code graphs
+  - Analyzer endpoints, services, datastores
+  - Pre-index configuration for dual-root setups
+
 - **[dr-map.md](../commands/dr-map.md)** — Extract architecture from your codebase
   - Recipe vs. Targeted modes
   - Layer-by-layer extraction
@@ -59,6 +69,7 @@ The comprehensive manual walkthrough covering every step from fresh project thro
   - Three-bucket reporting (matched, gaps, drift)
   - Interactive reconciliation
   - Ignore lists and drift management
+  - Works with dual-root analyzer setup
 
 - **[dr-validate.md](../commands/dr-validate.md)** — Validate model integrity
   - Schema and reference validation
@@ -69,8 +80,13 @@ The comprehensive manual walkthrough covering every step from fresh project thro
 
 - **[dr-init.md](../commands/dr-init.md)** — Initialize new models
 
+### MCP Integration
+
+- **[MCP_SERVER.md](MCP_SERVER.md)** — Configure an MCP client (Claude Code or otherwise) to connect to `dr mcp`, including the API key setup and rotation
+
 ### Skills & Agents
 
+- **[dr_change_planning/SKILL.md](../skills/dr_change_planning/SKILL.md)** — "Plan this change" as a DR changeset (the steps behind `/dr-plan`)
 - **[dr-codebase-memory/SKILL.md](../skills/dr_codebase_memory/SKILL.md)** — Codebase memory and context management
 - Layer-specific skills (Layer 1-13)
 
@@ -154,10 +170,12 @@ integrations/claude_code/
 │   ├── dr-sync.md              ← Sync with code changes
 │   ├── dr-design.md            ← Design elements
 │   ├── dr-info.md              ← Get model information
+│   ├── dr-plan.md              ← Plan a change as a changeset
 │   ├── dr-changeset.md         ← Manage changesets
 │   └── dr-relate.md            ← Establish relationships
 │
 ├── skills/                      ← Specialized knowledge modules
+│   ├── dr_change_planning/
 │   ├── dr_codebase_memory/
 │   ├── dr_01_motivation_layer/
 │   ├── ... (all 13 layers)
@@ -173,11 +191,44 @@ integrations/claude_code/
 
 ## 🔑 Key Concepts
 
+### Dual-Root Architecture
+
+Your Documentation Robotics project has two roots:
+
+- **Model Root** — Where your `documentation-robotics/` directory lives (contains manifest, layers, changesets)
+- **Codebase Root** — Where your actual source code is located
+
+These can be the same directory (typical) or different directories (useful for monorepos or federated architectures). Analyzer commands automatically respect this configuration.
+
+**Resolution Priority:**
+
+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`** — Configured in `documentation-robotics/model/manifest.yaml`; resolved relative to the model root, the directory that contains `documentation-robotics/`
+3. **Farm auto-resolution** — If your model is in a farm, resolved from farm configuration
+4. **Default** — Uses the model root itself
+
+**Configure via `manifest.codebase_path`:**
+
+```yaml
+# documentation-robotics/model/manifest.yaml
+codebase_path: ../my-app # Relative to the directory that contains documentation-robotics/, points to actual source code
+```
+
+After configuration, re-index for changes to take effect:
+
+```bash
+dr analyzer index --force
+```
+
+For details, see [dr-analyzer.md](../commands/dr-analyzer.md).
+
 ### Source Provenance
 
 Every extracted element includes:
 
-- **source_file** — The file path (relative to repo root)
+- **source_file** — The file path (relative to codebase root)
 - **source_symbol** — The specific class/function/symbol
 - **source_provenance** — "extracted" (from code) or "inferred" (from patterns)