@documentation-robotics/cli 0.2.0 → 0.4.0

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

@@ -1,10 +1,16 @@
 ---
-description: Analyze an existing codebase and automatically generate a Documentation Robotics architecture model
+description: "Deprecated: use the codebase_extract MCP tool. Analyze an existing codebase and generate a Documentation Robotics architecture model"
 argument-hint: "<path> [--layers <layers>] [--tech <technology>] [--recipe | --targeted]"
 ---
 
 # Extract Architecture Model from Codebase
 
+> **Deprecated.** Use the `codebase_extract` tool on the `dr` MCP server instead. It runs the
+> extraction cascade on the indexed code (`codebase_index` first): the Tier-0 rules stage what they
+> decide, and the symbols they can't place come back to you as cards to stage with `model_add`.
+> Everything lands in an as-built changeset, never the base model, for the user to review and
+> commit. This command still works but is no longer maintained.
+
 Analyze an existing codebase and automatically generate a Documentation Robotics architecture model.
 
 ## What This Command Does
@@ -246,6 +252,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,66 @@
+---
+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 for this change.
+In short:
+
+1. **Frame**: propose a kebab-case name and the change's intent, and confirm both with the human
+   before `changeset_create` uses them as the name and description (or `changeset_activate` an
+   existing one). Wait for their answer. Find or stage the goal, requirement or feature it serves.
+   With no model yet, confirm the model's name before `project_init`, and ask whether to bootstrap
+   it from the code or let it grow with each change.
+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. Wire several at once with the
+   lists: `model_add` `elements: [...]` (with `relationships` among them) and `relationship_add`
+   `relationships: [...]`; invalid items are skipped and reported. A planned element with no code
+   yet gets no source fields. `model_update` with
+   `attributePatch` to change one attribute; `changeset_unstage` to back out (`source` or `target`
+   alone drops every staged connection at that end; `changes: [...]` drops several in one call).
+4. **Pressure-test**: `changeset_brief` (compact; `detail: "full"` only when you need everything)
+   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` (list it with `sections: ["unwired"], unwiredLayers: [...]`, naming the layers
+   the change reaches; always pass a filter), and walk `changeset_impact` with `from` set to what
+   you just added.
+5. **Review**: show the human the brief, then call `review_open` and give them its `url`, which
+   opens the plan on the graph in the viewer. The human comments there; read the comments with
+   `annotation_list`, answer with `annotation_reply`, revise. Wait for agreement before building.
+6. **Build** from the brief: `changeset_brief` with `sections: ["changes"]` for each changed
+   element's attributes and connections (for a large plan, one layer at a time with
+   `layers: ["<layer>"]`, from the default brief's `byLayer`). 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. Don't verify during the build: no `codebase_extract`, no
+   as-built changeset and no `changeset_verify` until the build is committed.
+7. **Verify**, as its own step after the build is committed: `codebase_index` with `wait: 30`
+   (then `status: true`, `wait: 30` until it is done; if it reports `ignoreFile`, tell the developer
+   to commit that file), then `codebase_extract`
+   with `since` (the branch the work started from) and `changeset: "<name>-as-built"`. Stage the
+   cards it returns that are elements with `model_add` (`sourceProvenance: "extracted"`), call it again for their relationships, then
+   `changeset_verify` the plan against `<name>-as-built`. The as-built comes from `codebase_extract`,
+   never by hand: never copy plan elements into it, and name each element after its card, not the
+   plan. Ask the developer about the cards you can't place with confidence, batched in one short
+   list, instead of guessing. Fix what diverges, in the code or in the plan, and `changeset_activate`
+   the plan again. `unverifiable` items (what extraction can't see) and `notes` (description-only
+   differences) need no plan edit; never edit the plan to match extracted placeholder text. Then the
+   plan is what lands; ask the human whether to discard the as-built changeset or keep it as a
+   record. Landing the as-built first drifts the plan's base, so the plan would need `force`.
+8. **Land**: the human commits the plan in the PR, not the as-built changeset. When they ask you to land it, call
+   `changeset_commit`; they confirm it in a dialog, and it commits only then. If it is refused, they
+   land it in the viewer (`review_open`, then Apply), or you call it again from an interactive
+   session; never point them to the `dr` CLI. Never commit unasked, and never 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`.

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

@@ -9,47 +9,68 @@ description: Configure an MCP client to connect to the Documentation Robotics MC
 
 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.
 
-## Configuring Claude Code
+## Tools
 
-Add an entry to your project's `.mcp.json` (or the equivalent global MCP config):
+| 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`                                             |
+| Review                   | `review_open` (a link that opens a changeset in the viewer; reuses or starts `dr visualize`)                                                                       |
+| 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).
+
+## Installing in Claude Code
+
+Install the `dr` plugin once per machine. It registers the MCP server for every project and adds `/dr-plan` and the DR skills. It needs the `dr` CLI on `PATH`:
+
+```bash
+npm install -g @documentation-robotics/cli
+claude plugin marketplace add tinkermonkey/documentation_robotics
+claude plugin install dr@documentation-robotics
+```
+
+Inside a session, `/plugin marketplace add tinkermonkey/documentation_robotics` and `/plugin install dr@documentation-robotics` do the same.
+
+The server serves the project the session has open: it asks Claude Code for its MCP roots (the folder the session started in) and moves there, so one registration covers every project. Tool calls can still pass `rootPath` to work on another project. From the plugin, the tools are named `mcp__plugin_dr_dr__<tool>`.
+
+The plugin also ships the `dr:dr-architect` and `dr:dr-advisor` agents, with tool lists that use those names. See [Agents in the plugin](README.md#agents-in-the-plugin).
+
+### Registering the server by hand
+
+Without the plugin, add the server to a project's `.mcp.json` (or your user-scope MCP config). Name it `dr`, so its tools are `mcp__dr__<tool>`, which the `dr-architect` agent and DrBot expect:
 
 ```json
 {
   "mcpServers": {
-    "documentation-robotics": {
+    "dr": {
       "command": "dr",
-      "args": ["mcp"],
-      "env": {
-        "DR_MCP_API_KEY": "<key printed by dr mcp>"
-      }
+      "args": ["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
+Other MCP clients follow the same shape: a `command`/`args` pair that launches `dr mcp`. Over stdio there is no API key: the client starts the server as your own user, and that user can already read the model files. An older config that still sets `DR_MCP_API_KEY` keeps working; the server ignores it.
 
-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:
+## Environment
 
-```
-$ 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)
-```
+| Variable            | Effect                                                                                                                                                                                        |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DR_MCP_ROOT_PATH`  | Serve the model at this path instead of the client's roots or 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`. |
+| `DR_MCP_QUIET_KEY`  | HTTP transport only: don't print the API key to stderr on start.                                                                                                                              |
 
-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.
+## HTTP transport and the API key
 
-## Rotating the key
-
-If a key leaks or you just want a fresh one, run:
-
-```bash
-dr mcp --regenerate-key
-```
+`dr mcp --transport http` serves MCP at `http://127.0.0.1:3100/mcp` for clients that connect over the network. HTTP clients authenticate with the API key as a bearer token (`Authorization: Bearer <key>`). The server generates the key on first launch (prompting for a storage path interactively, defaulting to `~/.dr-mcp-key` otherwise) and prints it to stderr on every launch.
 
-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.
+To rotate the key, run `dr mcp --regenerate-key`. It overwrites the key at its existing storage path, updates `~/.dr-config.yaml` and prints the new key. Update every HTTP client afterwards.
 
 See [cli/README.md](../../../cli/README.md#mcp-server) for the full command reference.