feat: upgrade stable frameworks and migrate AI SDK 7

.github/actions/pack-auth-ui/action.yml

@@ -11,7 +11,7 @@ runs:
       uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
       with:
         repository: better-stack-ai/better-auth-ui
-        ref: 48ebf19cc598654e5a06296e808eb376c55a236a # Published 3.0.1 companion
+        ref: 8d4fc633f75defd06bfbef180ba4968ee316b0dd # Upstream 1.7.32; Auth 1.7.14 / Stack 5 compatibility
         path: .packed-consumer/better-auth-ui
     - name: Install and build Better Auth UI
       shell: bash

.github/workflows/release.yml

@@ -32,7 +32,7 @@ jobs:
           fetch-depth: 0
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
         with:
-          node-version: 22.22.1
+          node-version: 22.23.4
       - name: Verify exact release commit CI and deployments
         env:
           GH_TOKEN: ${{ github.token }}
@@ -65,7 +65,7 @@ jobs:
 
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
         with:
-          node-version: 22.22.1
+          node-version: 22.23.4
           registry-url: 'https://registry.npmjs.org'
 
       - name: Install npm with trusted publishing support

.nvmrc

@@ -1 +1 @@
-22.18.0
+22.23.4

docs/adr/0001-preserve-ui-primitives-during-upgrades.md

@@ -0,0 +1,3 @@
+# Preserve UI primitives during framework upgrades
+
+BTST's shared UI and generated application fixtures use Radix, while the playground uses Base UI. Keep those choices during framework and shadcn upgrades, reviewing upstream component changes while preserving existing APIs, behavior, and local customizations. Moving the shared components to Base UI would require a separate migration of component APIs and composition; [shadcn continues to support Radix](https://ui.shadcn.com/docs/changelog/2026-07-base-ui-default).

docs/adr/0002-stable-tanstack-node-server.md

@@ -0,0 +1,3 @@
+# Serve TanStack builds with a stable Node server
+
+Use TanStack Start's standard Vite output with stable `srvx` for codegen test servers and playground exports. Nitro 3 is still a prerelease, and its bundling previously required BTST to pin an older TanStack/Vite toolchain; keeping that dependency conflicts with the stable-release policy for this upgrade. Serve `/uploads/` from the writable `public` directory with a terminal 404 for missing files so that build-time copies cannot restore deleted uploads, and serve other static files from `dist/client` before delegating to the TanStack fetch handler.

docs/adr/0003-align-ai-and-auth-security-upgrades.md

