feat(api-docs): Redoc-rendered /api/docs + consolidate OpenAPI spec to docs/openapi.yaml (#4781)

Redoc /api/docs + OpenAPI spec consolidated to docs/openapi.yaml (canonical 201-path complete spec; old path → legacy fallback). All refs/gates/tests/CI updated. Integrated into release/v3.8.35.

docs/frameworks/AGENT-SKILLS.md

@@ -31,7 +31,7 @@ src/shared/constants/agentSkills.ts    — 42-entry curated list (name/desc/cate
 src/lib/agentSkills/
   catalog.ts                           — getCatalog(), getSkillById(), filterCatalog(), computeCoverage()
   generator.ts                         — generateAgentSkills() writes SKILL.md to skills/{id}/
-  openapiParser.ts                     — extracts REST endpoints from docs/reference/openapi.yaml
+  openapiParser.ts                     — extracts REST endpoints from docs/openapi.yaml
   cliRegistryParser.ts                 — extracts CLI subcommands from bin/cli-registry.ts
   schemas.ts                           — Zod schemas: AgentSkillSchema, SkillCoverageSchema, etc.
   types.ts                             — TypeScript interfaces: AgentSkill, SkillCoverage, etc.

docs/frameworks/AGENTBRIDGE.md

@@ -448,7 +448,7 @@ Base path: `/api/tools/agent-bridge/`
 | POST | `/api/tools/agent-bridge/upstream-ca/test` | Validate-only (dry-run) an upstream CA path — does not persist |
 | GET / POST / DELETE | `/api/tools/agent-bridge/tproxy` | TPROXY transparent-decrypt capture mode — see [`docs/security/MITM-TPROXY-DECRYPT.md`](../security/MITM-TPROXY-DECRYPT.md) |
 
-Full OpenAPI schemas: `docs/reference/openapi.yaml` → tag `AgentBridge`.
+Full OpenAPI schemas: `docs/openapi.yaml` → tag `AgentBridge`.
 
 ---
 

docs/frameworks/EMBEDDED-SERVICES.md

@@ -623,7 +623,7 @@ If the embedded service exposes an OpenAI-compatible `/v1/chat/completions` endp
    table in §1 and any new endpoints to §4.
 2. Add unit tests in `tests/unit/services/` (lifecycle, installer, API shape).
 3. Add integration test in `tests/integration/services/` (behind `RUN_SERVICES_INT=1`).
-4. Update `docs/reference/openapi.yaml` with the new endpoints.
+4. Update `docs/openapi.yaml` with the new endpoints.
 
 ---
 
@@ -791,5 +791,5 @@ the most recent lines within the `tail` limit. Logs are not persisted to disk un
 - `docs/security/ROUTE_GUARD_TIERS.md` — LOCAL_ONLY tier details
 - `docs/architecture/CODEBASE_DOCUMENTATION.md` — §3.2 Embedded Services module mapping
 - `docs/architecture/ARCHITECTURE.md` — system-level context
-- `docs/reference/openapi.yaml` — machine-readable endpoint definitions
+- `docs/openapi.yaml` — machine-readable endpoint definitions
 - `CLAUDE.md` §"Adding a New Embedded Service" — quick-reference checklist

docs/frameworks/TRAFFIC_INSPECTOR.md

@@ -477,4 +477,4 @@ Base path: `/api/tools/traffic-inspector/`
 |--------|------|-------------|
 | POST | `/internal/ingest` | Accepts intercepted request from `server.cjs` passthrough path; requires `INSPECTOR_INTERNAL_INGEST_TOKEN` header |
 
-Full OpenAPI schemas: `docs/reference/openapi.yaml` → tag `Traffic Inspector`.
+Full OpenAPI schemas: `docs/openapi.yaml` → tag `Traffic Inspector`.