docs(orm8): plain-language pass on the rest of the ORM reference section

apps/docs/content/docs/orm/coming-from-prisma-orm-7.mdx

@@ -56,6 +56,7 @@ The biggest visible change is in field types. Where Prisma ORM 7 wrote a Prisma
 | `@@schema("billing")` | `namespace billing { model ... }` | a `namespace` block is a PostgreSQL schema; wrap the models in it. They become `db.orm.billing.Invoice` and so on |
 | implicit many-to-many (`Post[]` on `Tag` and `Tag[]` on `Post`, with no model for the join table) | the same two list fields, plus a model for the join table | you write the join table as a model yourself. Example below |
 | `@id`, `@unique`, `@default`, `@relation`, `@map`, `@@map`, `@@index`, `@@id`, `@@unique` | unchanged | |
+| a required relation field over an optional foreign key, or the reverse | rejected | since `8.0.0-rc.10`, `contract emit` reports `PSL_RELATION_NULLABILITY_MISMATCH`. Give the relation field and its `@relation(fields: [...])` columns the same `?`, or none |
 
 :::note[DateTime values and Node.js versions]
 

apps/docs/content/docs/orm/reference/index.mdx

@@ -6,36 +6,46 @@ metaTitle: Prisma ORM API reference
 metaDescription: 'Reference index for the Prisma ORM client, SQL query builder, pipeline builder, raw queries, and runtime APIs.'
 ---
 
-Prisma ORM has three query surfaces. The **ORM client** gives you model-level methods like `where()`, `create()`, and `include()`, and works against both PostgreSQL and MongoDB. The **SQL query builder** gives you table-level, SQL-shaped methods like `select()`, `innerJoin()`, and `groupBy()`, and today targets PostgreSQL only. The **pipeline builder** gives you a typed way to build MongoDB aggregation pipelines through `db.query`.
+Prisma ORM gives you three typed ways to write a query. In Prisma ORM 7 you wrote `findMany({ where, include })`. Now each of those arguments is a method you chain: `.where(...).include(...)`. See [Coming from Prisma ORM 7](/orm/coming-from-prisma-orm-7), which maps each argument to its method.
 
-Use the ORM client for everyday application queries across models and relations. Reach for the SQL query builder when you need a join, aggregate, or SQL feature the ORM client doesn't expose on PostgreSQL, and the pipeline builder for MongoDB aggregation pipelines. When even those can't express a query, drop to a [raw query](/orm/reference/raw-queries); for client lifecycle, transactions, and prepared statements, see [Transactions and runtime](/orm/reference/transactions-and-runtime).
+- The **ORM client** is at `db.orm`. It has model methods such as `where()`, `create()`, and `include()`, it works on both PostgreSQL and MongoDB, and it covers everyday reads and writes across your models.
+- The **SQL query builder** is at `db.sql`. It has table methods that match SQL, such as `select()`, `innerJoin()`, and `groupBy()`, it is PostgreSQL only, and it returns whatever shape your `select()` asks for, not objects shaped like your models.
+- The **pipeline builder** is at `db.query`. It builds MongoDB aggregation pipelines, and it is MongoDB only.
 
-## How database differences are documented
+When none of the three can express the query you need, write raw SQL on PostgreSQL or a raw command on MongoDB. See [Raw queries](/orm/reference/raw-queries). For connecting and disconnecting the client, transactions, and prepared statements, see [Transactions and runtime](/orm/reference/transactions-and-runtime).
 
-The method reference pages document each method with the classic Remarks / Options / Return type / Examples structure (the raw queries page is deliberately more narrative). When a method's behavior differs between PostgreSQL and MongoDB, exists on only one database, or is type-checked but not enforced at runtime, the method's own Remarks call that out inline.
+## Running a query
 
-For a conceptual walkthrough of reading, writing, and querying data (rather than an exhaustive method-by-method reference), see the [Fundamentals](/orm/fundamentals/reading-data) section:
+The ORM client sends its own queries. `first()`, `create()`, `update()`, `upsert()`, `delete()`, and `aggregate()` send the query the moment you call them. `all()`, `createAll()`, `updateAll()`, and `deleteAll()` return a result object and send the query when you `await` that object or loop over it with `for await`. `all()` is what replaced `findMany`.
 
