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), [`@db`](#contract-references), or [`@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). |
@@ -34,7 +34,7 @@ npx prisma db migrate --db "$DATABASE_URL"
 
 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.
+`@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, or the empty database when the database has no marker. `@empty` names the empty database, before any migration.
 
 ## Recommended flow
 

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

@@ -22,7 +22,7 @@ npx prisma db sign --db "$DATABASE_URL"
 
 | Argument or option | What it does |
 | --- | --- |
-| `[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). |
+| `[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). It refuses `@contract`, `@db`, and `@empty` with the error code `MIGRATION.REF_WRONG_GRAMMAR`. To sign against the contract in `contract.json`, leave the argument out. |
 | `--db <url>` | Connects to the database. |
 | `--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. |

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,8 @@ 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`, and `--from` with `--show` | 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>^` |