#305 docs: GET /api/runs — generic run-status resource

Implements the docs row of recoupable/chat#1973 — the contract for the caller's background-run status.

• GET /api/runs added to releases.json (the spec file that owns /api/valuation): kind required (valuation is the only enum value today — future kinds are new enum values, not new endpoints), limit default 1 / max 20, newest first, 400 on unknown kind, 401 unauthenticated (shared error schema).
• ValuationRun schema: opaque id, kind, domain-phase state (queued | measuring | claimed | failed — deliberately not storage values, per the issue's run-resource decision so a future workflow backend swaps in without a contract change), album_count, created_at, result.catalog_id | null.
• Reference page api-reference/songs/runs.mdx + nav entry beside Run Valuation (surfaces it in llms.txt).
• One contract refinement vs the issue sketch, per accuracy-over-symmetry: no spotify_artist_id field — playcount_snapshots doesn't record it, so v1 run status is account-scoped; documenting it would be documented-but-false. Noted on the issue.
• Spec edits are anchored text inserts (the file doesn't round-trip json.dumps byte-identically); result re-validated as JSON.

Merge order: this PR → [api#TBD] (implementation) → chat PRs. Field-for-field reconciliation against the live api preview happens on the api PR before either merges.

🤖 Generated with Claude Code

---

Summary by cubic

Documents a new generic run-status resource at GET /api/runs so clients can list and poll background runs by kind. Previously there was no consolidated endpoint; now one endpoint covers valuation runs and can expand by enum.

• Adds GET /api/runs to releases.json: requires kind (valuation today), optional limit (default 1, max 20), newest first; 400 for unknown kind or invalid limit; 401 when unauthenticated; 200 returns GetRunsResponse with status, runs, and optional error.
• Adds ValuationRun schema: opaque id, kind, domain-phase state (queued | measuring | claimed | failed), album_count, created_at, and result.catalog_id | null (set when claimed). States name domain phases, not storage values.
• Omits spotify_artist_id (v1 run status is account-scoped).
• Adds reference page api-reference/songs/runs.mdx and nav entry in docs.json.

Client actions

• Pass kind=valuation; set limit up to 20.
• Treat id as opaque. Drive UI from state; use result.catalog_id when claimed. Handle failed gracefully.
• Do not expect a spotify_artist_id field in run status.

Summary by CodeRabbit

• New Features

  • Added an authenticated API endpoint for listing valuation runs.
  • Supports filtering by valuation type and retrieving up to 20 runs in newest-first order.
  • Responses include run status, metadata, optional catalog results, and error details.

• Documentation

  • Added API reference documentation for retrieving runs.
  • Added the new endpoint to the Catalogs navigation.