# 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