docs(docs): contract references after prisma/orm#30475

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

@@ -23,7 +23,7 @@ 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 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). |
+| `--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, [`<dir>^`](#contract-references), [`@contract`](#contract-references), or [`@db`](#contract-references). With `--show`, it also accepts [`@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>` | 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). |

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

@@ -22,7 +22,7 @@ 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 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). |
+| `--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). It refuses `@contract`, `@db`, and `@empty` with the error code `MIGRATION.REF_WRONG_GRAMMAR`. To update to the contract in `contract.json`, leave out `--to`. |
 | `--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. |

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

@@ -22,8 +22,8 @@ npx prisma migration status --db "$DATABASE_URL"
 | --- | --- |
 | `--db <url>` | Connects to the database. |
 | `--space <id>` | Narrows output to a single [contract space](#contract-spaces), named by its directory under `migrations/`. |
-| `--to <contract>` | Sets the 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, [`<dir>^`](#contract-references), or [`@empty`](#contract-references). |
-| `--from <contract>` | Sets the origin contract state, and accepts the same forms as `--to`. With `--from`, the command computes the path offline and does not need a database. |
+| `--to <contract>` | Sets the 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, [`<dir>^`](#contract-references), [`@contract`](#contract-references), [`@db`](#contract-references), or [`@empty`](#contract-references). |
+| `--from <contract>` | Sets the origin contract state, and accepts the same forms as `--to`. With `--from`, the command computes the path offline and does not need a database. It needs one when `--from` or `--to` is `@db`, because it then reads the marker from the database. |
 | `--legend` | Prints a key to the symbols in the rows (`○`, the arrows, `✓`, `⧗`, `∅`) and to the labels. |
 | `--ascii` | Uses ASCII glyphs (pipe-friendly). |
 | `--config <path>` | Read this config file instead of `./prisma.config.ts`. |
@@ -35,7 +35,7 @@ Prisma ORM keeps one migration history for your own models, called the `app` spa
 
 ### 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.
+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` names the contract in `contract.json`, which `contract emit` writes. `@db` names the contract state that the database's marker records. `@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.
 
 ## Examples
 
@@ -69,7 +69,7 @@ Read the drawing from the bottom up, because the earliest state is the bottom ro
 
 The last line suggests the command to run next. It names the pending state by the first 12 characters of its hash, `a4c3fa7fc3b2`, which is the same hash the drawing shortens to 7 characters, `a4c3fa7`.
 
-With `--db`, status reads the marker from the database and compares it with the target. With `--from`, it starts from the state you name instead and needs no database.
+With `--db`, status reads the marker from the database and compares it with the target. With `--from`, it starts from the state you name instead. It then needs no database, unless `--from` or `--to` is `@db`.
 
 ### Warnings
 

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

@@ -145,10 +145,9 @@ Not every command accepts every form. This table lists what each one accepts:
 | `migration plan --to` | a hash, a hash prefix, a ref name, a migration directory name, or `<dir>^` |
 | `migration new --from` | a hash, or a prefix of one, that an existing migration ends at |
 | `migration ref set <name> <contract>` | a hash, a hash prefix, a ref name, a migration directory name, or `<dir>^` |
-| `migration status --from`, `--to` | a hash, a hash prefix, a ref name, a migration directory name, `<dir>^`, or `@empty` |
-| `db migrate --to` | a hash, a hash prefix, a ref name, a migration directory name, or `<dir>^` |
-| `db migrate --show --to` | a hash, a hash prefix, a ref name, a migration directory name, `<dir>^`, `@contract`, or `@empty` |
-| `db migrate --show --from` | a hash, a hash prefix, a ref name, a migration directory name, `<dir>^`, `@contract`, `@db`, or `@empty` |
+| `migration status --from`, `--to` | a hash, a hash prefix, a ref name, a migration directory name, `<dir>^`, `@contract`, `@db`, or `@empty` |
+| `db migrate --to` | a hash, a hash prefix, a ref name, a migration directory name, `<dir>^`, `@contract`, or `@db` |
+| `db migrate --show --from`, `--to` | a hash, a hash prefix, a ref name, a migration directory name, `<dir>^`, `@contract`, `@db`, or `@empty` |
 | `db update --to` | a hash, a hash prefix, a ref name, a migration directory name, or `<dir>^` |
 | `db sign [contract]`, `--contract` | a hash, a hash prefix, a ref name, a migration directory name, or `<dir>^` |