docs(v3): publish canonical DX migration guide

.agents/skills/btst-backend-plugin-dev/REFERENCE.md

@@ -3,30 +3,34 @@
 ## defineBackendPlugin shape (api/plugin.ts)
 
 ```typescript
-export const myBackendPlugin = defineBackendPlugin({
-  name: "my-plugin",
-  dbPlugin: dbSchema,
-  operations: (adapter) => ({
-    createItem: defineOperation({
-      input: CreateItemSchema,
-      permission: itemPermissions.item.create,
-      facts: () => undefined,
-      execute: ({ input }) => createItem(adapter, input),
+/** Configuration accepted by `myBackendPlugin`. */
+export interface MyBackendPluginOptions {
+  /** Lifecycle callbacks composed around plugin operations. */
+  hooks?: MyBackendHooks
+}
+
+export const myBackendPlugin = (options: MyBackendPluginOptions = {}) =>
+  defineBackendPlugin({
+    id: "myPlugin",
+    dbPlugin: dbSchema,
+    operations: (adapter) => createMyOperations(adapter, options.hooks),
+    raw: (adapter) => ({
+      prefetchForRoute: createItemPrefetchForRoute(adapter),
     }),
-  }),
-  raw: (adapter) => ({
-    prefetchForRoute: createItemPrefetchForRoute(adapter),
-  }),
-  routes: (_adapter, _context, operations) => ({
-    createItem: createEndpoint(
-      "/items",
-      { method: "POST", body: CreateItemSchema, requireRequest: true },
-      operations.createItem.route((ctx) => ctx.body),
-    ),
-  }),
-})
+    routes: (_adapter, _context, operations) => {
+      const createItem = createEndpoint(
+        "/items",
+        { method: "POST", body: CreateItemSchema, requireRequest: true },
+        operations.createItem.route((ctx) => ctx.body),
+      )
+      return { createItem } as const
+    },
+  })
 
-export type MyApiRouter = ReturnType<typeof myBackendPlugin.routes>
+/** Inferred router contract imported by the client plugin. */
+export type MyApiRouter = ReturnType<
+  ReturnType<typeof myBackendPlugin>["routes"]
+>
 ```
 
 ## getters.ts
@@ -114,16 +118,16 @@ export { serializeItem } from "./serializers"
 
 Invoke domain hooks from the operation lifecycle after authorization. Hooks can enforce domain invariants, publish side effects, and observe errors; they are not the authorization policy.
 
-## Plugin stack() wiring (in stack.ts)
+## Plugin `createBackendStack()` wiring (in stack.ts)
 
 ```typescript
-import { stack } from "@btst/stack"
+import { createBackendStack } from "@btst/stack/api"
 import { myBackendPlugin } from "./src/plugins/my-plugin/api/plugin"
 
-export const myStack = stack({
+export const myStack = createBackendStack({
   basePath: "/api/data",
   plugins: {
-    myPlugin: myBackendPlugin,
+    myPlugin: myBackendPlugin(),
   },
   adapter: (db) => createDrizzleAdapter(schema, db, {}),
 })

.agents/skills/btst-backend-plugin-dev/SKILL.md

@@ -25,7 +25,7 @@ src/plugins/{name}/
 - **`api/index.ts`** — re-export everything from getters + mutations for direct server-side import.
 - **`operations.ts`** — define the one maintained business inventory with input validation, exact permission descriptors, authoritative facts, domain execution, and lifecycle hooks.
 - Bind HTTP routes to same-key operations. Use `operationRouteMap` only for real route-name mismatches.
-- The optional `raw` factory is narrow: first-party plugins expose only `prefetchForRoute` for SSG. Do not duplicate business getters or mutations on `stack().raw`.
+- The optional `raw` factory is narrow: first-party plugins expose only `prefetchForRoute` for SSG. Do not duplicate business getters or mutations on `createBackendStack().raw`.
 - Use `myStack.forRequest(request).operations.*` for request work and `myStack.trusted.*` for explicitly trusted jobs.
 
 ## Key patterns
@@ -61,7 +61,9 @@ already support.
 `myStack` is a module-level const. The `execute` closure runs lazily (only on HTTP request), so `myStack` is always initialised by then:
 
 ```typescript
-export const myStack = stack({ ... })
+import { createBackendStack } from "@btst/stack/api"
+
+export const myStack = createBackendStack({ ... })
 
 const myTool = tool({
   execute: async (params) => {
@@ -80,7 +82,7 @@ const myTool = tool({
 - **Wrong adapter type** — use `import type { DBAdapter as Adapter } from "@btst/db"` in getters/mutations/plugin files.
 - **`"GET /path"` string keys** — routes use `createEndpoint()`, not string-keyed method/path objects.
 - **`ctx.json()`** — does not exist; return data directly from route handlers.
-- **Business methods on `stack().raw`** — do not add them. Keep the composed lifecycle explicit through `forRequest(request).operations` or `trusted`, and reserve `raw` for narrow lower-level/SSG helpers.
+- **Business methods on `createBackendStack().raw`** — do not add them. Keep the composed lifecycle explicit through `forRequest(request).operations` or `trusted`, and reserve `raw` for narrow lower-level/SSG helpers.
 - **Authorization in lifecycle hooks** — routine access control belongs in operation descriptors and the one shared rule. Hooks receive already-authorized context.
 - **Write ops in `getters.ts`** — write functions belong in `mutations.ts`, not `getters.ts`.
 

.agents/skills/btst-build-config/SKILL.md

@@ -117,21 +117,14 @@ built-in plugin override. Configure `api`, `site`, and `queryClient` once in
 accept only plugin-specific options; their loaders and metadata receive shared
 runtime through the stack resolver.
 
-### Override type registration (in each layout)
-
-```typescript
-import type { YourPluginOverrides } from "@btst/stack/plugins/{name}/client"
-
-type LegacyPluginOverrides = {
-  "{name}": YourPluginOverrides,
-}
-```
+### Override type inference
 
 Resolved definitions contribute their public override type automatically under
-their canonical programmatic ID (`blog`, `aiChat`). Keep a manual map only for
-an unmigrated compatibility plugin, and delete it when that plugin adopts the
-resolved contract. Do not recreate removed v2 framework, API, guard, or identity
-fields in local intersection types.
+their canonical programmatic ID (`blog`, `aiChat`). Register the definition in
+`createClientStack({ plugins })` and pass that resolved stack to
+`StackProvider`; never recreate a manual application override map or provider
+generic. Do not restore removed framework, API, guard, or identity fields in
+local intersection types.
 
 ## Adding shared UI components (@workspace/ui)
 

.agents/skills/btst-client-plugin-dev/REFERENCE.md

@@ -132,7 +132,7 @@ export function createMyQueryKeys(client: ResourceClient, headers?: HeadersInit)
 ## Programmatic id (client/constants.ts)
 
 ```typescript
-export const MY_PLUGIN_ID = "my-plugin" as const
+export const MY_PLUGIN_ID = "myPlugin" as const
 ```
 
 ## defineClientPlugin shape (client/plugin.tsx)