docs(docs): list the contract references each CLI command accepts, and close eleven gaps on the ORM migration pages

.github/workflows/docs-prose.yml

@@ -2,7 +2,7 @@ name: Docs Prose
 
 # Runs the AI-signs prose checker from .claude/skills/docs-reader-review over
 # every docs page a pull request adds or changes. The generated error-reference
-# pages are skipped: their text comes from prisma/prisma and prisma/prisma-cli,
+# pages are skipped: their text comes from prisma/orm and prisma/prisma-cli,
 # so the fix for a hit there is upstream.
 
 on:

.github/workflows/error-reference-check.yml

@@ -1,7 +1,7 @@
 name: Error Reference Check
 
 # The published error-reference pages must list every structured error code
-# the products can emit — prisma/prisma (main) errors link to
+# the products can emit — prisma/orm (main) errors link to
 # /docs/orm/reference/error-reference#<CODE>, prisma/prisma-cli (main) errors
 # to /docs/cli/error-reference#<CODE>. This check fails if any known code is
 # missing from its page, even if the sync workflow breaks.
@@ -37,10 +37,10 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Checkout prisma/prisma (main)
+      - name: Checkout prisma/orm (main)
         uses: actions/checkout@v4
         with:
-          repository: prisma/prisma
+          repository: prisma/orm
           ref: main
           path: prisma-src
           persist-credentials: false

.github/workflows/sync-error-reference-docs.yml

@@ -24,10 +24,10 @@ jobs:
         with:
           persist-credentials: false
 
-      - name: Checkout prisma/prisma (main)
+      - name: Checkout prisma/orm (main)
         uses: actions/checkout@v4
         with:
-          repository: prisma/prisma
+          repository: prisma/orm
           ref: main
           path: prisma-src
           persist-credentials: false

apps/docs/content/docs/(index)/prisma-orm/from-scratch.mdx

@@ -128,6 +128,8 @@ App space
 ✔ Advanced ref "db" → b5ae4e66fad1f0b7dd5590568f75a12a6f4576e9f367a787a69a4e729abac1fb
 ```
 
+`1 contract space` and `App space` in the output both refer to the migration history for your own models, which is in `migrations/app/` and is called the `app` [contract space](/orm/migrations/the-migration-graph#terms-used-on-this-page).
+
 The `marker` line in the output is the record that signing stores in the database: the hash that identifies the version of the contract the database now matches. `db init` also writes `migrations/app/refs/db.json`, called the `db` ref: a file that records which contract version your development database is at, so that `migration plan` in step 6 knows where to start. The `Advanced ref "db"` line in the output is `db init` writing it. Commit it, together with the snapshot of the contract that `db init` writes under `migrations/snapshots/`. If the command fails with `DRIVER.CONNECTION_FAILED`, `DATABASE_URL` in `.env` is wrong or the database is not reachable. A `SECURITY WARNING` about SSL modes comes from the `pg` driver and does not stop the command; change `sslmode=require` to `sslmode=verify-full` in `.env` to silence it.
 
 ## 5. Write and read data

apps/docs/content/docs/(index)/prisma-orm/quickstart/mongodb.mdx

@@ -65,6 +65,8 @@ npm run migrate
 
 The output ends with a summary like `Applied 3 operation(s) across 1 contract space`. If it fails with a connection error, confirm `MONGODB_URL` is exported in this shell and points at a running MongoDB deployment; if the string still names `replicaSet=rs0`, that replica set has to exist.
 
+The `1 contract space` in the summary is the migration history for your own models. Prisma ORM calls it the `app` [contract space](/orm/migrations/the-migration-graph#terms-used-on-this-page), and its migrations are in `migrations/app/`.
+
 ## 4. Run the app
 
 Start the app and confirm the sample query runs successfully.

apps/docs/content/docs/cli/db-migrate.mdx

@@ -6,7 +6,9 @@ metaTitle: db migrate | Prisma ORM CLI
 metaDescription: Learn how to apply pending Prisma ORM on-disk migrations with the db migrate command.
 ---
 
-`db migrate` applies pending on-disk migrations to advance the database. It walks every contract space (app and extensions) and applies migrations in canonical order: extensions alphabetically, then the app. It applies only the migrations that exist on disk and never generates new operations.
+`db migrate` applies pending on-disk migrations to advance the database. It walks every contract space and applies migrations in canonical order: extensions alphabetically, then the app. It applies only the migrations that exist on disk and never generates new operations.
+
+Prisma ORM keeps one migration history for your own models, called the `app` space, in `migrations/app/`, and one for each [extension package](/orm/extensions/using-extensions) that ships its own migrations, such as pgvector. Each of these histories is a [contract space](/orm/migrations/the-migration-graph#terms-used-on-this-page).
 
 Use it from a controlled deployment step after reviewing migration packages.
 
@@ -21,13 +23,19 @@ npx prisma db migrate --db "$DATABASE_URL"
 | Option | What it does |
 | --- | --- |
 | `--db <url>` | Connects to the database. |
-| `--to <contract>` | Applies migrations up to a target contract (hash, prefix, ref name, migration directory name, `<dir>^`, or `./path`). |
+| `--to <contract>` | Applies migrations up to a target contract state. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, or [`<dir>^`](#contract-references). With `--show`, it also accepts the tokens [`@contract`](#contract-references) and [`@empty`](#contract-references). |
 | `--advance-ref <name>` | Advances the named [ref](/cli/migration-ref) to the post-apply marker after success. |
 | `--show` | Previews the migration route without applying (read-only). |
-| `--from <contract>` | Sets the from-state for the `--show` preview: `@contract` (the emitted contract), `@db` (the database's current marker), a hash, a ref name, or a migration directory. |
+| `--from <contract>` | Use it with `--show`, where it sets the starting state for the preview. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, [`<dir>^`](#contract-references), [`@contract`](#contract-references), [`@db`](#contract-references), or [`@empty`](#contract-references). |
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
 | `--json` | Prints a machine-readable result. |
 
+### Contract references [#contract-references]
+
+A ref name is a name you gave a contract state with [`migration ref set`](/cli/migration-ref), such as `prod`. `<dir>^` is a migration directory name followed by `^`, and it names the contract state before that migration, while the directory name alone names the state after it. [Contract references each command accepts](/orm/migrations/the-migration-graph#contract-reference-forms) lists the forms for every command.
+
+`@contract` names the contract in `contract.json`, which `contract emit` writes. The database stores a marker, a row that says which contract state it matches. `@db` names that state. `@empty` names the empty database, before any migration.
+
 ## Recommended flow
 
 ```npm

