docs: publish stable v3 migration playbook

[olliethedev]

Closes #175

Summary

• expands the canonical breaking-changes page into the stable-v3 production migration playbook
• documents the final constructor, plugin, auth, trust, hydration, framework, embedded-surface, and Better Auth UI contracts
• centralizes atomic-write transaction guidance for Prisma, Drizzle, and Kysely adapters
• distinguishes the immutable public RC3 artifacts from the forthcoming RC4/stable Codegen behavior
• adds the release-maintainer clean-room and snippet verification gate

Validation

• pnpm build
• pnpm typecheck
• pnpm lint
• pnpm --dir docs build
• internal link audit: 15 links across both changed pages
• targeted auth/constructor/hydration tests: 13 passed
• Codegen scaffold and passthrough tests: 96 passed
• packed-consumer harness: 8 passed
• four actual packed consumer smokes: core/auth × npm/pnpm
• clean Better Auth UI fixtures: Next.js, React Router, and TanStack Start built and typechecked
• final Standards review: no findings
• final Spec review: no findings

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated
better-stack-docs	Ignored		Aug 31, 2026 11:51pm UTC
better-stack-playground	Ignored		Aug 31, 2026 11:51pm UTC

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-31T23:58:47.985278Z	fd7a949	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fd7a949ce7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Pin the core peer cohort in the install command

When the migrating app does not already declare the Better Auth/DB peers, this example does not actually pin the documented cohort: @btst/db@2.2.3 requires exact better-auth, @better-auth/core, and @better-auth/utils peers, while Stack requires better-call@1.3.6. With peer auto-installation disabled this command fails, and with it enabled pnpm repairs the graph implicitly, contrary to the surrounding exact-cohort guidance. The repository's CORE_DEPENDENCIES packed-consumer fixture installs these packages directly, so this command should include the non-companion core cohort too.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Make the authorization example enforce the authorized snapshot

When a post's ownership can change between facts() and execute()—for example through another administrative workflow—the caller is authorized using the old authorId, but this delete matches only id and can remove the newly transferred record. Since this is the representative example immediately following the warning about server-derived authoritative facts, copied implementations inherit a TOCTOU authorization flaw; the write should re-read and compare/claim the authorized snapshot inside an isolated transaction or include the authorized ownership state in an atomic write precondition.

Useful? React with 👍 / 👎.