[v3 DX] Publish the complete canonical DX and migration guide

[olliethedev]

Parent

• #202 — Centralize client runtime configuration and normalize all plugin interfaces

What to build

Update every maintained consumer-facing source of truth to the finalized #202 API: README, installation/how-it-works/API reference, breaking-changes guide, every plugin page, plugin-authoring documentation, CLI/registry guidance, contributing guidance and applicable BTST agent skills.

Publish one mechanical before/after migration path covering:

• stack / createStackClient → createBackendStack / createClientStack;
• duplicated client factory/provider runtime → one client stack api, site, queryClient, request headers and browser projection;
• manual provider generics/maps → inference from registered client definitions;
• kebab-case programmatic plugin IDs → canonical camelCase IDs (without changing package/URL slugs);
• positional/flat backend options → one options object with nested hooks;
• every lifecycle callback old name → canonical new name;
• ambiguous api / internal surfaces → forRequest(request).operations, trusted, raw.

Use the structured hook mappings produced by the lifecycle tickets rather than reconstructing an incomplete table manually.

Required canonical example

const clientStack = createClientStack({
  api: { baseURL, basePath: "/api/data" },
  site: { baseURL, basePath: "/pages" },
  queryClient,
  plugins: {
    blog: blogClientPlugin(),
  },
})

<StackProvider
  stack={clientStack}
  router={router}
  auth={clientAuth}
  initialIdentity={initialIdentity}
  overrides={{ blog: { uploadImage } }}
>
  {children}
</StackProvider>

Explain that server/SSR helpers construct a separate request-specific client stack with request headers. Explain initialIdentity precisely: undefined means no snapshot was supplied, null is an explicitly hydrated anonymous identity, and an object is an authenticated snapshot.

Acceptance criteria

• All maintained docs/examples use only canonical constructors, runtime ownership, provider inference, camelCase programmatic IDs, factory shapes, lifecycle names and trust surfaces.
• The migration guide includes concise before/after snippets for every breaking category listed above.
• A complete old-to-new lifecycle table covers every renamed callback in AI Chat, Blog, CMS, Comments, Form Builder, Kanban and Media.
• Plugin docs preserve all real required configuration (AI model/tools/mode, CMS content types, Comments behavior/user resolution, Kanban user resolution/search, Media storage/tenant/upload, OpenAPI options).
• Docs explicitly describe OpenAPI as backend-only, Route Docs as client-only and UI Builder as client-only over CMS.
• Endpoint docs distinguish same-origin path inheritance, complete endpoint replacement, cross-origin sensitive-header isolation and the requirement to implement the BTST plugin HTTP contract.
• Provider docs keep router, auth, notify and i18n as framework/runtime services and plugin overrides as genuine browser customization.
• Authorization docs retain schema-bound rules, permissive omitted server auth, authoritative enabled auth, trusted-fact derivation, request/trusted/raw distinctions and tri-state identity hydration.
• Better Auth or Better Auth UI is not presented as a core dependency or hidden identity bridge; companion migration is downstream of [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202.
• A repository-level guard checks maintained examples/generated sources for removed constructors, duplicated runtime fields, old programmatic IDs, manual override maps/generics, positional/flat backend forms, removed hook names and ambiguous server namespaces.
• The guard excludes only explicit migration-guide “before” blocks or dedicated negative fixtures using narrow, documented markers.
• API reference extraction/type tables resolve canonical declaration names and docs production build succeeds.
• Applicable local BTST skills describe the canonical APIs so future agents do not restore removed shapes.

Non-goals

• Do not restore Better Auth UI CLI/docs scaffolding in this ticket; that migration is intentionally blocked on completed [v3 RC3 DX] Centralize client runtime configuration and normalize all plugin interfaces #202.
• Do not perform external better-stack-web or Bio Mogging RC3 validation.

Blocked by

• #223 — Migrate generated integrations, playground and registry to the canonical stack DX