apps/docs/content/docs/cli/db-sign.mdx

@@ -8,7 +8,7 @@ metaDescription: Learn how to sign a database once it matches the current Prisma
 
 `db sign` verifies that the live database satisfies the emitted contract and, if so, writes or updates the database signature. The signature records that this database instance matches a specific contract version.
 
-It is idempotent and safe to run in CI or a deployment pipeline. Use it after importing or inferring an existing schema, or after a deployment flow that already applied the required database changes.
+It is safe to run more than once, and safe to run in CI or a deployment pipeline. Use it after importing or inferring an existing schema, or after a deployment flow that already applied the required database changes.
 
 After a successful signature, `db sign` also stores the signed contract as a snapshot and points the [ref](/cli/migration-ref) named `db` at it, so the next [`migration plan`](/cli/migration-plan) starts from the state you just signed instead of from an empty database. Unlike `db init` and `db update`, passing `--db` does not turn this off, because you normally sign the real database. Pass `--no-advance-ref` when you do not want the command to write a ref or a snapshot, for example in a deployment pipeline.
 
@@ -22,14 +22,18 @@ npx prisma db sign --db "$DATABASE_URL"
 
 | Argument or option | What it does |
 | --- | --- |
-| `[contract]` | Signs against a specific contract reference (hash, prefix, ref name, or migration directory name) instead of the emitted contract. |
+| `[contract]` | Signs against a specific contract state instead of the emitted contract. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, or [`<dir>^`](#contract-references). |
 | `--db <url>` | Connects to the database. |
-| `--contract <contract>` | The contract reference as a flag. Also accepts the `<dir>^` and `./path` forms that the positional argument does not. |
+| `--contract <contract>` | The same value as `[contract]`, passed as an option in place of the argument. |
 | `--advance-ref <name>` | Advances this ref instead of `db` after a successful signature. |
 | `--no-advance-ref` | Signs without writing any ref or snapshot. Cannot be combined with `--advance-ref`. |
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
 | `--json` | Prints a machine-readable result. It includes `advancedRef` with the ref name and contract hash, or `null` when no ref was written. |
 
+### Contract references [#contract-references]
+
+A ref name is a name you gave a contract state with [`migration ref set`](/cli/migration-ref), such as `prod`. `<dir>^` is a migration directory name followed by `^`, and it names the contract state before that migration, while the directory name alone names the state after it. [Contract references each command accepts](/orm/migrations/the-migration-graph#contract-reference-forms) lists the forms for every command.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -61,7 +65,7 @@ The plan starts from the signed contract, so it contains only the change you mad
 
 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
+- `contract infer` for an existing database
 - a manually reviewed migration flow
 - a database restore that you need to mark as matching the current contract
 

apps/docs/content/docs/cli/db-update.mdx

@@ -22,11 +22,15 @@ npx prisma db update --db "$DATABASE_URL"
 | --- | --- |
 | `--db <url>` | Connects to the database. |
 | `--dry-run` | Shows planned operations without applying them. |
-| `--to <contract>` | Updates to a specific contract (hash, prefix, ref name, migration directory name, or `./path`). |
+| `--to <contract>` | Updates to a specific contract state. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, or [`<dir>^`](#contract-references). |
 | `--advance-ref <name>` | Advances the named [ref](/cli/migration-ref) to the post-command contract hash. Without it, `db update` advances `db` when `--db` is omitted, and advances nothing when `--db` is passed. |
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
 | `--json` | Prints a machine-readable result. |
 
+### Contract references [#contract-references]
+
+A ref name is a name you gave a contract state with [`migration ref set`](/cli/migration-ref), such as `prod`. `<dir>^` is a migration directory name followed by `^`, and it names the contract state before that migration, while the directory name alone names the state after it. [Contract references each command accepts](/orm/migrations/the-migration-graph#contract-reference-forms) lists the forms for every command.
+
 ## How the db ref moves
 
 Run without `--db`, `db update` takes the connection from `db.connection` in `prisma.config.ts` and advances the [ref](/cli/migration-ref) named `db` to the contract it just applied. Pass `--db` and that advancement is suppressed, even when the URL is the same one the config holds. Pass `--advance-ref db` alongside `--db` to get it back.

apps/docs/content/docs/cli/index.mdx

@@ -33,7 +33,7 @@ The platform commands manage the services, databases, and buckets your app runs
 
 ## Common workflows
 
-There are two main entry points. Platform users deploy apps, create databases, and provision buckets with the [platform commands](#platform-commands). ORM users manage their schema, contracts, and migrations with the ORM and migration commands.
+Platform users deploy apps, create databases, and provision buckets with the [platform commands](#platform-commands), while ORM users manage their schema, contracts, and migrations with the ORM and migration commands.
 
 ### Deploy an app
 
@@ -111,7 +111,7 @@ npx prisma skills sync
 
 ## Other commands
 
-A few commands ship without dedicated pages yet. `contract format` formats your PSL contract source in place, including a Prisma ORM 7 schema read through `prisma7Schema`, and `lsp` starts the Prisma ORM language server (spawned by editors, not run interactively; see [Editor support](/orm/contract-authoring/editor-support)). The `migration` group also has read-only inspection commands: `migration list` (on-disk migrations per contract space; `--space`, `--ascii`, `--legend`), `migration log` (executed history from the database ledger; `--db`, `--utc`, `--ascii`), `migration graph` (graph topology; `--space`, `--dot` for Graphviz output, `--ascii`, `--legend`), and `migration check [target]` (artifact and graph integrity; `--space`). Run any of them with `--help` for the details.
+A few commands ship without dedicated pages yet. `contract format` formats your PSL contract source in place, including a Prisma ORM 7 schema read through `prisma7Schema`, and `lsp` starts the Prisma ORM language server (spawned by editors, not run interactively; see [Editor support](/orm/contract-authoring/editor-support)). The `migration` group also has read-only inspection commands: `migration list` (on-disk migrations per [contract space](/orm/migrations/the-migration-graph#terms-used-on-this-page); `--space`, `--ascii`, `--legend`), `migration log` (executed history from the database ledger; `--db`, `--utc`, `--ascii`), `migration graph` (the chain of migrations; `--space`, `--dot` for Graphviz output, `--ascii`, `--legend`), and `migration check [target]` (artifact and graph integrity; `--space`). Run any of them with `--help` for the details.
 
 ## Global flags
 

apps/docs/content/docs/cli/migration-new.mdx

@@ -25,7 +25,7 @@ npx prisma migration new --name split-name
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
 | `--json` | Prints a machine-readable result. |
 
-`migration new --from` takes only a hash or a unique prefix of one. Unlike [`migration plan --from`](/cli/migration-plan#options), it does not accept a migration directory name or a ref name. It refuses `--from` when `migrations/app/` has no migrations, and refuses a prefix that matches more than one migration. Run `npx prisma migration list` to see the hashes of your migrations.
+`migration new --from` takes only a hash or a unique prefix of one. Unlike [`migration plan --from`](/cli/migration-plan#options), it does not accept a migration directory name or a ref name. It refuses `--from` when `migrations/app/` has no migrations, and refuses a prefix that matches more than one migration. Run `npx prisma migration list` to see the hashes of your migrations. [Contract references each command accepts](/orm/migrations/the-migration-graph#contract-reference-forms) compares it with the other commands.
 
 ## Where it starts
 

apps/docs/content/docs/cli/migration-plan.mdx

@@ -27,7 +27,7 @@ The baseline only creates things, because it is planned from an empty database,
 
 If a migration already starts from the contract the `db` ref points at, `migration plan` writes a second migration that starts from the same contract, so the [migration history](/orm/migrations/the-migration-graph) splits into two branches. This happens, for example, after `db migrate` without `--advance-ref db`, which applies migrations but leaves the `db` ref where it was. `migration plan` still writes the migration and prints a warning. A database that has already run the existing migration then has no migration leading to your new contract, so `db migrate` on that database fails with `MIGRATION.PATH_UNREACHABLE`. To build on the newest migration instead, delete the directory this run wrote and plan again with `--from` set to the newest migration's directory name.
 
-The command is offline. It does not need a database connection.
+The command is offline, so it does not need a database connection.
 
 ## Usage
 
@@ -40,11 +40,15 @@ npx prisma migration plan --name add_users_table
 | Option | What it does |
 | --- | --- |
 | `--name <slug>` | Sets the migration directory name suffix. |
-| `--from <contract>` | Uses a specific starting contract reference (hash, prefix, ref name, migration directory name, `<dir>^`, `./path`, or `@empty`) instead of the `db` ref. `migration plan` is offline, so `@db` and `@contract` are not accepted here. |
-| `--to <contract>` | Sets the destination contract reference. Defaults to the emitted contract. Same grammar as `--from`, except that `@empty` is refused as a destination. |
+| `--from <contract>` | Uses a specific starting contract state instead of the `db` ref. Accepts a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash, a hash prefix, a [ref name](#contract-references), a migration directory name, [`<dir>^`](#contract-references), or [`@empty`](#contract-references). `@db` is not accepted here, because `migration plan` is offline and cannot read a database. `@contract` is not accepted either. |
+| `--to <contract>` | Sets the destination contract state. Defaults to the emitted contract. Accepts the same forms as `--from`, except `@empty`, which is refused as a destination. |
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
 | `--json` | Prints a machine-readable result. |
 
+### Contract references [#contract-references]
+
+A ref name is a name you gave a contract state with [`migration ref set`](/cli/migration-ref), such as `prod`. `<dir>^` is a migration directory name followed by `^`, and it names the contract state before that migration, while the directory name alone names the state after it. `@empty` names the empty database, before any migration. [Contract references each command accepts](/orm/migrations/the-migration-graph#contract-reference-forms) lists the forms for every command.
+
 ## Recommended flow
 
 ```npm

apps/docs/content/docs/cli/migration-ref.mdx

@@ -34,7 +34,7 @@ npx prisma migration ref delete production
 
 | Subcommand | What it does |
 | --- | --- |
-| `set <name> <contract>` | Points a ref at a contract. The contract is a hash or prefix, another ref name, a migration directory name, or `<dir>^` for that migration's source contract. |
+| `set <name> <contract>` | Points a ref at a contract. The contract is a [contract reference](/orm/migrations/the-migration-graph#contract-reference-forms): a hash or prefix, another ref name, a migration directory name, or `<dir>^` for that migration's source contract. |
 | `list` | Lists every ref with the contract hash it points at and the invariants recorded against it. |
 | `delete <name>` | Deletes a ref. The contract it pointed at is untouched. |