docs: five-minute path, forward-reference pass, backlog polish

The overview page now runs the whole loop inline: three commands with
the verified plan and apply output and an explicit success signal, so a
newcomer is productive before leaving page one. Swept all six pages for
forward references: terms like ledger, marker, and contract space are
now glossed or linked at first use instead of assuming later sections.
Also links the graph page from the Prisma Next index bullet, links the
contract to Data Modeling, and straightens the branch/merge lanes in
the migration-graph animation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: sorenbs

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

@@ -25,7 +25,7 @@ Prisma's current architecture tightly couples three layers: the schema language,
 
 - **Better queries**: a cleaner API with simpler nested queries, custom collection methods on your models, and streaming results, plus a low-level, type-safe SQL query builder for the cases that need raw control.
 - **Extensible by design**: a minimal core exposed through a public SPI. Everything around it, including Postgres support itself, is an extension, so you can add databases, query builders, data types, and middleware.
-- **Rethought migrations**: graph-based migrations that resolve branch conflicts automatically and make partial failures safe to retry, with both schema and data migrations written in TypeScript and validated against your contract.
+- **Rethought migrations**: [graph-based migrations](/orm/next/migrations/the-migration-graph) that resolve branch conflicts automatically and make partial failures safe to retry, with both schema and data migrations written in TypeScript and validated against your contract.
 - **AI-agent friendly**: your schema compiles to a machine-readable contract, every query produces a structured, inspectable plan, and middleware adds compile-time guardrails. The installers also register agent skills so your editor's AI assistant can drive Prisma Next changes safely.
 
 ## How it works

apps/docs/content/docs/orm/next/migrations/applying-a-migration.mdx

@@ -35,6 +35,8 @@ App space
 Next: prisma-next migration status
 ```
 
+`App space` is your application's migration lane, one of the run's *contract spaces*; projects that use database extensions gain additional spaces, covered in [Extension spaces](#extension-spaces) below.
+
 ## Check before, preview, then apply
 
 The habit worth building, especially against shared databases, is a three-step rhythm:

apps/docs/content/docs/orm/next/migrations/generating-a-migration.mdx

@@ -13,7 +13,7 @@ We'll start from a minimal project. If you don't have one, `npx create-prisma@ne
 
 ## Your first migration
 
-Say your contract has a single model:
+Say your [contract](/orm/next/data-modeling) has a single model:
 
 ```prisma title="contract.prisma"
 model User {
@@ -66,6 +66,7 @@ Three things to notice:
 - **The DDL preview is right there.** You see the exact SQL before anything exists but files.
 - **`from: null`** means this migration starts from an empty database; it's the root of your [migration graph](/orm/next/migrations/the-migration-graph).
 - **`to:` is your contract's hash.** The migration promises to deliver a database matching exactly the contract you just emitted.
+- **`App space`** is your application's migration lane. Database extensions bring their own lanes; see [extension spaces](/orm/next/migrations/applying-a-migration#extension-spaces).
 
 The planned migration directory contains the TypeScript source, the compiled operations, and the contract snapshots:
 

apps/docs/content/docs/orm/next/migrations/how-migrations-work.mdx

@@ -18,13 +18,34 @@ The workflow is a loop you will run many times a day in development:
 3. **Review it**: read the generated TypeScript and the DDL preview. Edit the migration if the change needs a data step, then re-run the file to recompile it.
 4. **Apply it**: `prisma-next migrate` runs the pending migrations against your database.
 
+In a project with a database connection configured (the [quickstart](/next/quickstart/postgresql) gives you one), the whole loop is three commands. Add an optional `phone String?` field to a model in your `.prisma` file, then:
+
 ```bash
 npx prisma-next contract emit
 npx prisma-next migration plan --name add_user_phone
 npx prisma-next migrate
 ```
 
-Each page in this section walks through one part of the loop in detail. This page covers the model: what a migration is, and why it looks the way it does.
+`migration plan` prints the SQL it wrote before anything runs:
+
+```text
+✔ Planned 1 operation(s)
+
+│
+└─ Add column "phone" to "user"
+
+DDL preview
+
+ALTER TABLE "public"."user" ADD COLUMN "phone" text;
+```
+
+and `migrate` confirms what it applied:
+
+```text
+✔ Applied 1 migration(s) (1 operation(s)) across 1 contract space(s)
+```
+
+(The contract-space count only matters once you add database extensions; ignore it for now.) If you see that `✔ Applied` line, you've already run the entire workflow; the rest of this section is detail. This page covers the model: what a migration is, and why it looks the way it does.
 
 ## What a migration is
 
@@ -121,7 +142,7 @@ Two commands talk to a database:
 | ------------------ | ---------------------------------------------------------------------------- |
 | `migrate`          | [Apply pending migrations](/orm/next/migrations/applying-a-migration)        |
 | `migration status` | Show where the database is in the graph and which migrations are pending     |
-| `migration log`    | Show the history of applied migrations from the database's ledger            |
+| `migration log`    | Show the history of migrations the database has actually applied             |
 
 Note that applying is `prisma-next migrate`, not `migration apply`: `migration ...` commands manage the on-disk migration directories, while `migrate` moves a database.
 

apps/docs/content/docs/orm/next/migrations/rollbacks-and-recovery.mdx

@@ -14,7 +14,7 @@ Two different situations get called "rollback", and Prisma Next treats them diff
 
 ## Rollback: a migration like any other
 
-There is no `migrate down` command, and no separate "down migration" files. In the [graph model](/orm/next/migrations/the-migration-graph), the state you want to return to is a node you've already visited, so rolling back means planning a new edge that points at it. If you know git, this is `git revert`, not `git reset`: history only ever grows, and the ledger keeps a full record of the round trip.
+There is no `migrate down` command, and no separate "down migration" files. In the [graph model](/orm/next/migrations/the-migration-graph), the state you want to return to is a node you've already visited, so rolling back means planning a new edge that points at it. If you know git, this is `git revert`, not `git reset`: history only ever grows, and the ledger (the applied-history record every database keeps) retains the full round trip.
 
 <ConceptAnimation name="migration-rollback" />
 
@@ -60,7 +60,7 @@ Afterwards the graph shows the round trip: a forward edge up, a rollback edge ba
 *   -
 ```
 
