[Reconciliation][P2] Match CLI validation and public command examples to the shipped API #355

Parent workstream: #320
Epic: #318

Priority: P2 · Audit findings: W1

Outcome and problem

The CLI guide teaches --room-id instead of implemented --chat-id, marks optional subject required, describes unsupported metadata-only song analysis, calls estimation POST instead of GET, and states a version/default host that differs from source. The CLI also accepts missing audio or simultaneous preset and prompt before sending a request the API rejects, and its README omits shipped command groups.

Scope and ownership

• Owning repositories: recoupable/cli, recoupable/docs and recoupable/marketing for the currently published docs copy.
• Correct email, song-analysis and content-estimate examples in both active docs trees and the CLI README.
• Enforce required audio and exactly one of preset or prompt in the CLI before its network call, matching the shared API/MCP schema.
• Choose and document the intended default API host, keep environment overrides working, and verify the published npm version before claiming its current value.
• Cover shipped songs/emails/tasks/content command groups from registered commands or generated help; reconcile relevant work in open CLI PR Add marketing and admin submodules #23 rather than assuming it has shipped.

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

Acceptance criteria

• Documented email commands parse using --chat-id; the optional subject behavior matches the actual command.
• Missing audio, missing both analysis modes, or supplying both preset and prompt exits with a clear local error before any HTTP request; valid examples produce the expected body.
• Content estimation examples use GET and match the CLI request method.
• The guide's version/default-host claim is verified against the selected published release or clearly labeled source-only; legacy-host availability is not asserted without verification.
• README/help command coverage includes all registered command groups and documented environment overrides.
• Parser/client tests with network stubs execute the maintained examples without sending email, generating media or spending credits; CLI build/test checks and active published docs readback pass.

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

Related existing work:

• feat(songs): require audio_url on POST /api/songs/analyze, verified before any Modal call (422) api#907 — required-audio contract already merged.
• feat: expand CLI to full API parity (agent-first) cli#23 — open CLI work; inspect current diff and scope before reuse.

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

CLI #26 fixes the underlying analysis validation: exactly one preset/prompt plus audio, with no HTTP call on invalid input. 77 tests, bundle and TypeScript checking pass; CI now checks types. Docs correct optional subject, chat-id, required audio, installed-version caveat, actual source base URL, and GET estimate examples using existing lipsync/batch/compare options. Estimate command code was already correct. CLI #23 remains separate broader expansion work. Package publication and installed-binary readback remain after-merge gates.

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: Source and docs correction are merged. Keep this ticket open until npm credentials are repaired, a new version is actually published, and the downloaded/installed registry binary passes local invalid-request checks. CLI #23 remains open as separate broader command expansion work.

Internal executable verification added — October 18, 2026

Skills #200 merged at 3b12ce7eecc732aaaf850875953e9a73ee45dab0, adding recoup-internal-dev-verify-cli. The implementation record reports seven cases against compiled CLI source 805a2ff2a922bcb806894e6387989d6751c549a2, exact loopback request/output evidence, isolated dummy credentials, cleanup and 11 helper regressions.

The backend is replaced by a local fixture. This does not prove live sign-in, organization access, npm publication or installation of a registry release; the internal skill is not a new customer-package capability. The older registry/publishing observations above retain their original dates and were not refreshed by these fixture tests. Keep the original package-publication and installed-binary acceptance open until fresh registry evidence is attached. No token, charge or publication operation was used in this refresh.