docs(orm8): plain-language pass on the contract-authoring section

.claude/skills/docs-reader-review/scripts/check-plain.sh

@@ -6,7 +6,7 @@
 # "(unexplained)" there (emit, signature, marker, ref, plan) are allowed when the sentence
 # defines them, which a regex cannot judge; the reader review covers those.
 # What is skipped: fenced code (``` or ~~~, indented or not), indented code blocks,
-# inline code, and any line carrying the marker {/* plain-language:defined */}, which
+# inline code, link targets, pinned heading anchors, href attributes, the front-matter url line, and any line carrying the marker {/* plain-language:defined */}, which
 # an author adds only when the sentence itself defines the term in plain words.
 set -u
 pat='\bterminal (calls?|methods?|verbs?)\b|\b(read|write|query) terminals?\b|\bcodecs?\b|\benvelopes?\b|\btype position\b|\brelease (line|cycle)\b|\bruns ahead\b|\b(sql|raw|orm) lanes?\b|\blane object\b|\bfacades?\b|\bjunction (model|record|table)\b|\bjoin model\b|\bquery plans?\b|\blower(ed|ing)\b|\bnamespace-qualified\b|\bnamespace coordinate\b|\breducers?\b|\brefinement callback\b|\bdotted codes?\b|\b(CLI|config) envelope\b|\bdev loop\b|\bbrownfield\b|\bgreenfield\b|\bdeterministic\b|\bidempotent\b|\btopology\b|\bcapabilit(y|ies)\b|\bbuffer(s|ed)? (the|every|all)\b|\bmaterializ(e|es|ed)\b|\bunblocks?\b|\bAPI surface\b|\bsurfaces? (the|a|an|as)\b|\bwires? up\b|\blives at\b|\bhands back\b|\brides on\b|\broutes on\b|\bkeys on\b'
@@ -17,8 +17,9 @@ for f in "$@"; do
     infence { next }
     /^(    |\t)/ { next }
     /plain-language:defined/ { next }
+    /^url: / { next }
     { print NR": "$0 }
