PR #34 - recoupable/docs

What

Documents three API changes. These pages should merge after the API PRs they describe.

API PR	Change	Docs here
recoupable/api#1226	`POST /api/songs/analyze`: `full_report` returns `status: "success" \| "partial"` with `failed[]`, 502 bodies, M4A/AAC/OGG/WebM input	`analyze` reference page and OpenAPI: updated schemas, 502 response, request/response examples, report-key retry table
recoupable/api#1227	New `POST /api/songs/analyze/batch`: up to 40 prompts on one audio download, one base price plus seconds	New `analyze-batch` page and OpenAPI operation
recoupable/api#1228 (on #1225)	`POST /api/songs/moments` gains `tempo_hint` and the extended measurement	New `moments` page and OpenAPI operation (the endpoint had no page yet)

Each of the three pages has a short "Which to use" section (single preset vs batch vs moments). Pricing lines match the single-call wording already in the docs: $0.05 per model call plus $0.001166 per second; batch pays the base once; moments is $0.01 per song plus the analyze rate per described moment ($0.36 gate with the default describe: true). credits.mdx has rows for both new endpoints.

Request and response examples were checked against the code: Zod messages and paths for the 400 examples, the credit gates for the 402 examples, the tempo reconcile text, and the edit-point names and notes. The moments response example is a synthetic song whose sections, moments, cuts, bands, fingerprint and edit points are consistent with each other.

Before merging

Pending markers. The batch and moments operations carry x-recoup-availability: pending (the contract inventory records them as unmatched, pending) and a pending warning on their pages. Remove both once the API PRs are merged and the pin below is refreshed.
Fixture and pin (coordinated, like earlier hash changes). This PR changes releases.json and credits.mdx, whose hashes are recorded in content/docs/contracts/example-cases.json. The build-contract-examples.py --check step compares that file with lib/contracts/fixtures/published-docs.json in the pinned API checkout, so it stays red until the API repo carries the same file and apiSourceCommit in operation-inventory.json is bumped to the merged commit. The file to copy is this PR's content/docs/contracts/example-cases.json. Then re-run python3 scripts/refresh-contract-inventory.py --api <checkout> and pnpm docs:build.
#1227 currently shows as closed on GitHub (its base branch codex/analyze-m4a was deleted when #1226 merged); the docs describe its contract from branch codex/analyze-batch at 51c2b873.

Also changed

The analyze operation description no longer names the third-party model or links its announcement; it says "an audio language model".

Checks

pnpm docs:build, pnpm docs:check, pnpm test (145), pnpm type-check, pnpm lint, pnpm build all pass. refresh-contract-inventory.py --check passes against an API checkout at the pinned commit. build-contract-examples.py --check passes only against an API checkout whose fixture was refreshed (see above).

🤖 Generated with Claude Code

Summary by cubic

Documents three API changes in the OpenAPI source, song reference pages, contract fixtures, and the credits page: partial full_report status on POST /api/songs/analyze, the new POST /api/songs/analyze/batch endpoint, and the extended measurement on POST /api/songs/moments.

Changes

The analyze page now covers status: "partial" with failed[], 502 bodies, M4A/AAC/OGG/WebM input, and a table mapping each failed report section to the preset that retries it.
New analyze-batch and moments pages document limits, moment types, measurement fields, and pricing that matches the existing single-call wording.
Both new operations are marked pending (x-recoup-availability) with page warnings until their API PRs merge, and the analyze operation description no longer names the third-party model.
The contract inventory now pins the API revision (apiSourceCommit) that serves batch and moments.

Before merging

Remove the pending markers and warnings once the API PRs ship.
build-contract-examples.py --check stays red until the pinned API checkout carries this PR's example-cases.json; the apiSourceCommit pin is already updated.