tegwick
270065ff58
Add hub sync and report cohorts CLI commands with pytest coverage, document sibling index publish contract and hub hardening path, align INTENT layout, raise external evidence on three registry entries, and close gap priorities 19-23 (priority 18 deferred on sibling index blocks).
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_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 cohorts
Export capability cohorts for planning or implementation reuse decisions.
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,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 |
| Sync federation manifest from hub | reuse-surface hub sync |
| 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