docs(api): TRA-743 BB44-preflight followups

[mikestankavich]

TRA-743 follow-up to PR #158 — four items surfaced when validating the merged change against live preview surfaces ahead of BB44.

1. Spec redirect targets canonical platform URL

/api/openapi.{json,yaml} redirect now points at app.{env}.trakrf.id/api/openapi.{json,yaml} — the previous target /api/v1/openapi.{json,yaml} is itself a 301 to canonical on platform, so the middleware was sending every client through an extra hop:

docs/api/openapi.yaml → 302 → app/api/v1/openapi.yaml → 301 → app/api/openapi.yaml → 200

Same change in docusaurus.config.ts (build-time fetch) and in every customer-facing prose mention (README.md, docs/api/README.mdx, docs/api/postman.mdx, docs/api/quickstart.mdx, tests/blackbox/BB.md). The middleware REWRITE_MAP continues to rewrite /api/v1/openapi.* → /api/openapi.* so legacy callers still resolve cleanly.

2. Defensive 410 Gone for retired mirror artifacts

functions/_middleware.js returns 410 Gone with Cache-Control: no-store for /api/platform-meta.json and /api/trakrf-api.postman_collection.json.

The files themselves were deleted in PR #158 (gitignored Postman collection dropped from .gitignore, platform-meta.json removed from static/api/). But Cloudflare's edge cache continued serving the last-deploy 200 for the cache-TTL window — a BB cycle pulling platform-meta.json as "ground truth" would see an 07b5edb commit hash with a 2026-05-16T11:36:28Z spec_refreshed_at, neither of which matches the current platform deploy. False drift findings would result.

The 410 response displaces stale 200 entries on next request and no-store keeps the response itself out of edge cache. Verified locally: requests with a cache-buster already return 404 (the files are genuinely gone from the build); without a cache-buster, requests to plain paths return the stale cached 200. The 410 makes the cleanup observable to clients without depending on edge cache TTL.

3. BB.md "Multi-format spec consistency" → "Multi-format spec sanity"

The byte-equivalent-after-canonical-sort check guarded against independent docs-mirror copies of the YAML and JSON drifting. With both formats now 302-ing to the same platform binary, the only divergence class left is "platform encodes the spec twice and the two encoders disagree" — that's a platform bug, not a docs-mirror drift question. Section renamed and the byte-equivalence bullet dropped; the still-useful checks (numeric-literal divergence, hardcoded URLs, discoverability) stay.

4. BB.md §1 canonical-URL prose

§1 ("Fetch the spec") was naming the intermediate-hop URL (/api/v1/openapi.{yaml,json}) as canonical. Updated to name the actual canonical path so a BB run doesn't quote the wrong URL in findings.

Out of scope (platform-side)

Items 5 and 6 from the BB44 pre-flight comment are platform concerns and not addressed here:

• 5. app.preview.trakrf.id/health.json returns SPA HTML. Needs a platform /health.json route exposed, or the BB.md / check-deploy-lag.sh comment / acceptance criterion need to point at a different surface. Filed against TRA-743 platform side.
• 6. New components.headers.Deprecation in the spec. FYI only per the comment; BB44 will pick it up if relevant.

Test plan

• pnpm lint, pnpm typecheck, DEPLOY_ENV=preview pnpm build clean
• Build output verified to fetch from app.preview.trakrf.id/api/openapi.yaml (not /v1/)
• grep for api/v1/openapi shows only the middleware REWRITE_MAP (legacy-alias support) and the historical changelog entry
• After preview deploy: curl -sIL https://docs.preview.trakrf.id/api/openapi.yaml shows a single 302 hop to app.preview.trakrf.id/api/openapi.yaml (no longer chains through /api/v1/)
• After preview deploy: curl -I https://docs.preview.trakrf.id/api/platform-meta.json returns 410 (or 404 if edge cache TTL has already expired on its own)

🤖 Generated with Claude Code

[github-actions]

🚀 Preview Deployment Update

✅ This PR has been successfully merged into the preview branch.

The preview environment will update shortly at: https://docs.preview.trakrf.id

[cloudflare-workers-and-pages]

Deploying docs with    Cloudflare Pages

Latest commit:	4d213d3
Status:	✅  Deploy successful!
Preview URL:	https://e1713905.docs-4n7.pages.dev
Branch Preview URL:	https://preview.docs-4n7.pages.dev

View logs