Bootstrap and first implementation

tools/README.md

@@ -0,0 +1,55 @@
+# Registry Tools
+
+Reference tooling for the capability registry. The MVP is document-first; this
+directory documents validation and query workflows until executable tools land.
+
+## Current MVP workflows
+
+| Workflow | Location | Mode |
+|---|---|---|
+| Add capability | `templates/capability-entry.template.md` | manual |
+| Discover capabilities | `registry/indexes/capabilities.yaml` | manual / agent |
+| Validate entry shape | `registry/README.md` checklist | manual |
+| Schema reference | `schemas/capability.schema.yaml` | manual |
+| Maturity definitions | `specs/CapabilityMaturityStandard.md` | manual |
+
+## Manual validation procedure
+
+1. Open the capability entry Markdown file.
+2. Compare YAML front matter against `schemas/capability.schema.yaml`.
+3. Run the checklist in `registry/README.md`.
+4. Confirm the index entry exists and the `vector` is current.
+5. Confirm relation targets exist or are intentionally external.
+
+## Planned tools (out of MVP scope)
+
+Future CLI commands may include:
+
+```bash
+# validate one entry or the whole registry
+reuse-surface validate registry/capabilities/
+
+# query by planning need, availability, or vector
+reuse-surface query --discovery-min D4 --tag identity
+
+# export machine-readable registry bundle
+reuse-surface export --format yaml
+```
+
+These are documented here as targets only. Do not assume they exist yet.
+
+## Agent query pattern
+
+Agents should start with the index, not individual entry files:
+
+1. Read `registry/indexes/capabilities.yaml`.
+2. Filter by `vector`, `tags`, `consumption_modes`, or `summary`.
+3. Open only the candidate entry paths.
+4. Before creating a new capability, search for overlap using the duplicate
+   guidance in `registry/README.md`.
+
+## Related use cases
+
+- UC-RS-013 — Use registry metadata in agentic coding
+- UC-RS-019 — Publish a machine-readable registry export
+- UC-RS-023 — Validate registry entries against schema