@@ -0,0 +1,37 @@
+# Align AI and Auth dependency cohorts
+
+Upgrade the optional AI plugin to AI SDK 7 with `@ai-sdk/react` 4 and matching
+provider packages. This removes the AI SDK 5 dependency on Undici 5. Keep BTST's
+`systemPrompt` configuration, pass it as SDK instructions, and reject caller
+system/data messages before model execution. Keep existing history authorization,
+identity partitioning, transaction guards, and client tool execution behavior.
+Reconstruct each tool step from the SDK's initial and response messages before
+reapplying compaction, because SDK 7 carries message overrides into later steps.
+The AI plugin now requires Node 22; the current React 19, Next 15+, and React Router 7+ consumer contracts remain.
+
+Upgrade the DB/adapters/CLI together to the stable 3.0.1 patch prepared against
+published Better Auth/core 1.7.14 and utils 0.5.1. The published 3.0.0 packages pin
+Auth 1.7.6 exactly, so overriding their peers would not be a supported upgrade.
+The aligned patch also refreshes the vendored adapter fixes from upstream's exact
+stable tag and preserves BTST's memory transaction Date comparison patch.
+
+The DB patch is prepared in the Auth fork and must be published before this
+BTST dependency change can be installed from the public registry. Local validation
+uses the packed release artifacts. Review database schema/index migrations before
+applying them in existing applications.
+
+The Auth fork also fixes session-list pagination introduced in upstream 1.7.14.
+This fix affects the configuration combining secondary storage with
+`session.storeSessionInDatabase: true` and without
+`session.preserveSessionInDatabase: true`. The DB packages depend on official npm
+Better Auth, so publishing them does not ship this fork-only Auth fix. Avoid that
+configuration until the official package includes the correction; the default
+database session configuration is unaffected.
+
+The workspace pins the typography plugin's selector parser to patched 6.1.5 for
+[GHSA-rj75-hqrm-r3gf](https://github.com/advisories/GHSA-rj75-hqrm-r3gf).
+Two low-severity upstream findings remain: `rehype-katex` still requires KaTeX
+0.16, while the [KaTeX fix](https://github.com/advisories/GHSA-238p-pmpm-9mq7)
+starts at 0.18.2; `unbuild`'s Rollup resolver uses `deepmerge`, which has
+[no patched release](https://github.com/advisories/GHSA-gcqx-w48m-w2h4).
+Do not force a different KaTeX major or replace the build system in this upgrade.

docs/content/docs/cli.mdx

@@ -13,14 +13,17 @@ BTST has two CLI packages:
 - `@btst/cli` owns low-level DB schema generation and migrations
 
 `@btst/codegen generate` and `@btst/codegen migrate` run the aligned
-`@btst/cli@3.0.0` release in isolation. This avoids adding its dependency graph
+`@btst/cli@3.0.1` release in isolation. This avoids adding its dependency graph
 or competing `btst` binary to the application. The delegated CLI still loads
 the configuration, environment files, aliases, Better Auth adapter, and ORM
 peers from the application directory.
 
 ## Init (Codegen)
 
-Use `init` to scaffold BTST into an existing Next.js (App Router), React Router v7, or TanStack Start project:
+Use `init` to scaffold BTST into an existing Next.js (App Router), React Router v7/v8, or TanStack Start project.
+
+React Router v8 requires Node.js 22.22+ and React / React DOM 19.2.7+.
+React Router v7 remains supported with BTST’s existing React 19 consumer requirements.
 
 ```bash
 npx @btst/codegen init
@@ -71,7 +74,7 @@ npx @btst/codegen migrate --config=lib/stack.ts --database-url=postgres://...
 ```
 
 When a delegated command fails, fix the underlying issue and run the equivalent
-`npx @btst/cli@3.0.0 ...` command directly.
+`npx @btst/cli@3.0.1 ...` command directly.
 
 ## About Better DB
 
@@ -83,7 +86,7 @@ For v3 applications, prefer the codegen passthrough commands above. If a v2
 application lists `@btst/cli` in its dependencies, remove it during migration;
 the pinned one-off CLI keeps Better DB dependencies from polluting the consumer
 graph. You can still invoke the low-level CLI directly with
-`npx @btst/cli@3.0.0`.
+`npx @btst/cli@3.0.1`.
 
 ## Parameters
 
@@ -101,13 +104,13 @@ Generate database schemas for your ORM from your BTST `dbSchema`:
 <Tabs items={["prisma", "drizzle", "kysely"]}>
   <Tab value="prisma">
     ```bash
-    npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma
+    npx @btst/cli@3.0.1 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma
     ```
   </Tab>
 
   <Tab value="drizzle">
     ```bash
-    npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=drizzle --output=src/db/schema.ts
+    npx @btst/cli@3.0.1 generate --config=lib/stack.ts --orm=drizzle --output=src/db/schema.ts
     ```
   </Tab>
 
@@ -117,17 +120,17 @@ Generate database schemas for your ORM from your BTST `dbSchema`:
     **Using DATABASE_URL environment variable:**
 
     ```bash
-    DATABASE_URL=sqlite:./dev.db npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql
+    DATABASE_URL=sqlite:./dev.db npx @btst/cli@3.0.1 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql
     ```
 
     **Or using --database-url flag:**
 
     ```bash
-    npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=sqlite:./dev.db
+    npx @btst/cli@3.0.1 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=sqlite:./dev.db
     ```
 
     ```bash
-    npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=postgres://user:pass@localhost:5432/db
+    npx @btst/cli@3.0.1 generate --config=lib/stack.ts --orm=kysely --output=migrations/schema.sql --database-url=postgres://user:pass@localhost:5432/db
     ```
   </Tab>
 </Tabs>
@@ -140,25 +143,25 @@ Migrate your database schema directly (Kysely only). For Prisma and Drizzle, use
 **Using DATABASE_URL environment variable:**
 
 ```bash
-DATABASE_URL=sqlite:./dev.db npx @btst/cli@3.0.0 migrate --config=lib/stack.ts
+DATABASE_URL=sqlite:./dev.db npx @btst/cli@3.0.1 migrate --config=lib/stack.ts
 ```
 
 **Or using --database-url flag:**
 
 ```bash
-npx @btst/cli@3.0.0 migrate --config=lib/stack.ts --database-url=sqlite:./dev.db
+npx @btst/cli@3.0.1 migrate --config=lib/stack.ts --database-url=sqlite:./dev.db
 ```
 
 ```bash
-npx @btst/cli@3.0.0 migrate --config=lib/stack.ts --database-url=postgres://user:pass@localhost:5432/db
+npx @btst/cli@3.0.1 migrate --config=lib/stack.ts --database-url=postgres://user:pass@localhost:5432/db
 ```
 
 ### Generate SQL to File
 
 Instead of running migrations directly, generate SQL to a file:
 
 ```bash
-npx @btst/cli@3.0.0 migrate --config=lib/stack.ts --output=migrations.sql --database-url=sqlite:./dev.db
+npx @btst/cli@3.0.1 migrate --config=lib/stack.ts --output=migrations.sql --database-url=sqlite:./dev.db
 ```
 
 ## Project config loading
@@ -179,5 +182,5 @@ project context as the application:
 You can still override a value for one command:
 
 ```bash
-SOME_VAR=value npx @btst/cli@3.0.0 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma
+SOME_VAR=value npx @btst/cli@3.0.1 generate --config=lib/stack.ts --orm=prisma --output=schema.prisma
 ```

docs/content/docs/installation.mdx

@@ -176,6 +176,21 @@ Or manually copy the [`SKILL.md`](https://github.com/better-stack-ai/better-stac
 
 ---
 
+## Database and AI upgrades
+
+Update `@btst/db`, your `@btst/adapter-*` package, and `@btst/cli` together to
+`3.0.1`. Their exact companion peers are `better-auth@1.7.14`,
+`@better-auth/core@1.7.14`, and `@better-auth/utils@0.5.1`. Remove overrides for older
+Auth versions. If your app uses Better Auth directly, review its 1.7 migration
+notes, regenerate your database schema, and review the resulting migrations
+before applying them. BTST's adapter helpers enable joins through
+`advanced.database.joins`; applications configuring Auth directly should use that
+option instead of `experimental.joins`.
+
+AI Chat now uses AI SDK 7, `@ai-sdk/react` 4, and matching provider packages
+(OpenAI: `@ai-sdk/openai` 4). This optional plugin requires Node.js 22 or later;
+see the [AI Chat installation guide](/plugins/ai-chat).
+
 ## Manual installation
 
 The steps below preserve the complete framework and adapter integration

docs/content/docs/meta.json

@@ -33,6 +33,7 @@
       "api-reference",
       "standalone-components",
       "shadcn-registry",
+      "v5",
       "breaking-changes",
       "---[Play]Playground---",
       "[Try the Playground](https://www.better-stack.ai/playground)"

docs/content/docs/plugins/ai-chat.mdx

@@ -15,6 +15,24 @@ import { PluginEvaluatorHeader } from "@/components/plugin-evaluator";
 Ensure you followed the general [framework installation guide](/installation) first.
 </Callout>
 
+The AI plugin uses AI SDK 7 and requires Node.js 22 or later. Install a matching
+React wrapper and provider package:
+
+```bash
+pnpm add ai@^7.0.155 @ai-sdk/react@^4.0.159 @ai-sdk/openai@^4.0.104
+```
+
+Keep `systemPrompt` in your backend plugin configuration. BTST sends it through
+the SDK's `instructions` option; chat requests accept only `user` and `assistant`
+messages. Existing stored message records remain readable.
+
+The default tool display recognizes approval and denied states. It does not
+approve tools automatically or provide approval controls; applications that use
+approval-required tools need their own approval flow. Existing page tools retain
+their configured execution behavior.
+
+For custom SDK integrations, follow the [AI SDK 7 migration guide](https://ai-sdk.dev/docs/migration-guides/migration-guide-7-0).
+
 Follow these steps to add the AI Chat plugin to your BTST setup.
 
 ### 1. Add Plugin to Backend API
@@ -88,7 +106,7 @@ const { handler, dbSchema } = createBackendStack({
       model: openai("gpt-4o"), // Or any LanguageModel from AI SDK
       access: "authorized", // Default; use "public" only intentionally
       systemPrompt: "You are a helpful assistant.", // Optional
-      tools: {}, // Optional: AI SDK v5 tools
+      tools: {}, // Optional: AI SDK 7 tools
     })
   },
   adapter: (db) => createMemoryAdapter(db)({})
@@ -379,10 +397,10 @@ inherits the stack's top-level `site` location.
 
 - **Full-page Layout**: Responsive chat interface with collapsible sidebar
 - **Conversation Sidebar**: View, rename, and delete past conversations
-- **Streaming Responses**: Real-time streaming of AI responses using AI SDK v5
+- **Streaming Responses**: Real-time streaming of AI responses using AI SDK 7
 - **Markdown Support**: Full markdown rendering with code highlighting
 - **File Uploads**: Attach images, PDFs, and text files to messages
-- **Tools Support**: Use AI SDK v5 tools for function calling
+- **Tools Support**: Use AI SDK 7 tools for function calling
 - **Customizable Models**: Use any LanguageModel from the AI SDK
 - **Typed Authorization**: Reuse the same schema-backed rules for browser hints and authoritative server checks
 - **Localization**: Customize all UI strings
@@ -900,7 +918,7 @@ aiChat: aiChatBackendPlugin({
 
 ### Adding Tools
 
-Use AI SDK v5 tools for function calling:
+Use AI SDK 7 tools for function calling:
 
 ```ts title="lib/stack.ts"
 import { tool } from "ai"

docs/content/docs/shadcn-registry.mdx

@@ -23,6 +23,11 @@ Installing a registry block copies React component source files into your projec
 
 ## Install a plugin's UI
 
+BTST registry components use Radix APIs. Shadcn now defaults to Base UI, so
+initialize a **new** registry consumer with `npx shadcn@latest init --base radix`.
+Keep existing primitive libraries and component customizations when upgrading an
+existing app; switching them is a separate migration.
+
 Pick the plugin you want to customize:
 
 <Cards>