--- id: capability.registry.register name: Capability Registration summary: Register a new capability so it becomes visible for planning and implementation reuse. owner: reuse-surface status: draft domain: helix_forge tags: - registry - governance - meta maturity: discovery: current: D3 target: D5 confidence: medium rationale: > Core use case UC-RS-001 is documented in specs/UseCaseCatalog.md and the registry model is bounded in INTENT.md, but concrete promotion workflows are not yet grounded in registry artifacts. availability: current: A4 target: A5 confidence: medium rationale: > Local registry workflows use the reuse-surface CLI (A3). Federation repo registration is also available through the hosted hub HTTP API at reuse.coulomb.social (POST/PATCH /v1/repos), deployed and dogfood-tested on Railiance01 (REUSE-WP-0011). external_evidence: completeness: level: C2 name: Partial confidence: medium basis: scope_vs_intent_and_consumer_expectations satisfied_expectations: - capability IDs can be assigned in registry entries - maturity vectors can be recorded at registration time - CLI validate, query, and export support registry workflows - promotion history can be recorded in entries - federation repo registration via hosted hub API and hub CLI broken_expectations: - no automated duplicate detection yet out_of_scope_expectations: - hosting registered capabilities - enforcing implementation architecture reliability: level: R3 name: Usable confidence: medium basis: consumer_quality_signals known_reliability_risks: - index drift still possible if authors skip validate - CLI requires local venv install - sibling repos cannot register until indexes publish raw URLs evidence: satisfied_signals: - CI validate with fail-on-warnings on every push - hub register/list/federated smoke on production reuse.coulomb.social - pytest coverage for hub API and federation compose paths discovery: intent: > Make a capability candidate visible in the registry so humans and agents can discover, assess, compare, and reuse it instead of rebuilding it in isolation. includes: - stable capability ID assignment - initial discovery and availability classification - explicit completeness and reliability placeholders - evidence and relation references excludes: - implementing the registered capability - certifying implementation quality - operating runtime services for registered capabilities assumptions: - unregistered capabilities are invisible for registry-driven reuse - low-maturity entries are acceptable when evidence gaps are explicit use_cases: - UC-RS-001 research_memos: - specs/UseCaseCatalog.md - specs/ProductRequirementsDocument.md availability: current_level: A4 target_level: A5 current_artifacts: - templates/capability-entry.template.md - registry/indexes/capabilities.yaml - reuse_surface/cli.py - reuse_surface/hub/ - specs/FederationHubAPI.md - https://reuse.coulomb.social target_artifacts: - packaged container release with documented SLO consumption_modes: - informational - markdown authoring - cli - service API relations: depends_on: [] supports: - capability.feature-control.evaluate - capability.identity.vocabulary-canonicalize related_to: - capability.registry.validate evidence: documentation: - INTENT.md - specs/UseCaseCatalog.md - specs/FederationHubAPI.md - docs/deploy/reuse-kubernetes.md tests: - tests/test_hub.py - tests/test_hub_sync.py - .gitea/workflows/ci.yml consumer_feedback: - > reuse-surface dogfood (REUSE-WP-0011): production hub registration and /v1/federated compose succeeded on Railiance01 without write-path regressions after WP-0011 deploy. bug_reports: [] incidents: [] consumer_guidance: recommended_for: - making a new capability visible at D0/A0/C0/R0 with minimal friction - seeding planning discussions before implementation exists not_recommended_for: - treating registry presence as proof of implementation readiness - skipping explicit evidence for maturity promotion known_limitations: - manual index updates are required after adding an entry - duplicate detection is guidance-only in the MVP promotion_history: - date: "2026-06-14" dimension: discovery from: D0 to: D1 rationale: Added name, summary, and registry-first intent from INTENT.md. author: reuse-surface - date: "2026-06-15" dimension: discovery from: D1 to: D3 rationale: Bounded scope with UC-RS-001 and MVP registry artifacts in specs/. author: reuse-surface - date: "2026-06-15" dimension: availability from: A0 to: A3 rationale: reuse-surface CLI shipped validate, query, and export commands. author: reuse-surface - date: "2026-06-15" dimension: availability from: A3 to: A4 rationale: > Hosted federation hub live at reuse.coulomb.social; hub register/update via HTTP API and reuse-surface hub CLI; production deploy on Railiance01. author: reuse-surface - date: "2026-06-16" dimension: reliability from: R2 to: R3 rationale: > CI gates, pytest hub/federation coverage, and production hub smoke support normal registration workflows with documented limitations. author: reuse-surface --- # Capability Registration ## Overview Registration is the entry point for reuse visibility. A capability that is not registered cannot be discovered through the registry surface, even if code or documentation exists elsewhere. ## Current reuse mode **Local registry (A3 CLI):** add Markdown entries under `registry/capabilities/`, update `registry/indexes/capabilities.yaml`, run `reuse-surface validate`. **Federation registration (A4 API):** register published index URLs on the hosted hub (`reuse-surface hub register`, `POST /v1/repos`) for cross-repo discovery via `GET /v1/federated`. ## Next promotion steps 1. Attach concrete use cases and actors to reach D5. 2. Package hub as a versioned container release with operator SLO (A5). 3. Record consumer expectations and broken expectations as external evidence.