[Reconciliation][P2] Restore the comments workflow and reconcile eleven stale API operations #327

Parent workstream: #320
Epic: #318

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

Outcome and problem

The audited reference advertises six obsolete ElevenLabs POST operations, POST/DELETE artist pin, GET comments, GET admin agent-signups, and POST songs without matching operations in the API snapshot. Marketing generates pages for the six old music operations even when they are absent from navigation. Current music generation uses POST /api/music; songs exposes GET only.

Scope and ownership

• Restore authenticated, account-scoped access to stored comments and the fan-recency user outcome through existing app#2023, or a documented existing API alternative that satisfies that outcome. Preserve the original implementation tracker.
• Pinning is already supported by PATCH /api/artists/{id} with pinned: true/false. Replace the stale POST/DELETE /api/artists/{id}/pin examples with that operation rather than implement duplicate routes.
• Retire or replace the six old ElevenLabs music paths in favor of the current POST /api/music contract. Record any independently valuable lost capability, such as stem separation, as a separate product requirement; generic music generation is not evidence that each old specialized feature is equivalent.
• Decide the intended supported workflow for POST /api/songs and GET /api/admins/agent/signups. Do not invent a write/admin API solely to satisfy old documentation.
• Reconcile unsupported schemas, examples, generated endpoint pages, navigation and LLM indexes together. Interim availability corrections are allowed while important implementation gaps remain open.

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

Acceptance criteria

• The eleven method/path pairs are reconciled against an exported-handler inventory; dynamic GET /api/music/{generationId} is not accepted as evidence for any missing POST.
• Generated site and LLM navigation no longer advertise retired operations as available.
• Comments/fan-recency acceptance remains open until the original user workflow succeeds through an authorized, scoped API; deleting the page alone does not resolve app#2023.
• Pin/unpin examples use PATCH and preserve the authenticated account's pin preference.
• Each remaining operation has a specific implement/replace/retire disposition and links its owner/tracker.
• Published comments/admin-signup pages and music discovery are spot-checked after release without issuing paid or destructive requests.

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
• Source evidence 4
• Source evidence 5
• Source evidence 6
• Source evidence 7
• Source evidence 8
• Source evidence 9
• Source evidence 10
• Source evidence 11

Current pin implementation:

• https://github.com/recoupable/api/blob/c72887a212c506143ef9974143433ac7e7cba81b/lib/artists/validateUpdateArtistRequest.ts
• https://github.com/recoupable/api/blob/c72887a212c506143ef9974143433ac7e7cba81b/lib/artists/updateArtistHandler.ts

Related existing work:

• feat(music): POST /api/music generates songs with MiniMax Music 3 api#848
• docs(music): contract for music generation with MiniMax Music 3 docs#308
• docs(music): correct the contract to what the API returns docs#309
• GET /api/comments is documented but has no route (HTML 404 on prod) app#2023

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

Pin/unpin now use the implemented PATCH /api/artists/{id} with pinned true/false; both stale /pin operations are removed from the spec. The remaining ten unmatched references are explicitly pending: GET /api/admins/agent/signups, GET /api/catalogs/{catalogId}/valuations, GET /api/comments, POST /api/songs, and POST /api/music/{compose,compose/detailed,plan,stem-separation,stream,video-to-music}. Source absence is not a missing-feature count or proof that local/skill workflows are gone. Retained outcomes remain open for restoration, a supported replacement, or an explicit disposition.

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.

Customer outcome: show when a fan last commented — October 20, 2026

Customer: a manager preparing a weekly fan report. “Show when we last heard from this fan; if we do not have evidence, say unknown.”

Implemented and source-released: API #1057 returns last_comment_at only from a stored linked comment whose author matches the returned fan. Missing/mismatched evidence stays null; profile refresh and generic engagement dates are not substitutes. API #1058 and #1061 complete the public response fixture/standard-null guard; actual #1061 merge is 52a2e218bffdea2b69c0f8a8ba075202b08754d0. All 78 fan/contract cases pass within mocked service boundaries.

Main reference published: Marketing #197 merged as 872337abf19481678279d96e3766900009dab30c, after exact-head independent acceptance and actual-API source-reference checks. Normal HTML, Markdown and the complete Releases specification pass public readback. The optional date uses standard string/null types, preserves the unknown example and explains stored-evidence limits.

Retained publication ready for independent review: Docs #386 at 77e94d67fc539be74f02fc02f3170270a5421f54 is generated from that actual Marketing merge. All 238 files/hashes/navigation verify. Only Releases specification/provenance differ; the completed billing guide, Accounts reference and host controls are unchanged. Source checker/integrity regression and current source-provenance CI pass.

Independent review now passes: UI accepts exact 77e94d67fc539be74f02fc02f3170270a5421f54 for semantics, all 238 source mappings and current exact-head CI. Complete receipt is reproduced in Docs #386's description. The optional-property suggestion was independently declined; CodeRabbit withdrew it and resolved the thread. Remaining: coordinator merge of Docs #386 and automatic retained-host HTML/Markdown/spec/source-pin readback. No real customer fans or live weekly report were tested. This does not restore GET /api/comments, return comment bodies, prove exhaustive history or complete the other operations in this ticket. Valuation history remains separate.

Fan-date documentation published — October 20, 2026

Docs #386 is verified merged as 80470b41b72550270b9430b53b990a0c9a827603 at 14:19:39 UTC from independently accepted 77e94d67. Actual merge CI and Mintlify deployment succeed. Normal retained-host HTML, Markdown, complete Releases specification and source-provenance readback all pass at 14:23:02 UTC. The entire served specification and all 238 source hashes match actual Marketing 872337ab; the optional string/null field, matching-author evidence limits and known/unknown examples are preserved. Canonical HTML/Markdown/specification had already passed.

The initial older HTML/Markdown/spec/pin responses are preserved separately. Automatic publication settled without cache bypass, purge, host-control changes or manual deployment. A Markdown verification assertion initially missed a sentence because YAML wrapped it; the check now normalizes whitespace, and an explicit supplement proves the original intended statements were present. This was a local verification correction, not a product-content change.

Completed slice: the supported fan-date contract is published on both sites. Still open: the original authorized customer report, comments-body capability and other specialized-operation decisions in this ticket. No real customer fan read, paid/provider action or exhaustive history is claimed. Final receipt: .local/audits/recoup-reconciliation-2026-10-10/fan-date-docs/publication-retained-20261020T142302Z/readback.json.