reuse-surface/registry/capabilities/capability.registry.register.md

---
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: R2
    name: Tolerable
    confidence: medium
    basis: consumer_quality_signals
    known_reliability_risks:
      - index drift still possible if authors skip validate
      - CLI requires local venv install
      - schema ID pattern required a fix during WP-0003 dogfooding

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
  consumer_feedback: []
  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
---

# 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.