reuse-surface/tools/README.md

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

plan-check

Query-before-build check (REUSE-WP-0018): match a draft workplan or a free intent against the federated capability index before starting new work. Deterministic token matching against registry/indexes/federated.yaml; advisory only — never blocks workplan creation. See specs/PlanCheck.md.

reuse-surface plan-check workplans/XXX-WP-0042-something.md
reuse-surface plan-check --intent "parse invoices and file evidence"
reuse-surface plan-check --intent "..." --format json
reuse-surface plan-check --intent "..." --record-outcome reused
reuse-surface plan-check --intent "..." --file-request --requesting-domain infotech
export LLM_CONNECT_URL=http://127.0.0.1:8080   # optional, enables semantic rerank
reuse-surface plan-check --intent "..." --no-llm   # skip the rerank pass
reuse-surface plan-check --intent "..." --llm-url http://127.0.0.1:8080

reuse|extend|new verdict from --reuse-threshold/--extend-threshold (defaults 0.45/0.22). --record-outcome records a reuse event (REUSE-WP-0019-T04): POST /v1/reuse-events if the hub is reachable (REUSE_SURFACE_URL/REUSE_SURFACE_TOKEN set), else appends to registry/telemetry/plan-check-events.jsonl — never both, and the schema (schemas/reuse-event.schema.json) is identical either way. --file-request files a State Hub capability request on a new verdict (requires the hub reachable at 127.0.0.1:8000; degrades gracefully offline).

When LLM_CONNECT_URL is set, an optional rerank pass sends the top deterministic candidates to llm-connect for a semantic confidence score. Per design, this never reorders or replaces the deterministic result — LLM-scored entries are appended after as separately-labeled [llm] matches, so the trusted base result is identical whether or not the rerank runs. Malformed/non-JSON LLM responses are rejected and reported as a note, never silently guessed at; missing LLM_CONNECT_URL degrades the same way.

record-reuse

Manually record a retroactive reuse fact (REUSE-WP-0019-T04) — for decisions made outside plan-check, e.g. discovered during a review. Same hub-first-then-local-fallback behavior as plan-check --record-outcome.

reuse-surface record-reuse --consumer-repo some-repo \
  --capability-id capability.infotech.issue-tracking \
  --verdict reuse --outcome reused
reuse-surface record-reuse --consumer-repo some-repo --verdict new --format json

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
reuse-surface report gaps --check-capability-requests

--check-capability-requests (REUSE-WP-0018-T04) also lists open State Hub capability requests with no matching federated capability; requires the hub reachable at 127.0.0.1:8000 and degrades gracefully (prints "skipped") when it isn't. Off by default so report gaps stays fast and offline-safe.

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

report reuse

Reuse telemetry aggregation (REUSE-WP-0019-T05): per-capability consumer counts, outcome breakdown, last-used, merged from the hub's GET /v1/reuse-events (if reachable) and this repo's local registry/telemetry/plan-check-events.jsonl fallback, deduped.

reuse-surface report reuse
reuse-surface report reuse --capability-id capability.infotech.issue-tracking
reuse-surface report reuse --format json
reuse-surface report reuse --suggest-relations
reuse-surface report reuse --suggest-relations --apply

--suggest-relations lists evidence-gated relations.reused_by suggestions for capabilities this repo owns (skips consumer repos already listed). --apply applies them via the same apply_patches mechanism maintain uses for relation_add patches — requires --suggest-relations, and never runs without it: nothing is written unless real observed-reuse events exist and an operator explicitly passes --apply. See specs/CapabilityMaturityStandard.md §8.9 for what observed-reuse evidence does (and doesn't) count toward R-axis promotion.

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
export REUSE_SURFACE_URL=https://reuse.coulomb.social
reuse-surface stats   # hub section gains composed_at/stale/age_days/stale_warning

Hub freshness (REUSE-WP-0019-T06): when REUSE_SURFACE_URL is configured, stats's hub section reports the federated index's composed_at, stale flag, age_days, and a computed stale_warning (age beyond REUSE_SURFACE_FRESHNESS_DAYS, default 7, or the hub's own stale flag). CI runs this as an informational (non-failing) check on every push.

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:8080
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
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.

maintain

Interactive or automated registry maintenance (REUSE-WP-0016). Preferred entry point for sibling repo operators.

export LLM_CONNECT_URL=http://127.0.0.1:8080   # optional
reuse-surface maintain --all --from-git-since origin/main
reuse-surface maintain --capability capability.registry.register
reuse-surface maintain --all --auto --no-llm
reuse-surface maintain --all --auto --from-git-since HEAD~3
reuse-surface maintain --publish --raw-url https://.../capabilities.yaml --all --auto --no-llm

Mode	Flags	Behavior
Interactive (TTY)	(default)	Prompt per patch: apply / skip / edit / quit
Full automation	--auto or --yes	Safe deterministic + gated LLM patches
Deterministic only	--auto --no-llm	No llm-connect required
Publish chain	--publish --raw-url	maintain → validate → publish-check

Templates: templates/Makefile.registry.fragment, templates/git-hook.pre-commit.registry. Install hook: reuse-surface establish --scaffold --hook.

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
Interactive registry maintain	reuse-surface maintain
Planning cohort export	reuse-surface report cohorts
Relation graph	reuse-surface graph
Query before building	reuse-surface plan-check --intent "..."
Record a reuse fact retroactively	reuse-surface record-reuse
Aggregate reuse telemetry into evidence	reuse-surface report reuse --suggest-relations

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