diff --git a/.gitignore b/.gitignore
index 6cd1410a81..d974a2a963 100644
--- a/.gitignore
+++ b/.gitignore
@@ -40,3 +40,4 @@ next-env.d.ts
 # opensrc - source code for packages
 opensrc
 .env
+prisma-next/
diff --git a/apps/docs/content/docs/(index)/meta.json b/apps/docs/content/docs/(index)/meta.json
index 878f912fea..1737611716 100644
--- a/apps/docs/content/docs/(index)/meta.json
+++ b/apps/docs/content/docs/(index)/meta.json
@@ -5,6 +5,7 @@
     "---Getting Started---",
     "index",
     "getting-started",
+    "next",
     "---Prisma ORM---",
     "...prisma-orm",
     "---Prisma Postgres---",
diff --git a/apps/docs/content/docs/(index)/next/add-to-existing-project/meta.json b/apps/docs/content/docs/(index)/next/add-to-existing-project/meta.json
new file mode 100644
index 0000000000..84c814653c
--- /dev/null
+++ b/apps/docs/content/docs/(index)/next/add-to-existing-project/meta.json
@@ -0,0 +1,4 @@
+{
+  "title": "Add to Existing Project",
+  "pages": ["postgresql", "mongodb"]
+}
diff --git a/apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx b/apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx
new file mode 100644
index 0000000000..15dd0684c0
--- /dev/null
+++ b/apps/docs/content/docs/(index)/next/add-to-existing-project/mongodb.mdx
@@ -0,0 +1,186 @@
+---
+title: MongoDB
+description: Add Prisma Next to an existing MongoDB project.
+url: /next/add-to-existing-project/mongodb
+metaTitle: Add Prisma Next to an existing MongoDB project
+metaDescription: Add Prisma Next to an existing MongoDB project.
+---
+
+This guide shows how to add Prisma Next to a project that already uses MongoDB. You will initialize Prisma Next, describe the collections you want to work with, emit the generated artifacts, and run a couple of queries.
+
+:::warning[Prisma Next is still in development]
+
+Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today.
+
+:::
+
+## Prerequisites
+
+Before you start, make sure you can already reach the MongoDB deployment this project uses today.
+
+- Node.js 24 or newer
+- npm
+- An existing MongoDB 6.0 or newer deployment
+
+For local development, use a replica set. MongoDB Atlas already gives you that.
+
+## 1. Make sure you can run the example script
+
+If your project already runs TypeScript scripts, you can skip this step.
+
+Otherwise, install the script tooling:
+
+```npm
+npm install --save-dev tsx typescript
+```
+
+Later, `prisma-next init` will also add the Node.js types it needs and make sure the generated Prisma Next files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma Next leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app.
+
+## 2. Initialize Prisma Next
+
+From the root of your existing project, run:
+
+```npm
+npx prisma-next init --write-env
+```
+
+When Prisma Next asks a few setup questions:
+
+- choose `MongoDB`
+- choose `PSL`
+- keep the default schema path, `prisma/contract.prisma`
+
+## 3. Set your database connection string
+
+Update `.env` with the connection string for the MongoDB deployment your app already uses:
+
+```text title=".env"
+DATABASE_URL="mongodb://127.0.0.1:27017/my-app?replicaSet=rs0"
+```
+
+## 4. Describe the collections you want Prisma Next to know about
+
+This is the key adoption step for MongoDB, because you decide which part of the existing database Prisma Next should model first.
+
+PostgreSQL has `contract infer`. MongoDB does not, so this step is manual.
+
+Open `prisma/contract.prisma` and make it match the collections you want Prisma Next to query first. If your existing database already has `users` and `posts` collections with `email`, `name`, `title`, and `authorId`, the starter contract is already a useful first draft:
+
+```prisma title="prisma/contract.prisma"
+// use prisma-next
+
+model User {
+  id    ObjectId @id @map("_id")
+  email String   @unique
+  name  String?
+  posts Post[]
+  @@map("users")
+}
+
+model Post {
+  id       ObjectId @id @map("_id")
+  title    String
+  content  String?
+  author   User     @relation(fields: [authorId], references: [id])
+  authorId ObjectId
+  @@map("posts")
+}
+```
+
+You do not need to model every collection on day one. Start with the part of the database you want to read and write first.
+
+## 5. Emit the generated artifacts
+
+Once the contract looks right, this step turns it into the generated files the runtime and query APIs use.
+
+Run:
+
+```npm
+npx prisma-next contract emit
+```
+
+This refreshes `prisma/contract.json` and `prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed.
+
+## 6. Run a simple high-level query
+
+With the emitted artifacts in place, you can test the higher-level API first and confirm Prisma Next can read the existing collections.
+
+Create a `script.ts` file:
+
+```typescript title="script.ts"
+import "dotenv/config";
+import { db } from "./prisma/db";
+
+async function main() {
+  const user = await db.orm.users.where({ email: "existing@example.com" }).first();
+  console.log(user);
+
+  await db.close();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+Run it:
+
+```npm
+npx tsx script.ts
+```
+
+## 7. Run a simple low-level query
+
+After the ORM example, this step shows the lower-level MongoDB pipeline builder against the same existing collections.
+
+Replace `script.ts` with this version:
+
+```typescript title="script.ts"
+import "dotenv/config";
+import { db } from "./prisma/db";
+
+async function main() {
+  const runtime = await db.runtime();
+  const plan = db.query
+    .from("users")
+    .match((fields) => fields.email.eq("existing@example.com"))
+    .project("email", "name")
+    .build();
+
+  const rows = await runtime.execute(plan);
+  console.log(rows);
+
+  await db.close();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+Run it again:
+
+```npm
+npx tsx script.ts
+```
+
+## 8. Commands you will use next
+
+Once Prisma Next is in the project, these are the MongoDB commands to remember:
+
+```npm
+npx prisma-next contract emit
+```
+
+Run this after you change `prisma/contract.prisma`.
+
+```npm
+npx prisma-next migration plan --name add-user-bio
+npx prisma-next migration apply
+```
+
+Use these when you want Prisma Next to manage a schema change for the collections in your contract.
+
+You do not need to create a migration just to start reading collections that already exist. Create a migration when you are ready for Prisma Next to own a change.
diff --git a/apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx b/apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx
new file mode 100644
index 0000000000..6db183be5e
--- /dev/null
+++ b/apps/docs/content/docs/(index)/next/add-to-existing-project/postgresql.mdx
@@ -0,0 +1,190 @@
+---
+title: Postgres
+description: Add Prisma Next to an existing PostgreSQL project.
+url: /next/add-to-existing-project/postgresql
+metaTitle: Add Prisma Next to an existing Postgres project
+metaDescription: Add Prisma Next to an existing PostgreSQL project.
+---
+
+This guide shows how to add Prisma Next to a project that already uses PostgreSQL. You will initialize Prisma Next, infer a contract from the live schema, sign the database, and run a couple of queries.
+
+:::warning[Prisma Next is still in development]
+
+Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today.
+
+:::
+
+## Prerequisites
+
+Before you start, make sure you can already reach the PostgreSQL database this project uses today.
+
+- Node.js 24 or newer
+- npm
+- An existing PostgreSQL database
+
+## 1. Make sure you can run the example script
+
+If your project already runs TypeScript scripts, you can skip this step.
+
+Otherwise, install the script tooling:
+
+```npm
+npm install --save-dev tsx typescript
+```
+
+Later, `prisma-next init` will also add the Node.js types it needs and make sure the generated Prisma Next files can run as ES modules. If your project already declares `"type": "commonjs"`, Prisma Next leaves that choice alone and prints a warning so you can decide how to wire the generated helper into your app.
+
+## 2. Initialize Prisma Next
+
+From the root of your existing project, run:
+
+```npm
+npx prisma-next init --write-env
+```
+
+When Prisma Next asks a few setup questions:
+
+- choose `PostgreSQL`
+- choose `PSL`
+- keep the default schema path, `prisma/contract.prisma`
+
+## 3. Set your database connection string
+
+Update `.env` with the connection string for the database your app already uses:
+
+```text title=".env"
+DATABASE_URL="postgres://username:password@host:5432/database?sslmode=require"
+```
+
+## 4. Infer a starter contract from the live database
+
+This step gives you a starting contract by reading the schema that already exists in PostgreSQL.
+
+Run:
+
+```npm
+npx prisma-next contract infer --output ./prisma/contract.prisma
+```
+
+This reads the live PostgreSQL schema and writes a first draft of `prisma/contract.prisma`.
+
+Open that file and review it before you go on. This is the moment to clean up model names, keep only the tables you want Prisma Next to know about first, and make the file easier to read.
+
+## 5. Emit the generated artifacts
+
+Once the contract looks right, this step turns it into the generated files the runtime and CLI use.
+
+After you are happy with the contract, run:
+
+```npm
+npx prisma-next contract emit
+```
+
+This refreshes `prisma/contract.json` and `prisma/contract.d.ts` so the runtime and query APIs are aligned with the contract you just reviewed.
+
+## 6. Sign the database
+
+Record that the live database matches the emitted contract:
+
+```npm
+npx prisma-next db sign
+```
+
+This step matters in two common cases:
+
+- the database has never been signed by Prisma Next before
+- the database was signed earlier, but under an older contract hash
+
+## 7. Run a simple high-level query
+
+With the database signed, you can test the higher-level API first and confirm Prisma Next is reading the existing schema correctly.
+
+Create a `script.ts` file:
+
+```typescript title="script.ts"
+import "dotenv/config";
+import { db } from "./prisma/db";
+
+async function main() {
+  const runtime = await db.connect({ url: process.env.DATABASE_URL! });
+
+  const users = await db.orm.User
+    .select("id", "email", "name")
+    .take(2)
+    .all();
+
+  console.log(users);
+
+  await runtime.close();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+Run it:
+
+```npm
+npx tsx script.ts
+```
+
+## 8. Run a simple low-level query
+
+After the ORM example, this step shows the lower-level SQL builder against the same existing schema.
+
+Replace `script.ts` with this version:
+
+```typescript title="script.ts"
+import "dotenv/config";
+import { db } from "./prisma/db";
+
+async function main() {
+  const runtime = await db.connect({ url: process.env.DATABASE_URL! });
+
+  const plan = db.sql.user
+    .select("id", "email", "name")
+    .limit(2)
+    .build();
+
+  const rows = await db.runtime().execute(plan);
+  console.log(rows);
+
+  await runtime.close();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+```
+
+Run it again:
+
+```npm
+npx tsx script.ts
+```
+
+## 9. Commands you will use next
+
+Once Prisma Next is in the project, these are the PostgreSQL commands to remember:
+
+```npm
+npx prisma-next contract emit
+```
+
+Run this after you change `prisma/contract.prisma`.
+
+```npm
+npx prisma-next db update
+```
+
+Use this when you want Prisma Next to update the live database directly so it matches the latest contract.
+
+```npm
+npx prisma-next migration plan --name add-user-bio
+npx prisma-next migration apply
+```
+
+Use these when you want checked-in migration packages instead of a direct database update.
diff --git a/apps/docs/content/docs/(index)/next/create-prisma.mdx b/apps/docs/content/docs/(index)/next/create-prisma.mdx
new file mode 100644
index 0000000000..903e92d836
--- /dev/null
+++ b/apps/docs/content/docs/(index)/next/create-prisma.mdx
@@ -0,0 +1,80 @@
+---
+title: create-prisma@next
+description: Scaffold a new Prisma Next app with create-prisma@next.
+url: /next/create-prisma
+metaTitle: Scaffold a Prisma Next app with create-prisma@next
+metaDescription: Use create-prisma@next to create a new Prisma Next app with templates, database scripts, and runtime helpers.
+---
+
+`create-prisma@next` creates a new Prisma Next project from an app template. It installs the Prisma Next packages and adds the files and scripts needed to start developing.
+
+:::warning[Prisma Next is still in development]
+
+Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today.
+
+:::
+
+Use this when you want to start from a working app template. If you already have an app, use [Add Prisma Next to an existing PostgreSQL project](/next/add-to-existing-project/postgresql) or [Add Prisma Next to an existing MongoDB project](/next/add-to-existing-project/mongodb).
+
+## Create a project
+
+Run:
+
+```npm
+npx create-prisma@next
+```
+
+Then choose a project name, app template, database provider, contract authoring style, and package manager.
+
+Generated Node.js projects expect Node.js 24 LTS or newer.
+
+## Skip the prompts
+
+Pass flags when you already know the project shape:
+
+```npm
+npx create-prisma@next --name my-app --template next --provider postgres
+```
+
+Use `--name .` to create the project in the current directory.
+
+Useful flags:
+
+| Flag | What it does |
+| --- | --- |
+| `--template <name>` | Chooses the app template. |
+| `--provider postgres\|mongodb` | Chooses the database provider. |
+| `--authoring psl\|typescript` | Chooses the contract authoring style. |
+| `--package-manager <name>` | Chooses `npm`, `pnpm`, `yarn`, `bun`, or `deno`. |
+| `--database-url <url>` | Writes `DATABASE_URL` during setup. |
+| `--no-install` | Scaffolds files without installing dependencies. |
+| `--no-emit` | Skips `prisma-next contract emit`. |
+| `--force` | Allows scaffolding into a non-empty directory. |
+
+## What gets created
+
+The generated project includes Prisma Next dependencies, a contract file, Prisma Next configuration, environment files, and package scripts for local development.
+
+Supported templates include Hono, Elysia, NestJS, Next.js, SvelteKit, Astro, Nuxt, TanStack Start, and Turborepo.
+
+## Start the app
+
+Review `DATABASE_URL` in `.env`, then initialize the database.
+
+For PostgreSQL:
+
+```npm
+npm run db:init
+npm run dev
+```
+
+For MongoDB:
+
+```npm
+npm run db:up
+npm run migration:plan -- --name init
+npm run migration:apply
+npm run dev
+```
+
+To add Prisma Next to an app you already have, use the [PostgreSQL existing-project guide](/next/add-to-existing-project/postgresql) or [MongoDB existing-project guide](/next/add-to-existing-project/mongodb).
diff --git a/apps/docs/content/docs/(index)/next/index.mdx b/apps/docs/content/docs/(index)/next/index.mdx
new file mode 100644
index 0000000000..54e4e477d5
--- /dev/null
+++ b/apps/docs/content/docs/(index)/next/index.mdx
@@ -0,0 +1,29 @@
+---
+title: Get started with Prisma Next
+description: Start a new Prisma Next app or add Prisma Next to an existing project.
+url: /next
+metaTitle: Get started with Prisma Next
+metaDescription: Start a Prisma Next project with create-prisma@next or add Prisma Next to an existing project.
+badge: early-access
+---
+
+Prisma Next is the next foundation for Prisma ORM. Start here if you want to try the Prisma Next workflow.
+
+:::warning[Prisma Next is still in development]
+
+Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today.
+
+:::
+
+## Start a new project
+
+- [Scaffold a Prisma Next app with create-prisma@next](/next/create-prisma)
+
+## Add Prisma Next to an existing project
+
+- [Add Prisma Next to an existing PostgreSQL project](/next/add-to-existing-project/postgresql)
+- [Add Prisma Next to an existing MongoDB project](/next/add-to-existing-project/mongodb)
+
+## Learn the ORM workflow
+
+Read the [Prisma Next overview](/orm/next) to learn about contracts, emitted artifacts, runtime clients, query styles, and database change commands.
diff --git a/apps/docs/content/docs/(index)/next/meta.json b/apps/docs/content/docs/(index)/next/meta.json
new file mode 100644
index 0000000000..022d2ebb44
--- /dev/null
+++ b/apps/docs/content/docs/(index)/next/meta.json
@@ -0,0 +1,11 @@
+{
+  "title": "Next",
+  "defaultOpen": true,
+  "root": true,
+  "pages": [
+    "---Getting Started---",
+    "index",
+    "create-prisma",
+    "add-to-existing-project"
+  ]
+}
diff --git a/apps/docs/content/docs/cli/meta.json b/apps/docs/content/docs/cli/meta.json
index 648b580a5d..e95c2953ad 100644
--- a/apps/docs/content/docs/cli/meta.json
+++ b/apps/docs/content/docs/cli/meta.json
@@ -6,6 +6,7 @@
   "pages": [
     "---Introduction---",
     "index",
+    "next",
 
     "---Standalone commands---",
     "init",
diff --git a/apps/docs/content/docs/cli/next/configuration.mdx b/apps/docs/content/docs/cli/next/configuration.mdx
new file mode 100644
index 0000000000..2559fb493f
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/configuration.mdx
@@ -0,0 +1,91 @@
+---
+title: CLI configuration
+description: Configure Prisma Next CLI commands with prisma-next.config.ts and global flags.
+url: /cli/next/configuration
+metaTitle: Prisma Next CLI configuration
+metaDescription: Learn how Prisma Next CLI commands find config, read database URLs, and format output.
+---
+
+Prisma Next CLI commands use `prisma-next.config.ts` as the project entrypoint for contract emission, database operations, and migrations.
+
+## Config file
+
+Commands that need project context read the Prisma Next config from your project. For PostgreSQL projects, use the Postgres config helper:
+
+```typescript title="prisma-next.config.ts"
+import "dotenv/config";
+import { defineConfig } from "@prisma-next/postgres/config";
+
+export default defineConfig({
+  contract: "./prisma/contract.prisma",
+  db: {
+    connection: process.env["DATABASE_URL"]!,
+  },
+});
+```
+
+For MongoDB projects, import `defineConfig` from `@prisma-next/mongo/config` instead.
+
+Pass `--config` when your config file is not in the default project location:
+
+```bash
+prisma-next contract emit --config ./config/prisma-next.config.ts
+```
+
+## Emit-only config
+
+`contract emit` does not connect to a database, so the config can omit `db.connection`:
+
+```typescript title="prisma-next.config.ts"
+import { defineConfig } from "@prisma-next/postgres/config";
+
+export default defineConfig({
+  contract: "./prisma/contract.prisma",
+});
+```
+
+Add `db.connection` before running commands such as `db verify`, `db sign`, `db init`, `db update`, `db schema`, `contract infer`, or `migration apply`.
+
+## Extension packs
+
+Add extension control descriptors to the config when your contract uses extension-provided types:
+
+```typescript title="prisma-next.config.ts"
+import { defineConfig } from "@prisma-next/postgres/config";
+import pgvector from "@prisma-next/extension-pgvector/control";
+
+export default defineConfig({
+  contract: "./prisma/contract.prisma",
+  extensions: [pgvector],
+  db: {
+    connection: process.env["DATABASE_URL"]!,
+  },
+});
+```
+
+Re-run `prisma-next contract emit` after changing extension packs, then update the matching runtime client.
+
+## Database URLs
+
+Database commands accept `--db <url>`. If you omit it, Prisma Next can use the database connection from `prisma-next.config.ts`.
+
+```bash
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+## Environment variables
+
+| Variable | What it does |
+| --- | --- |
+| `DATABASE_URL` | Common place to store the database connection string used by config files and scripts. |
+| `NO_COLOR=1` | Disables colored terminal output. |
+
+## Output modes
+
+Use the default text output when running commands locally. Use `--json` in CI or automation:
+
+```bash
+prisma-next db verify --db "$DATABASE_URL" --json
+```
+
+Use `--no-interactive` for scripts that must never pause for user input.
diff --git a/apps/docs/content/docs/cli/next/contract-emit.mdx b/apps/docs/content/docs/cli/next/contract-emit.mdx
new file mode 100644
index 0000000000..7991b19c5c
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/contract-emit.mdx
@@ -0,0 +1,52 @@
+---
+title: prisma-next contract emit
+description: Emit Prisma Next contract artifacts.
+url: /cli/next/contract-emit
+metaTitle: prisma-next contract emit
+metaDescription: Learn how to emit contract.json and contract.d.ts for Prisma Next.
+---
+
+`prisma-next contract emit` reads your contract source and writes the generated artifacts used by the runtime, verification, and migration tooling.
+
+The command is offline. It does not need a database connection.
+
+## Usage
+
+```bash
+prisma-next contract emit
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--json` | Prints a machine-readable result. |
+| `-q`, `--quiet` | Suppresses nonessential output. |
+| `-v`, `--verbose` | Prints more detail. |
+
+## What it creates
+
+The command emits:
+
+- `contract.json`, the canonical machine-readable contract
+- `contract.d.ts`, the generated TypeScript contract declarations
+
+Do not edit these files by hand. Re-run `contract emit` after changing the contract source or extension pack list.
+
+## Examples
+
+```bash
+prisma-next contract emit
+prisma-next contract emit --config ./custom-config.ts
+prisma-next contract emit --json
+```
+
+## Next steps
+
+After emitting, choose the database workflow:
+
+- use [`prisma-next db init`](/cli/next/db-init) for first-time bootstrap
+- use [`prisma-next db update`](/cli/next/db-update) for direct reconciliation
+- use [`prisma-next migration plan`](/cli/next/migration-plan) for checked-in migrations
+- use [`prisma-next db verify`](/cli/next/db-verify) to check drift
diff --git a/apps/docs/content/docs/cli/next/contract-infer.mdx b/apps/docs/content/docs/cli/next/contract-infer.mdx
new file mode 100644
index 0000000000..c4e80b446a
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/contract-infer.mdx
@@ -0,0 +1,54 @@
+---
+title: prisma-next contract infer
+description: Infer a starter contract from an existing database.
+url: /cli/next/contract-infer
+metaTitle: prisma-next contract infer
+metaDescription: Learn how to infer a Prisma Next PSL contract from a live database schema.
+---
+
+`prisma-next contract infer` inspects a live database and writes a starter PSL contract.
+
+Use it when you are adding Prisma Next to an existing database and want an initial contract to review and edit.
+
+## Usage
+
+```bash
+prisma-next contract infer --db "$DATABASE_URL"
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--db <url>` | Connects to the database. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--output <path>` | Writes the inferred PSL contract to a specific path. |
+| `--json` | Prints a machine-readable result. |
+
+## Examples
+
+```bash
+prisma-next contract infer --db "$DATABASE_URL"
+prisma-next contract infer --db "$DATABASE_URL" --output ./prisma/contract.prisma
+prisma-next contract infer --db "$DATABASE_URL" --json
+```
+
+## What to review
+
+Inference gives you a starting point, not a finished design. Review:
+
+- model and field names
+- relation names
+- mapped database names
+- defaults, indexes, and constraints
+- extension-backed column types
+
+Then run:
+
+```bash
+prisma-next contract emit
+prisma-next db sign --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+`db sign` is the handoff point where you record that the existing database matches the reviewed contract.
diff --git a/apps/docs/content/docs/cli/next/db-init.mdx b/apps/docs/content/docs/cli/next/db-init.mdx
new file mode 100644
index 0000000000..0129b726fa
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/db-init.mdx
@@ -0,0 +1,52 @@
+---
+title: prisma-next db init
+description: Initialize a database from the current Prisma Next contract.
+url: /cli/next/db-init
+metaTitle: prisma-next db init
+metaDescription: Learn how to create missing database structures from a Prisma Next contract and sign the database.
+---
+
+`prisma-next db init` creates missing database structures from the current emitted contract and signs the database.
+
+Use it for first setup of a database that should match your current contract.
+
+## Usage
+
+```bash
+prisma-next db init --db "$DATABASE_URL"
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--db <url>` | Connects to the database. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--dry-run` | Shows planned operations without applying them. |
+| `--json` | Prints a machine-readable result. |
+
+## Behavior
+
+`db init` is intended for bootstrap work. It creates missing structures needed by the contract and writes the contract marker after the database matches.
+
+Run a dry run first when you are not working with a disposable local database:
+
+```bash
+prisma-next db init --db "$DATABASE_URL" --dry-run
+```
+
+## Examples
+
+```bash
+prisma-next contract emit
+prisma-next db init --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+```bash
+prisma-next db init --db "$DATABASE_URL" --dry-run --json
+```
+
+## When to use db update instead
+
+Use [`prisma-next db update`](/cli/next/db-update) when the database already exists and you want Prisma Next to reconcile it with a changed contract. Use [`prisma-next migration plan`](/cli/next/migration-plan) when you want a reviewable migration package in version control.
diff --git a/apps/docs/content/docs/cli/next/db-schema.mdx b/apps/docs/content/docs/cli/next/db-schema.mdx
new file mode 100644
index 0000000000..668f5fc4cd
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/db-schema.mdx
@@ -0,0 +1,36 @@
+---
+title: prisma-next db schema
+description: Inspect a live database schema.
+url: /cli/next/db-schema
+metaTitle: prisma-next db schema
+metaDescription: Learn how to inspect a live database schema with Prisma Next.
+---
+
+`prisma-next db schema` reads the live database schema and prints it. The command is read-only.
+
+Use it when you need to inspect what Prisma Next sees in the database before inferring, signing, updating, or debugging drift.
+
+## Usage
+
+```bash
+prisma-next db schema --db "$DATABASE_URL"
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--db <url>` | Connects to the database. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--json` | Prints machine-readable schema output. |
+
+## Examples
+
+```bash
+prisma-next db schema --db "$DATABASE_URL"
+prisma-next db schema --db "$DATABASE_URL" --json > schema.json
+```
+
+## Related commands
+
+Use [`prisma-next contract infer`](/cli/next/contract-infer) when you want to turn a live schema into a starter PSL contract. Use [`prisma-next db verify`](/cli/next/db-verify) when you want to compare the live schema with the emitted contract.
diff --git a/apps/docs/content/docs/cli/next/db-sign.mdx b/apps/docs/content/docs/cli/next/db-sign.mdx
new file mode 100644
index 0000000000..7e265dcdc2
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/db-sign.mdx
@@ -0,0 +1,43 @@
+---
+title: prisma-next db sign
+description: Sign a database with the current Prisma Next contract.
+url: /cli/next/db-sign
+metaTitle: prisma-next db sign
+metaDescription: Learn how to sign a database once it matches the current Prisma Next contract.
+---
+
+`prisma-next db sign` verifies that the live database satisfies the emitted contract and writes the database signature.
+
+Use it after importing or inferring an existing schema, or after a deployment flow that already applied the required database changes.
+
+## Usage
+
+```bash
+prisma-next db sign --db "$DATABASE_URL"
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--db <url>` | Connects to the database. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--json` | Prints a machine-readable result. |
+
+## Example
+
+```bash
+prisma-next contract emit
+prisma-next db sign --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+## When to use it
+
+Use `db sign` only after you believe the live database already matches the emitted contract. It is common after:
+
+- `contract infer` for a brownfield database
+- a manually reviewed migration flow
+- a database restore that you need to mark as matching the current contract
+
+Do not use `db sign` to hide drift. If verification fails, fix the contract or database first.
diff --git a/apps/docs/content/docs/cli/next/db-update.mdx b/apps/docs/content/docs/cli/next/db-update.mdx
new file mode 100644
index 0000000000..68d622f3f6
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/db-update.mdx
@@ -0,0 +1,44 @@
+---
+title: prisma-next db update
+description: Update a database to match the current Prisma Next contract.
+url: /cli/next/db-update
+metaTitle: prisma-next db update
+metaDescription: Learn how to reconcile a database with the current Prisma Next contract.
+---
+
+`prisma-next db update` compares the live database with the emitted contract and applies the required changes.
+
+Use it for direct reconciliation when you do not need a checked-in migration package.
+
+## Usage
+
+```bash
+prisma-next db update --db "$DATABASE_URL"
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--db <url>` | Connects to the database. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--dry-run` | Shows planned operations without applying them. |
+| `-y`, `--yes` | Confirms prompts where the command supports confirmation. |
+| `--json` | Prints a machine-readable result. |
+
+## Recommended flow
+
+```bash
+prisma-next contract emit
+prisma-next db update --db "$DATABASE_URL" --dry-run
+prisma-next db update --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+Use `--dry-run` before applying changes in shared environments.
+
+## When to use migrations instead
+
+For reviewable database changes in version control, use [`prisma-next migration plan`](/cli/next/migration-plan) and [`prisma-next migration apply`](/cli/next/migration-apply).
+
+Use `db update` for local development, preview environments, and workflows where direct reconciliation is acceptable.
diff --git a/apps/docs/content/docs/cli/next/db-verify.mdx b/apps/docs/content/docs/cli/next/db-verify.mdx
new file mode 100644
index 0000000000..dca6a1d1ed
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/db-verify.mdx
@@ -0,0 +1,54 @@
+---
+title: prisma-next db verify
+description: Verify a database against the current Prisma Next contract.
+url: /cli/next/db-verify
+metaTitle: prisma-next db verify
+metaDescription: Learn how to verify that a database marker and live schema match the Prisma Next contract.
+---
+
+`prisma-next db verify` checks whether the database marker and live schema match your emitted contract.
+
+Use it in CI and deployment checks before application code that depends on a contract reaches users.
+
+## Usage
+
+```bash
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--db <url>` | Connects to the database. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--marker-only` | Checks only the database marker. |
+| `--schema-only` | Checks only whether the live schema satisfies the contract. |
+| `--strict` | Fails if the database includes schema elements not present in the contract. |
+| `--json` | Prints machine-readable output. |
+
+## Examples
+
+```bash
+prisma-next db verify --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL" --strict
+prisma-next db verify --db "$DATABASE_URL" --schema-only
+prisma-next db verify --db "$DATABASE_URL" --marker-only
+```
+
+Use JSON output in automation:
+
+```bash
+prisma-next db verify --db "$DATABASE_URL" --json
+```
+
+## What failures mean
+
+| Failure | Meaning |
+| --- | --- |
+| Marker mismatch | The database was not signed for the emitted contract, or the contract changed after signing. |
+| Schema mismatch | The live database does not satisfy the emitted contract. |
+| Strict mismatch | The database has extra schema elements not present in the contract. |
+| Extension mismatch | The contract requires an extension that is not wired in the config. |
+
+Fix the database or contract, emit again if needed, then verify again.
diff --git a/apps/docs/content/docs/cli/next/index.mdx b/apps/docs/content/docs/cli/next/index.mdx
new file mode 100644
index 0000000000..bcd24d33db
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/index.mdx
@@ -0,0 +1,97 @@
+---
+title: Prisma Next CLI
+description: Reference for the Prisma Next command line interface.
+url: /cli/next
+metaTitle: Prisma Next CLI reference
+metaDescription: Learn the Prisma Next CLI commands for contracts, databases, and migrations.
+badge: early-access
+---
+
+The Prisma Next CLI is exposed as `prisma-next`. It reads your `prisma-next.config.ts`, emits contract artifacts, verifies databases, and manages Prisma Next migrations.
+
+:::warning[Prisma Next is still in development]
+
+Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today.
+
+:::
+
+Install the CLI package in a Prisma Next project:
+
+```bash
+npm install -D prisma-next
+```
+
+Then run commands with your package manager:
+
+```bash
+npx prisma-next help
+npx prisma-next contract emit
+```
+
+For a full app scaffold, use [`create-prisma@next`](/next/create-prisma). That path creates the project files and package scripts for you. This CLI reference is for the lower-level commands those scripts call.
+
+## Common workflows
+
+Start an existing project:
+
+```bash
+prisma-next init --target postgres --authoring psl
+prisma-next contract emit
+prisma-next db init --db "$DATABASE_URL"
+```
+
+Adopt an existing database:
+
+```bash
+prisma-next contract infer --db "$DATABASE_URL" --output ./prisma/contract.prisma
+prisma-next contract emit
+prisma-next db sign --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+Use checked-in migrations:
+
+```bash
+prisma-next contract emit
+prisma-next migration plan --name add-users
+prisma-next migration status --db "$DATABASE_URL"
+prisma-next migration apply --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+## Command groups
+
+| Command | Purpose |
+| --- | --- |
+| [`prisma-next init`](/cli/next/init) | Add Prisma Next files to a project. |
+| [`prisma-next contract emit`](/cli/next/contract-emit) | Emit `contract.json` and `contract.d.ts` from your contract source. |
+| [`prisma-next contract infer`](/cli/next/contract-infer) | Infer a starter PSL contract from an existing database. |
+| [`prisma-next db init`](/cli/next/db-init) | Create missing database structures from the current contract and sign the database. |
+| [`prisma-next db update`](/cli/next/db-update) | Reconcile an existing database with the current contract. |
+| [`prisma-next db schema`](/cli/next/db-schema) | Inspect the live database schema. |
+| [`prisma-next db sign`](/cli/next/db-sign) | Record that a database matches the current contract. |
+| [`prisma-next db verify`](/cli/next/db-verify) | Check that a database still matches the current contract. |
+| [`prisma-next migration plan`](/cli/next/migration-plan) | Create an on-disk migration package from contract changes. |
+| [`prisma-next migration new`](/cli/next/migration-new) | Scaffold a migration package for manual authoring. |
+| [`prisma-next migration apply`](/cli/next/migration-apply) | Apply pending on-disk migrations. |
+| [`prisma-next migration status`](/cli/next/migration-status) | Show migration history and applied state. |
+| [`prisma-next migration show`](/cli/next/migration-show) | Inspect a migration package. |
+| [`prisma-next migration ref`](/cli/next/migration-ref) | Manage named migration refs. |
+
+## Global flags
+
+Most Prisma Next commands accept these flags.
+
+| Flag | What it does |
+| --- | --- |
+| `--json` | Print machine-readable output. Use this in CI and scripts. |
+| `-q`, `--quiet` | Suppress nonessential output. |
+| `-v`, `--verbose` | Print more detail. |
+| `--trace` | Include stack traces for failures. |
+| `--color` | Force colored output. |
+| `--no-color` | Disable colored output. |
+| `--interactive` | Allow prompts. |
+| `--no-interactive` | Disable prompts. |
+| `-y`, `--yes` | Accept prompts where the command supports confirmation. |
+
+Use `prisma-next <command> --help` when you need the exact command help from the installed preview version.
diff --git a/apps/docs/content/docs/cli/next/init.mdx b/apps/docs/content/docs/cli/next/init.mdx
new file mode 100644
index 0000000000..07f76eb742
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/init.mdx
@@ -0,0 +1,69 @@
+---
+title: prisma-next init
+description: Initialize Prisma Next files in a project.
+url: /cli/next/init
+metaTitle: prisma-next init
+metaDescription: Learn how to initialize Prisma Next files in an existing project.
+---
+
+`prisma-next init` scaffolds the Prisma Next config, contract source, and runtime files inside an existing project.
+
+Use [`create-prisma@next`](/next/create-prisma) when you want a complete new application template. Use `prisma-next init` when you already have a project and want to add the lower-level Prisma Next files.
+
+## Usage
+
+```bash
+prisma-next init
+```
+
+Run it non-interactively:
+
+```bash
+prisma-next init --yes --target postgres --authoring psl
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--target <db>` | Sets the database target. Use `postgres` or `mongodb`. |
+| `--authoring <style>` | Sets the contract authoring style. Use `psl` or `typescript`. |
+| `--schema-path <path>` | Sets where the starter contract is written. |
+| `--force` | Overwrites an existing scaffold without prompting. |
+| `--write-env` | Writes `.env` from `.env.example`. |
+| `--probe-db` | Connects to `DATABASE_URL` once and checks the server version. |
+| `--strict-probe` | Treats a failed database probe as fatal. |
+| `--no-install` | Skips dependency installation and contract emission. |
+
+## What it creates
+
+The exact files depend on the target and authoring style, but a Postgres PSL setup normally includes:
+
+- `prisma-next.config.ts`
+- a starter contract file such as `prisma/contract.prisma`
+- emitted contract artifacts after installation runs
+- a runtime client file that imports `contract.json`
+- package scripts for contract emission and database commands
+
+## Examples
+
+```bash
+prisma-next init --yes --target postgres --authoring psl
+prisma-next init --yes --target mongodb --authoring typescript --json
+prisma-next init --no-install
+```
+
+## After initialization
+
+Review the generated files, set `DATABASE_URL`, and emit the contract when you change the schema:
+
+```bash
+prisma-next contract emit
+```
+
+Then initialize or verify the database:
+
+```bash
+prisma-next db init --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
diff --git a/apps/docs/content/docs/cli/next/meta.json b/apps/docs/content/docs/cli/next/meta.json
new file mode 100644
index 0000000000..0ccb677d40
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/meta.json
@@ -0,0 +1,32 @@
+{
+  "title": "Next",
+  "root": true,
+  "defaultOpen": true,
+  "pages": [
+    "---Introduction---",
+    "index",
+    "configuration",
+
+    "---Project setup---",
+    "init",
+
+    "---Contract commands---",
+    "contract-emit",
+    "contract-infer",
+
+    "---Database commands---",
+    "db-init",
+    "db-update",
+    "db-schema",
+    "db-sign",
+    "db-verify",
+
+    "---Migration commands---",
+    "migration-plan",
+    "migration-new",
+    "migration-apply",
+    "migration-status",
+    "migration-show",
+    "migration-ref"
+  ]
+}
diff --git a/apps/docs/content/docs/cli/next/migration-apply.mdx b/apps/docs/content/docs/cli/next/migration-apply.mdx
new file mode 100644
index 0000000000..4952a488a8
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/migration-apply.mdx
@@ -0,0 +1,47 @@
+---
+title: prisma-next migration apply
+description: Apply pending Prisma Next migrations.
+url: /cli/next/migration-apply
+metaTitle: prisma-next migration apply
+metaDescription: Learn how to apply pending Prisma Next on-disk migrations.
+---
+
+`prisma-next migration apply` applies pending on-disk migrations to the database.
+
+Use it from a controlled deployment step after reviewing migration packages.
+
+## Usage
+
+```bash
+prisma-next migration apply --db "$DATABASE_URL"
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--db <url>` | Connects to the database. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--ref <name>` | Applies migrations up to a named target ref. |
+| `--json` | Prints a machine-readable result. |
+
+## Recommended flow
+
+```bash
+prisma-next migration status --db "$DATABASE_URL"
+prisma-next migration apply --db "$DATABASE_URL"
+prisma-next migration status --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+Run `migration status` before and after applying migrations to see what changed.
+
+## Applying to a ref
+
+If your project uses named migration refs, apply up to a target ref:
+
+```bash
+prisma-next migration apply --db "$DATABASE_URL" --ref production
+```
+
+Manage refs with [`prisma-next migration ref`](/cli/next/migration-ref).
diff --git a/apps/docs/content/docs/cli/next/migration-new.mdx b/apps/docs/content/docs/cli/next/migration-new.mdx
new file mode 100644
index 0000000000..f741f00b28
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/migration-new.mdx
@@ -0,0 +1,49 @@
+---
+title: prisma-next migration new
+description: Scaffold a Prisma Next migration package for manual authoring.
+url: /cli/next/migration-new
+metaTitle: prisma-next migration new
+metaDescription: Learn how to scaffold a manual Prisma Next migration package.
+---
+
+`prisma-next migration new` creates a migration package with a `migration.ts` file for manual authoring.
+
+Use it when the generated plan is not enough and you want to write the migration operations yourself.
+
+## Usage
+
+```bash
+prisma-next migration new --name split-name
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--name <slug>` | Sets the migration directory name suffix. |
+| `--from <hash>` | Sets the starting contract hash. Defaults to the latest migration target. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--json` | Prints a machine-readable result. |
+
+## Examples
+
+```bash
+prisma-next migration new --name split-name
+prisma-next migration new --name custom-fk --from sha256:abc...
+```
+
+## After scaffolding
+
+Edit the generated migration package, then inspect it:
+
+```bash
+prisma-next migration show
+```
+
+Apply the migration only after review:
+
+```bash
+prisma-next migration apply --db "$DATABASE_URL"
+```
+
+Manual migrations should still end at a contract state that matches the emitted contract.
diff --git a/apps/docs/content/docs/cli/next/migration-plan.mdx b/apps/docs/content/docs/cli/next/migration-plan.mdx
new file mode 100644
index 0000000000..af52bbbf89
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/migration-plan.mdx
@@ -0,0 +1,42 @@
+---
+title: prisma-next migration plan
+description: Plan an on-disk migration from Prisma Next contract changes.
+url: /cli/next/migration-plan
+metaTitle: prisma-next migration plan
+metaDescription: Learn how to create a Prisma Next migration package from contract changes.
+---
+
+`prisma-next migration plan` compares the emitted contract against the latest on-disk migration state and creates a migration package.
+
+The command is offline. It does not need a database connection.
+
+## Usage
+
+```bash
+prisma-next migration plan --name add-users-table
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--name <slug>` | Sets the migration directory name suffix. Defaults to `migration`. |
+| `--from <hash>` | Uses a specific starting contract hash instead of the latest migration target. |
+| `--json` | Prints a machine-readable result. |
+
+## Recommended flow
+
+```bash
+prisma-next contract emit
+prisma-next migration plan --name add-users-table
+prisma-next migration show
+```
+
+Review the generated migration package before applying it with [`prisma-next migration apply`](/cli/next/migration-apply).
+
+## When to use migration plan
+
+Use `migration plan` when your team wants database changes reviewed in version control. For local prototypes where review is not needed, [`prisma-next db update`](/cli/next/db-update) is usually faster.
+
+If the generated migration is not the migration you want, use [`prisma-next migration new`](/cli/next/migration-new) and author the migration manually.
diff --git a/apps/docs/content/docs/cli/next/migration-ref.mdx b/apps/docs/content/docs/cli/next/migration-ref.mdx
new file mode 100644
index 0000000000..6d5bcc802d
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/migration-ref.mdx
@@ -0,0 +1,46 @@
+---
+title: prisma-next migration ref
+description: Manage named Prisma Next migration refs.
+url: /cli/next/migration-ref
+metaTitle: prisma-next migration ref
+metaDescription: Learn how to set, get, list, and delete Prisma Next migration refs.
+---
+
+`prisma-next migration ref` manages named refs stored with your migration history.
+
+Refs let you name a migration hash and use that name in commands such as [`prisma-next migration apply --ref <name>`](/cli/next/migration-apply).
+
+## Usage
+
+```bash
+prisma-next migration ref set production sha256:abc...
+prisma-next migration ref get production
+prisma-next migration ref list
+prisma-next migration ref delete production
+```
+
+## Subcommands
+
+| Subcommand | What it does |
+| --- | --- |
+| `set <name> <hash>` | Writes or updates a ref. |
+| `get <name>` | Prints the hash for a ref. |
+| `list` | Lists all refs. |
+| `delete <name>` | Deletes a ref. |
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--json` | Prints a machine-readable result. |
+
+## Example workflow
+
+```bash
+prisma-next migration ref set production sha256:abc...
+prisma-next migration status --db "$DATABASE_URL" --ref production
+prisma-next migration apply --db "$DATABASE_URL" --ref production
+```
+
+Use refs when environments need named targets instead of always applying to the latest migration on disk.
diff --git a/apps/docs/content/docs/cli/next/migration-show.mdx b/apps/docs/content/docs/cli/next/migration-show.mdx
new file mode 100644
index 0000000000..9734d8646a
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/migration-show.mdx
@@ -0,0 +1,48 @@
+---
+title: prisma-next migration show
+description: Inspect a Prisma Next migration package.
+url: /cli/next/migration-show
+metaTitle: prisma-next migration show
+metaDescription: Learn how to inspect Prisma Next migration operations, statements, and metadata.
+---
+
+`prisma-next migration show` displays the operations, statement preview, and metadata for a migration package.
+
+Use this command during review before applying a migration package.
+
+## Usage
+
+```bash
+prisma-next migration show
+```
+
+Pass a directory path or migration hash prefix to inspect a specific migration:
+
+```bash
+prisma-next migration show sha256:a1b2c3
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `[target]` | Migration path or migration hash prefix. Defaults to the latest migration. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--json` | Prints a machine-readable result. |
+
+## Examples
+
+```bash
+prisma-next migration show
+prisma-next migration show ./migrations/app/20260515T1200_add-users
+prisma-next migration show sha256:a1b2c3 --json
+```
+
+## What to check
+
+Before applying, review:
+
+- the source and destination contract hashes
+- the planned operations
+- generated SQL statements or operation payloads
+- any extension-space migrations included with the application migration
diff --git a/apps/docs/content/docs/cli/next/migration-status.mdx b/apps/docs/content/docs/cli/next/migration-status.mdx
new file mode 100644
index 0000000000..59d8911a20
--- /dev/null
+++ b/apps/docs/content/docs/cli/next/migration-status.mdx
@@ -0,0 +1,44 @@
+---
+title: prisma-next migration status
+description: Show Prisma Next migration history and applied state.
+url: /cli/next/migration-status
+metaTitle: prisma-next migration status
+metaDescription: Learn how to inspect Prisma Next migration history and pending migrations.
+---
+
+`prisma-next migration status` displays migration history. With a database connection, it also shows applied and pending migrations.
+
+Use it before and after `migration apply`, and when debugging why an environment is not at the expected contract state.
+
+## Usage
+
+```bash
+prisma-next migration status
+```
+
+## Options
+
+| Option | What it does |
+| --- | --- |
+| `--db <url>` | Connects to the database. |
+| `--config <path>` | Reads a specific `prisma-next.config.ts` file. |
+| `--ref <name>` | Shows status relative to a target ref. |
+| `--graph` | Shows the full migration graph with branches. |
+| `--limit <n>` | Limits displayed migrations. Defaults to `10`. |
+| `--all` | Shows full history. |
+| `--json` | Prints a machine-readable result. |
+
+## Examples
+
+```bash
+prisma-next migration status
+prisma-next migration status --db "$DATABASE_URL"
+prisma-next migration status --db "$DATABASE_URL" --graph --all
+prisma-next migration status --db "$DATABASE_URL" --ref production
+```
+
+## Reading the result
+
+Without `--db`, status can report the migration packages available on disk. With `--db`, it can also compare those packages to what has been applied in the database.
+
+Use [`prisma-next db verify`](/cli/next/db-verify) after applying migrations to check the final database shape against the emitted contract.
diff --git a/apps/docs/content/docs/orm/next/concepts/contract-first-design.mdx b/apps/docs/content/docs/orm/next/concepts/contract-first-design.mdx
new file mode 100644
index 0000000000..979a57c959
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/concepts/contract-first-design.mdx
@@ -0,0 +1,78 @@
+---
+title: Contract-first design in Prisma Next
+description: Understand how Prisma Next uses a contract as the source of truth for runtime queries and database changes.
+url: /orm/next/concepts/contract-first-design
+metaTitle: Contract-first design in Prisma Next
+metaDescription: Understand how Prisma Next uses a contract as the source of truth for runtime queries and database changes.
+---
+
+Prisma Next is contract-first. The contract describes the data shape your application expects, and Prisma Next uses that contract to drive generated types, runtime clients, verification, and database changes.
+
+The contract-first model answers the important questions from one source of truth:
+
+- What models, fields, relations, enums, and custom types can application code use?
+- Which generated TypeScript types should query code receive?
+- Which extension capabilities are required by this application?
+- What database shape must exist before this code runs?
+- Has the live database drifted away from the contract?
+
+## What the contract contains
+
+The emitted `contract.json` is the canonical machine-readable artifact. It is generated from your PSL or TypeScript contract source and then consumed by Prisma Next tooling and runtime clients.
+
+At a high level, the contract includes:
+
+| Area | Examples |
+| --- | --- |
+| Target information | Database family, target database, and extension pack requirements. |
+| Application shape | Models, fields, enums, relations, mapped table names, and custom types. |
+| Storage mapping | Column types, database names, constraints, indexes, and defaults. |
+| Generated metadata | Hashes and metadata used by verification and migration tooling. |
+
+`contract.d.ts` sits next to `contract.json` and gives TypeScript a typed view of the same contract.
+
+## Contract lifecycle
+
+A typical Prisma Next workflow starts by emitting the contract:
+
+```bash
+prisma-next contract emit
+```
+
+Then run the database workflow that fits the environment:
+
+| Workflow | Use it when |
+| --- | --- |
+| `db init` | You are creating missing database structures from the current contract. |
+| `db update` | You want Prisma Next to reconcile an existing database directly. |
+| `migration plan` and `migration apply` | You want reviewable migration packages in version control. |
+| `db verify` | You want to check a live database against the emitted contract. |
+
+## Drift detection
+
+Prisma Next verification compares the database marker and live schema with the emitted contract:
+
+```bash
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+Use verification before deploying code that depends on a changed contract. In CI, prefer JSON output so failures can be parsed reliably:
+
+```bash
+prisma-next db verify --db "$DATABASE_URL" --json
+```
+
+## Control plane and runtime plane
+
+Prisma Next separates the tools that understand and change the database from the runtime client that executes application queries.
+
+| Plane | Where it is used | What it does |
+| --- | --- | --- |
+| Control plane | `prisma-next.config.ts` and CLI commands | Emits contracts, introspects schemas, plans migrations, verifies drift, and applies changes. |
+| Runtime plane | Application code | Loads `contract.json`, exposes query APIs, encodes values, decodes rows, and runs queries. |
+
+Extension packs usually have both planes. For example, `@prisma-next/extension-pgvector/control` teaches the CLI about vector columns and migration requirements, while `@prisma-next/extension-pgvector/runtime` teaches runtime queries how to encode vectors and expose vector operations.
+
+## Contracts are not just documentation
+
+The contract is an executable boundary between your app and the database. If the contract changes, emit it again. If the database changes, verify it again. That is the heart of Prisma Next's design.
diff --git a/apps/docs/content/docs/orm/next/concepts/extension-packs.mdx b/apps/docs/content/docs/orm/next/concepts/extension-packs.mdx
new file mode 100644
index 0000000000..4e44a4b56c
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/concepts/extension-packs.mdx
@@ -0,0 +1,81 @@
+---
+title: 'Extension packs: adding capabilities'
+description: Add database-specific types, operations, and migrations to Prisma Next with extension packs.
+url: /orm/next/concepts/extension-packs
+metaTitle: Prisma Next extension packs
+metaDescription: Add database-specific types, operations, and migrations to Prisma Next with extension packs.
+---
+
+Extension packs add capabilities that are not part of the base database target. They can contribute column types, query operations, runtime codecs, and migration artifacts.
+
+Examples include:
+
+- [pgvector](/orm/next/extensions/pgvector) for vector similarity search
+- [PostGIS](/orm/next/extensions/postgis) for geospatial data
+- [CipherStash](/orm/next/extensions/cipherstash) for searchable encrypted columns
+
+## What an extension pack can provide
+
+| Capability | Example |
+| --- | --- |
+| Column types | `pgvector.Vector(1536)`, `postgis.Geometry(4326)`, `cipherstash.EncryptedString()`. |
+| Query operations | `cosineDistance`, `distanceSphere`, `within`, `cipherstashEq`. |
+| Runtime codecs | Encode JavaScript values before sending them to the database and decode returned values. |
+| Database setup | Baseline migrations such as `CREATE EXTENSION IF NOT EXISTS vector` or `CREATE EXTENSION IF NOT EXISTS postgis`. |
+| Capability gates | Signals that a contract depends on a feature such as `pgvector.cosine` or `postgis.geometry`. |
+
+## Control and runtime descriptors
+
+Most extension packs have two sides:
+
+| Side | Where it is used | Purpose |
+| --- | --- | --- |
+| Control descriptor | `prisma-next.config.ts` | Lets contract emission and database tooling understand the extension. |
+| Runtime descriptor | `prisma/db.ts` or similar | Lets query execution encode, decode, and expose extension operations. |
+
+Register the control descriptor in config:
+
+```typescript title="prisma-next.config.ts"
+import { defineConfig } from "@prisma-next/postgres/config";
+import pgvector from "@prisma-next/extension-pgvector/control";
+
+export default defineConfig({
+  contract: "./prisma/contract.prisma",
+  extensions: [pgvector],
+});
+```
+
+Register the matching runtime descriptor in your database client:
+
+```typescript title="prisma/db.ts"
+import pgvector from "@prisma-next/extension-pgvector/runtime";
+import postgres from "@prisma-next/postgres/runtime";
+import type { Contract } from "./contract.d";
+import contractJson from "./contract.json" with { type: "json" };
+
+export const db = postgres<Contract>({
+  contractJson,
+  extensions: [pgvector],
+});
+```
+
+The contract and runtime must agree. If the emitted contract requires an extension pack, the runtime must register the matching runtime descriptor.
+
+## Add an extension to a project
+
+1. Install the extension package.
+2. Add the control descriptor to `prisma-next.config.ts`.
+3. Use the extension's types in your contract.
+4. Run `prisma-next contract emit`.
+5. Add the runtime descriptor to your Prisma Next client.
+6. Run `prisma-next db init`, `db update`, or your migration workflow so database-side requirements are applied.
+
+## Available packs in these docs
+
+| Pack | Package | Adds |
+| --- | --- | --- |
+| pgvector | `@prisma-next/extension-pgvector` | Vector columns and cosine distance or similarity operations. |
+| PostGIS | `@prisma-next/extension-postgis` | Geometry columns and geospatial operations. |
+| CipherStash | `@prisma-next/extension-cipherstash` | Searchable encrypted columns, encryption middleware, and encrypted query operators. |
+
+Use only the extension packs your contract needs. Keeping the extension list small makes database setup and runtime wiring easier to reason about.
diff --git a/apps/docs/content/docs/orm/next/concepts/meta.json b/apps/docs/content/docs/orm/next/concepts/meta.json
new file mode 100644
index 0000000000..9a22bab442
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/concepts/meta.json
@@ -0,0 +1,9 @@
+{
+  "title": "Core Concepts",
+  "pages": [
+    "contract-first-design",
+    "schema-definition-and-contract-emission",
+    "query-apis",
+    "extension-packs"
+  ]
+}
diff --git a/apps/docs/content/docs/orm/next/concepts/query-apis.mdx b/apps/docs/content/docs/orm/next/concepts/query-apis.mdx
new file mode 100644
index 0000000000..a241807498
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/concepts/query-apis.mdx
@@ -0,0 +1,118 @@
+---
+title: 'Query APIs: SQL DSL and ORM client'
+description: Choose between Prisma Next model-oriented and lower-level query APIs.
+url: /orm/next/concepts/query-apis
+metaTitle: Prisma Next query APIs
+metaDescription: Learn when to use db.orm, db.sql, and db.query in Prisma Next.
+---
+
+Prisma Next gives you more than one query surface because different queries need different levels of control.
+
+| API | Use it for |
+| --- | --- |
+| `db.orm` | Model-oriented CRUD and readable application queries. |
+| `db.sql` | PostgreSQL queries where you want an explicit SQL-shaped plan. |
+| `db.query` | MongoDB queries where you want an explicit document query plan. |
+
+All of these APIs are contract-aware. They use the emitted contract to type fields, validate model names, and expose extension-provided operations.
+
+## ORM client
+
+Use the ORM client when you want model-oriented code:
+
+```typescript
+const user = await db.orm.User
+  .where((user) => user.email.eq("alice@example.com"))
+  .first();
+```
+
+The ORM client is the default place for normal application reads and writes:
+
+```typescript
+const newestUsers = await db.orm.User
+  .orderBy((user) => user.createdAt.desc())
+  .take(10)
+  .all();
+```
+
+## SQL DSL
+
+Use `db.sql` when you want a lower-level PostgreSQL plan:
+
+```typescript
+const plan = db.sql.user
+  .select("id", "email", "createdAt")
+  .where((field, fns) => fns.eq(field.email, "alice@example.com"))
+  .limit(1)
+  .build();
+
+const rows = await db.runtime().execute(plan);
+```
+
+The SQL DSL is useful for explicit projections, computed columns, extension operations, and query shapes where reviewing the plan matters.
+
+## Same query, two surfaces
+
+Use the ORM surface for the everyday version:
+
+```typescript
+const posts = await db.orm.Post
+  .where((post) => post.title.ilike("%prisma%"))
+  .orderBy((post) => post.createdAt.desc())
+  .take(10)
+  .all();
+```
+
+Use the SQL DSL when you want the plan object:
+
+```typescript
+const plan = db.sql.post
+  .select("id", "title", "createdAt")
+  .where((field, fns) => fns.ilike(field.title, "%prisma%"))
+  .orderBy((field) => field.createdAt, { direction: "desc" })
+  .limit(10)
+  .build();
+
+const posts = await db.runtime().execute(plan);
+```
+
+## Transactions
+
+The Postgres runtime facade exposes transaction scopes:
+
+```typescript
+await db.transaction(async (tx) => {
+  await tx.orm.User.create({
+    id: crypto.randomUUID(),
+    email: "alice@example.com",
+  });
+
+  await tx.execute(
+    tx.sql.post
+      .insert({
+        id: crypto.randomUUID(),
+        title: "Welcome",
+        userId: "user-id",
+        createdAt: new Date(),
+      })
+      .build(),
+  );
+});
+```
+
+Use the transaction context when related reads and writes must commit or roll back together.
+
+## MongoDB query builder
+
+MongoDB uses `db.query` for lower-level document queries:
+
+```typescript
+const plan = db.query
+  .from("products")
+  .sort({ _id: 1 })
+  .skip(20)
+  .limit(10)
+  .build();
+```
+
+Use it when the query is naturally expressed as a document query plan instead of a model-oriented operation.
diff --git a/apps/docs/content/docs/orm/next/concepts/schema-definition-and-contract-emission.mdx b/apps/docs/content/docs/orm/next/concepts/schema-definition-and-contract-emission.mdx
new file mode 100644
index 0000000000..3ea9009f1b
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/concepts/schema-definition-and-contract-emission.mdx
@@ -0,0 +1,105 @@
+---
+title: Schema definition and contract emission
+description: Define a Prisma Next contract in PSL or TypeScript and emit generated artifacts.
+url: /orm/next/concepts/schema-definition-and-contract-emission
+metaTitle: Schema definition and contract emission in Prisma Next
+metaDescription: Define a Prisma Next contract in PSL or TypeScript and emit contract.json and contract.d.ts.
+---
+
+Prisma Next lets you author a contract in PSL or TypeScript. Both paths emit the same kind of generated artifacts for runtime clients, database verification, and migration planning.
+
+## PSL authoring
+
+PSL keeps the contract close to the Prisma schema syntax many users already know:
+
+```prisma title="prisma/contract.prisma"
+// use prisma-next
+
+model User {
+  id        String   @id @default(uuid())
+  email     String   @unique
+  createdAt DateTime @default(now())
+}
+```
+
+The config points Prisma Next at that contract source:
+
+```typescript title="prisma-next.config.ts"
+import "dotenv/config";
+import { defineConfig } from "@prisma-next/postgres/config";
+
+export default defineConfig({
+  contract: "./prisma/contract.prisma",
+  db: {
+    connection: process.env["DATABASE_URL"]!,
+  },
+});
+```
+
+MongoDB projects use the same shape with `@prisma-next/mongo/config`.
+
+## TypeScript authoring
+
+TypeScript authoring uses builder APIs instead of a `.prisma` file. It is useful when you want a programmable schema surface or want to compose shared schema pieces in code.
+
+Choose TypeScript authoring when you scaffold:
+
+```bash
+npx create-prisma@next --authoring typescript
+```
+
+Or when you initialize the lower-level CLI workflow:
+
+```bash
+prisma-next init --authoring typescript
+```
+
+## Emit the contract
+
+Run `contract emit` after changing the contract source:
+
+```bash
+prisma-next contract emit
+```
+
+The command is offline. It reads `prisma-next.config.ts`, validates the contract source, and writes the generated artifacts.
+
+| Artifact | Purpose |
+| --- | --- |
+| `contract.json` | The canonical contract used by runtimes, verification, and migration tooling. |
+| `contract.d.ts` | Generated TypeScript declarations used by query code. |
+
+Do not edit these generated files by hand. Re-run `prisma-next contract emit` when the contract source changes.
+
+## Load the emitted contract at runtime
+
+Your runtime client imports the emitted JSON contract and its generated type:
+
+```typescript title="prisma/db.ts"
+import postgres from "@prisma-next/postgres/runtime";
+import type { Contract } from "./contract.d";
+import contractJson from "./contract.json" with { type: "json" };
+
+export const db = postgres<Contract>({
+  contractJson,
+  url: process.env["DATABASE_URL"]!,
+});
+```
+
+For serverless runtimes, use the serverless facade instead:
+
+```typescript title="prisma/db.ts"
+import postgresServerless from "@prisma-next/postgres/serverless";
+import type { Contract } from "./contract.d";
+import contractJson from "./contract.json" with { type: "json" };
+
+export const db = postgresServerless<Contract>({
+  contractJson,
+});
+```
+
+## No-emit authoring
+
+Some development workflows can pass a TypeScript-authored contract directly to the runtime client instead of loading `contract.json`. This is useful for local experimentation, but emitted artifacts are still the clearest boundary for CI, deployments, and database verification.
+
+Use emitted contracts when you need repeatable builds or any CLI command that checks or changes a database.
diff --git a/apps/docs/content/docs/orm/next/extensions/cipherstash.mdx b/apps/docs/content/docs/orm/next/extensions/cipherstash.mdx
new file mode 100644
index 0000000000..be3a6f8169
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/extensions/cipherstash.mdx
@@ -0,0 +1,172 @@
+---
+title: CipherStash extension
+description: Add searchable encrypted columns to Prisma Next with CipherStash.
+url: /orm/next/extensions/cipherstash
+metaTitle: CipherStash extension in Prisma Next
+metaDescription: Learn how to configure CipherStash encryption and searchable encrypted queries in Prisma Next.
+---
+
+The `@prisma-next/extension-cipherstash` pack adds searchable encrypted column support for PostgreSQL.
+
+Use it when values should be encrypted at rest but still queried through CipherStash-supported operations such as equality, text search, range search, and JSON search.
+
+## Install the package
+
+```bash
+npm install @prisma-next/extension-cipherstash
+```
+
+You also need a CipherStash workspace, credentials for your app, and the database-side EQL bundle required by your encryption setup.
+
+## Configure the extension
+
+Register the control descriptor:
+
+```typescript title="prisma-next.config.ts"
+import { defineConfig } from "@prisma-next/postgres/config";
+import cipherstash from "@prisma-next/extension-cipherstash/control";
+
+export default defineConfig({
+  contract: "./prisma/contract.prisma",
+  extensions: [cipherstash],
+});
+```
+
+Register the runtime descriptor and middleware:
+
+```typescript title="src/db.ts"
+import { bulkEncryptMiddleware } from "@prisma-next/extension-cipherstash/middleware";
+import { createCipherstashRuntimeDescriptor } from "@prisma-next/extension-cipherstash/runtime";
+import postgres from "@prisma-next/postgres/runtime";
+import type { Contract } from "./prisma/contract.d";
+import contractJson from "./prisma/contract.json" with { type: "json" };
+import { createCipherstashSdk } from "./sdk";
+
+const sdk = createCipherstashSdk();
+
+export const db = postgres<Contract>({
+  contractJson,
+  extensions: [createCipherstashRuntimeDescriptor({ sdk })],
+  middleware: [bulkEncryptMiddleware(sdk)],
+});
+```
+
+## Define encrypted fields
+
+CipherStash provides six encrypted column types:
+
+| PSL constructor | Plain JavaScript value | Search modes |
+| --- | --- | --- |
+| `cipherstash.EncryptedString()` | `string` | Equality, text search, order and range. |
+| `cipherstash.EncryptedDouble()` | `number` | Equality, order and range. |
+| `cipherstash.EncryptedBigInt()` | `bigint` | Equality, order and range. |
+| `cipherstash.EncryptedDate()` | `Date` | Equality, order and range. |
+| `cipherstash.EncryptedBoolean()` | `boolean` | Equality. |
+| `cipherstash.EncryptedJson()` | JSON value | Searchable JSON. |
+
+```prisma title="prisma/contract.prisma"
+// use prisma-next
+
+model User {
+  id            String @id
+  email         cipherstash.EncryptedString()
+  salary        cipherstash.EncryptedDouble()
+  accountId     cipherstash.EncryptedBigInt()  @map("accountid")
+  birthday      cipherstash.EncryptedDate()
+  emailVerified cipherstash.EncryptedBoolean() @map("emailverified")
+  preferences   cipherstash.EncryptedJson()
+
+  @@map("users")
+}
+```
+
+Search flags default to enabled for the modes supported by each encrypted type. Disable modes explicitly when a column should be storage-only or should expose fewer query operators.
+
+## Insert encrypted values
+
+Wrap plaintext values with the encrypted runtime classes:
+
+```typescript
+import {
+  EncryptedBoolean,
+  EncryptedDate,
+  EncryptedDouble,
+  EncryptedJson,
+  EncryptedString,
+} from "@prisma-next/extension-cipherstash/runtime";
+
+await db.orm.User.create({
+  id: "user-1",
+  email: EncryptedString.from("alice@example.com"),
+  salary: EncryptedDouble.from(95_000),
+  birthday: EncryptedDate.from(new Date("1990-04-12")),
+  emailVerified: EncryptedBoolean.from(true),
+  preferences: EncryptedJson.from({ theme: "dark" }),
+});
+```
+
+The middleware groups encryption work before the query reaches the database.
+
+## Query encrypted values
+
+CipherStash operators are exposed only on compatible encrypted columns:
+
+```typescript
+const users = await db.orm.User
+  .where((user) => user.email.cipherstashIlike("%@example.com"))
+  .all();
+```
+
+Range operators are available on encrypted string, number, bigint, and date fields:
+
+```typescript
+const users = await db.orm.User
+  .where((user) => user.salary.cipherstashGt(100_000))
+  .all();
+```
+
+Equality-style lookups can use array operators:
+
+```typescript
+const users = await db.orm.User
+  .where((user) => user.emailVerified.cipherstashInArray([true]))
+  .all();
+```
+
+## Decrypt returned rows
+
+Use `decryptAll` to batch-decrypt envelopes from a result set:
+
+```typescript
+import { decryptAll } from "@prisma-next/extension-cipherstash/runtime";
+
+const rows = await db.orm.User
+  .where((user) => user.email.cipherstashEq("alice@example.com"))
+  .all();
+
+await decryptAll(rows);
+
+console.log(await rows[0]?.email.decrypt());
+```
+
+## Operator reference
+
+| Operator | Applies to |
+| --- | --- |
+| `cipherstashEq(value)` | All encrypted types with equality enabled. |
+| `cipherstashNe(value)` | All encrypted types with equality enabled. |
+| `cipherstashInArray(values)` | All encrypted types with equality enabled. |
+| `cipherstashNotInArray(values)` | All encrypted types with equality enabled. |
+| `cipherstashIlike(pattern)` | `EncryptedString` with text search enabled. |
+| `cipherstashNotIlike(pattern)` | `EncryptedString` with text search enabled. |
+| `cipherstashGt(value)`, `cipherstashGte(value)` | String, number, bigint, and date fields with order and range enabled. |
+| `cipherstashLt(value)`, `cipherstashLte(value)` | String, number, bigint, and date fields with order and range enabled. |
+| `cipherstashBetween(min, max)` | String, number, bigint, and date fields with order and range enabled. |
+| `cipherstashNotBetween(min, max)` | String, number, bigint, and date fields with order and range enabled. |
+| `cipherstashJsonbPathExists(path)` | `EncryptedJson` with searchable JSON enabled. |
+
+The runtime package also exports helpers such as `cipherstashAsc`, `cipherstashDesc`, `cipherstashJsonbPathQueryFirst`, and `cipherstashJsonbGet` for sort and projection use cases.
+
+## Security notes
+
+Searchable encryption intentionally exposes limited search behavior through configured indexes. Enable only the search modes your application needs, protect CipherStash credentials like production secrets, and keep encryption setup in a controlled deployment workflow.
diff --git a/apps/docs/content/docs/orm/next/extensions/meta.json b/apps/docs/content/docs/orm/next/extensions/meta.json
new file mode 100644
index 0000000000..0a31731836
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/extensions/meta.json
@@ -0,0 +1,8 @@
+{
+  "title": "Extensions",
+  "pages": [
+    "pgvector",
+    "postgis",
+    "cipherstash"
+  ]
+}
diff --git a/apps/docs/content/docs/orm/next/extensions/pgvector.mdx b/apps/docs/content/docs/orm/next/extensions/pgvector.mdx
new file mode 100644
index 0000000000..d16f0efd43
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/extensions/pgvector.mdx
@@ -0,0 +1,141 @@
+---
+title: pgvector extension
+description: Add vector similarity search to Prisma Next with pgvector.
+url: /orm/next/extensions/pgvector
+metaTitle: pgvector extension in Prisma Next
+metaDescription: Learn how to configure pgvector and run vector similarity queries in Prisma Next.
+---
+
+The `@prisma-next/extension-pgvector` pack adds pgvector columns and vector similarity operations for PostgreSQL.
+
+Use it when your app stores embeddings and needs nearest-neighbor style queries, such as semantic search, recommendations, or similarity ranking.
+
+## Install the package
+
+```bash
+npm install @prisma-next/extension-pgvector
+```
+
+## Configure the extension
+
+Register the control descriptor in `prisma-next.config.ts`:
+
+```typescript title="prisma-next.config.ts"
+import { defineConfig } from "@prisma-next/postgres/config";
+import pgvector from "@prisma-next/extension-pgvector/control";
+
+export default defineConfig({
+  contract: "./prisma/contract.prisma",
+  extensions: [pgvector],
+});
+```
+
+Register the runtime descriptor in your database client:
+
+```typescript title="prisma/db.ts"
+import pgvector from "@prisma-next/extension-pgvector/runtime";
+import postgres from "@prisma-next/postgres/runtime";
+import type { Contract } from "./contract.d";
+import contractJson from "./contract.json" with { type: "json" };
+
+export const db = postgres<Contract>({
+  contractJson,
+  extensions: [pgvector],
+});
+```
+
+## Define vector fields
+
+Every vector column must declare a dimension:
+
+```prisma title="prisma/contract.prisma"
+// use prisma-next
+
+types {
+  Embedding1536 = pgvector.Vector(1536)
+}
+
+model Post {
+  id        String         @id @default(uuid())
+  title     String
+  embedding Embedding1536?
+}
+```
+
+The emitted `contract.d.ts` uses a dimensioned `Vector<1536>` type so query results preserve the vector size in TypeScript.
+
+## Emit and apply database setup
+
+After adding the extension and vector field, emit the contract:
+
+```bash
+prisma-next contract emit
+```
+
+Then run your database workflow:
+
+```bash
+prisma-next db init --db "$DATABASE_URL"
+```
+
+The extension pack contributes a baseline migration that installs pgvector with:
+
+```sql
+CREATE EXTENSION IF NOT EXISTS vector;
+```
+
+If your database is managed, make sure the provider allows the pgvector extension.
+
+## Query by similarity with the ORM
+
+Use vector operations on vector fields:
+
+```typescript
+const similarPosts = await db.orm.Post
+  .where((post) => post.embedding.cosineDistance(queryVector).lt(0.3))
+  .orderBy((post) => post.embedding.cosineDistance(queryVector).asc())
+  .take(10)
+  .all();
+```
+
+Use the ORM surface when you want model rows ordered by similarity.
+
+## Query by similarity with the SQL DSL
+
+Use the SQL DSL when you also want to project the computed distance:
+
+```typescript
+const plan = db.sql.post
+  .select("id", "title")
+  .select("distance", (field, fns) => fns.cosineDistance(field.embedding, queryVector))
+  .orderBy((field, fns) => fns.cosineDistance(field.embedding, queryVector), {
+    direction: "asc",
+  })
+  .limit(10)
+  .build();
+
+const rows = await db.runtime().execute(plan);
+```
+
+## Operations
+
+| Operation | Returns | Use it for |
+| --- | --- | --- |
+| `cosineDistance(rhs)` | `number` | Ranking nearest vectors first. Lower values are closer. |
+| `cosineSimilarity(rhs)` | `number` | Ranking by similarity score. Higher values are more similar. |
+
+Both operations are available only on vector fields from the pgvector extension.
+
+## Type exports
+
+Use the codec types when a helper needs to reference vector values directly:
+
+```typescript
+import type { Vector } from "@prisma-next/extension-pgvector/codec-types";
+
+function normalizeEmbedding(value: Vector<1536>) {
+  return value;
+}
+```
+
+For TypeScript-authored contracts, the package also exports `vector` from `@prisma-next/extension-pgvector/column-types` and a pure pack descriptor from `@prisma-next/extension-pgvector/pack`.
diff --git a/apps/docs/content/docs/orm/next/extensions/postgis.mdx b/apps/docs/content/docs/orm/next/extensions/postgis.mdx
new file mode 100644
index 0000000000..0ddd88e490
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/extensions/postgis.mdx
@@ -0,0 +1,180 @@
+---
+title: PostGIS extension
+description: Add geospatial types and queries to Prisma Next with PostGIS.
+url: /orm/next/extensions/postgis
+metaTitle: PostGIS extension in Prisma Next
+metaDescription: Learn how to configure PostGIS and write geospatial queries in Prisma Next.
+---
+
+The `@prisma-next/extension-postgis` pack adds geospatial column types and PostGIS-backed query operations for PostgreSQL.
+
+Use it when your app stores points, routes, neighborhoods, service areas, or any other location-aware data.
+
+## Install the package
+
+```bash
+npm install @prisma-next/extension-postgis
+```
+
+Your PostgreSQL server must allow the PostGIS extension. For local development, a PostGIS-enabled PostgreSQL image is usually the easiest path.
+
+## Configure the extension
+
+Register the control descriptor:
+
+```typescript title="prisma-next.config.ts"
+import { defineConfig } from "@prisma-next/postgres/config";
+import postgis from "@prisma-next/extension-postgis/control";
+
+export default defineConfig({
+  contract: "./prisma/contract.prisma",
+  extensions: [postgis],
+});
+```
+
+Register the runtime descriptor:
+
+```typescript title="prisma/db.ts"
+import postgis from "@prisma-next/extension-postgis/runtime";
+import postgres from "@prisma-next/postgres/runtime";
+import type { Contract } from "./contract.d";
+import contractJson from "./contract.json" with { type: "json" };
+
+export const db = postgres<Contract>({
+  contractJson,
+  extensions: [postgis],
+});
+```
+
+## Define geospatial fields
+
+Declare a `Geometry` type in PSL. SRID `4326` is the common WGS84 longitude and latitude coordinate system:
+
+```prisma title="prisma/contract.prisma"
+// use prisma-next
+
+types {
+  WgsGeometry = postgis.Geometry(4326)
+}
+
+model Cafe {
+  id       String      @id @default(uuid())
+  name     String
+  location WgsGeometry
+}
+
+model Neighborhood {
+  id       String      @id @default(uuid())
+  name     String
+  boundary WgsGeometry
+}
+```
+
+`postgis.Geometry()` without an SRID is also valid when your schema needs to store mixed coordinate systems.
+
+## Create geometry values
+
+Use the helpers from `@prisma-next/extension-postgis/geojson`:
+
+```typescript
+import { bboxPolygon, point, polygon } from "@prisma-next/extension-postgis/geojson";
+
+const ferryBuilding = point(-122.3937, 37.7955, 4326);
+
+const downtown = bboxPolygon([-122.425, 37.775, -122.4, 37.8], 4326);
+
+const boundary = polygon(
+  [
+    [-122.418, 37.77],
+    [-122.4, 37.77],
+    [-122.4, 37.785],
+    [-122.418, 37.785],
+    [-122.418, 37.77],
+  ],
+  4326,
+);
+```
+
+Coordinates are longitude first, then latitude.
+
+## Query geospatial data with the ORM
+
+Use geospatial operations on geometry fields:
+
+```typescript
+const cafes = await db.orm.Cafe
+  .where((cafe) => cafe.location.within(boundary))
+  .all();
+```
+
+Find rows within a radius and order nearest first:
+
+```typescript
+const nearby = await db.orm.Cafe
+  .where((cafe) => cafe.location.distanceSphere(ferryBuilding).lte(2_000))
+  .orderBy((cafe) => cafe.location.distanceSphere(ferryBuilding).asc())
+  .take(10)
+  .all();
+```
+
+Use `intersectsBbox` for map viewport queries:
+
+```typescript
+const visible = await db.orm.Cafe
+  .where((cafe) => cafe.location.intersectsBbox(downtown))
+  .all();
+```
+
+## Query geospatial data with the SQL DSL
+
+Use the SQL DSL when you want an explicit PostGIS projection or sort:
+
+```typescript
+const plan = db.sql.cafe
+  .select("id", "name")
+  .select("meters", (field, fns) => fns.distanceSphere(field.location, ferryBuilding))
+  .orderBy((field, fns) => fns.distanceSphere(field.location, ferryBuilding), {
+    direction: "asc",
+  })
+  .limit(5)
+  .build();
+
+const rows = await db.runtime().execute(plan);
+```
+
+## Operations
+
+| Operation | Use it for |
+| --- | --- |
+| `distance(other)` | Cartesian distance in the geometry's native units. |
+| `distanceSphere(other)` | Approximate metres between longitude and latitude geometries. |
+| `dwithin(other, distance)` | Index-friendly "within this distance" checks. |
+| `contains(other)` | Polygon or geometry containment. |
+| `within(other)` | The inverse of `contains`. |
+| `intersects(other)` | Any overlap between geometries. |
+| `intersectsBbox(other)` | Fast 2D bounding-box overlap for viewport filtering. |
+
+## SRID and units
+
+Declare an SRID at the column level when you know the coordinate system. Values created with `point`, `polygon`, and `bboxPolygon` should use the same SRID.
+
+For SRID 4326 data, `distance` returns degrees. Use `distanceSphere` when the product needs metres.
+
+## Wire format and types
+
+Runtime values are GeoJSON-shaped objects with optional SRID metadata. The codec handles the PostGIS wire format for you.
+
+```typescript
+import type { Geometry } from "@prisma-next/extension-postgis/codec-types";
+
+const route: Geometry = {
+  type: "LineString",
+  coordinates: [
+    [-122.4194, 37.7749],
+    [-122.4106, 37.7765],
+  ],
+  srid: 4326,
+};
+```
+
+The extension declares the `postgis.geometry` capability, which gates the geometry type and the operations above.
diff --git a/apps/docs/content/docs/orm/next/guides/building-queries-with-sql-dsl.mdx b/apps/docs/content/docs/orm/next/guides/building-queries-with-sql-dsl.mdx
new file mode 100644
index 0000000000..f429cfcf0b
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/guides/building-queries-with-sql-dsl.mdx
@@ -0,0 +1,136 @@
+---
+title: Building queries with the SQL DSL
+description: Build explicit PostgreSQL query plans with Prisma Next db.sql.
+url: /orm/next/guides/building-queries-with-sql-dsl
+metaTitle: Building queries with Prisma Next SQL DSL
+metaDescription: Learn how to build explicit PostgreSQL query plans with Prisma Next db.sql.
+---
+
+Use `db.sql` when you want an explicit PostgreSQL query plan while keeping contract-aware fields, result types, and extension operations.
+
+`db.sql` builds a plan. The runtime executes the plan:
+
+```typescript
+const plan = db.sql.user
+  .select("id", "email", "createdAt")
+  .limit(10)
+  .build();
+
+const rows = await db.runtime().execute(plan);
+```
+
+## Select fields
+
+```typescript
+const plan = db.sql.user
+  .select("id", "email", "createdAt")
+  .limit(10)
+  .build();
+```
+
+Select only the fields your caller needs. The result type follows the projection.
+
+## Add filters
+
+Use the `fns` helper in `where` callbacks for SQL predicates:
+
+```typescript
+const plan = db.sql.user
+  .select("id", "email")
+  .where((field, fns) => fns.eq(field.email, "alice@example.com"))
+  .build();
+```
+
+Chain `where` calls to add more conditions:
+
+```typescript
+const plan = db.sql.post
+  .select("id", "title", "createdAt")
+  .where((field, fns) => fns.ilike(field.title, "%prisma%"))
+  .where((field, fns) => fns.gte(field.createdAt, new Date("2026-01-01")))
+  .build();
+```
+
+## Order and limit
+
+```typescript
+const plan = db.sql.post
+  .select("id", "title", "createdAt")
+  .orderBy((field) => field.createdAt, { direction: "desc" })
+  .orderBy((field) => field.id, { direction: "asc" })
+  .limit(20)
+  .build();
+```
+
+Use a stable tie-breaker such as `id` when a query powers pagination or a feed.
+
+## Add computed projections
+
+Extension packs can add query operations to the SQL DSL. For example, pgvector exposes cosine distance:
+
+```typescript
+const plan = db.sql.post
+  .select("id", "title")
+  .select("distance", (field, fns) => fns.cosineDistance(field.embedding, queryVector))
+  .orderBy((field, fns) => fns.cosineDistance(field.embedding, queryVector), {
+    direction: "asc",
+  })
+  .limit(10)
+  .build();
+```
+
+This is the kind of query where the SQL DSL is a better fit than the ORM surface: the result includes a computed column that is not part of the model.
+
+## Insert, update, and delete
+
+The SQL DSL also builds mutation plans:
+
+```typescript
+const insertPlan = db.sql.user
+  .insert({
+    id: crypto.randomUUID(),
+    email: "alice@example.com",
+    createdAt: new Date(),
+  })
+  .returning("id", "email")
+  .build();
+
+const inserted = await db.runtime().execute(insertPlan);
+```
+
+```typescript
+const updatePlan = db.sql.user
+  .update({ email: "alice@prisma.io" })
+  .where((field, fns) => fns.eq(field.id, userId))
+  .returning("id", "email")
+  .build();
+
+const updated = await db.runtime().execute(updatePlan);
+```
+
+```typescript
+const deletePlan = db.sql.user
+  .delete()
+  .where((field, fns) => fns.eq(field.id, userId))
+  .returning("id")
+  .build();
+
+const deleted = await db.runtime().execute(deletePlan);
+```
+
+## Build first, execute later
+
+Because `db.sql` returns plans, you can pass plans through your own helpers before execution:
+
+```typescript
+function usersByDomain(domain: string) {
+  return db.sql.user
+    .select("id", "email")
+    .where((field, fns) => fns.ilike(field.email, `%@${domain}`))
+    .build();
+}
+
+const rows = await db.runtime().execute(usersByDomain("example.com"));
+```
+
+User input is passed as parameters by the query builder. Do not build SQL by concatenating strings.
diff --git a/apps/docs/content/docs/orm/next/guides/deploying-to-serverless-runtimes.mdx b/apps/docs/content/docs/orm/next/guides/deploying-to-serverless-runtimes.mdx
new file mode 100644
index 0000000000..ef36ef3580
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/guides/deploying-to-serverless-runtimes.mdx
@@ -0,0 +1,91 @@
+---
+title: Deploying Prisma Next to serverless runtimes
+description: Use Prisma Next in serverless and edge-like runtimes with request-scoped database connections.
+url: /orm/next/guides/deploying-to-serverless-runtimes
+metaTitle: Deploying Prisma Next to serverless runtimes
+metaDescription: Learn the Prisma Next runtime pattern for serverless deployments.
+---
+
+Serverless runtimes work best when static query surfaces are created once and database connections are acquired per request.
+
+For PostgreSQL serverless environments, use `@prisma-next/postgres/serverless`:
+
+```typescript title="prisma/db.ts"
+import postgresServerless from "@prisma-next/postgres/serverless";
+import type { Contract } from "./contract.d";
+import contractJson from "./contract.json" with { type: "json" };
+
+export const db = postgresServerless<Contract>({
+  contractJson,
+});
+```
+
+Then connect inside the request handler:
+
+```typescript
+interface Env {
+  HYPERDRIVE: { connectionString: string };
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    await using runtime = await db.connect({
+      url: env.HYPERDRIVE.connectionString,
+    });
+
+    const rows = await runtime.execute(
+      db.sql.user.select("id", "email").limit(10).build(),
+    );
+
+    return Response.json(rows);
+  },
+};
+```
+
+## Node runtime versus serverless runtime
+
+| Runtime | Import | Connection model |
+| --- | --- | --- |
+| Node or long-lived process | `@prisma-next/postgres/runtime` | Configure a URL or pool once and call `db.runtime()` or `db.connect()`. |
+| Serverless or edge-like handler | `@prisma-next/postgres/serverless` | Keep the query surface at module scope and call `db.connect({ url })` inside each request. |
+
+The serverless facade intentionally exposes `db.sql`, `db.context`, and `db.connect`. It does not keep a process-wide `db.orm` or `db.runtime()` because those can accidentally retain stale request connections.
+
+## ORM queries in serverless handlers
+
+When a serverless route needs the ORM surface, build it from the request runtime and the shared context:
+
+```typescript
+import { orm } from "@prisma-next/sql-orm-client";
+
+export default {
+  async fetch(request: Request, env: Env) {
+    await using runtime = await db.connect({
+      url: env.HYPERDRIVE.connectionString,
+    });
+
+    const client = orm({
+      runtime,
+      context: db.context,
+    });
+
+    const users = await client.User
+      .orderBy((user) => user.createdAt.desc())
+      .take(10)
+      .all();
+
+    return Response.json(users);
+  },
+};
+```
+
+## Deployment checklist
+
+- Emit `contract.json` and `contract.d.ts` before building the deployment bundle.
+- Keep the `db` object at module scope.
+- Open database connections inside the request, job, or handler.
+- Dispose request-scoped runtimes when the handler finishes.
+- Run `prisma-next db verify` in CI or before deployment.
+- Run migrations from a Node environment or controlled deployment job, not from every request.
+
+If your platform provides a database proxy such as Hyperdrive, use the connection string from that binding instead of a process-wide static URL.
diff --git a/apps/docs/content/docs/orm/next/guides/error-handling-patterns.mdx b/apps/docs/content/docs/orm/next/guides/error-handling-patterns.mdx
new file mode 100644
index 0000000000..f6212f32c1
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/guides/error-handling-patterns.mdx
@@ -0,0 +1,93 @@
+---
+title: Error handling patterns in Prisma Next
+description: Handle Prisma Next CLI and runtime errors in local development, CI, and application code.
+url: /orm/next/guides/error-handling-patterns
+metaTitle: Error handling patterns in Prisma Next
+metaDescription: Learn practical error handling patterns for Prisma Next CLI commands and runtime code.
+---
+
+Prisma Next is early-access, so error handling should make failures easy to inspect and safe to automate.
+
+## Common failure categories
+
+| Category | Where it appears | Typical fix |
+| --- | --- | --- |
+| Config errors | CLI startup | Check `prisma-next.config.ts`, `--config`, and database target wiring. |
+| Missing database URL | Database and migration commands | Pass `--db` or set `db.connection` in the config. |
+| Contract drift | `db verify`, runtime verification | Emit the contract again, apply the required database changes, then verify. |
+| Extension mismatch | CLI database commands or runtime startup | Register the same extension packs in config and runtime. |
+| Query/runtime errors | Application code | Catch errors at request or job boundaries and return an application-level error. |
+
+## Use JSON output in automation
+
+Use `--json` for scripts and CI:
+
+```bash
+prisma-next db verify --db "$DATABASE_URL" --json
+```
+
+JSON output is easier to parse than terminal text and avoids brittle log matching.
+
+## Keep verification separate from deployment
+
+Run verification before code that depends on a new contract is deployed:
+
+```bash
+prisma-next contract emit
+prisma-next db verify --db "$DATABASE_URL" --strict
+```
+
+Use `--strict` when extra database schema elements should fail the check.
+
+## Add trace output only when debugging
+
+Use trace output when a command fails in a way you need to report or debug:
+
+```bash
+prisma-next db verify --db "$DATABASE_URL" --trace
+```
+
+Keep trace output out of normal CI logs unless you need it.
+
+## Handle runtime failures at boundaries
+
+Create and close runtimes at request or job boundaries. Keep query code focused on the application operation, and translate Prisma Next failures into errors your API can return consistently.
+
+```typescript
+export async function loadUsers() {
+  try {
+    return await db.orm.User
+      .select("id", "email")
+      .take(50)
+      .all();
+  } catch (error) {
+    console.error(error);
+    throw new Error("Could not load users");
+  }
+}
+```
+
+For serverless handlers, dispose the runtime even when a query fails:
+
+```typescript
+try {
+  await using runtime = await db.connect({ url: env.HYPERDRIVE.connectionString });
+  return Response.json(
+    await runtime.execute(db.sql.user.select("id", "email").build()),
+  );
+} catch (error) {
+  console.error(error);
+  return Response.json({ error: "Could not load users" }, { status: 500 });
+}
+```
+
+## Handle migration errors conservatively
+
+Migration failures should stop deployment. Prefer this order:
+
+1. Run `prisma-next migration status --db "$DATABASE_URL"` before applying.
+2. Run `prisma-next migration apply --db "$DATABASE_URL"` from a controlled job.
+3. Run `prisma-next db verify --db "$DATABASE_URL"` after applying.
+4. Deploy application code only after verification succeeds.
+
+If a migration fails partway through, inspect the database state and migration history before retrying. Do not blindly re-run destructive changes in production.
diff --git a/apps/docs/content/docs/orm/next/guides/managing-database-migrations.mdx b/apps/docs/content/docs/orm/next/guides/managing-database-migrations.mdx
new file mode 100644
index 0000000000..e765228e05
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/guides/managing-database-migrations.mdx
@@ -0,0 +1,85 @@
+---
+title: Managing database migrations
+description: Choose between direct database reconciliation and checked-in migrations in Prisma Next.
+url: /orm/next/guides/managing-database-migrations
+metaTitle: Managing database migrations in Prisma Next
+metaDescription: Learn how Prisma Next handles database initialization, updates, verification, and migration packages.
+---
+
+Prisma Next database changes start from the emitted contract. After you change the contract, emit artifacts first:
+
+```bash
+prisma-next contract emit
+```
+
+Then choose either the direct database workflow or the checked-in migration workflow.
+
+## Direct database workflow
+
+Use direct commands when you want Prisma Next to bring a database in line with the current contract:
+
+```bash
+prisma-next db init --db "$DATABASE_URL"
+prisma-next db update --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+| Command | Use it when |
+| --- | --- |
+| `db init` | Creating missing structures for the first time. It is intended for additive bootstrap work. |
+| `db update` | Reconciling an existing database with a changed contract. |
+| `db verify` | Checking that a live database still matches the emitted contract. |
+
+Use `--dry-run` with `db init` or `db update` before touching a shared database:
+
+```bash
+prisma-next db update --db "$DATABASE_URL" --dry-run
+```
+
+## Checked-in migration workflow
+
+Use migration packages when you want database changes reviewed in version control:
+
+```bash
+prisma-next migration plan --name add-users-table
+prisma-next migration status --db "$DATABASE_URL"
+prisma-next migration apply --db "$DATABASE_URL"
+```
+
+`migration plan` is offline. It creates a migration package from contract changes. `migration apply` runs pending packages against the database.
+
+## Suggested development loop
+
+1. Edit the PSL or TypeScript contract source.
+2. Run `prisma-next contract emit`.
+3. Run `prisma-next migration plan --name <change-name>`.
+4. Review the generated migration package.
+5. Run `prisma-next migration status --db "$DATABASE_URL"`.
+6. Run `prisma-next migration apply --db "$DATABASE_URL"`.
+7. Run `prisma-next db verify --db "$DATABASE_URL"`.
+
+For a small local prototype, `db update --dry-run` followed by `db update` can be faster. For team development, checked-in migrations are easier to review and reproduce.
+
+## Existing databases
+
+For an existing database, start by inferring a contract:
+
+```bash
+prisma-next contract infer --db "$DATABASE_URL" --output ./prisma/contract.prisma
+```
+
+Review and edit the inferred contract, then emit and sign:
+
+```bash
+prisma-next contract emit
+prisma-next db sign --db "$DATABASE_URL"
+prisma-next db verify --db "$DATABASE_URL"
+```
+
+`db sign` records that the current database matches the current contract. After signing, use `db verify` in CI to detect drift.
+
+## Extension pack migrations
+
+Some extension packs contribute their own database setup. For example, pgvector and PostGIS need database extensions enabled. When those packs are registered in your config, Prisma Next can include the required extension-space migrations alongside your application schema workflow.
+
+Always re-emit the contract after adding or removing an extension pack, then run your database workflow again.
diff --git a/apps/docs/content/docs/orm/next/guides/meta.json b/apps/docs/content/docs/orm/next/guides/meta.json
new file mode 100644
index 0000000000..e4558789bf
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/guides/meta.json
@@ -0,0 +1,10 @@
+{
+  "title": "Guides",
+  "pages": [
+    "using-the-orm-client",
+    "building-queries-with-sql-dsl",
+    "managing-database-migrations",
+    "deploying-to-serverless-runtimes",
+    "error-handling-patterns"
+  ]
+}
diff --git a/apps/docs/content/docs/orm/next/guides/using-the-orm-client.mdx b/apps/docs/content/docs/orm/next/guides/using-the-orm-client.mdx
new file mode 100644
index 0000000000..ff6a504033
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/guides/using-the-orm-client.mdx
@@ -0,0 +1,147 @@
+---
+title: Using the ORM client with Prisma Next
+description: Use db.orm for model-oriented Prisma Next queries.
+url: /orm/next/guides/using-the-orm-client
+metaTitle: Using the Prisma Next ORM client
+metaDescription: Learn how to use db.orm for model-oriented Prisma Next queries.
+---
+
+Use `db.orm` for model-oriented reads and writes. It is the highest-level Prisma Next query API and the best default for application code.
+
+## Create records
+
+```typescript
+await db.orm.User.create({
+  id: crypto.randomUUID(),
+  email: "alice@example.com",
+  createdAt: new Date(),
+});
+```
+
+Use the values your contract requires. Prisma Next checks model and field names from the emitted contract.
+
+## Filter records
+
+```typescript
+const user = await db.orm.User
+  .where((user) => user.email.eq("alice@example.com"))
+  .first();
+```
+
+Use `.all()` when you expect multiple rows:
+
+```typescript
+const users = await db.orm.User
+  .where((user) => user.createdAt.gte(new Date("2026-01-01")))
+  .all();
+```
+
+You can chain filters:
+
+```typescript
+const posts = await db.orm.Post
+  .where((post) => post.title.ilike("%prisma%"))
+  .where((post) => post.createdAt.gte(new Date("2026-01-01")))
+  .all();
+```
+
+## Order, skip, and limit records
+
+```typescript
+const newestUsers = await db.orm.User
+  .orderBy((user) => user.createdAt.desc())
+  .take(10)
+  .all();
+```
+
+Use an array when you need stable ordering by more than one field:
+
+```typescript
+const feed = await db.orm.Post
+  .orderBy([(post) => post.createdAt.desc(), (post) => post.id.asc()])
+  .skip(20)
+  .take(20)
+  .all();
+```
+
+## Select fields
+
+Use `select` to return only the fields a view needs:
+
+```typescript
+const users = await db.orm.User
+  .select("id", "email", "createdAt")
+  .take(20)
+  .all();
+```
+
+## Include relations
+
+Use `include` to load relations from the same model query:
+
+```typescript
+const users = await db.orm.User
+  .include("posts", (posts) =>
+    posts
+      .select("id", "title", "createdAt")
+      .orderBy((post) => post.createdAt.desc())
+      .take(5),
+  )
+  .take(10)
+  .all();
+```
+
+`include` works best for user-facing views that need a parent row and a small, bounded set of related rows.
+
+## Update records
+
+Filter before updating:
+
+```typescript
+await db.orm.User
+  .where((user) => user.email.eq("alice@example.com"))
+  .update({ email: "alice@prisma.io" });
+```
+
+For MongoDB collections, update helpers can also express operations such as pushing or pulling array values.
+
+## Delete records
+
+Filter before deleting:
+
+```typescript
+await db.orm.User
+  .where((user) => user.email.eq("alice@prisma.io"))
+  .delete();
+```
+
+Avoid unbounded mutations in application code. Keep destructive actions behind explicit filters and reviewable workflows.
+
+## Run ORM queries in transactions
+
+The Postgres runtime facade exposes a transaction helper:
+
+```typescript
+await db.transaction(async (tx) => {
+  const id = crypto.randomUUID();
+
+  await tx.orm.User.create({
+    id,
+    email: "alice@example.com",
+    createdAt: new Date(),
+  });
+
+  await tx.orm.Post.create({
+    id: crypto.randomUUID(),
+    userId: id,
+    title: "Hello Prisma Next",
+    createdAt: new Date(),
+  });
+});
+```
+
+The transaction commits when the callback resolves and rolls back when the callback throws.
+
+## When to switch to a lower-level API
+
+Stay with `db.orm` for normal model work. Switch to [`db.sql`](/orm/next/guides/building-queries-with-sql-dsl) when you need explicit PostgreSQL projections, computed columns, extension functions, or a query plan you want to review directly.
diff --git a/apps/docs/content/docs/orm/next/index.mdx b/apps/docs/content/docs/orm/next/index.mdx
new file mode 100644
index 0000000000..c4846f5b6c
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/index.mdx
@@ -0,0 +1,68 @@
+---
+title: What is Prisma Next?
+description: Learn the Prisma Next ORM model, from contracts to query APIs, migrations, and extensions.
+url: /orm/next
+metaTitle: What is Prisma Next?
+metaDescription: Learn the Prisma Next ORM model, from contracts to query APIs, migrations, and extensions.
+badge: early-access
+---
+
+Prisma Next is the next foundation for Prisma ORM. It keeps the familiar idea of modeling application data in one place, then makes that model more explicit: you emit a contract, load that contract at runtime, verify databases against it, and use it from more than one query API.
+
+:::warning[Prisma Next is still in development]
+
+Prisma Next is not ready for production yet. Prisma ORM 7 is still the recommended choice for production applications today.
+
+:::
+
+## Why Prisma Next exists
+
+Prisma Next is built around a contract that can be checked by both tooling and runtime code. That gives you a clearer path for early-access workflows that need:
+
+- contract artifacts that can be generated, committed, and inspected
+- database verification before code that depends on a contract is deployed
+- model-oriented ORM queries and lower-level SQL plans in the same project
+- extension packs for capabilities such as vector search, geospatial queries, and searchable encrypted columns
+
+## How Prisma Next fits together
+
+The ORM workflow has four main pieces:
+
+| Piece | What it does |
+| --- | --- |
+| Contract | The schema your application expects. You can author it in PSL or TypeScript. |
+| Emitted artifacts | `contract.json` and `contract.d.ts`, generated with `prisma-next contract emit`. |
+| Runtime client | The database-specific client that loads the emitted contract. |
+| Query APIs | `db.orm` for model queries, `db.sql` for PostgreSQL plans, and `db.query` for MongoDB plans. |
+
+Database changes build on the same contract. You can initialize or reconcile a database directly with `db init` and `db update`, or create checked-in migration packages with `migration plan` and `migration apply`.
+
+## How it differs from Prisma ORM 7
+
+| Prisma ORM 7 | Prisma Next |
+| --- | --- |
+| Generates a client from `schema.prisma`. | Emits an explicit contract used by tooling and runtime clients. |
+| Uses Prisma Client as the main query API. | Provides `db.orm` plus lower-level query builders such as `db.sql`. |
+| Migration workflows are centered on Prisma Migrate. | Migration and verification commands operate from the emitted contract. |
+| Preview database capabilities are usually part of the main ORM surface. | Optional capabilities can be composed through extension packs. |
+
+## Typical workflow
+
+1. Define a contract in PSL or TypeScript.
+2. Run `prisma-next contract emit`.
+3. Use `db init`, `db update`, or `migration plan` to align the database.
+4. Query through `db.orm`, `db.sql`, or `db.query`.
+5. Run `db verify` in CI or before deployment to catch drift.
+
+## Start with the right section
+
+Use [Getting Started](/next) when you want setup instructions, including [`create-prisma@next`](/next/create-prisma). `create-prisma@next` scaffolds a complete application template and adds package scripts for contract emission, database initialization, verification, and migrations.
+
+Stay in this ORM section when you want to understand the Prisma Next model:
+
+- [Contract-first design](/orm/next/concepts/contract-first-design)
+- [Schema definition and contract emission](/orm/next/concepts/schema-definition-and-contract-emission)
+- [Query APIs](/orm/next/concepts/query-apis)
+- [Extension packs](/orm/next/concepts/extension-packs)
+
+Use the [Prisma Next CLI reference](/cli/next) when you need exact command flags.
diff --git a/apps/docs/content/docs/orm/next/meta.json b/apps/docs/content/docs/orm/next/meta.json
new file mode 100644
index 0000000000..4ea134414c
--- /dev/null
+++ b/apps/docs/content/docs/orm/next/meta.json
@@ -0,0 +1,18 @@
+{
+  "title": "Next",
+  "defaultOpen": true,
+  "root": true,
+  "pages": [
+    "---Introduction---",
+    "index",
+
+    "---Core Concepts---",
+    "...concepts",
+
+    "---Guides---",
+    "...guides",
+
+    "---Extensions---",
+    "...extensions"
+  ]
+}
diff --git a/apps/docs/cspell.json b/apps/docs/cspell.json
index d7efb2b6c0..49df3a803f 100644
--- a/apps/docs/cspell.json
+++ b/apps/docs/cspell.json
@@ -5,6 +5,7 @@
   "words": [
     "ABAC",
     "Activeusers",
+    "accountid",
     "Aiven",
     "amcheck",
     "amet",
@@ -46,6 +47,8 @@
     "catcat",
     "cerbos",
     "Cerbos",
+    "cipherstash",
+    "Cipherstash",
     "citext",
     "Citext",
     "cloudflare",
@@ -77,7 +80,9 @@
     "Dmmf",
     "Dockerfiles",
     "dotenvx",
+    "dwithin",
     "Dreamies",
+    "geospatial",
     "earthdistance",
     "ecommerce",
     "Ecommerce",
@@ -87,6 +92,7 @@
     "Emelie",
     "Enya",
     "epsg",
+    "emailverified",
     "everytime",
     "extralight",
     "favorited",
diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs
index 8a4fe83e2f..f89ccb2b99 100644
--- a/apps/docs/next.config.mjs
+++ b/apps/docs/next.config.mjs
@@ -258,11 +258,35 @@ const config = {
         destination: "/orm/v6/:path*",
         permanent: true,
       },
+      {
+        source: "/orm/next/create-prisma",
+        destination: "/next/create-prisma",
+        permanent: false,
+      },
+      {
+        source: "/next/quickstart",
+        destination: "/next/create-prisma",
+        permanent: false,
+      },
+      {
+        source: "/next/quickstart/:path*",
+        destination: "/next/create-prisma",
+        permanent: false,
+      },
+      {
+        source: "/orm/next/quickstart/:path*",
+        destination: "/next/create-prisma",
+        permanent: false,
+      },
+      {
+        source: "/orm/next/add-to-existing-project/:path*",
+        destination: "/next/add-to-existing-project/:path*",
+        permanent: false,
+      },
     ];
   },
   async rewrites() {
     return [
-    
       // {
       //   source: "/orm/:path((?!latest(?:/|$)|v6(?:/|$)).*)",
       //   destination: "/orm/latest/:path",
diff --git a/apps/docs/src/app/(docs)/(default)/layout.tsx b/apps/docs/src/app/(docs)/(default)/layout.tsx
index c3e72e332f..1fd661035c 100644
--- a/apps/docs/src/app/(docs)/(default)/layout.tsx
+++ b/apps/docs/src/app/(docs)/(default)/layout.tsx
@@ -25,11 +25,7 @@ const SIDEBAR_SLIDES = [
   },
 ];
 
-export default async function Layout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
+export default async function Layout({ children }: { children: React.ReactNode }) {
   const { nav, ...base } = baseOptions();
 
   const navbarLinks: LinkItemType[] = [...links, ...authLinks];
@@ -47,6 +43,7 @@ export default async function Layout({
 
   const badges = Object.fromEntries(getPageBadges());
   const ormVersions = getOrmVersions(source.pageTree);
+  const pageUrls = source.getPages().map((page) => page.url);
 
   return (
     <BadgeProvider badges={badges}>
@@ -56,7 +53,7 @@ export default async function Layout({
         nav={{ ...nav }}
         sidebar={{
           collapsible: false,
-          banner: <VersionSwitcher versions={ormVersions} />,
+          banner: <VersionSwitcher versions={ormVersions} availablePathnames={pageUrls} />,
           components: { Item: SidebarBadgeItem },
           footer: ({ className, ...props }: ComponentProps<"div">) => (
             <div className={cn("flex flex-col p-4 pt-2 gap-3", className)} {...props}>
diff --git a/apps/docs/src/app/layout.tsx b/apps/docs/src/app/layout.tsx
index 5ed0591ba7..973197038b 100644
--- a/apps/docs/src/app/layout.tsx
+++ b/apps/docs/src/app/layout.tsx
@@ -1,11 +1,15 @@
 import { Provider } from "@/components/provider";
+import { buttonVariants } from "@/components/ui/button";
+import { cn } from "@prisma-docs/ui/lib/cn";
 import { getBaseUrl } from "@/lib/urls";
 import "./global.css";
 import { Inter, Barlow } from "next/font/google";
 import type { Metadata } from "next";
 import type { ReactNode } from "react";
+import Link from "next/link";
 import Script from "next/script";
 import { FontAwesomeScript as EclipseFA } from "@prisma/eclipse";
+import { Banner } from "fumadocs-ui/components/banner";
 
 const inter = Inter({
   subsets: ["latin"],
@@ -82,6 +86,27 @@ export default function Layout({ children }: { children: ReactNode }) {
         />
       </head>
       <body className="flex flex-col min-h-screen">
+        <Banner
+          id="prisma-next-docs"
+          height="3.25rem"
+          className="border-b border-fd-border bg-fd-background text-fd-foreground"
+        >
+          <div className="flex w-full items-center justify-center gap-2 pr-8 text-xs sm:text-sm">
+            <span className="font-semibold">Prisma Next is in early access.</span>
+            <span className="hidden text-fd-muted-foreground sm:inline">
+              Explore the next Prisma ORM workflow.
+            </span>
+            <Link
+              href="/next"
+              className={cn(
+                buttonVariants({ variant: "secondary", size: "sm" }),
+                "h-7 shrink-0 whitespace-nowrap px-2 py-1 text-xs",
+              )}
+            >
+              Read the docs
+            </Link>
+          </div>
+        </Banner>
         <Provider>{children}</Provider>
         {/* Tolt affiliate tracking — type="text/plain" + data-cookieyes mirrors
             the consent-gate pattern used in the site app; stays inert until
diff --git a/apps/docs/src/components/layout/link-item.tsx b/apps/docs/src/components/layout/link-item.tsx
index 10e0379f53..addbbd3e10 100644
--- a/apps/docs/src/components/layout/link-item.tsx
+++ b/apps/docs/src/components/layout/link-item.tsx
@@ -2,6 +2,7 @@
 import { type ComponentProps, type ReactNode, useEffect, useState } from "react";
 import { usePathname } from "fumadocs-core/framework";
 import { isActive, isActiveAny } from "../../lib/urls";
+import { getVersionedNavPathname } from "../../lib/version";
 import { getUtmParams, hasUtmParams } from "@prisma-docs/ui/lib/utm";
 import Link from "fumadocs-core/link";
 
@@ -44,6 +45,10 @@ interface WithHref {
    * @defaultValue 'url'
    */
   active?: "url" | "nested-url" | "none";
+  /**
+   * Preserve the current docs version when linking between top-level docs sections.
+   */
+  preserveDocsVersion?: boolean;
   /**
    * Optional list of paths that make this link active (exact or nested).
    * Use for catch-all links that should be active on e.g. `/`, `/prisma-orm/*`, `/prisma-postgres/*`.
@@ -134,7 +139,9 @@ export function LinkItem({
     ? isActiveAny(item.activePaths, pathname)
     : activeType !== "none" && isActive(item.url, pathname, activeType === "nested-url");
 
-  const href = useUtmHref(item.url);
+  const href = useUtmHref(
+    item.preserveDocsVersion ? getVersionedNavPathname(item.url, pathname) : item.url,
+  );
 
   return (
     <Link ref={ref} href={href} external={item.external} {...props} data-active={active}>
diff --git a/apps/docs/src/components/layout/notebook/page/client.tsx b/apps/docs/src/components/layout/notebook/page/client.tsx
index 198c6f0997..5a704d92d2 100644
--- a/apps/docs/src/components/layout/notebook/page/client.tsx
+++ b/apps/docs/src/components/layout/notebook/page/client.tsx
@@ -22,12 +22,13 @@ import { usePathname } from "fumadocs-core/framework";
 import { type BreadcrumbOptions, getBreadcrumbItemsFromPath } from "fumadocs-core/breadcrumb";
 import { formatSlugDisplayName } from "@/lib/breadcrumb-utils";
 import { getPageTitleText } from "@/lib/page-title";
+import { getVersionedSidebarTree } from "@/lib/versioned-sidebar-tree";
 import { isActive } from "../../../../lib/urls";
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from "../../../ui/collapsible";
 import { useTOCItems } from "../../../toc";
 import { useActiveAnchor } from "fumadocs-core/toc";
 import { LayoutContext, SidebarEnabledSetterContext } from "../client";
-import { useFooterItems } from "@fumadocs/base-ui/utils/use-footer-items";
+import { flattenTree } from "fumadocs-core/page-tree";
 
 const TocPopoverContext = createContext<{
   open: boolean;
@@ -261,8 +262,12 @@ export interface FooterProps extends ComponentProps<"div"> {
 }
 
 export function PageFooter({ items, children, className, ...props }: FooterProps) {
-  const footerList = useFooterItems();
   const pathname = usePathname();
+  const { root } = useTreeContext();
+  const footerList = useMemo(() => {
+    const tree = getVersionedSidebarTree(root as PageTree.Root, pathname);
+    return flattenTree(tree.children).filter((item) => !item.external);
+  }, [pathname, root]);
   const { previous, next } = useMemo(() => {
     if (items) return items;
 
diff --git a/apps/docs/src/components/version-switcher.tsx b/apps/docs/src/components/version-switcher.tsx
index 371d74b187..92f4ce08c5 100644
--- a/apps/docs/src/components/version-switcher.tsx
+++ b/apps/docs/src/components/version-switcher.tsx
@@ -4,9 +4,14 @@ import { usePathname, useRouter } from "next/navigation";
 import { ChevronDownIcon } from "lucide-react";
 
 import {
+  getCliVersionFromPathname,
+  getGettingStartedVersionFromPathname,
   getOrmVersionFromPathname,
   getVersionLabel,
-  getVersionRoot,
+  getVersionSwitchPathname,
+  isCliVersionPathname,
+  isGettingStartedVersionPathname,
+  LATEST_VERSION,
   type Version,
 } from "@/lib/version";
 
@@ -18,43 +23,67 @@ import {
   DropdownMenuTrigger,
 } from "@prisma/eclipse";
 
-export function VersionSwitcher({ versions }: { versions: Version[] }) {
-  const pathname = usePathname();
+export function VersionSwitcher({
+  versions,
+  availablePathnames,
+}: {
+  versions: Version[];
+  availablePathnames?: string[];
+}) {
+  const pathname = usePathname() as string;
   const router = useRouter();
-  const currentVersion = getOrmVersionFromPathname(pathname);
+  const isGettingStartedVersion = isGettingStartedVersionPathname(pathname);
+  const isCliVersion = isCliVersionPathname(pathname);
+  const detectedVersion =
+    getGettingStartedVersionFromPathname(pathname) ??
+    getCliVersionFromPathname(pathname) ??
+    getOrmVersionFromPathname(pathname);
+  const currentVersion = detectedVersion ?? null;
+  const usesScopedVersions = isGettingStartedVersion || isCliVersion;
+  const visibleVersions = usesScopedVersions
+    ? versions.filter((version) => version === LATEST_VERSION || version === "next")
+    : versions;
+  const label = isGettingStartedVersion
+    ? "Docs version"
+    : isCliVersion
+      ? "CLI version"
+      : "ORM version";
 
-  if (!currentVersion || !versions.includes(currentVersion)) {
+  if (!currentVersion || !visibleVersions.includes(currentVersion)) {
     return null;
   }
 
   const handleVersionChange = (newVersion: Version) => {
     if (newVersion === currentVersion) return;
 
-    router.push(getVersionRoot(newVersion));
+    router.push(getVersionSwitchPathname(pathname, newVersion, availablePathnames));
   };
 
   return (
-    <DropdownMenu>
-      <DropdownMenuTrigger className="flex items-center rounded-md border background bg-fd-background px-3 py-1.5 text-sm font-medium text-fd-foreground hover:bg-fd-accent transition-colors cursor-pointer justify-between">
-        <p>{getVersionLabel(currentVersion)}</p>
-        <ChevronDownIcon className="size-4 text-fd-muted-foreground" />
-      </DropdownMenuTrigger>
-      <DropdownMenuContent align="start">
-        <DropdownMenuRadioGroup
-          value={currentVersion}
-          onValueChange={handleVersionChange}
+    <div className="flex flex-col gap-1.5">
+      <span className="px-1 text-xs font-medium text-fd-muted-foreground">{label}</span>
+      <DropdownMenu>
+        <DropdownMenuTrigger
+          aria-label={`Select ${label.toLowerCase()}`}
+          className="flex w-full cursor-pointer items-center justify-between gap-2 rounded-md border bg-fd-background px-3 py-2 text-sm font-medium text-fd-foreground transition-colors hover:bg-fd-accent"
         >
-          {versions.map((v) => (
-            <DropdownMenuRadioItem
-              key={v}
-              value={v}
-              className="cursor-pointer transition-colors hover:bg-fd-accent"
-            >
-              {getVersionLabel(v)}
-            </DropdownMenuRadioItem>
-          ))}
-        </DropdownMenuRadioGroup>
-      </DropdownMenuContent>
-    </DropdownMenu>
+          <span>{getVersionLabel(currentVersion)}</span>
+          <ChevronDownIcon className="size-4 text-fd-muted-foreground" />
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="start" className="min-w-(--radix-dropdown-menu-trigger-width)">
+          <DropdownMenuRadioGroup value={currentVersion} onValueChange={handleVersionChange}>
+            {visibleVersions.map((version) => (
+              <DropdownMenuRadioItem
+                key={version}
+                value={version}
+                className="cursor-pointer transition-colors hover:bg-fd-accent"
+              >
+                {getVersionLabel(version)}
+              </DropdownMenuRadioItem>
+            ))}
+          </DropdownMenuRadioGroup>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
   );
 }
diff --git a/apps/docs/src/lib/layout.shared.tsx b/apps/docs/src/lib/layout.shared.tsx
index 0ed483d0ed..79a5ff1e7f 100644
--- a/apps/docs/src/lib/layout.shared.tsx
+++ b/apps/docs/src/lib/layout.shared.tsx
@@ -22,13 +22,15 @@ export const links: LinkItemTypeWithActivePaths[] = [
     text: "Getting Started",
     url: "/",
     active: "nested-url",
-    activePaths: ["/", "/prisma-orm", "/prisma-postgres"],
+    activePaths: ["/", "/next", "/prisma-orm", "/prisma-postgres"],
+    preserveDocsVersion: true,
   },
   {
     text: "ORM",
     url: "/orm",
     active: "nested-url",
-    activePaths: ["/orm", "/orm/v6"],
+    activePaths: ["/orm", "/orm/next", "/orm/v6"],
+    preserveDocsVersion: true,
   },
   {
     text: "Postgres",
@@ -39,6 +41,7 @@ export const links: LinkItemTypeWithActivePaths[] = [
     text: "CLI",
     url: "/cli",
     active: "nested-url",
+    preserveDocsVersion: true,
   },
   {
     text: "Guides",
diff --git a/apps/docs/src/lib/version.ts b/apps/docs/src/lib/version.ts
index a868ef86ca..a94852ded0 100644
--- a/apps/docs/src/lib/version.ts
+++ b/apps/docs/src/lib/version.ts
@@ -1,7 +1,7 @@
 import type * as PageTree from "fumadocs-core/page-tree";
 
 export const LATEST_VERSION = "latest";
-const NAMED_VERSIONS = ["next", 'v6'] as const;
+const NAMED_VERSIONS = ["next", "v6"] as const;
 export type Version = string;
 
 type TreeNode = {
@@ -16,11 +16,49 @@ type TreeNode = {
 
 const VERSION_SEGMENT_REGEX = /^v\d+$/i;
 const LEGACY_ORM_VERSION_REGEX = /^\/(?<version>[a-z0-9-]+)\/orm(?:\/|$)/i;
+const DOCS_PREFIX = "/docs";
+const NEXT_GETTING_STARTED_ROOT = "/next";
+const LATEST_CLI_ROOT = "/cli";
+const NEXT_CLI_ROOT = "/cli/next";
+const NEXT_GETTING_STARTED_PATHS_BY_LATEST_PATH = new Map<string, string>([
+  ["/", NEXT_GETTING_STARTED_ROOT],
+  ["/getting-started", NEXT_GETTING_STARTED_ROOT],
+  ["/prisma-orm", NEXT_GETTING_STARTED_ROOT],
+  ["/prisma-orm/quickstart/postgresql", "/next/create-prisma"],
+  ["/prisma-orm/quickstart/mongodb", "/next/create-prisma"],
+  ["/prisma-orm/add-to-existing-project/postgresql", "/next/add-to-existing-project/postgresql"],
+  ["/prisma-orm/add-to-existing-project/mongodb", "/next/add-to-existing-project/mongodb"],
+]);
+const LATEST_GETTING_STARTED_PATHS_BY_NEXT_PATH = new Map<string, string>([
+  [NEXT_GETTING_STARTED_ROOT, "/"],
+  ["/next/create-prisma", "/"],
+  ["/next/add-to-existing-project/postgresql", "/prisma-orm/add-to-existing-project/postgresql"],
+  ["/next/add-to-existing-project/mongodb", "/prisma-orm/add-to-existing-project/mongodb"],
+]);
+
+function normalizePathname(pathname: string) {
+  const path = pathname.split(/[?#]/, 1)[0] || "/";
+  return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+}
+
+function withoutDocsPrefix(pathname: string) {
+  const normalizedPathname = normalizePathname(pathname);
+
+  if (normalizedPathname === DOCS_PREFIX) {
+    return "/";
+  }
+
+  if (normalizedPathname.startsWith(`${DOCS_PREFIX}/`)) {
+    return normalizedPathname.slice(DOCS_PREFIX.length) || "/";
+  }
+
+  return normalizedPathname;
+}
 
 function isOrmNode(node: TreeNode) {
   return (
     node.type === "folder" &&
-    (node.root === true || node.name === "ORM" || node.index?.url === "/orm")
+    (node.name === "ORM" || node.index?.url === "/orm" || node.index?.url?.startsWith("/orm/"))
   );
 }
 
@@ -118,22 +156,200 @@ export function getVersionRoot(version: Version) {
   return version === LATEST_VERSION ? "/orm" : `/orm/${version}`;
 }
 
+function isLatestGettingStartedPathname(pathname: string) {
+  return (
+    pathname === "/" ||
+    pathname === "/getting-started" ||
+    pathname === "/prisma-orm" ||
+    pathname.startsWith("/prisma-orm/") ||
+    pathname === "/prisma-postgres" ||
+    pathname.startsWith("/prisma-postgres/")
+  );
+}
+
+function isNextGettingStartedPathname(pathname: string) {
+  return (
+    pathname === NEXT_GETTING_STARTED_ROOT || pathname.startsWith(`${NEXT_GETTING_STARTED_ROOT}/`)
+  );
+}
+
+function getGettingStartedSwitchPathname(docsPathname: string, targetVersion: Version) {
+  if (targetVersion === "next") {
+    return NEXT_GETTING_STARTED_PATHS_BY_LATEST_PATH.get(docsPathname) ?? NEXT_GETTING_STARTED_ROOT;
+  }
+
+  if (targetVersion === LATEST_VERSION) {
+    return LATEST_GETTING_STARTED_PATHS_BY_NEXT_PATH.get(docsPathname) ?? "/";
+  }
+
+  return getVersionRoot(targetVersion);
+}
+
+function isLatestCliPathname(pathname: string) {
+  return (
+    pathname === LATEST_CLI_ROOT ||
+    (pathname.startsWith(`${LATEST_CLI_ROOT}/`) && !isNextCliPathname(pathname))
+  );
+}
+
+function isNextCliPathname(pathname: string) {
+  return pathname === NEXT_CLI_ROOT || pathname.startsWith(`${NEXT_CLI_ROOT}/`);
+}
+
+function getAvailablePathnameSet(availablePathnames: Iterable<string>) {
+  return new Set(
+    Array.from(availablePathnames, (availablePathname) => withoutDocsPrefix(availablePathname)),
+  );
+}
+
+function getCliSwitchPathname(
+  docsPathname: string,
+  targetVersion: Version,
+  availablePathnames: Iterable<string>,
+) {
+  if (targetVersion !== LATEST_VERSION && targetVersion !== "next") {
+    return getVersionRoot(targetVersion);
+  }
+
+  const targetRoot = targetVersion === "next" ? NEXT_CLI_ROOT : LATEST_CLI_ROOT;
+  const currentRoot = isNextCliPathname(docsPathname) ? NEXT_CLI_ROOT : LATEST_CLI_ROOT;
+  const suffix =
+    docsPathname === currentRoot
+      ? ""
+      : docsPathname.startsWith(`${currentRoot}/`)
+        ? docsPathname.slice(currentRoot.length)
+        : "";
+  const candidate = `${targetRoot}${suffix}`;
+  const available = getAvailablePathnameSet(availablePathnames);
+
+  if (available.size === 0 || available.has(candidate)) {
+    return candidate;
+  }
+
+  return targetRoot;
+}
+
+export function getGettingStartedVersionFromPathname(pathname: string): Version | null {
+  const docsPathname = withoutDocsPrefix(pathname);
+
+  if (isNextGettingStartedPathname(docsPathname)) {
+    return "next";
+  }
+
+  if (isLatestGettingStartedPathname(docsPathname)) {
+    return LATEST_VERSION;
+  }
+
+  return null;
+}
+
+export function isGettingStartedVersionPathname(pathname: string) {
+  return getGettingStartedVersionFromPathname(pathname) !== null;
+}
+
+export function getCliVersionFromPathname(pathname: string): Version | null {
+  const docsPathname = withoutDocsPrefix(pathname);
+
+  if (isNextCliPathname(docsPathname)) {
+    return "next";
+  }
+
+  if (isLatestCliPathname(docsPathname)) {
+    return LATEST_VERSION;
+  }
+
+  return null;
+}
+
+export function isCliVersionPathname(pathname: string) {
+  return getCliVersionFromPathname(pathname) !== null;
+}
+
 export function getOrmVersionFromPathname(pathname: string): Version | null {
-  const legacyMatch = pathname.match(LEGACY_ORM_VERSION_REGEX);
+  const docsPathname = withoutDocsPrefix(pathname);
+  const legacyMatch = docsPathname.match(LEGACY_ORM_VERSION_REGEX);
   if (legacyMatch?.groups?.version) {
     return legacyMatch.groups.version.toLowerCase();
   }
 
-  if (pathname !== "/orm" && !pathname.startsWith("/orm/")) {
+  if (docsPathname !== "/orm" && !docsPathname.startsWith("/orm/")) {
     return null;
   }
 
-  const segments = pathname.split("/").filter(Boolean);
+  const segments = docsPathname.split("/").filter(Boolean);
   const version = segments[1];
 
   return isVersionSegment(version) ? version.toLowerCase() : LATEST_VERSION;
 }
 
+export function getVersionSwitchPathname(
+  pathname: string,
+  targetVersion: Version,
+  availablePathnames: Iterable<string> = [],
+) {
+  const docsPathname = withoutDocsPrefix(pathname);
+  const gettingStartedVersion = getGettingStartedVersionFromPathname(docsPathname);
+
+  if (gettingStartedVersion) {
+    return getGettingStartedSwitchPathname(docsPathname, targetVersion);
+  }
+
+  const cliVersion = getCliVersionFromPathname(docsPathname);
+
+  if (cliVersion) {
+    return getCliSwitchPathname(docsPathname, targetVersion, availablePathnames);
+  }
+
+  const currentVersion = getOrmVersionFromPathname(docsPathname);
+  const targetRoot = getVersionRoot(targetVersion);
+
+  if (!currentVersion) {
+    return targetRoot;
+  }
+
+  const currentRoot = getVersionRoot(currentVersion);
+  const suffix =
+    docsPathname === currentRoot
+      ? ""
+      : docsPathname.startsWith(`${currentRoot}/`)
+        ? docsPathname.slice(currentRoot.length)
+        : "";
+  const candidate = `${targetRoot}${suffix}`;
+  const available = getAvailablePathnameSet(availablePathnames);
+
+  if (available.size === 0 || available.has(candidate)) {
+    return candidate;
+  }
+
+  return targetRoot;
+}
+
+export function getVersionedNavPathname(targetPathname: string, currentPathname: string) {
+  const targetDocsPathname = withoutDocsPrefix(targetPathname);
+  const isNextDocsPathname =
+    getGettingStartedVersionFromPathname(currentPathname) === "next" ||
+    getOrmVersionFromPathname(currentPathname) === "next" ||
+    getCliVersionFromPathname(currentPathname) === "next";
+
+  if (!isNextDocsPathname) {
+    return targetPathname;
+  }
+
+  if (targetDocsPathname === "/") {
+    return NEXT_GETTING_STARTED_ROOT;
+  }
+
+  if (targetDocsPathname === "/orm") {
+    return "/orm/next";
+  }
+
+  if (targetDocsPathname === LATEST_CLI_ROOT) {
+    return NEXT_CLI_ROOT;
+  }
+
+  return targetPathname;
+}
+
 export function getOrmVersionFromRoute(route?: string | string[]): Version | null {
   if (Array.isArray(route)) {
     if (route[0] !== "orm") {
@@ -152,7 +368,7 @@ export function getOrmVersionFromRoute(route?: string | string[]): Version | nul
 
 export function getOrmVersions(tree: PageTree.Root): Version[] {
   const ormNode = findOrmNode(tree as TreeNode);
-  const versions = new Set<Version>();
+  const versions = new Set<Version>(NAMED_VERSIONS);
 
   for (const child of ormNode?.children ?? []) {
     const version = getVersionFromNode(child);
@@ -161,5 +377,5 @@ export function getOrmVersions(tree: PageTree.Root): Version[] {
     }
   }
 
-  return [LATEST_VERSION, "v6", ...Array.from(versions).sort(compareVersionsDescending)];
+  return [LATEST_VERSION, ...Array.from(versions).sort(compareVersionsDescending)];
 }
diff --git a/apps/docs/src/lib/versioned-sidebar-tree.ts b/apps/docs/src/lib/versioned-sidebar-tree.ts
index 7a226742b1..6e7abdde15 100644
--- a/apps/docs/src/lib/versioned-sidebar-tree.ts
+++ b/apps/docs/src/lib/versioned-sidebar-tree.ts
@@ -1,6 +1,8 @@
 import type * as PageTree from "fumadocs-core/page-tree";
 import {
   LATEST_VERSION,
+  getCliVersionFromPathname,
+  getGettingStartedVersionFromPathname,
   getOrmVersionFromRoute,
   getOrmVersions,
   getVersionRoot,
@@ -23,10 +25,46 @@ type TreeRootNode = TreeNode & {
 function isOrmNode(node: TreeNode) {
   return (
     node.type === "folder" &&
-    (node.root === true || node.name === "ORM" || node.index?.url === "/orm")
+    (node.name === "ORM" || node.index?.url === "/orm" || node.index?.url?.startsWith("/orm/"))
   );
 }
 
+function isGettingStartedNode(node: TreeNode) {
+  return node.type === "folder" && (node.name === "Getting Started" || node.index?.url === "/");
+}
+
+function isCliNode(node: TreeNode) {
+  return node.type === "folder" && (node.name === "CLI" || node.index?.url === "/cli");
+}
+
+function isGettingStartedVersionNode(node: TreeNode, version: Version) {
+  if (node.type !== "folder") {
+    return false;
+  }
+
+  const name = String(node.name ?? "").toLowerCase();
+
+  if (version === "next") {
+    return name === "next" || node.index?.url === "/next";
+  }
+
+  return false;
+}
+
+function isCliVersionNode(node: TreeNode, version: Version) {
+  if (node.type !== "folder") {
+    return false;
+  }
+
+  const name = String(node.name ?? "").toLowerCase();
+
+  if (version === "next") {
+    return name === "next" || node.index?.url === "/cli/next";
+  }
+
+  return false;
+}
+
 function isVersionNode(node: TreeNode, version: Version) {
   if (node.type !== "folder") {
     return false;
@@ -70,6 +108,76 @@ function collapseVersionChildren(
   };
 }
 
+function filterGettingStartedSidebarTree(node: TreeNode, version: Version): TreeNode {
+  const children = node.children?.map((child) => filterGettingStartedSidebarTree(child, version));
+
+  if (!children) {
+    return node;
+  }
+
+  if (isGettingStartedNode(node)) {
+    const versionChildren = children.filter((child) => isGettingStartedVersionNode(child, "next"));
+
+    if (version === "next") {
+      const selectedVersion = versionChildren.find((child) =>
+        isGettingStartedVersionNode(child, version),
+      );
+
+      if (selectedVersion?.children) {
+        return {
+          ...node,
+          index: selectedVersion.index ?? node.index,
+          children: selectedVersion.children,
+        };
+      }
+    }
+
+    return {
+      ...node,
+      children: children.filter((child) => !versionChildren.includes(child)),
+    };
+  }
+
+  return {
+    ...node,
+    children,
+  };
+}
+
+function filterCliSidebarTree(node: TreeNode, version: Version): TreeNode {
+  const children = node.children?.map((child) => filterCliSidebarTree(child, version));
+
+  if (!children) {
+    return node;
+  }
+
+  if (isCliNode(node)) {
+    const versionChildren = children.filter((child) => isCliVersionNode(child, "next"));
+
+    if (version === "next") {
+      const selectedVersion = versionChildren.find((child) => isCliVersionNode(child, version));
+
+      if (selectedVersion?.children) {
+        return {
+          ...node,
+          index: selectedVersion.index ?? node.index,
+          children: selectedVersion.children,
+        };
+      }
+    }
+
+    return {
+      ...node,
+      children: children.filter((child) => !versionChildren.includes(child)),
+    };
+  }
+
+  return {
+    ...node,
+    children,
+  };
+}
+
 function filterOrmSidebarTree(node: TreeNode, version: Version): TreeNode {
   const children = node.children?.map((child) => filterOrmSidebarTree(child, version));
 
@@ -95,7 +203,91 @@ function filterOrmSidebarTree(node: TreeNode, version: Version): TreeNode {
   };
 }
 
+function findGettingStartedNode(node: TreeNode): TreeNode | null {
+  if (isGettingStartedNode(node)) {
+    return node;
+  }
+
+  for (const child of node.children ?? []) {
+    const gettingStartedNode = findGettingStartedNode(child);
+    if (gettingStartedNode) {
+      return gettingStartedNode;
+    }
+  }
+
+  return null;
+}
+
+function findCliNode(node: TreeNode): TreeNode | null {
+  if (isCliNode(node)) {
+    return node;
+  }
+
+  for (const child of node.children ?? []) {
+    const cliNode = findCliNode(child);
+    if (cliNode) {
+      return cliNode;
+    }
+  }
+
+  return null;
+}
+
+function getGettingStartedSidebarTree(tree: TreeRootNode, version: Version): TreeRootNode {
+  const filteredTree = filterGettingStartedSidebarTree(tree, version) as TreeRootNode;
+
+  if (isGettingStartedNode(filteredTree)) {
+    return filteredTree;
+  }
+
+  const gettingStartedNode = findGettingStartedNode(filteredTree);
+
+  if (!gettingStartedNode) {
+    return filteredTree;
+  }
+
+  return {
+    ...filteredTree,
+    children: [gettingStartedNode],
+  };
+}
+
+function getCliSidebarTree(tree: TreeRootNode, version: Version): TreeRootNode {
+  const filteredTree = filterCliSidebarTree(tree, version) as TreeRootNode;
+
+  if (isCliNode(filteredTree)) {
+    return filteredTree;
+  }
+
+  const cliNode = findCliNode(filteredTree);
+
+  if (!cliNode) {
+    return filteredTree;
+  }
+
+  return {
+    ...filteredTree,
+    children: [cliNode],
+  };
+}
+
 export function getVersionedSidebarTree(tree: PageTree.Root, route?: string | string[]) {
+  const gettingStartedVersion =
+    typeof route === "string" ? getGettingStartedVersionFromPathname(route) : null;
+
+  if (gettingStartedVersion) {
+    return getGettingStartedSidebarTree(
+      tree as TreeRootNode,
+      gettingStartedVersion,
+    ) as PageTree.Root;
+  }
+
+  const cliVersion = typeof route === "string" ? getCliVersionFromPathname(route) : null;
+
+  if (cliVersion) {
+    return getCliSidebarTree(tree as TreeRootNode, cliVersion) as PageTree.Root;
+  }
+
   const versions = getOrmVersions(tree);
   const explicitVersions = versions.filter((version) => version !== LATEST_VERSION);
   const version = getOrmVersionFromRoute(route);