-The database's marker is back at `705b1a6`, and the ledger records both the apply and the rollback. Nothing was rewritten or deleted.
+The database's marker (its record of which graph node it currently matches) is back at `705b1a6`, and the ledger records both the apply and the rollback. Nothing was rewritten or deleted.
 
 Two things to be clear-eyed about:
 

apps/docs/content/docs/orm/next/migrations/the-migration-graph.mdx

@@ -44,7 +44,7 @@ npx prisma-next migration graph
 1 space(s), 5 contract(s), 5 migration(s)
 ```
 
-This project's history is a diamond. Read it bottom-up: from an empty database (`-`), `init` establishes state `789dd79`. Alice and Bob branch from it in parallel: she adds a phone column, he adds an avatar. Then each branch gets a merge migration into the combined state `f9a41d7`, which the `prod` ref points at.
+This project's history is a diamond. Read it bottom-up: from an empty database (`-`), `init` establishes state `789dd79`. Alice and Bob branch from it in parallel: she adds a phone column, he adds an avatar. Then each branch gets a merge migration into the combined state `f9a41d7`, which the `prod` ref points at. (The summary line counts contract *spaces*: independent migration lanes, one for your app plus one per [database extension](/orm/next/migrations/applying-a-migration#extension-spaces).)
 
 ## What the graph gives you
 

apps/docs/src/components/concept-animation/presets.ts

@@ -224,10 +224,10 @@ export const CONCEPT_PRESETS = {
       {
         title: "2. Two people branch",
         code:
-          "[[*   93be6c2         *   7e3fa7f]]\n" +
-          "[[|^  alice_phone     |^  bob_avatar]]\n" +
-          " \\               /\n" +
-          "  *   9f49f8f   ← both branched from here\n" +
+          "[[*   93be6c2]]        [[*   7e3fa7f]]\n" +
+          "[[|^  alice_phone]]    [[|^  bob_avatar]]\n" +
+          " \\                  /\n" +
+          "  *   9f49f8f    ← both branched from here\n" +
           "  |^  add_posts\n" +
           "  *   705b1a6",
         caption:
@@ -236,13 +236,13 @@ export const CONCEPT_PRESETS = {
       {
         title: "3. The branches merge",
         code:
-          "      *   [[f9a41d7  (prod)]]\n" +
-          "     / \\\n" +
-          "[[|^ merge_alice  |^ merge_bob]]\n" +
-          "  *   93be6c2   *   7e3fa7f\n" +
-          "  |^  alice_phone   |^  bob_avatar\n" +
-          "   \\             /\n" +
-          "    *   9f49f8f",
+          "         *   [[f9a41d7  (prod)]]\n" +
+          "        /            \\\n" +
+          "[[|^  merge_alice]]     [[|^  merge_bob]]\n" +
+          "*   93be6c2         *   7e3fa7f\n" +
+          "|^  alice_phone     |^  bob_avatar\n" +
+          " \\                  /\n" +
+          "  *   9f49f8f",
         caption:
           "After the git merge, each branch gets a small merge migration into the combined state. A database that followed Alice takes merge_alice; one that followed Bob takes merge_bob. Every environment finds its own path.",
       },