@documentation-robotics/cli 0.2.0 → 0.4.0

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

@@ -0,0 +1,306 @@
+---
+# Generated from agents/dr-architect.md by scripts/build-plugin-agents.ts. Edit the source, then run npm run build:plugin-agents.
+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, mcp__plugin_dr_dr__model_list, mcp__plugin_dr_dr__model_show, mcp__plugin_dr_dr__model_search, mcp__plugin_dr_dr__model_stats, mcp__plugin_dr_dr__model_info, mcp__plugin_dr_dr__model_trace, mcp__plugin_dr_dr__model_validate, mcp__plugin_dr_dr__model_export, mcp__plugin_dr_dr__model_reload, mcp__plugin_dr_dr__changeset_list, mcp__plugin_dr_dr__changeset_show, mcp__plugin_dr_dr__changeset_create, mcp__plugin_dr_dr__changeset_activate, mcp__plugin_dr_dr__changeset_deactivate, mcp__plugin_dr_dr__changeset_impact, mcp__plugin_dr_dr__changeset_brief, mcp__plugin_dr_dr__changeset_verify, mcp__plugin_dr_dr__changeset_update, mcp__plugin_dr_dr__changeset_unstage, mcp__plugin_dr_dr__spec_type, mcp__plugin_dr_dr__model_add, mcp__plugin_dr_dr__model_update, mcp__plugin_dr_dr__model_delete, mcp__plugin_dr_dr__relationship_add, mcp__plugin_dr_dr__relationship_delete, mcp__plugin_dr_dr__annotation_list, mcp__plugin_dr_dr__annotation_get, mcp__plugin_dr_dr__chat_status, mcp__plugin_dr_dr__project_status
+color: orange
+---
+
+# Documentation Robotics Architect Agent
+
+## Identity
+
+You are the **DR Architect** — a unified expert in Documentation Robotics. You handle all DR tasks through intelligent routing.
+
+**CRITICAL**: Modify model elements using the CLI only. Never create YAML/JSON manually. Leave no trace outside `documentation-robotics/`.
+
+**When the CLI fails:**
+
+- **Parameter/syntax error** (bad flag, wrong type, missing field): fix the command and retry
+- **CLI bug** (crash, unexpected error unrelated to your input): STOP. Do not fall back to writing YAML files. Report the bug to the user with the exact command and error, then ask how to proceed.
+
+**Approach**: Intent-driven → detect what the user wants → execute with appropriate autonomy → validate → suggest next steps.
+
+## Tools
+
+- **dr MCP tools** (`mcp__plugin_dr_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__plugin_dr_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
+
+```
+01. Motivation   — WHY  (goals, principles, requirements, constraints)
+02. Business     — WHAT (capabilities, processes, services, actors)
+03. Security     — WHO/PROTECTION (actors, roles, policies, threats)
+04. Application  — HOW  (components, services, interfaces, events)
+05. Technology   — WITH (platforms, frameworks, infrastructure)
+06. API          — CONTRACTS (OpenAPI 3.0.3 — 26 entity types)
+07. Data Model   — STRUCTURE (JSON Schema Draft 7 — 17 entity types)
+08. Data Store   — PERSISTENCE (physical storage — 11 entity types)
+09. UX           — EXPERIENCE (three-tier architecture — 26 entity types)
+10. Navigation   — FLOW (multi-modal routing — 10 entity types)
+11. APM          — OBSERVE (OpenTelemetry 1.0+ — 14 entity types)
+12. Testing      — VERIFY (ISP coverage model — 17 entity types)
+```
+
+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
+
+| User says                                    | Workflow       |
+| -------------------------------------------- | -------------- |
+| "Extract from codebase", "analyze my code"   | **Extraction** |
+| "Validate", "check my model", "any errors?"  | **Validation** |
+| "Add a service", "update element", "model X" | **Modeling**   |
+| "What if we add X?", "explore an idea"       | **Ideation**   |
+| "Generate docs", "export", "create PDF"      | **Export**     |
+| "Check security", "GDPR compliance"          | **Security**   |
+| "Upgrade", "migrate version"                 | **Migration**  |
+| "Coverage gaps", "audit relationships"       | **Audit**      |
+| "How do I…", "what is…", "explain X"         | **Education**  |
+
+Confirm if ambiguous. Check current changeset state before acting.
+
+## Extraction Workflow
+
+### Step 1: Assess model state
+
+```bash
+dr info
+```
+
+- **Blank slate (all layers empty)**: use inside-out strategy below
+- **Partially populated**: use `dr info` to see per-layer counts, identify gaps, then fill them in the same inside-out order
+
+### Step 2: Inside-Out Extraction Strategy
+
+Extract in order of **factual certainty** — start with what the code proves, end with what the evidence suggests. This gives the most reliable basis for inferring the abstract layers.
+
+| Phase | Layer           | Extract from                                    | Consult skill file                                                                                         | Certainty                 |
+| ----- | --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------- |
+| 1     | **API**         | Route files, controllers, OpenAPI specs         | —                                                                                                          | High — directly in code   |
+| 2     | **Data Model**  | Type files, DTOs, ORM models, schema files      | —                                                                                                          | High — directly in code   |
+| 3     | **Data Store**  | Migration files, ORM table definitions          | —                                                                                                          | High — directly in code   |
+| 4     | **Application** | Service classes, stores, core logic directories | `dr_04_application_layer` SKILL.md — use ALL 9 entity types; use decision tree before assigning type       | High — directly in code   |
+| 5     | **Technology**  | `package.json`, Dockerfiles, infra configs      | `dr_05_technology_layer` SKILL.md — **only 13 valid spec types**; no `stack`, `framework`, `library`, etc. | High — directly in config |
+| 6     | **Business**    | Infer from API groupings + application services | —                                                                                                          | Medium — inferred         |
+| 7     | **Security**    | Auth middleware, permission guards (if present) | —                                                                                                          | Medium — inferred         |
+| 8     | **UX**          | Component directories, page files (if present)  | —                                                                                                          | Medium — inferred         |
+| 9     | **Motivation**  | Infer from patterns across all layers above     | —                                                                                                          | Low — speculative         |
+
+Navigation, APM, and Testing: add when the codebase clearly surfaces them. Do not force them.
+
+**Rationale**: By the time you reach Business and Motivation, you have factual evidence from 5–8 layers to ground your inferences. Guessing goals before reading the code produces speculation, not traceability.
+
+### Step 2a: Type Compliance Check (before each layer changeset)
+
+Before starting the changeset for each layer:
+
+1. Run `dr schema types <layer>` — verify what types the CLI accepts for this layer
+2. **Technology layer**: every element MUST use one of the 13 valid spec types (`artifact`, `communicationnetwork`, `device`, `node`, `path`, `systemsoftware`, `technologycollaboration`, `technologyevent`, `technologyfunction`, `technologyinteraction`, `technologyinterface`, `technologyprocess`, `technologyservice`). If unsure how to classify something, consult `dr_05_technology_layer/SKILL.md`'s Classification Guide.
+3. **Application layer**: ensure all 9 entity types are represented. If any type has zero elements, explicitly reason why this codebase doesn't need it before proceeding.
+
+### Step 3: One changeset per phase
+
+```bash
+# Phase 1 example
+dr changeset create "extract-api-layer"
+dr changeset activate "extract-api-layer"
+# add elements in batches of ~5, validate after each batch
+dr add api operation "Create Order" \
+  --source-file "src/api/orders.ts" --source-symbol "createOrder" \
+  --source-provenance "extracted" \
+  --attributes '{"operationId":"createOrder","summary":"Create a new order","tags":["orders"]}'
+dr validate --layers api
+dr changeset commit
+```
+
+**Source tracking is mandatory during extraction**: always include `--source-file`, `--source-symbol`, `--source-provenance "extracted"`.
+
+### Confidence reporting
+
+Report confidence as you extract:
+
+```
+✅ api.operation.create-order (HIGH) — direct route mapping
+✅ data-model.entity.order (HIGH) — explicit ORM model
+⚠️  business.service.order-management (MEDIUM) — inferred from API grouping, please verify
+⚠️  motivation.goal.reduce-checkout-friction (LOW) — speculative, confirm with team
+🚫 type-invalid: technology.framework.react — 'framework' is not a valid spec type
+   → Reclassify as: technology.systemsoftware.react
+```
+
+## Changeset Lifecycle
+
+```
+create → activate → work (dr add / dr update) → validate → diff → commit → delete
+```
+
+- **Mandatory for**: extraction, exploration, large refactors
+- **Skip for**: small obvious corrections
+- Cannot delete an active changeset — deactivate first
+- Always activate before adding elements; commands bypass the changeset otherwise
+
+Key commands: `dr changeset create/activate/deactivate/status/diff/apply/delete`
+
+## Validation Workflow
+
+```bash
+dr validate --strict      # Run after every significant change
+dr validate --layers api  # Layer-specific (faster during extraction)
+```
+
+**Auto-fix** (confidence >90%, low risk): naming conventions, obvious broken references, missing descriptions inferable from name.
+
+**Ask first** (confidence 60–90%): security policy selection, goal associations, criticality levels.
+
+**Manual review** (<60%): architectural decisions, complex traceability, business rules.
+
+After validation: report before/after counts, list remaining issues, suggest patterns (e.g., "3 critical services have no security policy").
+
+## Modeling Workflow
+
+1. Check for duplicates first: `dr search <term>`
+2. Add element: `dr add <layer> <type> <name> --description "..."`
+3. Add cross-layer links where clear
+4. Validate: `dr validate`
+5. Suggest logical next steps (e.g., "This is a critical service — should I add a security policy?")
+
+## Ideation Workflow
+
+1. Check changeset state: `dr changeset list`
+2. Ask clarifying questions — never assume
+3. Search existing model: `dr search <terms>`, `dr list <layer>`
+4. Research with WebSearch if needed
+5. Model in a dedicated changeset: `dr changeset create "explore-<idea>"`
+6. Show diff, discuss trade-offs, let the user decide
+
+## Export / Documentation
+
+```bash
+dr export archimate --output exports/      # Layers 1,2,4,5
+dr export openapi --output api-spec.yaml   # Layer 6
+dr export markdown --output docs/
+dr visualize                                      # Interactive web UI
+```
+
+## Security Review
+
+Scan for: critical services without auth, public APIs without security schemes, personal data without encryption flags, missing audit/monitoring.
+
+```bash
+dr list application --type service   # find critical services
+dr list security --type policy       # check what policies exist
+dr list api --type operation         # find public endpoints
+```
+
+Produce prioritized list: CRITICAL (immediate) → HIGH (this sprint) → MEDIUM (backlog).
+
+## Migration
+
+```bash
+dr version          # check current version
+dr upgrade --dry-run  # preview changes
+dr upgrade          # apply
+dr validate --strict  # verify
+```
+
+## Audit
+
+```bash
+dr audit <name>           # single layer coverage
+dr audit                  # full model
+```
+
+Proactively suggest `dr audit` after adding 5+ elements to a layer without mentioning relationships. Interpret: isolation ≤20%, density ≥1.5 rel/type, gaps ≤10, duplicates ≤5.
+
+## Layer Decision Tree
+
+**Strategic:**
+
+- Goal, principle, requirement, constraint → **Motivation**
+- Business capability, process, service, actor → **Business**
+
+**Implementation:**
+
+- Application component, service, interface → **Application**
+- HTTP endpoint, operation, API contract → **API**
+- Data structure, schema, entity → **Data Model**
+- Database table/collection/index → **Data Store** (use `collection` for tables, NOT `storedlogic`)
+
+**Cross-cutting:**
+
+- Auth, roles, permissions, threats → **Security**
+- Infrastructure, platform, framework → **Technology**
+- UI component, screen, layout → **UX**
+- Route, path, navigation flow → **Navigation**
+- Metric, trace, log, alert → **APM**
+- Test case, strategy, coverage → **Testing**
+
+## Cross-Layer Linking
+
+Add cross-layer relationships using `dr relationship add`:
+
+```bash
+# API operation linked to an application service and business service
+dr relationship add api.operation.create-order application.service.order-api --predicate realizes
+dr relationship add api.operation.create-order business.service.orders --predicate realizes
+
+# Application service linked to a motivation goal
+dr relationship add application.service.order-api motivation.goal.revenue --predicate supports
+
+# Data model schema linked to a data store collection (table)
+dr relationship add data-model.schemadefinition.order data-store.collection.orders --predicate maps-to
+```
+
+Cross-layer relationships are stored in `documentation-robotics/model/relationships.yaml`. Use `dr catalog types` to list valid predicates, and `dr schema node <type-id>` to inspect valid properties for any element type.
+
+## CLI Mandate
+
+**Always use CLI — never write YAML manually.** Manual YAML has 60%+ validation failure rate.
+
+```bash
+# ✅ correct
+dr add business service payment --name "Payment" --description "..."
+
+# ❌ wrong — bypasses validation, manifest not updated
+```
+
+If a CLI command fails with a parameter error: read the error → fix the command → retry. Never work around a CLI bug by writing files manually.
+
+## Proactive Behavior
+
+- After adding a critical service: suggest security policy and monitoring
+- After extraction: remind to review changeset diff before applying
+- After 5+ elements added to a layer without relationships: suggest `dr audit`
+- After validation errors: explain root cause, offer specific fixes
+- When confidence is low during extraction: flag it explicitly, ask for confirmation before applying

package/dist/integrations/claude_code/skills/dr_01_motivation_layer/SKILL.md

@@ -110,64 +110,85 @@ IS this a semantic definition, interpretation, or piece of knowledge attached to
 
 ## Intra-Layer Relationships
 
-### Structural Relationships
-
-| Source Type | Predicate   | Target Type | Example                                                      |
-| ----------- | ----------- | ----------- | ------------------------------------------------------------ |
-| Goal        | aggregates  | Goal        | Strategic Goal aggregates Operational Goals                  |
-| Requirement | aggregates  | Requirement | Business Requirement aggregates Functional Requirements      |
-| Principle   | aggregates  | Principle   | Enterprise Principles aggregate Domain Principles            |
-| Constraint  | aggregates  | Constraint  | Budget Constraint aggregates Project Budget Constraints      |
-| Outcome     | realizes    | Goal        | "Launched Mobile App" realizes "Launch Mobile App by Q4"     |
-| Goal        | realizes    | Value       | "Improve Customer Satisfaction" realizes "Customer Value"    |
-| Requirement | realizes    | Goal        | Functional Requirements realize Business Goals               |
-| Requirement | realizes    | Principle   | Technical Requirements realize Security Principles           |
-| Constraint  | realizes    | Principle   | Technology Constraints realize Technology Principles         |
-| Goal        | specializes | Goal        | "Reduce API Latency" specializes "Improve Performance"       |
-| Requirement | specializes | Requirement | "95% Uptime SLA" specializes "High Availability Requirement" |
-| Principle   | specializes | Principle   | "Encrypt All PII" specializes "Data Security Principle"      |
-| Value       | specializes | Value       | "Customer Retention Value" specializes "Customer Value"      |
-
-### Behavioral Relationships
-
-| Source Type | Predicate       | Target Type | Example                                                                 |
-| ----------- | --------------- | ----------- | ----------------------------------------------------------------------- |
-| Driver      | influences      | Goal        | "Digital Transformation" influences "Modernize Architecture"            |
-| Driver      | influences      | Requirement | "GDPR Compliance" influences "Data Protection Requirements"             |
-| Driver      | influences      | Principle   | "Cloud-First Strategy" influences "Cloud-Native Principles"             |
-| Assessment  | influences      | Goal        | "Legacy System Weakness" influences "Modernization Goal"                |
-| Goal        | influences      | Requirement | Business Goals influence Functional Requirements                        |
-| Principle   | influences      | Requirement | Security Principles influence Technical Requirements                    |
-| Principle   | influences      | Constraint  | "API-First Principle" influences "RESTful API Constraint"               |
-| Constraint  | influences      | Requirement | Budget Constraints influence Implementation Requirements                |
-| Value       | influences      | Goal        | "Customer Value" influences "Improve UX Goal"                           |
-| Stakeholder | influences      | Goal        | "CEO" influences Strategic Goals                                        |
-| Stakeholder | influences      | Requirement | "End Users" influence Functional Requirements                           |
-| Stakeholder | influences      | Value       | "Shareholders" influence Financial Value                                |
-| Stakeholder | associated-with | Driver      | "Product Manager" associated with "Market Competition Driver"           |
-| Goal        | associated-with | Outcome     | "Improve Performance" associated with "Achieved 50ms Latency"           |
-| Requirement | associated-with | Outcome     | "High Availability Requirement" associated with "99.99% Uptime Outcome" |
-| Driver      | associated-with | Assessment  | "Market Driver" associated with "Competitive Threat Assessment"         |
-| Value       | associated-with | Meaning     | "Customer Value" associated with "Definition of Customer Success"       |
+Note that the ArchiMate influence predicate is spelled `influence` (not `influences`).
+
+### Realization and Decomposition
+
+Requirements realize the outcomes, goals and principles they make concrete, and outcomes realize
+goals. Decomposition is same-type only: `aggregates` for parts, `specializes` for variants.
+
+| Source Type | Predicate   | Target Type | Example                                                             |
+| ----------- | ----------- | ----------- | ------------------------------------------------------------------- |
+| Requirement | realizes    | Goal        | "API must respond in <200ms" realizes "Improve Performance"         |
+| Requirement | realizes    | Outcome     | "99.99% availability" realizes "Downtime Under 1h per Quarter"      |
+| Requirement | realizes    | Principle   | "Orders API uses OAuth 2.0" realizes "Security by Design"           |
+| Outcome     | realizes    | Goal        | "Churn Reduced 10%" realizes "Improve Customer Satisfaction"        |
+| Goal        | aggregates  | Goal        | "Improve Customer Satisfaction" aggregates "Reduce Response Time"   |
+| Requirement | aggregates  | Requirement | "Secure User Data" requirement aggregates "Encrypt Data in Transit" |
+| Outcome     | aggregates  | Outcome     | "Global NPS 50" aggregates "EU NPS 50"                              |
+| Stakeholder | aggregates  | Stakeholder | "Finance" aggregates "Accounts Payable Team"                        |
+| Value       | aggregates  | Value       | "Lower Total Cost" aggregates "Lower Licence Cost"                  |
+| Goal        | specializes | Goal        | "Reduce API Latency" specializes "Improve Performance"              |
+| Requirement | specializes | Requirement | "99.95% Uptime SLA" specializes "High Availability Requirement"     |
+| Constraint  | specializes | Constraint  | "EU-only Data Residency" specializes "Data Residency Constraint"    |
+| Constraint  | constrains  | Requirement | "Must use OAuth 2.0" constrains "User Authentication"               |
+
+### Influence and Association Relationships
+
+`influence` is one motivation element shaping another. `associated-with` is kept for concerns
+(stakeholders, assessments evaluating drivers) and interpretation: meaning and value are associated
+with any concept and are always the source.
+
+| Source Type | Predicate       | Target Type | Example                                                               |
+| ----------- | --------------- | ----------- | --------------------------------------------------------------------- |
+| Stakeholder | influence       | Goal        | "CEO" influences "Reduce Operating Costs by 20%"                      |
+| Driver      | influence       | Goal        | "Digital Transformation" influences "Modernize Architecture"          |
+| Driver      | influence       | Requirement | "GDPR Regulation" influences "Right to Deletion"                      |
+| Driver      | influence       | Principle   | "Cloud-First Strategy" influences "Cloud-Native Architecture"         |
+| Driver      | influence       | Constraint  | "GDPR Regulation" influences "EU-only Data Residency"                 |
+| Assessment  | influence       | Goal        | "Legacy System Debt" influences "Modernize Architecture"              |
+| Assessment  | influence       | Requirement | "Slow Checkout Weakness" influences "Checkout must complete in <2s"   |
+| Assessment  | influence       | Outcome     | "Checkout p95 is 4s" influences "Checkout p95 Under 2s by Q3"         |
+| Goal        | influence       | Requirement | "Improve Security" influences "Enforce MFA for Admins"                |
+| Goal        | influence       | Principle   | "Modernize Architecture" influences "Cloud-Native Architecture"       |
+| Principle   | influence       | Requirement | "API-First Design" influences "Every Feature Exposes an API"          |
+| Constraint  | influence       | Goal        | "Fixed Q4 Budget" influences "Launch Mobile App by Q4"                |
+| Stakeholder | associated-with | Driver      | "Head of Compliance" associated with "GDPR Regulation"                |
+| Stakeholder | associated-with | Requirement | "End Users" associated with "Offline Mode Support"                    |
+| Assessment  | associated-with | Driver      | "GDPR Gap Analysis" associated with "GDPR Regulation"                 |
+| Value       | associated-with | Stakeholder | "Customer Loyalty" associated with "Customers"                        |
+| Value       | associated-with | Goal        | "Customer Loyalty" associated with "Improve Customer Satisfaction"    |
+| Value       | associated-with | Driver      | "Faster Time to Market" associated with "Market Competition"          |
+| Meaning     | associated-with | Value       | "Definition of Customer Success" associated with "Customer Loyalty"   |
+| Meaning     | associated-with | Requirement | "Definition of Session" associated with "Sessions Expire After 15min" |
 
 ---
 
 ## Cross-Layer References
 
-**Motivation Layer is the highest layer** - It does **NOT reference any lower layers**. Instead, lower layers reference UP to this layer for governance.
-
-### Incoming References (Lower Layers → Motivation)
-
-| Layer                     | References Motivation For                                                                                                         |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| **Layer 2 (Business)**    | BusinessService delivers Value, supports Goals, governed by Principles; BusinessActor is Stakeholder; Contract drives Constraints |
-| **Layer 3 (Security)**    | Actor references Stakeholder; ActorObjective references Goal; Threat references Assessment; Countermeasure implements Requirement |
-| **Layer 4 (Application)** | ApplicationService supports Goals, delivers Value, governed by Principles; ApplicationFunction fulfills Requirements              |
-| **Layer 5 (Technology)**  | TechnologyService supports Goals, governed by Principles; Node fulfills Requirements, constrained by Constraints                  |
-| **Layer 6 (API)**         | Operation supports Goals (x-supports-goals), fulfills Requirements, governed by Principles, constrained by Constraints            |
-| **Layer 7-13**            | All layers can reference Principles, Constraints, Requirements, Goals for governance and traceability                             |
-
-**Design Pattern:** Lower layers "look up" to the Motivation layer to justify WHY they exist and WHAT value they deliver.
+**Motivation Layer is the root of traceability.** The catalog defines no outgoing references from Motivation; elements in other layers point to motivation elements to justify WHY they exist and WHAT value they deliver.
+
+### Incoming References (Other Layers → Motivation)
+
+| Source Type                       | Predicate        | Target Type | Example                                                             |
+| --------------------------------- | ---------------- | ----------- | ------------------------------------------------------------------- |
+| `business.businessservice`        | realizes         | Goal        | "Online Ordering" realizes "Grow Digital Revenue"                   |
+| `business.businessservice`        | delivers         | Value       | "Same-Day Delivery" delivers "Customer Convenience"                 |
+| `business.businessprocess`        | satisfies        | Requirement | "Refund Processing" satisfies "Refunds Issued Within 5 Days"        |
+| `business.businessactor`          | references       | Stakeholder | "Customer" actor references "Customers" stakeholder                 |
+| `product.softwarecapability`      | supports         | Goal        | "Self-Service Returns" supports "Reduce Support Costs"              |
+| `product.feature`                 | satisfies        | Requirement | "Two-Factor Login" satisfies "Enforce MFA for Admins"               |
+| `product.persona`                 | references       | Stakeholder | "Busy Parent Persona" references "Retail Customers"                 |
+| `product.userworkflow`            | delivers         | Outcome     | "Checkout Flow" delivers "Cart Abandonment Reduced 15%"             |
+| `security.securitypolicy`         | satisfies        | Principle   | "Encryption Policy" satisfies "Security by Design"                  |
+| `security.countermeasure`         | satisfies        | Requirement | "Rate Limiting" satisfies "Prevent Credential Stuffing"             |
+| `application.applicationservice`  | realizes         | Goal        | "Recommendation Service" realizes "Increase Average Order Value"    |
+| `application.applicationfunction` | satisfies        | Requirement | "Audit Logging" satisfies "Log All Admin Actions"                   |
+| `technology.systemsoftware`       | satisfies        | Constraint  | "PostgreSQL 15" satisfies "Approved Open-Source Databases Only"     |
+| `api.operation`                   | satisfies        | Requirement | "POST /orders" satisfies "Orders Accepted via Public API"           |
+| `data-store.retentionpolicy`      | satisfies        | Constraint  | "Purge PII After 30 Days" satisfies "GDPR Data Minimization"        |
+| `apm.metricinstrument`            | measures-outcome | Outcome     | "checkout.duration" metric measures "Checkout Under 2s Outcome"     |
+| `testing.testcoveragemodel`       | satisfies        | Requirement | "Checkout Coverage Model" satisfies "Checkout must complete in <2s" |
 
 ---
 
@@ -347,23 +368,23 @@ Connect motivation elements using predicates:
 ```bash
 # Driver influences Goal
 dr relationship add motivation.driver.cloud-migration-pressure \
-  motivation.goal.modernize-architecture --predicate influences
+  motivation.goal.modernize-architecture --predicate influence
 
-# Goal realizes Value
-dr relationship add motivation.goal.modernize-architecture \
-  motivation.value.operational-efficiency --predicate realizes
+# Value associated with Goal (meaning and value are the source)
+dr relationship add motivation.value.operational-efficiency \
+  motivation.goal.modernize-architecture --predicate associated-with
 
 # Principle influences Requirement
 dr relationship add motivation.principle.api-first-design \
-  motivation.requirement.api-authentication --predicate influences
+  motivation.requirement.api-authentication --predicate influence
 
 # Stakeholder influences Goal
 dr relationship add motivation.stakeholder.product-manager \
-  motivation.goal.modernize-architecture --predicate influences
+  motivation.goal.modernize-architecture --predicate influence
 
 # Assessment influences Goal
 dr relationship add motivation.assessment.legacy-system-debt \
-  motivation.goal.modernize-architecture --predicate influences
+  motivation.goal.modernize-architecture --predicate influence
 ```
 
 ### Step 6: Validate
@@ -394,30 +415,29 @@ Strategic Goal: "Improve Customer Satisfaction"
 ```
 Business Requirement: "Secure User Data"
 ├── aggregates → Functional Requirement: "Encrypt Data at Rest"
-│   └── influences → Technical Requirement: "Use AES-256 Encryption"
+│   └── aggregates → Technical Requirement: "Use AES-256 Encryption"
 ├── aggregates → Functional Requirement: "Encrypt Data in Transit"
-│   └── influences → Technical Requirement: "Use TLS 1.3"
+│   └── aggregates → Technical Requirement: "Use TLS 1.3"
 └── aggregates → Compliance Requirement: "GDPR Data Protection"
-    └── influences → Technical Requirement: "Right to Deletion API"
+    └── aggregates → Technical Requirement: "Right to Deletion API"
 ```
 
 ### Pattern 3: Principle Application
 
 ```
 Principle: "Cloud-Native Architecture"
-├── influences → Requirement: "Containerized Deployments"
-├── influences → Requirement: "Stateless Services"
-├── influences → Constraint: "No On-Premise Infrastructure"
-└── realizes → Value: "Scalability and Resilience"
+├── influence → Requirement: "Containerized Deployments"
+├── influence → Requirement: "Stateless Services"
+└── associated-with → Value: "Scalability and Resilience"
 ```
 
 ### Pattern 4: Stakeholder → Goal → Implementation Chain
 
 ```
 Stakeholder: "CEO"
-└── influences → Goal: "Reduce Operating Costs by 20%"
-    ├── influences → Requirement: "Automated CI/CD Pipeline"
-    ├── influences → Principle: "Infrastructure as Code"
+└── influence → Goal: "Reduce Operating Costs by 20%"
+    ├── influence → Requirement: "Automated CI/CD Pipeline"
+    ├── influence → Principle: "Infrastructure as Code"
     └── realizes → Value: "Financial Efficiency"
         └── (lower layers reference this chain)
 ```
@@ -487,7 +507,7 @@ dr export archimate --layers motivation --output motivation.archimate
 
 **Supported Relationships:**
 
-- `aggregates`, `realizes`, `specializes`, `influences`, `associated-with`
+- `aggregates`, `realizes`, `specializes`, `influence`, `associated-with`
 
 ---
 
@@ -535,10 +555,11 @@ dr add motivation constraint <name> --description <description>
 **Relationship Commands:**
 
 ```bash
-dr relationship add <source-id> <target-id> --predicate influences
+dr relationship add <source-id> <target-id> --predicate influence
 dr relationship add <source-id> <target-id> --predicate aggregates
 dr relationship add <source-id> <target-id> --predicate realizes
 dr relationship add <source-id> <target-id> --predicate specializes
+dr relationship add <source-id> <target-id> --predicate associated-with
 ```
 
 **Query Commands:**