diff --git a/specs/UseCaseCatalog.md b/specs/UseCaseCatalog.md
new file mode 100755
index 0000000..2ab251a
--- /dev/null
+++ b/specs/UseCaseCatalog.md
@@ -0,0 +1,935 @@
+# UseCaseCatalog.md — reuse-surface
+
+## 1. Purpose
+
+This Use Case Catalog captures the primary use cases for `reuse-surface`, a capability registry and reuse assessment surface.
+
+`reuse-surface` exists to make capabilities visible, comparable, reusable, and assessable across planning, implementation, operation, and product evolution. A capability that is not represented in the registry is considered invisible for reuse within the scope of this product.
+
+The catalog is designed for human and agentic consumers. It supports product planning, architecture work, implementation selection, capability governance, and evidence-based reuse decisions.
+
+## 2. Scope
+
+### 2.1 In Scope
+
+`reuse-surface` supports the following capability registry functions:
+
+- Register capabilities and their metadata.
+- Assess internal maturity through Discovery and Availability.
+- Expose external consumer-derived evidence through Completeness and Reliability.
+- Support planning reuse based on capability Discovery maturity.
+- Support implementation reuse based on capability Availability maturity.
+- Help consumers find, compare, select, and reuse capabilities.
+- Track INTENT, SCOPE, expectation satisfaction, and expectation breaks.
+- Track quality signals such as bugs, support issues, star ratings, operational evidence, and consumer feedback.
+- Provide registry information in forms usable by humans, CLIs, automation, and agents.
+
+### 2.2 Out of Scope
+
+`reuse-surface` does not itself implement the registered capabilities.
+
+It does not replace:
+
+- Source code repositories.
+- Package registries.
+- Service catalogs.
+- Observability platforms.
+- Issue trackers.
+- Product management systems.
+- Architecture decision records.
+
+Instead, it references, aggregates, and interprets evidence from those sources where useful.
+
+## 3. Actors
+
+| Actor | Description |
+|---|---|
+| Product Planner | Uses capabilities to structure product ideas, roadmaps, MVPs, and enhancements. |
+| Architect | Uses the registry to reason about capability boundaries, dependencies, alternatives, and reuse potential. |
+| Implementer | Looks for reusable source modules, CLIs, SDKs, services, or platform capabilities. |
+| Agentic Coding Agent | Uses registry metadata to find relevant capabilities and avoid unnecessary reinvention. |
+| Capability Owner | Maintains capability entries, maturity levels, scope, evidence, and links. |
+| Platform Owner | Manages shared capabilities and decides which capabilities should become platform services. |
+| Product Owner | Assesses whether capability SCOPE satisfies declared INTENT and consumer expectations. |
+| Consumer | Uses a capability through documentation, code, package, CLI, SDK, service, platform interface, or cloud offering. |
+| Reviewer | Checks registry entries for consistency, evidence quality, and maturity claims. |
+| Governance Maintainer | Maintains standards, schemas, scoring rules, and registry quality expectations. |
+
+## 4. Capability Maturity Dimensions
+
+The registry uses four primary dimensions.
+
+| Dimension | Type | Purpose |
+|---|---|---|
+| Discovery | Internal maturity | How reusable the capability is for planning, orientation, comparison, roadmap design, and architectural reasoning. |
+| Availability | Internal maturity | How the capability can be consumed by implementation or operational consumers. |
+| Completeness | External evidence | How well current SCOPE satisfies declared INTENT and consumer expectations. |
+| Reliability | External evidence | How consistently the capability satisfies consumer-relevant quality expectations. |
+
+Canonical short form:
+
+```text
+D5 / A4 / C3 / R3
+```
+
+This means:
+
+- Discovery: Grounded
+- Availability: Service API / SDK
+- Completeness: Functional Core
+- Reliability: Usable
+
+## 5. Use Case Scoring Dimensions
+
+Each use case may be scored with the following dimensions.
+
+| Dimension | Scale | Meaning |
+|---|---:|---|
+| Planning Value | 0–2 | How strongly the use case supports planning reuse. |
+| Implementation Value | 0–2 | How strongly the use case supports implementation reuse. |
+| Governance Value | 0–2 | How strongly the use case supports registry quality, ownership, and decision discipline. |
+| MVP Relevance | 0–2 | Whether the use case should be included early. |
+| Complexity | 0–2 | Expected effort or conceptual complexity. 0 = low, 2 = high. |
+| Automation Potential | 0–2 | How suitable the use case is for CLI, API, or agentic automation. |
+
+Suggested interpretation:
+
+```text
+0 = low / not relevant / not needed yet
+1 = useful / medium / later candidate
+2 = high / central / early priority
+```
+
+## 6. Use Case Index
+
+| ID | Title | Primary Actor | Planning Value | Implementation Value | MVP Relevance |
+|---|---|---|---:|---:|---:|
+| UC-RS-001 | Register a New Capability | Capability Owner | 2 | 1 | 2 |
+| UC-RS-002 | Classify Capability Discovery Maturity | Capability Owner | 2 | 0 | 2 |
+| UC-RS-003 | Classify Capability Availability | Capability Owner | 1 | 2 | 2 |
+| UC-RS-004 | Search for Capabilities by Planning Need | Product Planner | 2 | 0 | 2 |
+| UC-RS-005 | Search for Capabilities by Consumption Mode | Implementer | 0 | 2 | 2 |
+| UC-RS-006 | Compare Capability Candidates | Architect | 2 | 2 | 2 |
+| UC-RS-007 | Identify Reuse Gaps for MVP Planning | Product Planner | 2 | 1 | 2 |
+| UC-RS-008 | Track SCOPE vs INTENT Completeness | Product Owner | 2 | 1 | 1 |
+| UC-RS-009 | Track Reliability Evidence | Capability Owner | 1 | 2 | 1 |
+| UC-RS-010 | Record Broken Consumer Expectations | Consumer | 2 | 1 | 1 |
+| UC-RS-011 | Promote a Capability to Higher Discovery Maturity | Capability Owner | 2 | 0 | 1 |
+| UC-RS-012 | Promote a Capability to Higher Availability | Implementer | 0 | 2 | 1 |
+| UC-RS-013 | Use Registry Metadata in Agentic Coding | Agentic Coding Agent | 1 | 2 | 2 |
+| UC-RS-014 | Generate Capability Reuse Recommendations | Architect | 2 | 2 | 1 |
+| UC-RS-015 | Detect Duplicate or Overlapping Capabilities | Governance Maintainer | 2 | 1 | 1 |
+| UC-RS-016 | Maintain Capability Relations | Architect | 2 | 2 | 1 |
+| UC-RS-017 | Review Capability Entry Quality | Reviewer | 1 | 1 | 1 |
+| UC-RS-018 | Publish a Human-Readable Capability Catalog | Platform Owner | 2 | 1 | 1 |
+| UC-RS-019 | Publish a Machine-Readable Registry Export | Agentic Coding Agent | 1 | 2 | 2 |
+| UC-RS-020 | Select Capabilities for Platformization | Platform Owner | 2 | 2 | 1 |
+| UC-RS-021 | Identify Capabilities Ready for Commercial Offering | Product Owner | 2 | 2 | 0 |
+| UC-RS-022 | Track Capability Evolution Over Time | Capability Owner | 2 | 1 | 1 |
+| UC-RS-023 | Validate Registry Entries Against Schema | Governance Maintainer | 1 | 2 | 2 |
+| UC-RS-024 | Produce Capability Maturity Reports | Governance Maintainer | 2 | 1 | 1 |
+
+## 7. Use Cases
+
+### UC-RS-001 — Register a New Capability
+
+**Primary Actor:** Capability Owner  
+**Supporting Actors:** Architect, Reviewer, Agentic Coding Agent
+
+#### Intent
+
+Create a new visible capability entry in the registry so the capability can be considered for reuse.
+
+#### Trigger
+
+A person or agent identifies a capability candidate that should be made visible for planning or implementation reuse.
+
+#### Preconditions
+
+- The registry exists.
+- The capability candidate has at least a name and rough summary.
+
+#### Main Flow
+
+1. Actor creates a new capability entry.
+2. Actor assigns a stable capability ID.
+3. Actor provides name, summary, owner, and initial maturity values.
+4. Actor links available evidence, if any.
+5. Registry validates required fields.
+6. Registry stores the capability entry.
+
+#### Acceptance Criteria
+
+- The capability has a unique ID.
+- The capability is findable by name and summary.
+- The capability has initial Discovery, Availability, Completeness, and Reliability values.
+- Missing evidence is represented explicitly rather than hidden.
+
+#### Scoring
+
+| Dimension | Score |
+|---|---:|
+| Planning Value | 2 |
+| Implementation Value | 1 |
+| Governance Value | 2 |
+| MVP Relevance | 2 |
+| Complexity | 1 |
+| Automation Potential | 2 |
+
+---
+
+### UC-RS-002 — Classify Capability Discovery Maturity
+
+**Primary Actor:** Capability Owner  
+**Supporting Actors:** Product Planner, Architect, Reviewer
+
+#### Intent
+
+Assess how reusable a capability is for planning.
+
+#### Trigger
+
+A capability is created, reviewed, promoted, or prepared for roadmap use.
+
+#### Main Flow
+
+1. Actor reviews capability documentation.
+2. Actor checks evidence against Discovery levels D0–D7.
+3. Actor selects the highest defensible level.
+4. Actor records rationale and supporting evidence.
+5. Reviewer validates the classification if required.
+
+#### Acceptance Criteria
+
+- Discovery level is assigned using the standard definitions.
+- Evidence supports the selected level.
+- Missing evidence is visible.
+- Promotion rationale is documented.
+
+#### Discovery Levels
+
+| Level | Name |
+|---|---|
+| D0 | Named |
+| D1 | Described |
+| D2 | Bounded |
+| D3 | Explored |
+| D4 | Researched |
+| D5 | Grounded |
+| D6 | Exhaustive |
+| D7 | Generalized |
+
+---
+
+### UC-RS-003 — Classify Capability Availability
+
+**Primary Actor:** Capability Owner  
+**Supporting Actors:** Implementer, Platform Owner, Reviewer
+
+#### Intent
+
+Assess how directly consumers can consume a capability for implementation or operation.
+
+#### Trigger
+
+A new artifact becomes available: prototype, source module, CLI, SDK, service, container, managed platform service, or cloud offering.
+
+#### Main Flow
+
+1. Actor reviews available artifacts.
+2. Actor checks evidence against Availability levels A0–A7.
+3. Actor selects current and target availability levels.
+4. Actor links artifacts and access instructions.
+5. Registry exposes the availability to consumers.
+
+#### Acceptance Criteria
+
+- Current Availability level is clear.
+- Target Availability level may be stated separately.
+- Consumption mode is visible.
+- Consumers can find the referenced artifact or understand that none exists yet.
+
+#### Availability Levels
+
+| Level | Name |
+|---|---|
+| A0 | Informational Only |
+| A1 | Experimental Prototype |
+| A2 | Source Module / Library |
+| A3 | Command-Line Package |
+| A4 | Service API / SDK |
+| A5 | Containerized Service |
+| A6 | Managed Platform Capability |
+| A7 | External Cloud Service Offering |
+
+---
+
+### UC-RS-004 — Search for Capabilities by Planning Need
+
+**Primary Actor:** Product Planner  
+**Supporting Actors:** Architect, Agentic Planning Agent
+
+#### Intent
+
+Find capabilities relevant to a product idea, roadmap theme, MVP candidate, or enhancement area.
+
+#### Main Flow
+
+1. Actor enters a planning need or topic.
+2. Registry searches names, summaries, intents, use cases, and related capabilities.
+3. Registry returns candidate capabilities.
+4. Actor filters by Discovery maturity, domain, tags, and relations.
+5. Actor selects capabilities for planning reuse.
+
+#### Acceptance Criteria
+
+- Results include maturity vectors.
+- Results distinguish planning-ready and weakly described capabilities.
+- Results show related capabilities and known gaps.
+
+#### Example
+
+Search:
+
+```text
+multi-tenant feature control for agents and users
+```
+
+Possible result:
+
+```text
+capability.feature-control.evaluate — D5 / A4 / C3 / R3
+```
+
+---
+
+### UC-RS-005 — Search for Capabilities by Consumption Mode
+
+**Primary Actor:** Implementer  
+**Supporting Actors:** Agentic Coding Agent
+
+#### Intent
+
+Find capabilities available in a usable form for implementation.
+
+#### Main Flow
+
+1. Actor specifies desired consumption mode.
+2. Registry filters by Availability level.
+3. Actor reviews available artifacts.
+4. Actor selects suitable capability for implementation reuse.
+
+#### Example Filters
+
+```yaml
+availability:
+  minimum: A3
+consumption_modes:
+  - cli
+  - sdk
+  - service-api
+```
+
+#### Acceptance Criteria
+
+- Results distinguish informational entries from consumable artifacts.
+- Artifacts include links or paths.
+- Limitations and reliability evidence are visible.
+
+---
+
+### UC-RS-006 — Compare Capability Candidates
+
+**Primary Actor:** Architect  
+**Supporting Actors:** Product Planner, Implementer
+
+#### Intent
+
+Compare several capabilities to decide whether to reuse, extend, merge, replace, or build new.
+
+#### Main Flow
+
+1. Actor selects two or more candidate capabilities.
+2. Registry displays maturity vectors, scope, availability, completeness, reliability, and relations.
+3. Actor reviews overlaps and differences.
+4. Actor records selection decision or follow-up action.
+
+#### Acceptance Criteria
+
+- Comparison exposes Discovery and Availability differences.
+- Completeness and Reliability are shown separately.
+- Duplicate and overlapping scope is visible.
+
+---
+
+### UC-RS-007 — Identify Reuse Gaps for MVP Planning
+
+**Primary Actor:** Product Planner  
+**Supporting Actors:** Architect, Capability Owner
+
+#### Intent
+
+Identify which capabilities are ready for MVP reuse and which require development, research, or clarification.
+
+#### Main Flow
+
+1. Actor selects an MVP concept or product theme.
+2. Registry maps related capabilities.
+3. Registry shows current maturity and target maturity.
+4. Actor identifies gaps.
+5. Actor exports capability work items or planning notes.
+
+#### Acceptance Criteria
+
+- Registry distinguishes planning gaps from implementation gaps.
+- D-level gaps and A-level gaps are visible separately.
+- Capabilities with low Completeness or Reliability are flagged.
+
+---
+
+### UC-RS-008 — Track SCOPE vs INTENT Completeness
+
+**Primary Actor:** Product Owner  
+**Supporting Actors:** Consumer, Capability Owner
+
+#### Intent
+
+Assess whether the current scope of a capability satisfies its declared intent and consumer expectations.
+
+#### Main Flow
+
+1. Actor reviews declared INTENT.
+2. Actor reviews current SCOPE.
+3. Actor reviews satisfied expectations, broken expectations, and out-of-scope expectations.
+4. Actor assigns Completeness level C0–C6.
+5. Actor records evidence and confidence.
+
+#### Acceptance Criteria
+
+- Completeness is based on INTENT, SCOPE, and consumer expectations.
+- Broken expectations are recorded.
+- Out-of-scope expectations are classified explicitly.
+
+#### Completeness Levels
+
+| Level | Name |
+|---|---|
+| C0 | Unknown |
+| C1 | Fragmentary |
+| C2 | Partial |
+| C3 | Functional Core |
+| C4 | Broadly Covered |
+| C5 | Expectation Complete |
+| C6 | Saturated |
+
+---
+
+### UC-RS-009 — Track Reliability Evidence
+
+**Primary Actor:** Capability Owner  
+**Supporting Actors:** Consumer, Platform Owner, Reviewer
+
+#### Intent
+
+Capture consumer-relevant quality evidence for a capability.
+
+#### Main Flow
+
+1. Actor collects quality evidence.
+2. Actor groups evidence by bugs, support feedback, operational evidence, consumer feedback, compatibility evidence, and integration evidence.
+3. Actor assigns Reliability level R0–R6.
+4. Registry exposes reliability risks and confidence.
+
+#### Acceptance Criteria
+
+- Reliability is assessed from consumer-relevant evidence.
+- Bugs, ratings, incidents, and support signals may contribute.
+- Reliability is not confused with Completeness.
+
+#### Reliability Levels
+
+| Level | Name |
+|---|---|
+| R0 | Unknown |
+| R1 | Fragile |
+| R2 | Tolerable |
+| R3 | Usable |
+| R4 | Dependable |
+| R5 | Trusted |
+| R6 | Proven |
+
+---
+
+### UC-RS-010 — Record Broken Consumer Expectations
+
+**Primary Actor:** Consumer  
+**Supporting Actors:** Product Owner, Capability Owner
+
+#### Intent
+
+Capture cases where consumers expected the capability to do something that it did not do.
+
+#### Main Flow
+
+1. Consumer reports a broken expectation.
+2. Registry links the expectation to a capability.
+3. Product Owner classifies the expectation as in-scope, out-of-scope, unclear, or future extension.
+4. Completeness evidence is updated.
+5. Follow-up work may be created.
+
+#### Acceptance Criteria
+
+- Broken expectation is preserved as evidence.
+- Classification is explicit.
+- Completeness level can be adjusted based on repeated patterns.
+
+---
+
+### UC-RS-011 — Promote a Capability to Higher Discovery Maturity
+
+**Primary Actor:** Capability Owner  
+**Supporting Actors:** Reviewer
+
+#### Intent
+
+Raise the Discovery maturity of a capability when sufficient evidence exists.
+
+#### Main Flow
+
+1. Actor identifies a target Discovery level.
+2. Actor checks required evidence.
+3. Actor adds missing documentation or links.
+4. Actor updates maturity level.
+5. Reviewer accepts or rejects promotion.
+
+#### Acceptance Criteria
+
+- Promotion has evidence.
+- The registry stores promotion history.
+- Review comments remain traceable.
+
+---
+
+### UC-RS-012 — Promote a Capability to Higher Availability
+
+**Primary Actor:** Implementer  
+**Supporting Actors:** Capability Owner, Platform Owner
+
+#### Intent
+
+Raise Availability maturity when a capability becomes consumable through a richer mode.
+
+#### Example Promotion Paths
+
+```text
+A0 → A1: add prototype
+A1 → A2: extract source module
+A2 → A3: publish CLI
+A3 → A4: expose API/SDK
+A4 → A5: package as containerized service
+A5 → A6: operate as managed platform capability
+A6 → A7: offer as external cloud service
+```
+
+#### Acceptance Criteria
+
+- Availability level matches actual consumer access.
+- Target and current availability may differ.
+- Consumers receive clear usage guidance.
+
+---
+
+### UC-RS-013 — Use Registry Metadata in Agentic Coding
+
+**Primary Actor:** Agentic Coding Agent  
+**Supporting Actors:** Implementer, Capability Owner
+
+#### Intent
+
+Allow coding agents to find existing capabilities before creating new code.
+
+#### Main Flow
+
+1. Agent receives a development task.
+2. Agent searches registry for relevant capabilities.
+3. Agent evaluates availability and reliability.
+4. Agent reuses an existing capability or explains why not.
+5. Agent may suggest updates to the registry.
+
+#### Acceptance Criteria
+
+- Machine-readable registry export exists.
+- Capability entries include enough metadata for automated selection.
+- Agent can distinguish reusable implementation from planning-only entries.
+
+---
+
+### UC-RS-014 — Generate Capability Reuse Recommendations
+
+**Primary Actor:** Architect  
+**Supporting Actors:** Agentic Planning Agent
+
+#### Intent
+
+Generate recommendations for which capabilities should be reused, improved, ignored, or created.
+
+#### Main Flow
+
+1. Actor provides project context.
+2. Registry finds candidate capabilities.
+3. Recommendation engine applies maturity, completeness, reliability, and relations.
+4. Registry outputs recommendations with rationale.
+
+#### Acceptance Criteria
+
+- Recommendations include evidence and uncertainty.
+- Recommendations do not treat maturity as quality alone.
+- Recommendations distinguish planning reuse from implementation reuse.
+
+---
+
+### UC-RS-015 — Detect Duplicate or Overlapping Capabilities
+
+**Primary Actor:** Governance Maintainer  
+**Supporting Actors:** Architect, Capability Owner
+
+#### Intent
+
+Find capabilities that may represent the same or overlapping reusable behavior.
+
+#### Main Flow
+
+1. Registry analyzes names, descriptions, scopes, relations, and use cases.
+2. Registry flags possible overlap.
+3. Maintainer reviews candidates.
+4. Maintainer merges, links, renames, or marks as distinct.
+
+#### Acceptance Criteria
+
+- Potential overlap is visible.
+- Distinct variants can coexist when justified.
+- Merged or deprecated capabilities remain traceable.
+
+---
+
+### UC-RS-016 — Maintain Capability Relations
+
+**Primary Actor:** Architect  
+**Supporting Actors:** Capability Owner
+
+#### Intent
+
+Maintain graph relations between capabilities.
+
+#### Relation Types
+
+```yaml
+relations:
+  depends_on: []
+  supports: []
+  replaces: []
+  replaced_by: []
+  specializes: []
+  generalizes: []
+  related_to: []
+  conflicts_with: []
+```
+
+#### Acceptance Criteria
+
+- Relations are typed.
+- Cycles are detected where relevant.
+- Dependency and reuse graphs can be generated.
+
+---
+
+### UC-RS-017 — Review Capability Entry Quality
+
+**Primary Actor:** Reviewer  
+**Supporting Actors:** Governance Maintainer, Capability Owner
+
+#### Intent
+
+Check whether a capability entry is clear, evidence-based, and useful for reuse.
+
+#### Main Flow
+
+1. Reviewer selects registry entry.
+2. Reviewer checks required fields and maturity claims.
+3. Reviewer comments on missing evidence, unclear scope, or poor naming.
+4. Capability Owner updates entry.
+5. Reviewer approves entry quality.
+
+#### Acceptance Criteria
+
+- Review history is traceable.
+- Registry supports status such as draft, reviewed, approved, deprecated.
+- Maturity claims can be challenged.
+
+---
+
+### UC-RS-018 — Publish a Human-Readable Capability Catalog
+
+**Primary Actor:** Platform Owner  
+**Supporting Actors:** Product Planner, Architect
+
+#### Intent
+
+Publish a browsable catalog for humans.
+
+#### Main Flow
+
+1. Actor selects registry scope.
+2. Registry renders catalog pages.
+3. Catalog groups capabilities by domain, maturity, availability, owner, and relations.
+4. Consumers browse and filter.
+
+#### Acceptance Criteria
+
+- Catalog is readable without knowing schema internals.
+- Maturity vectors are visible.
+- Consumers can navigate to evidence and artifacts.
+
+---
+
+### UC-RS-019 — Publish a Machine-Readable Registry Export
+
+**Primary Actor:** Agentic Coding Agent  
+**Supporting Actors:** Implementer, Governance Maintainer
+
+#### Intent
+
+Expose registry data for automation, agents, CLIs, and integration tools.
+
+#### Main Flow
+
+1. Registry validates entries.
+2. Registry exports JSON, YAML, or other supported machine-readable formats.
+3. Consumers fetch or import the export.
+4. Consumers use metadata for planning or implementation selection.
+
+#### Acceptance Criteria
+
+- Export format is documented.
+- Schema validation is available.
+- Entries include stable IDs and maturity fields.
+
+---
+
+### UC-RS-020 — Select Capabilities for Platformization
+
+**Primary Actor:** Platform Owner  
+**Supporting Actors:** Architect, Product Owner
+
+#### Intent
+
+Identify capabilities that should become shared platform capabilities.
+
+#### Main Flow
+
+1. Actor filters capabilities with high reuse potential.
+2. Actor reviews Discovery, Availability, Completeness, and Reliability.
+3. Actor checks known consumers and expected demand.
+4. Actor selects platformization candidates.
+5. Registry records target Availability, usually A5 or A6.
+
+#### Acceptance Criteria
+
+- Selection is evidence-based.
+- Target availability is explicit.
+- Capability gaps are visible before platformization begins.
+
+---
+
+### UC-RS-021 — Identify Capabilities Ready for Commercial Offering
+
+**Primary Actor:** Product Owner  
+**Supporting Actors:** Platform Owner, Architect
+
+#### Intent
+
+Find capabilities that may become external cloud service offerings or commercial API products.
+
+#### Main Flow
+
+1. Actor filters capabilities with high Discovery and high consumer value.
+2. Actor reviews Availability target A7.
+3. Actor checks Completeness and Reliability evidence.
+4. Actor identifies packaging, billing, support, and governance gaps.
+5. Actor records commercial offering candidate status.
+
+#### Acceptance Criteria
+
+- Commercial readiness is not inferred from implementation alone.
+- Completeness and Reliability are considered before externalization.
+- Missing support and governance requirements are visible.
+
+---
+
+### UC-RS-022 — Track Capability Evolution Over Time
+
+**Primary Actor:** Capability Owner  
+**Supporting Actors:** Governance Maintainer
+
+#### Intent
+
+Track how capability maturity, availability, completeness, and reliability change over time.
+
+#### Main Flow
+
+1. Registry stores maturity history.
+2. Actor records promotion, demotion, or evidence change.
+3. Registry can generate timeline or changelog.
+4. Consumers can inspect current and historical state.
+
+#### Acceptance Criteria
+
+- Maturity changes are timestamped.
+- Previous levels remain auditable.
+- Rationale and evidence links are preserved.
+
+---
+
+### UC-RS-023 — Validate Registry Entries Against Schema
+
+**Primary Actor:** Governance Maintainer  
+**Supporting Actors:** Agentic Coding Agent
+
+#### Intent
+
+Ensure registry entries conform to expected structure.
+
+#### Main Flow
+
+1. Actor runs validation.
+2. Registry schema checks required fields, enum values, relation references, and evidence structure.
+3. Validation reports errors and warnings.
+4. Actor or agent repairs entries.
+
+#### Acceptance Criteria
+
+- Invalid maturity values are rejected.
+- Broken relation references are detected.
+- Required registry fields are enforced.
+
+---
+
+### UC-RS-024 — Produce Capability Maturity Reports
+
+**Primary Actor:** Governance Maintainer  
+**Supporting Actors:** Product Planner, Platform Owner
+
+#### Intent
+
+Generate reports that summarize registry maturity and reuse readiness.
+
+#### Main Flow
+
+1. Actor selects reporting scope.
+2. Registry aggregates capability maturity vectors.
+3. Registry identifies strong, weak, missing, overlapping, and high-potential capabilities.
+4. Report is exported as Markdown, JSON, or dashboard data.
+
+#### Acceptance Criteria
+
+- Reports distinguish internal maturity and external evidence.
+- Reports identify planning-ready and implementation-ready capabilities separately.
+- Reports can guide roadmap and platform decisions.
+
+## 8. MVP Use Cases
+
+The initial MVP should prioritize use cases that establish the registry as a useful reuse surface.
+
+Recommended MVP set:
+
+| ID | Title | Reason |
+|---|---|---|
+| UC-RS-001 | Register a New Capability | Core registry function. |
+| UC-RS-002 | Classify Capability Discovery Maturity | Enables planning reuse. |
+| UC-RS-003 | Classify Capability Availability | Enables implementation reuse. |
+| UC-RS-004 | Search for Capabilities by Planning Need | Makes registry useful to planners. |
+| UC-RS-005 | Search for Capabilities by Consumption Mode | Makes registry useful to implementers. |
+| UC-RS-006 | Compare Capability Candidates | Enables reuse decision-making. |
+| UC-RS-013 | Use Registry Metadata in Agentic Coding | Supports agentic development workflows. |
+| UC-RS-019 | Publish a Machine-Readable Registry Export | Enables automation and integration. |
+| UC-RS-023 | Validate Registry Entries Against Schema | Keeps registry data usable. |
+
+## 9. Suggested Capability Entry Skeleton
+
+```yaml
+id: capability.example
+name: Example Capability
+summary: A short explanation of what the capability enables.
+owner: team-or-person
+status: draft
+
+maturity:
+  discovery:
+    current: D1
+    target: D5
+  availability:
+    current: A0
+    target: A3
+
+external_evidence:
+  completeness:
+    level: C0
+    confidence: low
+    satisfied_expectations: []
+    broken_expectations: []
+    out_of_scope_expectations: []
+  reliability:
+    level: R0
+    confidence: low
+    evidence: []
+
+intent:
+  statement: >
+    Explain what this capability is intended to make possible.
+
+scope:
+  includes: []
+  excludes: []
+  assumptions: []
+
+availability:
+  current_artifacts: []
+  target_artifacts: []
+  consumption_modes: []
+
+relations:
+  depends_on: []
+  supports: []
+  related_to: []
+
+use_cases: []
+
+evidence:
+  research_memos: []
+  design_notes: []
+  implementation_refs: []
+  issue_refs: []
+  feedback_refs: []
+```
+
+## 10. Open Questions
+
+- Should `reuse-surface` store registry entries as individual Markdown files, YAML files, JSON documents, or a hybrid format?
+- Should human-readable Markdown be generated from canonical YAML/JSON, or should Markdown with frontmatter be canonical?
+- How strict should maturity promotion review be in early repo usage?
+- Should the registry support multiple scopes, such as personal, company, platform, product, and public ecosystem?
+- Should external evidence be manually curated first and automated later, or should issue/star/usage connectors be part of the early design?
+- Should relation graphs be represented directly in registry files or derived during validation?
+
+## 11. Success Criteria
+
+`reuse-surface` succeeds when:
+
+- Planners can find capabilities relevant to roadmap and MVP work.
+- Implementers can find capabilities available for reuse.
+- Agents can use registry metadata to avoid reinventing already available capabilities.
+- Capability maturity is visible without being confused with implementation quality alone.
+- Completeness and Reliability incorporate consumer evidence.
+- Capability owners can promote capabilities based on evidence.
+- Registry data can be validated, exported, searched, and reviewed.
+