tegwick
ea5918b1e6
Add FederationHubAPI spec, hub registration schema, FastAPI hub with SQLite persistence, reuse-surface hub CLI client, Dockerfile, and hub tests. Activate workplan; T05 deploy and T06 ops docs remain open pending railiance01 cutover.
Registry Tools
CLI tooling for the capability registry, implemented in reuse_surface/.
Install
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.
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.
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.
reuse-surface export
reuse-surface export --format json
overlaps
Detect potential duplicate or overlapping capabilities (UC-RS-015).
reuse-surface overlaps
reuse-surface overlaps --threshold 0.35
catalog
Generate human-readable catalog artifacts (UC-RS-018).
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.
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.
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).
export REUSE_SURFACE_HUB_URL=https://reuse-hub.whywhynot.de
export REUSE_SURFACE_HUB_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
Run the hub service locally: reuse-surface-hub (requires REUSE_SURFACE_HUB_TOKEN).
Export format
The export bundle includes:
version,domain,updatedfrom the indexcapabilities[]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 |
| 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