Source the OpenAPI spec from the pinned upstream commit (raw), not a live instance

[strausmann]

Motivation

Today the tool layer is built from a spec extracted from a live Dockhand instance
(api:extract → docs/dockhand-openapi.json), pinned via PINNED_DOCKHAND_OPENAPI_COMMIT.
Consequences: CI can't refresh it (no live instance), and every new Dockhand release needs a
manual review of the API diff to spot new/changed endpoints.

Dockhand now commits its generated spec to the repo: src/lib/openapi.generated.json
(raw-fetchable, ~250 paths, info.version per release), regenerated from the route tree on every
build (prebuild → generate:openapi) and drift-checked (generate:openapi:check). Every
operation is 100% annotated. It's the same document served at GET /api/docs when
FEAT_API_DOCS=true, and the upstream manual now references this MCP server as driving the API
from that document.

Proposal — change the spec SOURCE, not the curation

• Fetch src/lib/openapi.generated.json from the pinned upstream commit via
  raw.githubusercontent.com/Finsys/dockhand/<PINNED_DOCKHAND_OPENAPI_COMMIT>/src/lib/openapi.generated.json
  instead of extracting from a live instance. Reproducible (pinned to a commit), CI-friendly
  (just an HTTP GET), no FEAT_API_DOCS/running instance needed.
• Keep the entire curation layer unchanged: body-contract gate, tool-endpoint-map,
  EXPLICIT_OVERRIDES, omission-registry, and the business-logic tools that don't 1:1-proxy REST
  (e.g. update_stack_env's get-merge-put) — none of which a spec can express.
• Add drift automation: a Renovate/CI check that bumps the pin toward upstream main; the
  bump PR's CI (body-contract gate + tool-endpoint-map against the new spec) surfaces new/changed
  endpoints automatically — replacing the manual release-diff review.

Non-goals

• Not full live tool-generation. Auto-converted raw specs measurably underperform curated MCP
  servers; the curation is the value and stays.
• Not reading from a running instance at runtime — a pinned committed spec is reproducible; a
  live instance is not.

To validate during implementation

• Does the raw upstream spec carry everything the current handler-source extraction
  (extract-dockhand-api.mjs) adds — in particular query-param required flags — so that separate
  extraction can be retired? Evidence-based check, not assumed.
• Renovate ergonomics for a "raw file at a pinned commit" dependency.

Process

This issue is the intake of the initiative (decided to take it on, likely soon). Implementation
goes through brainstorming → plan first — the source swap plus drift automation is a real design
step, not a mechanical change.

[strausmann]

Two refinements from a design review, worth folding into this issue's scope:

1. Consolidate to a single spec source — not just re-source the body-contract one. Today there are two spec files with different freshness: dockhand-api-schema.json (routes/query-params, re-extracted from upstream main nightly & unpinned) and dockhand-openapi.json (body-contracts, from a hardcoded pinned commit). That divergence is precisely why body-contract drift (the class of bug in #194) slips through: the two clocks drift apart and the body-contract gate runs against the frozen one. Since Dockhand now commits a single, 100%-annotated src/lib/openapi.generated.json (routes + query-params + body-contracts in one document), it can replace both current sources. Target: one source of truth, not two — this extends the proposal beyond just the body-contract source.

2. Keep it pinned (with CI drift-bump), not live-at-runtime. Fetch the single spec from a pinned upstream commit that a Renovate/CI check bumps toward main; each build stays reproducible ("v1.15.0 has these tools") while the bump PR surfaces new/changed endpoints. Unpinned/always-main trades the two-files problem for a not-reproducible one; reading from a running instance at runtime stays a non-goal (chicken-and-egg — the server often starts before Dockhand is reachable).

Related — version-gating (no issue yet): the server already exposes dockhandServerVersion (via get_server_info, best-effort from GET /api/changelog) and dockhandOpenApiVersion (the pinned spec's info.version, via get_tool_manifest), but never compares them, and there's no declared min-supported Dockhand version. The single pinned spec version from this work could feed a lightweight preflight server-compat check (warn on mismatch) instead of every call going in blind and failing at the individual-request level — the exact pattern #194 showed against an old v1.9.1. Worth designing alongside this.