[Reconciliation][P2] Complete the credits and subscription schema migration to three plans #344

Parent workstream: #322
Epic: #318

Priority: P2 · Audit findings: BILL-03

Outcome and problem

The credits guide and API include plan, task_limit and min_cadence_minutes, but AccountCreditsResponse omits them, keeps old-scale 87/100/13 examples and misses the used_credits clamp. SubscriptionResponse.isPro is documented as any active paid subscription even though paid Starter correctly returns false. The subscription response is a current-entitlement view that can return status none for inactive subscriptions, not complete lifecycle history.

Scope and ownership

• Docs/Marketing + API contracts: align credits response schema, units/examples, required plan fields and nullable unlimited task_limit with the current builder.
• Define isPro as Pro entitlement specifically and guide paid-plan consumers toward plan rather than the boolean.
• Clarify current-entitlement versus subscription-history behavior; change lifecycle semantics only if separately agreed, not by inference from stale enum wording.

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

Acceptance criteria

• The generated credits response schema includes plan, task_limit and min_cadence_minutes with correct required/nullability rules and micro-dollar examples.
• A balance above the plan allotment is documented and verified to produce used_credits=0.
• Examples cover Free, paid Starter with isPro=false, direct Pro and organization-derived Pro consistently with the source builder.
• Documentation states the inactive/current-entitlement response behavior explicitly and does not imply complete subscription lifecycle history.
• A focused response-schema check catches omission or nullability drift between the public schema and response fixtures.

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

Related existing work:

• feat(credits): cut the api over to six-decimal (micro-dollar) credits api#855
• feat(plans): three-plan entitlements, 402 plan_limit task gate, Starter checkout (app#2044 row 3) api#877
• docs(credits): balances and prices are US dollars; the ledger unit is integer micro-dollars docs#310
• docs(plans): plan entitlements contract: plan fields on credits, 402 plan_limit on tasks, plan on subscription sessions (app#2044 row 2) docs#324

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

Execution status — October 11, 2026

Documentation/schema migration released via Marketing #149 and Docs #372: Free/Starter/Pro plan, task_limit/min_cadence_minutes, micro-dollar examples, usage clamp and effective-Pro-only isPro guidance. Subscription status none has explicitly nullable billing fields in OpenAPI 3.1. This reconciles documentation with the existing response builders; no new entitlement behavior was introduced.

Credits, credits reference, subscription reference and full LLM content returned 200. One authenticated production credit read returned the documented plan/task/cadence fields; it does not cover all plan states.

Hosting work remains deferred by Sidney. October 12 readback now confirms the retained host publishes Research availability, its Markdown, research search Markdown and both LLM catalogs at HTTP 200, without research-provider branding. The human GET https://docs.recoupable.dev/mcp still returns 405; /mcp.md and the canonical Marketing human guide return 200. The October 11 restored-page 404s are historical rather than the current state of these checked pages. Final route/host compatibility and complete publication verification remain open.

Remaining acceptance: representative Free, paid Starter, direct/organization Pro and inactive response coverage, above-allotment clamp/response-fixture guards and retained Mintlify publication. Do not claim all entitlement samples were exercised.