Complete REUSE-WP-0003: registry CLI, docs alignment, and coverage

Align INTENT.md with delivered layout, add CapabilityRegistryConcept guide,
extend schema with promotion_history, ship reuse-surface validate/query/export
CLI, register three more helix_forge capabilities, and refresh SCOPE and gap
analysis to reflect A3 tooling and D5/A3/C4/R2 self-assessment.

docs/CapabilityRegistryConcept.md

@@ -0,0 +1,129 @@
+# Capability Registry Concept
+
+**Repository:** `reuse-surface`  
+**Audience:** Humans onboarding to the registry  
+**Companion docs:** `INTENT.md`, `SCOPE.md`, `specs/CapabilityMaturityStandard.md`
+
+---
+
+## 1. What problem this solves
+
+Reusable capabilities are often scattered across repositories, documents,
+prototypes, and services. Without a registry, teams and agents rediscover,
+duplicate, and inconsistently assess the same behaviors.
+
+`reuse-surface` makes capabilities **visible**, **comparable**, and **reusable**
+for planning and implementation through a registry-first reuse layer.
+
+> A capability that is not registered is invisible for registry-driven reuse.
+
+---
+
+## 2. Core principles
+
+### Registry first
+
+The registry is the boundary of practical reuse awareness. Analysis starts with
+what is registered, not with everything that might exist informally.
+
+### Reuse over inventory
+
+The goal is capability reuse, not a complete inventory of all work products.
+
+### Planning and implementation are different
+
+- **Planning reuse** feeds primarily on **Discovery** maturity (D0–D7).
+- **Implementation reuse** feeds primarily on **Availability** maturity (A0–A7).
+
+A capability may be well researched (D5) but only informational (A0). Another
+may be deployable (A4) but weakly bounded (D2). Compare both dimensions.
+
+### Internal and external evidence stay separate
+
+| Type | Dimensions | Question |
+|---|---|---|
+| Internal registry assessment | Discovery, Availability | How reusable is it for planning? How consumable is it? |
+| External consumer evidence | Completeness, Reliability | Does scope satisfy intent? Does it behave well in use? |
+
+Do not treat availability as reliability, or research depth as completeness.
+
+---
+
+## 3. Maturity vector
+
+A compact summary:
+
+```text
+D5 / A4 / C3 / R3
+```
+
+Vectors are descriptive, not grades. A research vocabulary capability may
+naturally target `D5 / A0 / C4 / R3`. A CLI tool may target `D5 / A3 / C5 / R5`.
+
+Canonical level definitions: `specs/CapabilityMaturityStandard.md`.
+
+---
+
+## 4. How the artifacts fit together
+
+```text
+templates/capability-entry.template.md   → authoring starting point
+registry/capabilities/*.md               → canonical entries (YAML front matter)
+registry/indexes/capabilities.yaml       → fast discovery index for agents
+schemas/capability.schema.yaml           → machine-readable entry contract
+registry/README.md                       → validation and search guidance
+tools/                                   → CLI validate, query, export
+```
+
+**Authoring flow**
+
+1. Search the index for overlap.
+2. Copy the template to `registry/capabilities/`.
+3. Fill maturity and evidence fields explicitly.
+4. Add an index row.
+5. Validate with `reuse-surface validate`.
+
+**Consumption flow**
+
+1. Read `registry/indexes/capabilities.yaml`.
+2. Filter by vector, tags, or consumption mode.
+3. Open candidate entry files for scope, relations, and guidance.
+4. Prefer planning reuse at D3+ and implementation reuse at A2+.
+
+---
+
+## 5. What is manual vs automated today
+
+See `SCOPE.md` for the live boundary. In summary:
+
+| Activity | Mode |
+|---|---|
+| Discover capabilities | Index + `reuse-surface query` |
+| Add or promote entries | Markdown authoring + index update |
+| Validate shape | `reuse-surface validate` |
+| Export for agents | `reuse-surface export` |
+| Promotion history | Optional `promotion_history` in entries |
+| Graph visualization, federation, CI gates | Not yet available |
+
+---
+
+## 6. When to register a capability
+
+Register when a bounded reusable behavior should be:
+
+- discoverable for roadmap or architecture planning
+- comparable to adjacent capabilities
+- consumable through known artifacts (now or later)
+- assessed with explicit evidence over time
+
+Do not register one-off features, tickets, or internal code modules unless they
+represent a reusable capability boundary.
+
+---
+
+## 7. Further reading
+
+- Product requirements: `specs/ProductRequirementsDocument.md`
+- Use cases: `specs/UseCaseCatalog.md`
+- Intent vs delivered scope: `docs/IntentScopeGapAnalysis.md`
+- Agent workflows: `AGENTS.md`