reuse-surface/tools/README.md

# Registry Tools

CLI tooling for the capability registry, implemented in `reuse_surface/`.

## Install

```bash
python3 -m venv .venv
.venv/bin/pip install -e .
```

## Commands

### validate

Validate one entry or the full registry against `schemas/capability.schema.yaml`
and warn on index drift.

```bash
reuse-surface validate
reuse-surface validate registry/capabilities/capability.registry.register.md
```

### query

Filter the capability index by maturity, tags, domain, consumption mode, or keyword.

```bash
reuse-surface query --discovery-min D4
reuse-surface query --availability-min A3
reuse-surface query --tag identity
reuse-surface query --consumption-mode cli
reuse-surface query --keyword rollout
```

### export

Export a machine-readable bundle combining index rows and parsed entry front matter.

```bash
reuse-surface export
reuse-surface export --format json
```

### overlaps

Detect potential duplicate or overlapping capabilities (UC-RS-015).

```bash
reuse-surface overlaps
reuse-surface overlaps --threshold 0.35
```

### catalog

Generate human-readable catalog artifacts (UC-RS-018).

```bash
reuse-surface catalog
```

Writes `docs/CapabilityCatalog.md` and `docs/catalog/index.html`.

## Export format

The export bundle includes:

- `version`, `domain`, `updated` from the index
- `capabilities[]` with `{ index, entry }` pairs

Stable IDs and maturity fields are preserved for agent consumption (UC-RS-019).

## Workflows

| Workflow | Command |
|---|---|
| Add capability | template + index update + `reuse-surface validate` |
| Discover capabilities | `reuse-surface query` or read the index |
| Validate entry shape | `reuse-surface validate` |
| Export for agents | `reuse-surface export --format json` |
| Detect overlap | `reuse-surface overlaps` |
| Publish catalog | `reuse-surface catalog` |

## 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