api-design: add API-first methodology, DX, and contract testing

Extends api-design.md beyond its security/operations focus with three
new dimensions:

- §0 API-First Design Process — OpenAPI 3.1 as single source of truth,
  Spectral governance, dogfooding (UIs consume the public API, no
  privileged backdoors), auth-required-by-default as a design stance.
- §7 Documentation and Developer Experience — Scalar/Mintlify,
  RFC 9457 Problem Details error envelope, interactive playgrounds,
  generated SDKs (Stainless, Speakeasy, Fern), RFC 9745 deprecation
  signals and changelog UX.
- §8 Contract Testing and API Quality — schema validation in the
  test suite, Pact CDC vs provider verification, Schemathesis
  property-based fuzzing, oasdiff drift detection in CI, the API
  test pyramid.

Intro, cross-refs in §3.1/§3.3/§4.1, and Sources block reorganised
by topic. Index entry in BESTPRACTICES.md updated. PLAN file included
for traceability.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

BESTPRACTICES.md

@@ -23,7 +23,7 @@ Generalised best practices extracted from real project work via the `/distill-be
 - [Docker UID Matching](docker-uid-matching.md) — UID wrapper entrypoint for mounted volumes, gosu pattern, when to use vs K8s securityContext
 - [Database Selection](database-selection.md) — SQLite is not a production database; always use PostgreSQL for services with FQDNs, multiple consumers, or concurrent access
 - [Docker](docker.md) — gosu PID 1, GIT_SSH_COMMAND scope, slim image health checks, buildx local images, Compose networking/restart gotchas, volume paths, override merge behaviour, init script privilege order, payload size limits, bind-mount rm gotcha
-- [API Design](api-design.md) — Transport security, auth (OAuth2/JWT/mTLS), versioning, pagination, error handling, idempotency, rate limiting, input validation, zero-trust patterns
+- [API Design](api-design.md) — API-first methodology (OpenAPI 3.1 source of truth, Spectral governance, dogfooding, auth-by-default); transport, auth (OAuth2/JWT/mTLS), versioning, errors, idempotency, rate limiting, validation, zero-trust; docs/DX (Scalar/Mintlify, RFC 9457 errors, generated SDKs, RFC 9745 deprecation); contract testing (Schemathesis, Pact, oasdiff drift detection, test pyramid)
 - [API Integration](api-integration.md) — Client-side third-party API integration: capability verification, app-layer compensation, git+SOPS polling sync, bidirectional SoR
 - [Octopus Process Templates](octopus-process-templates.md) — OCL syntax, step template references, channel scoping, parameters, versioning, Platform Hub patterns
 - [LLM Code Security](llm-code-security.md) — Security vulnerabilities in AI-generated code: injection flaws, hardcoded secrets, hallucinated packages, over-permissive defaults, IaC risks, crypto mistakes, operational vulnerabilities (idempotency, CI/CD integrity, supply chain provenance, concurrent access), review checklists