-  ' "$f" | sed 's/`[^`]*`//g' | grep -E -i "$pat" || true)
+  ' "$f" | sed -E 's/`[^`]*`//g; s/\]\([^)]*\)/]/g; s/\[#[^]]*\]//g; s/href="[^"]*"//g' | grep -E -i "$pat" || true)
   if [ -n "$hits" ]; then status=1; echo "== $f"; echo "$hits" | cut -c1-160; fi
 done
 if [ $status -eq 0 ]; then echo "plain-language check: clean"; else echo "plain-language check: banned terms found"; fi

apps/docs/content/docs/(index)/prisma-orm/meta.json

@@ -1,5 +1,12 @@
 {
   "title": "Prisma ORM",
   "defaultOpen": true,
-  "pages": ["index", "release-status", "create-prisma", "quickstart", "add-to-existing-project"]
+  "pages": [
+    "index",
+    "release-status",
+    "supported-databases",
+    "create-prisma",
+    "quickstart",
+    "add-to-existing-project"
+  ]
 }

apps/docs/content/docs/(index)/prisma-orm/release-status.mdx

@@ -33,7 +33,7 @@ npm install --save-dev prisma
 npm install @prisma/orm-postgres
 ```
 
-For MongoDB the library is `@prisma/orm-mongo`, and for SQLite it is `@prisma/orm-sqlite`. MySQL is not supported yet.
+For MongoDB the library is `@prisma/orm-mongo`. [Supported databases](/prisma-orm/supported-databases) lists every database and its status.
 
 The two packages have different version numbers, and that is normal: they are released separately, and the command-line tool gets more frequent releases. Install both at `latest`; any two `latest` versions work together, and you do not pair the numbers yourself.
 

apps/docs/content/docs/(index)/prisma-orm/supported-databases.mdx

@@ -0,0 +1,36 @@
+---
+title: Supported databases
+description: 'Which databases Prisma ORM 8 supports today, what release candidate and early access mean, and which databases are coming.'
+url: /prisma-orm/supported-databases
+metaTitle: Databases supported by Prisma ORM 8
+metaDescription: 'PostgreSQL is a release candidate and MongoDB is in early access. MySQL, MariaDB, SQLite, SQL Server, and CockroachDB are coming. What each label means and how to ask for a database.'
+---
+
+Prisma ORM 8 ships one library per database. Today there are two you can build on.
+
+| Database | Status | Library |
+| --- | --- | --- |
+| PostgreSQL, including Prisma Postgres | Release candidate | `@prisma/orm-postgres` |
+| MongoDB | Early access | `@prisma/orm-mongo` |
+| MySQL | Coming soon | |
+| MariaDB | Coming soon | |
+| SQLite | Coming soon | |
+| Microsoft SQL Server | Coming soon | |
+| CockroachDB | Coming soon | |
+
+## What the labels mean
+
+**Release candidate.** Install it and build with it today. Until the final release, some details of the API may still change, so code you write now may need small edits later. Each release candidate fixes bugs found in the last one. [Release status](/prisma-orm/release-status) has the dates and what `npm install` gives you.
+
+**Early access.** The library works and you can build with it, but some of what the PostgreSQL library does is not there yet. The reference pages say on each method whether it works on MongoDB, and [what is not available yet](/orm/coming-from-prisma-orm-7#not-available-yet) lists the gaps. Report what you hit on [GitHub](https://github.com/prisma/orm/issues).
+
+**Coming soon.** There is no Prisma ORM 8 library for the database yet. Prisma ORM 7 supports it, and Prisma ORM 7 keeps receiving bug fixes and security updates for 18 months after Prisma ORM 8 reaches general availability. [How to stay on Prisma ORM 7](/prisma-orm/release-status#how-to-stay-on-prisma-orm-7) shows how to lock the version.
+
+## How to ask for a database
+
+Add a 👍 to the GitHub issue for the database you need, or open one if there is none. The number of reactions is one of the inputs to what gets built next. Organizations that need a database sooner can talk to [Prisma enterprise support](https://www.prisma.io/enterprise).
+
+## Next steps
+
+- The quickstart sets up a project on [PostgreSQL](/prisma-orm/quickstart/postgresql) or [MongoDB](/prisma-orm/quickstart/mongodb).
+- [Release status](/prisma-orm/release-status) covers versions, dates, and staying on Prisma ORM 7.

apps/docs/content/docs/guides/v7/meta.json

@@ -7,6 +7,9 @@
     "deployment",
     "database",
     "switch-to-prisma-orm",
-    "integrations"
+    "integrations",
+    "---Upgrade Prisma ORM---",
+    "[Prisma ORM 7 to 8 (PostgreSQL)](/guides/upgrade-prisma-orm/postgresql)",
+    "[Prisma ORM 6 to 8 (MongoDB)](/guides/upgrade-prisma-orm/mongodb)"
   ]
 }

apps/docs/content/docs/orm/contract-authoring/capabilities.mdx

@@ -1,97 +1,97 @@
 ---
-title: Capabilities
-description: 'Capabilities record what your database stack supports, so Prisma ORM can reject unsupported features early with a clear error.'
+title: Supported database features
+description: 'The contract records which database features your packages support, so Prisma ORM can reject an unsupported one early with a clear error.'
+metaTitle: Supported database features in Prisma ORM
+metaDescription: 'How a Prisma ORM contract records which database features you can use, where the list comes from, what each key controls, and what happens when one is missing.'
 url: /orm/contract-authoring/capabilities
-metaTitle: Capabilities in Prisma ORM
-metaDescription: 'How Prisma ORM capabilities are derived from the target, adapter, and extension packs, what they gate, and what happens when a required capability is missing.'
 ---
 
-Not every database stack supports every feature. One setup can run lateral joins, `RETURNING` clauses, and vector distance operations; another cannot.
+Your [contract](/orm/contract-authoring/the-data-contract), the `contract.prisma` file that replaced `schema.prisma`, describes your data. [`npx prisma contract emit`](/cli/contract-emit) writes `contract.json` and `contract.d.ts` beside it. The `capabilities` section of `contract.json` lists the database features you can use, under keys such as `sql.lateral`. Prisma ORM writes that section, and you never edit it. If you use a feature that is not listed, Prisma ORM raises an error instead of sending the query to the database.
 
-Capabilities are how the [data contract](/orm/contract-authoring/the-data-contract) records what yours supports. Prisma ORM checks them before using a gated feature. An unsupported feature fails early with an error that names the missing capability, instead of surfacing as a database error mid-query.
+## Where the `capabilities` section comes from [#where-capabilities-come-from]
 
-## Where capabilities come from
+The keys come from your database package (`@prisma/orm-postgres`, `@prisma/orm-sqlite`, or `@prisma/orm-mongo`) and any extension packages listed in `prisma.config.ts`. `npx prisma contract emit` never connects to your database. It reads those packages and writes what they report, in groups:
 
-You do not write capabilities yourself. When [`contract emit`](/cli/contract-emit) runs, it merges the capability declarations of every component composed in your project: the target (PostgreSQL, SQLite, MongoDB), its adapter and driver, and any extension packs from the config. The merged result lands in the contract's `capabilities` section, grouped by namespace:
-
-```json title="prisma/contract.json (excerpt)"
+```json title="src/prisma/contract.json (excerpt)"
 {
   "capabilities": {
-    "postgres": {
-      "distinctOn": true,
-      "jsonAgg": true,
-      "lateral": true,
-      "limit": true,
-      "orderBy": true,
-      "pgvector.cosine": true,
-      "returning": true
-    },
-    "sql": {
-      "defaultInInsert": true,
-      "enums": true,
-      "lateral": true,
-      "returning": true,
-      "scalarList": true
-    }
+    "postgres": { "distinctOn": true, "pgvector.cosine": true },
+    "sql": { "lateral": true, "scalarList": true }
   }
 }
 ```
 
-The `sql` namespace holds keys shared across SQL databases; the `postgres` namespace holds PostgreSQL-specific keys. Extension packs contribute keys of their own: composing the pgvector pack is what adds `pgvector.cosine` above. Because the packs declare the keys, adding or removing an extension in `prisma.config.ts` and re-running `contract emit` changes the capability set with no further work.
+Error messages and the table below name a key group first, `postgres.pgvector.cosine`. The `sql` group holds keys that more than one SQL database may support. SQLite reports `false` for some of them. Keys under `postgres` belong to PostgreSQL only. Extension packages add keys of their own, and `pgvector.cosine` comes from the pgvector package. Install it with `npm install @prisma/orm-extension-pgvector`, list it in `prisma.config.ts`, and run `npx prisma contract emit` again:
+
+```typescript title="prisma.config.ts"
+import "dotenv/config";
+import { definePrismaConfig } from "prisma/config";
+import pgvector from "@prisma/orm-extension-pgvector/control";
+import { defineConfig as ormConfig } from "@prisma/orm-postgres/config";
+
+export default definePrismaConfig({
+  orm: ormConfig({
+    contract: "./src/prisma/contract.prisma",
+    extensions: [pgvector],
+    db: { connection: process.env['DATABASE_URL']! },
+  }),
+});
+```
 
-## What capabilities gate
+pgvector is also a PostgreSQL server extension, and the package ships a migration that installs it. Apply it with `npx prisma db migrate`, see [Using extensions](/orm/extensions/using-extensions). Run `npx prisma contract emit` after every change to the contract or to the extension list.
 
-Capabilities are checked at two points, both before any SQL reaches the database.
+## What the `capabilities` section controls [#what-capabilities-gate]
 
-**When the contract is built.** If the schema uses a feature the target cannot store, `contract emit` fails with a diagnostic. For example, SQLite does not report the `scalarList` capability, so a scalar list field in a contract targeting SQLite fails to emit:
+**When the contract is built.** If your contract uses a feature your database package does not support, `npx prisma contract emit` fails. SQLite has no `scalarList` key, so a list field such as `tags String[]` fails on SQLite:
 
 ```text
 Field "User.tags" is a scalar list, but target "sqlite" does not support
 scalar lists (the adapter does not report the "scalarList" capability).
+Remove the list or author it against a target that supports scalar lists.
 ```
 
-**When a query is built.** Query-builder methods that depend on a capability check the contract's `capabilities` section and throw if the key is missing, naming the method and the capability:
+In that message, both words mean your database package, and the message's `"scalarList"` is the `sql.scalarList` key. Do one of the two: remove the list field, or move to a database that supports list fields. To move to PostgreSQL, change the `@prisma/orm-sqlite/config` import and the connection string in `prisma.config.ts`, and create the new database.
+
+**When you call a method on the [SQL query builder](/orm/reference/sql-query-builder) or on the ORM client.** A method that needs a feature throws an error whose `code` is `ORM.CAPABILITY_MISSING`. The message names the method and the key:
 
 ```text
 distinctOn() requires capability postgres.distinctOn
-lateralJoin() requires capability sql.lateral
 ```
 
-The error fires when your code constructs the query, so a test that builds the query catches it: a query that uses a feature your stack lacks cannot be built at all.
+That message means the method is not available on the database package you chose. Rewrite the query without it, or move to a database that supports the feature. If the key comes from an extension package, install that package and list it in `prisma.config.ts`. You do not have to run the query to get the error, so a test that only builds the query still fails. Your own code can read the same list through `db`, the client you create once in `src/prisma/db.ts`, which `npx prisma orm init` writes. A value such as `db.contract.capabilities.sql?.lateral` is `true` or `false`, or `undefined` if the whole group is missing. For a key with a dot in it, write `db.contract.capabilities.postgres?.["pgvector.cosine"]`:
+
+```typescript
+if (db.contract.capabilities.sql?.lateral) {
+  // run the lateral join here, or fall back to a second query
+}
+```
 
-## Example capabilities
+## Example keys [#example-capabilities]
 
-A few of the keys the built-in components declare, to give a sense of the granularity:
+A few of the keys your database package and extension packages supply:
 
-| Capability | Gates |
+| Key | What it covers |
 | --- | --- |
-| `sql.lateral` | Lateral joins (`lateralJoin()`); PostgreSQL declares it, SQLite does not |
+| `sql.lateral` | Lateral joins (`lateralJoin()`) |
 | `sql.returning` | `RETURNING` clauses on writes |
-| `sql.enums` | Enum value sets enforced in the database; SQLite does not declare it |
-| `sql.defaultInInsert` | Using `DEFAULT` as a value in multi-row inserts |
-| `sql.scalarList` | Scalar list fields in the schema |
+| `sql.scalarList` | List fields such as `tags String[]` |
 | `postgres.distinctOn` | `DISTINCT ON` queries (`distinctOn()`) |
-| `postgres.jsonAgg` | JSON aggregation for nested reads |
-| `postgres.pgvector.cosine` | Cosine distance operations, contributed by the pgvector pack |
-
-This table is a sample, not the full registry. Each target, adapter, and pack ships its own declarations. Your project's emitted `contract.json` is the authoritative list of what your stack supports.
-
-MongoDB currently declares no capability keys: the capability system mostly differentiates SQL targets and their extensions, and the MongoDB pipeline does not yet gate features this way.
+| `postgres.pgvector.cosine` | Cosine distance from the pgvector package |
 
-## Capabilities and verification
+PostgreSQL reports `true` for all three `sql` keys above. SQLite reports `false` for `sql.lateral`, `true` for `sql.returning`, and has no `sql.scalarList` key at all. This table is a sample, not the full list. Open `src/prisma/contract.json` in your project to see every key you have. The MongoDB packages report no keys, so neither check applies on MongoDB. The [ORM reference](/orm/reference) lists the methods each database has.
 
-Capabilities describe what the composed software stack supports, as declared by the target, adapter, and packs. They are recorded in the contract at emit time rather than probed from the live database, so the same contract behaves identically in every environment. Database-side verification is separate: [`db verify`](/cli/db-verify) checks that the database matches the contract's schema and profile, using the hashes described in [the contract artifact](/orm/contract-authoring/the-contract-artifact#the-content-hashes).
+## The `capabilities` section and `prisma db verify` [#capabilities-and-verification]
 
-Extensions are the main source of capabilities beyond the core. [Using extensions](/orm/extensions/using-extensions) shows the full flow from install to first query.
+[`npx prisma db verify`](/cli/db-verify) checks the live database against the contract's tables and columns, not against this section. The keys say what your packages support, recorded when you run `npx prisma contract emit`.
 
 ## Prompt your coding agent
 
-Projects scaffolded with `create-prisma@latest` install [Prisma ORM skills](/ai/tools/skills#available-skills-for-prisma-8) for your coding agent. The `prisma-8` skill covers this page. Ask your agent to:
+Projects created with `npm create prisma@latest` include the [Prisma ORM skills](/ai/tools/skills#available-skills-for-prisma-8) for your coding agent. In an existing project, run `npx prisma skills sync`. The `prisma-8` skill covers this material. Ask your agent to:
 
-- "Which capabilities does our contract currently require, and which package provides each?"
-- "Add pgvector to the project and confirm the capability shows up in the emitted contract."
+- "Which keys in the `capabilities` section does our code rely on, and which package provides each?"
+- "Add pgvector to the project and confirm its key shows up in the emitted contract."
 
 ## Next steps
 
-- See where the `capabilities` block sits in [the contract artifact](/orm/contract-authoring/the-contract-artifact).
-- Compose extension packs, and the capabilities they bring, in the [CLI configuration](/cli/configuration).
+- See where the `capabilities` block is, and what `contract.d.ts` holds, in [contract.json and contract.d.ts](/orm/contract-authoring/the-contract-artifact).
+- Add extension packages, and the keys they bring, in the [CLI configuration](/cli/configuration).