[Reconciliation][P2] Document the supported 366-day catalog stream-history range #331

Parent workstream: #320
Epic: #318

Priority: P2 · Audit findings: API-DOC-07

Outcome and problem

GET /api/catalogs/{catalogId}/streams is documented with maximum 31 days while the audited validator and MCP tool support 1–366. Generated clients or forms may reject valid longer comparisons. The separate Spotify playcount endpoint intentionally retains its 31-day limit.

Scope and ownership

• Update only catalog stream-history days constraints and examples.
• Preserve the distinct Spotify playcount limit and existing completeness/provenance caveats.
• Document paging/performance considerations without implying historical data was backfilled.
• Propagate the corrected contract to both public documentation surfaces under the maintained-source workflow.

Planning is tracked in Mono. Implementation and release PRs belong in the owning repositories under their current branch rules.

Acceptance criteria

• Stream-history schema accepts 1 and 366 and rejects 0 and 367, matching the released validator.
• The independent playcount contract still rejects values above 31.
• A 90-day or year-long example is present with accurate coverage caveats.
• Rendered forms/spec downloads and LLM discovery show the corrected bound after publication.

Evidence and existing work

Baseline: October 10, 2026 audit of July 10–October 10 merges. Recheck current source and existing tracker comments before implementation. Source findings do not establish authenticated production behavior.

• Source evidence 1
• Source evidence 2
• Source evidence 3

Related existing work:

• Document daily catalog stream tracking and history docs#354
• Support year-long saved catalog stream comparisons api#997

Continue or reconcile the linked implementation work; this ticket owns the stated audit correction and does not replace the original feature tracker.

Source corrections released — October 12, 2026

The streams history parameter now accepts 1–366 days with a 90-day example and coverage/paging caveats. The separate playcount limit stays 31. The contract guard compares the accepted maximum and maximum+1 against the actual validator. Published forms/spec/LLM readback remains a release gate.

All five approved source PRs are merged: API #1032, Marketing #152, Docs #373, CLI #26, and App #2242. Mono #373 records the five source references at e650245fe3267a08b94abbb75dc30a8a4108c020. The immutable provenance chain is API 0a590490c0e005045e4cbf399fe552dc41e6b9a3 → Marketing 62cc352c4c90d4578bea4352001fc459b7566e1b → Docs fa6dc9e761056066299dde4525552b0d14442f1f. App source is d13bdcb7b112ff0ed8d9d243ae7c6fd56f9a80d4; CLI source is a11bff0a36e339e94ad6921e55d82ec9472d0e35.

Verified publication: API, App and Marketing main checks pass and their canonical Vercel aliases are READY at those actual merge commits. All 231 merged Docs files/navigation match Marketing. Five representative Markdown pages pass on both public hosts; all 12 downloadable split specs on both hosts exactly match source. Canonical Marketing human pages and both LLM catalogs pass. Both human catalog pages show the 1–366 range; the separate playcount maximum remains 31.

Remaining release gates: CLI build/typecheck/77 tests passed, but npm publication failed with HTTP 404; the registry still serves 0.1.15. The release bot bumped source to 0.1.16 without publishing it. A valid NPM_TOKEN replacement and installed-registry-package verification are required; no token value belongs in an issue. Retained-host normal /llms-full.txt still returns cached v0.1.13/--room-id guidance (cf-cache-status: HIT, max-age=86400); a cache-busted read shows the corrected CLI/Context/Sites content. Its human /mcp still returns 405. Docs main's Mintlify deployment succeeds, but these URL/cache problems are not thereby resolved. Mintlify connection/routing repair and host cutover remain explicitly deferred. No hosted Context, media, OAuth/client, or unresolved-feature acceptance is inferred from this source release.

Ticket acceptance update: First three range criteria are verified by actual validator fixtures and published source/examples. Canonical LLM content is current; retained aggregate discovery/cache compatibility remains tracked with #337 before complete dual-host acceptance.