[Reconciliation][P2] Align Sites publishing and lifecycle documentation with the paid publication gate #330

Parent workstream: #320
Epic: #318

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

Outcome and problem

The guide says unpaid workspaces can publish with email signup, but prepareSiteFanConnection in the audited API returns 402 before publication. The guide also omits newer deletion and generation-token behavior. Some Sites routes are provider callbacks or covered in prose, so the raw route count does not establish that every route belongs in a public OpenAPI spec.

Scope and ownership

• Replace the obsolete free-publishing flow with the actual subscription requirement and 402 contract.
• Document supported deletion/cancellation and revision/generation-token behavior using current mutation schemas.
• Curate the publicly supported Sites operations and separate their documentation from provider callbacks or internal routes.
• Coordinate the guide/spec publication with API#942, #958 and #959 behavior.

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

Acceptance criteria

• Guide examples no longer promise publication before the required subscription gate.
• Mutation examples and errors match the released schema, including revision-bound deletion/cancellation and generationToken publication.
• Public operation coverage is explicitly enumerated, with intentional exclusions recorded rather than blindly publishing all routes.
• A contract fixture verifies upgrade/error and lifecycle cases; published pages are checked without claiming an unperformed live 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
• Source evidence 4

Related existing work:

• Document paid Spotify fan connection for external site builders docs#347
• Require a paid subscription to publish any site api#942
• Add authorized site deletion and stop deleted builds api#958
• Allow publishing working site previews independently of review api#959

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 lifecycle reference adds PATCH /api/sites/{id} with action delete, a JSON-body example, expected revision, optional generationToken cancellation, and the deleted/id receipt. Omitting the token does not cancel all jobs. Paid publish behavior remains as previously documented; no real publish/delete was performed for this doc fix.

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.