reuse-surface/tools

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 gaps

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.

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.

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.

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.

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