OpenAPI Prose Endpoint Migration Triage
Status: OAPI-059-006 pilot.
Scope: endpoint-bearing prose under docs/modules/**. The scan seed was:
rg -n '(^|[ `|*-])(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+/?(api|v1|v2|concelier|excititor|vex|healthz|readyz|metrics|offline-kit|bundles|scans|sboms|vuln|ledger|openapi|oauth|connect|token|userinfo|authorize|revoke|introspect|jwks|health|readyz|api/)' docs/modules -g '*.md'
Buckets:
- A - pure endpoint reference: replace with a stable-link stub to the generated module
api-reference.md. - B - mixed reference and narrative: keep hand-authored context; replace endpoint-shape sections with
OPENAPI-GENERATEDblocks or an include pointer to generated reference material. - C - architecture, workflow, runbook, UI, CLI, schema, telemetry, or external-protocol docs: leave hand-authored; endpoint mentions are contextual and are not the source of truth for HTTP shape.
Generated reference files are derivatives, not prose migration targets. The current repo has a generated Platform reference and this pilot adds a generated Concelier reference from devops/compose/openapi_current.json; live per-service regeneration remains blocked by OAPI-059-004.
Triage Table
| Document set | Bucket | Endpoint line ranges | OAPI-059-006 action |
|---|---|---|---|
docs/modules/platform/api-reference.md | Generated | 16-2099 | Already generated; excluded from prose migration. |
docs/modules/concelier/api/advisories-summary.md | A | 1-78 | Replaced with stub to ../api-reference.md. |
docs/modules/concelier/api/conflicts.md | A | 1-137 | Replaced with stub to ../api-reference.md. |
docs/modules/concelier/api/evidence-batch.md | A | 1-47 | Replaced with stub to ../api-reference.md. |
docs/modules/concelier/api/lnm-linksets.md | A | 1-149 | Replaced with stub to ../api-reference.md. |
docs/modules/concelier/api/observations.md | A | 1-180 | Replaced with stub to ../api-reference.md. |
docs/modules/concelier/api/public-advisory-import.md | A | 1-61 | Replaced with stub to ../api-reference.md. |
docs/modules/concelier/sbom-learning-api.md | B | 113-221 | Keep SBOM learning narrative; follow-up should replace the endpoint section with an OpenAPI block once live Concelier regeneration is available. |
docs/modules/concelier/interest-scoring.md | B | 70-162 | Pilot OPENAPI-GENERATED block added for score and SBOM-learning endpoint references. |
docs/modules/concelier/architecture.md, attestation.md, backport-deduplication.md, bridges/vuln-29-001.md, connector-aggregation-state.md, connector-configuration.md, connectors/credentials-acquisition.md, federation-bundle-export.md, federation-operations.md, operations/connectors/cve-kev.md, operations/console-lnm-consumption.md, operations/exporters.md, operations/valkey-advisory-cache.md, unified-issue-projection.md | C | Contextual endpoint mentions throughout each file. | Leave hand-authored; references explain Concelier workflows, connectors, and operations rather than endpoint shape. |
docs/modules/platform/cryptography-and-compliance.md | B | 107-120 | Pilot OPENAPI-GENERATED block added for compliance/profile endpoint references. |
docs/modules/platform/platform-service.md, regional-crypto-route-matrix.md, explainable-triage-implementation-plan.md, TASKS.md | C | Contextual endpoint mentions throughout each file. | Leave hand-authored; references explain platform behavior, readiness, or task state. |
docs/modules/advisory-ai/** endpoint-bearing docs | B | architecture.md, chat-interface.md, guides/*.md, knowledge-search.md, orchestration-pipeline.md, runs.md, unified-search-architecture.md | Follow-up AdvisoryAI migration sprint. Preserve run, policy-studio, explanation, and chat narratives; replace endpoint-shape sections only. |
docs/modules/airgap/** endpoint-bearing docs | B | architecture.md, guides/advisory-implementation-roadmap.md, guides/offline-bundle-format.md, guides/time-api.md | Follow-up AirGap migration sprint. Keep offline workflow context; generated blocks should cover upload, verify, import, status, alert bundle, and time-anchor shapes. |
docs/modules/attestor/** endpoint-bearing docs | B | architecture.md, guides/identity-watchlist.md, operations/bundle-rotation.md, operations/observability.md, predicate-schema-registry.md, tile-proxy-design.md | Follow-up Attestor migration sprint. External Rekor examples in diagrams/trust-architecture.md are Bucket C. |
docs/modules/authority/** endpoint-bearing docs | B | architecture.md, AUTHORITY.md, README.md, tenant-model.md, verdict-manifest.md | Follow-up Authority migration sprint. Keep tenant/verdict narrative and replace HTTP-shape snippets only. |
docs/modules/binary-index/semantic-diffing.md | C | 150-153, 522-525 | Leave hand-authored; endpoint mentions are operational diagnostics inside a design dossier. |
docs/modules/cli/** endpoint-bearing docs | C | architecture.md, cli-vs-ui-parity.md, guides/commands/*.md | Leave hand-authored; CLI docs cite backend routes to explain command behavior, not to define HTTP shape. |
docs/modules/cryptography/** endpoint-bearing docs | C | architecture.md, eidas-qscd-bridge-contract.md, sm-remote-vendor-adapter-contract.md | Leave hand-authored; these are provider/adapter contracts and setup decisions, not generated service API references. |
docs/modules/doctor/** endpoint-bearing docs | C | architecture.md, checks/README.md, compose-baseline.md | Leave hand-authored; docs cite scheduler/doctor catalog probes. |
docs/modules/evidence-locker/** endpoint-bearing docs | B | architecture.md, dora-roi-retention.md, eu-regulatory-persistence.md, export-format.md, guides/evidence-pack-schema.md | Follow-up EvidenceLocker migration sprint. Keep evidence model/runbook text; generated blocks should cover capsule, pack, export, and verify routes. |
docs/modules/excititor/** endpoint-bearing docs | B | architecture.md, evidence-contract.md, graph-overlays.md, mirrors.md, operations/*.md, schemas/issuer_directory_contract.md, trust-lattice.md, vex_linksets_api.md, vex_observations.md | Follow-up Excititor migration sprint. vex_linksets_api.md is likely Bucket A once an Excititor generated reference exists. |
docs/modules/export-center/api.md | B | 73-478 | Follow-up ExportCenter migration sprint. This is a full API guide, but examples and operational semantics should remain around generated endpoint blocks. |
docs/modules/export-center/** non-API endpoint-bearing docs | C | architecture.md, cli.md, operations/runbook.md, profiles.md, provenance-and-signing.md | Leave hand-authored; endpoint mentions are workflow or artifact context. |
docs/modules/findings-ledger/** endpoint-bearing docs | B | export-http-surface.md, oas-baseline.md, runtime-instrumentation-api.md, runtime-instrumentation-operations.md, runtime-instrumentation-ui-requirements.md, schema.md, contracts/staleness-time-anchor-contract.md | Follow-up FindingsLedger migration sprint. Preserve runtime instrumentation narrative; generated blocks should cover live HTTP shape. |
docs/modules/integrations/architecture.md | C | 88, 299-302 | Leave hand-authored; endpoint mentions describe integration flows and provider probes. |
docs/modules/jobengine/architecture.md | C | 89 | Leave hand-authored; contextual job query reference. |
docs/modules/notify/** endpoint-bearing docs | C | api.md, architecture.md, channels/nis2-csirt.md, pack-approvals-integration.md, templates.md | Leave hand-authored until Notify OpenAPI live regeneration exists; current references are readiness and integration context. |
docs/modules/policy/** endpoint-bearing docs | B | architecture.md, budget-attestation.md, contracts/*.md, cvss-v4.md, data-handling.md, guides/*.md | Follow-up Policy migration sprint. Keep assurance/control-register/gateway narrative; replace endpoint-shape tables only. |
docs/modules/reach-graph/** endpoint-bearing docs | B | architecture.md, README.md, guides/*.md, schemas/*.md | Follow-up ReachGraph migration sprint. Preserve schema semantics; generated blocks should cover graph/replay/explainability endpoints. |
docs/modules/registry/** endpoint-bearing docs | C | architecture.md, operations/token-service.md, README.md | Leave hand-authored; Docker registry token exchange is a protocol-specific contract. |
docs/modules/release-orchestrator/api/*.md | B | API directory files | Follow-up ReleaseOrchestrator API migration sprint. These are the closest Bucket A candidates after live regeneration, but today they carry operator workflow context and no generated reference exists. |
docs/modules/release-orchestrator/** non-API endpoint-bearing docs | C | architecture.md, deployment/*.md, enhancements/*.md, integrations/*.md, modules/*.md, operations/*.md, security/*.md, workflow/*.md | Leave hand-authored; these mention endpoints inside workflow, design, and future-enhancement context. |
docs/modules/remediation/architecture.md | C | 95 | Leave hand-authored; single contextual route mention. |
docs/modules/replay/** endpoint-bearing docs | B | architecture.md, replay-proof-schema.md | Follow-up Replay migration sprint. Keep proof schema narrative; endpoint snippets become generated blocks when Replay specs regenerate. |
docs/modules/router/openapi-aggregation.md, schema-validation.md | C | OpenAPI aggregation and schema-validation route mentions | Leave hand-authored; these docs define the OpenAPI source-of-truth workflow itself. |
docs/modules/router/migration-guide.md, messaging-valkey-transport.md | C | Contextual examples | Leave hand-authored. |
docs/modules/sbom-service/** endpoint-bearing docs | B | api/projection-read.md, artifact-links-api.md, byos-ingestion.md, ledger-lineage.md, lineage/architecture.md, sources/architecture.md, spdx3-profile-support.md | Follow-up SbomService migration sprint. Preserve lineage/source narrative; generated blocks should cover endpoint shapes. |
docs/modules/scanner/endpoint-registration-matrix.md | B | 14-86 | Follow-up Scanner migration sprint; recommended as the Scanner proof doc because it intentionally mixes endpoint maps with authorization posture. |
docs/modules/scanner/** other endpoint-bearing docs | C | architecture.md, byos-ingestion.md, design/*.md, guides/*.md, observability.md, operations/*.md, README.md, signed-sbom-archive-spec.md, entropy.md, reachability-drift.md | Leave hand-authored unless a module sprint explicitly upgrades a section to generated blocks. These docs are architecture, workflow, or analyzer/runbook context. |
docs/modules/signals/** endpoint-bearing docs | B | guides/unknowns-ranking.md, unified-score.md | Follow-up Signals migration sprint. |
docs/modules/signer/README.md | C | 12 | Leave hand-authored; route mention documents Signer integration. |
docs/modules/telemetry/** endpoint-bearing docs | C | architecture.md, guides/*.md, operations/*.md, ttfs-architecture.md | Leave hand-authored; telemetry docs describe probes, read models, and operational dashboards. |
docs/modules/timeline/** endpoint-bearing docs | C | anomaly-v2.md, audit-retention.md | Leave hand-authored; endpoint mentions are audit workflow context. |
docs/modules/ui/** and docs/modules/web/** endpoint-bearing docs | C | UI architecture, console architecture, v2-rewire, wireframes, smart-diff, unified triage | Leave hand-authored; frontend docs cite backend endpoints consumed by UI and are not HTTP source-of-truth. |
docs/modules/unknowns/grey-queue-state-machine.md | C | 106 | Leave hand-authored; state-machine transition table. |
docs/modules/vex-hub/** endpoint-bearing docs | B | architecture.md, integration-guide.md, README.md | Follow-up VexHub migration sprint. |
docs/modules/vex-lens/** endpoint-bearing docs | B | architecture.md, guides/consensus-api.md | Follow-up VexLens migration sprint. |
Bucket B Block Contract
For mixed docs, endpoint-shape snippets must be replaced with this sentinel block. The block body is generated or copied mechanically from a generated api-reference.md; hand-authored rationale stays outside the block.
<!-- BEGIN OPENAPI-GENERATED: service=<service> source=<service>/api-reference.md paths=<comma-separated paths> -->
...generated endpoint summary...
<!-- END OPENAPI-GENERATED -->
Until OAPI-059-004 live regeneration produces per-service openapi/v1.json files, the pilot blocks point at generated module references derived from devops/compose/openapi_current.json. A follow-up guardrail must extend OAPI-059-005 Job A to validate OPENAPI-GENERATED blocks, not only full api-reference.md files with the OAPI-059 sentinel.
Follow-Up Sprint Backlog
Create one docs-only migration sprint per Bucket B module after OAPI-059-004 live regeneration succeeds:
- AdvisoryAI
- AirGap
- Attestor
- Authority
- Concelier remaining mixed docs
- EvidenceLocker
- Excititor
- ExportCenter
- FindingsLedger
- Policy
- ReachGraph
- ReleaseOrchestrator API docs
- Replay
- SbomService
- Scanner
- Signals
- VexHub
- VexLens