# 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`, `docs/catalog/index.html`,
`docs/catalog/registry.json`, and `docs/catalog/search.html`.

### federation compose

Compose a federated index from `registry/federation/sources.yaml`.

```bash
reuse-surface federation compose
reuse-surface federation compose --refresh
```

Composes local and remote HTTP index sources. Writes
`registry/indexes/federated.yaml` with `source_repo` attribution. Remote indexes
cache under `registry/federation/cache/`.

### graph

Generate a Mermaid relation graph from capability entry relations.

```bash
reuse-surface graph
reuse-surface graph --check
reuse-surface graph --stdout
```

Writes `docs/graph/capability-graph.mmd` and `docs/graph/index.html`.

### hub

Client for the federation hub service (REUSE-WP-0011).

```bash
export REUSE_SURFACE_URL=https://reuse.coulomb.social
export REUSE_SURFACE_TOKEN=<write-token>
reuse-surface hub status
reuse-surface hub list
reuse-surface hub register --repo state-hub --url https://.../capabilities.yaml
reuse-surface hub update --repo state-hub --enabled true
reuse-surface hub sync --merge
reuse-surface hub sync --dry-run
```

Run the service locally: `REUSE_SURFACE_TOKEN=dev-token reuse-surface serve`

### report gaps

```bash
reuse-surface report gaps
reuse-surface report gaps --format json
reuse-surface report gaps --roster registry/federation/local-repo-roster.yaml
```

Workstation roster report: publish blockers, empty scaffolds, seed-ready repos,
and local index owner stubs pending dedup.

### stats

Registry maturity aggregates and federation readiness.

```bash
reuse-surface stats
reuse-surface stats --format json
reuse-surface stats --federation-ready --raw-url https://.../capabilities.yaml
reuse-surface stats --roster registry/federation/local-repo-roster.yaml --federation-ready
```

### establish

Bootstrap or discover a capability registry in the current or target repo.

```bash
reuse-surface establish --scaffold --domain helix_forge
reuse-surface establish --scaffold --path ../state-hub
reuse-surface establish --publish-check --raw-url https://.../capabilities.yaml
export LLM_CONNECT_URL=http://127.0.0.1:8088
reuse-surface establish --discover --dry-run
reuse-surface establish --discover --apply
```

`--scaffold` creates `registry/` layout. `--publish-check` probes raw URL and
local index YAML. `--discover` drafts capabilities via llm-connect (optional).

### update

Refresh registry metadata from repo drift signals.

```bash
reuse-surface update --capability capability.registry.register --dry-run
reuse-surface update --all --from-git-since HEAD~5 --apply
reuse-surface update --capability capability.registry.register --suggest-maturity
```

Deterministic patches (`vector_drift`, new `tests/` citations) apply with
`--apply`. LLM suggestions use `--suggest-maturity` and remain review-only.

### report cohorts

Export capability cohorts for planning or implementation reuse decisions.

```bash
reuse-surface report cohorts
reuse-surface report cohorts --planning-min D5 --availability-max A1
reuse-surface report cohorts --implementation-min A4
reuse-surface report cohorts --format json
```

Planning preset (`--planning-min`) sets discovery minimum and defaults
`availability-max` to `A1`. Implementation preset (`--implementation-min`) sets
availability minimum. Output is Markdown (default) or JSON.

## 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` |
| Compose federation | `reuse-surface federation compose` |
| Sync federation manifest from hub | `reuse-surface hub sync` |
| Registry stats | `reuse-surface stats` |
| Bootstrap sibling registry | `reuse-surface establish --scaffold` |
| Verify index publish URL | `reuse-surface establish --publish-check` |
| Draft capabilities (LLM) | `reuse-surface establish --discover` |
| Refresh entry metadata | `reuse-surface update` |
| Planning cohort export | `reuse-surface report cohorts` |
| Relation graph | `reuse-surface graph` |

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