-- [Reading data](/orm/fundamentals/reading-data)
-- [Writing data](/orm/fundamentals/writing-data)
-- [Relations and joins](/orm/fundamentals/relations-and-joins)
-- [Transactions](/orm/fundamentals/transactions)
-- [Advanced queries](/orm/fundamentals/advanced-queries)
+The SQL query builder and the pipeline builder send nothing on their own. `.build()` gives you a built query. Pass it to `runtime.query(...)` for rows, or to `runtime.execute(...)` for a write that returns no rows. Get `runtime` from `db.runtime()` once and reuse it.
+
+### PostgreSQL
+
+```ts
+const runtime = db.runtime();
+const admins = await db.orm.public.User.where((u) => u.kind.eq('admin')).all();
+const plan = db.sql.public.user.select('id', 'email').where((f, fns) => fns.eq(f.kind, 'admin')).build();
+const rows = await runtime.query(plan);
+```
+
+`User` is the model name and `user` is the table name. The ORM client compares on the column, `u.kind.eq(...)`. The SQL query builder compares through `fns`, `fns.eq(f.kind, ...)`.
+
+### MongoDB
+
+```ts
+const runtime = await db.runtime();
+const admins = await db.orm.users.where({ role: 'admin' }).all();
+const plan = db.query.from('users').match((f) => f.role.eq('admin')).build();
+const docs = await runtime.query(plan);
+```
+
+`db.runtime()` returns a promise on MongoDB, so `await` it. `users` is the collection name, and both `db.orm` and `db.query.from()` are keyed by it. The ORM client's `where()` takes an object of field values. The pipeline builder's `match()` takes a callback that compares on the field, `f.role.eq(...)`. Two different things are named `query`: `db.query` builds a pipeline, and `runtime.query(...)` runs a query that has already been built.
 
 <Cards>
-  <Card href="/orm/reference/orm-client" title="ORM client reference" icon={<BookOpen className="text-primary" />}>
-    Every ORM client method, with PostgreSQL and MongoDB behavior documented side by side.
-  </Card>
-  <Card href="/orm/reference/sql-query-builder" title="SQL query builder reference" icon={<BookOpen className="text-primary" />}>
-    Every SQL query builder method for building typed, table-level queries against PostgreSQL.
-  </Card>
-  <Card href="/orm/reference/pipeline-builder" title="Pipeline builder reference" icon={<BookOpen className="text-primary" />}>
-    Every MongoDB pipeline-builder stage, accumulator, expression helper, and write terminal.
-  </Card>
-  <Card href="/orm/reference/raw-queries" title="Raw queries reference" icon={<BookOpen className="text-primary" />}>
-    Raw escape hatches: PostgreSQL raw SQL fragments and MongoDB raw commands.
-  </Card>
-  <Card href="/orm/reference/transactions-and-runtime" title="Transactions and runtime reference" icon={<BookOpen className="text-primary" />}>
-    Client lifecycle, transactions, prepared statements, and execution options.
-  </Card>
-</Cards>
+  <Card href="/orm/reference/orm-client" title="ORM client reference" icon={<BookOpen className="text-primary" />}>Every ORM client method, with PostgreSQL and MongoDB behavior documented side by side.</Card>
+  <Card href="/orm/reference/sql-query-builder" title="SQL query builder reference" icon={<BookOpen className="text-primary" />}>Every SQL query builder method for building typed, table-level queries against PostgreSQL.</Card>
+  <Card href="/orm/reference/pipeline-builder" title="Pipeline builder reference" icon={<BookOpen className="text-primary" />}>Every MongoDB pipeline-builder stage, accumulator, expression helper, and write method.</Card>
+  <Card href="/orm/reference/raw-queries" title="Raw queries reference" icon={<BookOpen className="text-primary" />}>Raw SQL on PostgreSQL and raw commands on MongoDB, for queries the typed APIs cannot express.</Card>
+  <Card href="/orm/reference/transactions-and-runtime" title="Transactions and runtime reference" icon={<BookOpen className="text-primary" />}>Connecting and disconnecting the client, transactions, prepared statements, and execution options.</Card>
+</Cards>