@prisma/orm-mongo 8.0.0-rc.1-dev.46 → 8.0.0-rc.10

package/skills/prisma-8/references/feedback.md

@@ -0,0 +1,251 @@
+
+# Prisma 8 — Feedback (Bug Reports, Feature Requests, Team Q&A)
+
+> **Edit your data contract. Prisma handles the rest.**
+
+This skill is the *terminal* of the capability-gap routing pattern. Every other Prisma 8 skill's *What Prisma 8 doesn't do yet* entries route here when the user wants the gap closed; the skill also fires directly on prompts like *"this is a bug"*, *"file an issue"*, *"feature request"*, *"can I ask the team about this?"*, *"how should I integrate X with Prisma 8?"*.
+
+The skill's job is to pick the *right channel* — GitHub issue or Discord — and then either produce a **structured, public-safe** issue body (no secrets, no proprietary schema) the framework team can act on, or hand the user a direct link to the Prisma Discord for synchronous Q&A. Submission to GitHub never happens without explicit user confirmation.
+
+Canonical channels:
+
+- **GitHub Issues** (bugs + concrete feature requests): <https://github.com/prisma/orm/issues/new/choose>
+- **Prisma Discord** (Q&A, design feedback, direct team contact — including extension authors): <https://pris.ly/discord>
+
+## When to Use
+
+- A capability-gap entry from another `prisma-8` skill fired and the user said *"yes, file the feature request"*.
+- User says *"this is a bug"*, *"file this"*, *"report this"*, *"file an issue against PN"*, *"send feedback"*, *"this should be a feature"*.
+- User describes an unexpected behaviour — wrong exit code, error message that didn't match what happened, type signature that doesn't match runtime behaviour, planner refused a migration that looked safe — and wants it on the framework team's radar.
+- User asks *"can I ask the Prisma team about this?"*, *"is there somewhere I can talk to the team?"*, *"is this the intended way to do X?"*, *"how should I integrate <my extension / my tool> with PN?"*, or any other open-ended Q&A or design-feedback prompt — including extension authors asking integration questions.
+
+## When Not to Use
+
+- User wants to fix the bug themselves in the user's own code. The fix lives in another workflow reference (debug / contract / migrations / queries / runtime / build). Open the right reference first; only fall back to feedback if the user explicitly wants the framework to do something differently.
+- User wants to upgrade Prisma 8 (the bug may already be fixed) → [`upgrade-app.md`](upgrade-app.md); this reference mentions it as a pre-flight check.
+- The user's question is already covered by a workflow reference in this skill (*"how do I add a column?"* → `references/contract.md`; *"what's the right query interface?"* → `references/queries.md`). Route to the workflow reference, not to the team — open the reference, answer the question, and only escalate to Discord if the agent can't.
+
+## Key Concepts
+
+- **Three channels, one decision.** GitHub Issues (bugs + concrete feature requests), Prisma Discord (Q&A, design feedback, direct team contact), or another workflow reference in this skill (when the question turns out to be a workflow question, not a hand-off-to-team question). The first move is the channel decision; everything else follows.
+- **Public artifact.** GitHub issues *and* Discord messages are world-readable and archived. The body / message must not contain `DATABASE_URL` strings, internal company schema fragments, customer data in sample rows, or any other content the user wouldn't share publicly. The agent redacts before either kind of submission.
+- **Bug vs feature vs question.** A *bug* is "documented surface behaved unexpectedly". A *feature request* is "I want a capability that doesn't exist". A *question* is "I want to discuss X with someone, or I'm not sure this is a bug at all". Many capability-gap routes are feature requests; many extension-author prompts are questions.
+- **The framework team needs to reproduce (issues only).** A bug report without a reproduction is much harder to act on. Where possible, the agent produces a minimal repro the team can re-run locally — ideally a small change against [`examples/prisma-8-demo`](https://github.com/prisma/prisma/tree/main/examples/prisma-8-demo), which the team already has checked out. Discord Q&A doesn't require a full repro — a short code snippet plus the question is usually enough.
+
+## Workflow
+
+### 1. Pick the channel
+
+The user wants to hand something off to the team. Which channel?
+
+**GitHub Issue** if any of:
+
+- The user describes a concrete bug (see *Classify* below for the bug-vs-feature split).
+- The user has a concrete feature request — a named capability, a specific API shape, a specific CLI flag — that they want on the backlog.
+- A capability-gap entry from another `prisma-8` skill routed them here for a feature request.
+
+**Prisma Discord** (<https://pris.ly/discord>) if any of:
+
+- The user is asking an open-ended question — *"is this the intended way to do X?"*, *"how would you approach Y?"*, *"I'm seeing weird behaviour but I'm not sure if it's a bug."*
+- The user wants design feedback before committing to a feature request — *"we're thinking of building a custom middleware that does X, does this fit the framework's direction?"*
+- The user is an extension author with an integration question that needs back-and-forth with the team (peer-dependency coordination, breaking-change timing, a new extension surface).
+- The user explicitly asks for the team — *"can I ask the team about this?"*, *"is there somewhere I can talk to Prisma?"*, *"where do extension authors discuss things with the team?"*
+
+**Both, in sequence**, if any of:
+
+- The user has a bug *and* a related feature request — file two separate GitHub issues, do not mix them in one issue.
+- The user wants to discuss a design before filing the feature request — start in Discord, file the issue once the shape is settled.
+
+### 2. Classify (issue path only)
+
+The user is filing a GitHub issue. Is it a bug or a feature request?
+
+**Bug** if any of:
+
+- A documented CLI command exited with the wrong code.
+- The `fix` field of an error envelope was misleading or wrong.
+- A published TypeScript signature doesn't match runtime behaviour.
+- The planner refused a migration that should have been valid (or accepted one that shouldn't have been).
+- The contract emit produced an artifact that doesn't load at runtime.
+- Any other case where the documented surface did the wrong thing.
+
+**Feature request** if any of:
+
+- The user wants a capability that doesn't exist yet (most of the *What PN doesn't do yet* entries land here).
+- The user wants a better error message, an additional CLI flag, a new middleware, an additional bundler plugin, etc.
+
+If both — a bug *and* the user wants a related feature — file two separate issues. Mixing them makes the framework team's triage harder.
+
+### 3. Collect the minimum body (issue path only)
+
+For **either** kind:
+
+- **Prisma 8 version**: `pnpm ls @internal/postgres` (or `@internal/mongo`). If the project uses a target package, that version is canonical.
+- **Node version**: `node -v`.
+- **Package manager**: `pnpm` / `npm` / `yarn` / `bun` / `deno`.
+- **OS**: `darwin` / `linux` / `win32` and the version string is enough.
+
+For **bug reports**, additionally:
+
+- **The exact command** that misbehaved (e.g. `prisma migration plan --name add-email`).
+- **The full output**, with `-v` if a structured error envelope is involved. Redact `DATABASE_URL` and any other secrets.
+- **A minimal `src/prisma/contract.prisma` / `src/prisma/contract.ts` excerpt** that reproduces the issue. Strip unrelated models. Keep the original model and field names from the user's contract when they don't expose anything compromising — a faithful excerpt is much easier for the framework team (and future readers of the issue) to reason about than a re-themed one. Only rename to neutral placeholders (`User`, `Post`, `Tag`) when the original names would leak confidential domain detail (product names, internal codenames, customer identifiers, regulated-data field names).
+- **Steps to reproduce**, as a numbered list.
+- **Expected behaviour** — one sentence.
+- **Actual behaviour** — one sentence plus the relevant output line.
+- **Workaround**, if any — one sentence.
+
+For **feature requests**, additionally:
+
+- **Desired API or behaviour** — one paragraph. Concrete shape (CLI flag, config field, middleware export, plugin API) where possible.
+- **Where the gap surfaces today** — which skill's *What PN doesn't do yet* entry triggered the request, or the workflow the user was trying to complete.
+- **Current workaround**, if any — one sentence (and the skill body the user is following may already say this).
+
+### 4. Render the body
+
+The repository ships GitHub Issue Forms (`.github/ISSUE_TEMPLATE/bug_report.yml` and `feature_request.yml`). When the user lands on <https://github.com/prisma/orm/issues/new/choose> they pick the matching template and fill in the form fields; the skill produces the body in the same structured shape so it maps onto the form one-to-one (and so `gh issue create --body-file` produces a parseable artifact even when the form isn't in play).
+
+Bug-report body shape (fields named to match `.github/ISSUE_TEMPLATE/bug_report.yml`):
+
+~~~markdown
+## Package and version
+
+<e.g. @internal/postgres@0.5.2>
+
+## What happened?
+
+<one-sentence summary plus the relevant output line, secrets redacted>
+
+## What did you expect to happen?
+
+<one sentence>
+
+## Minimal reproduction
+
+1. <step one>
+2. <step two>
+3. <step three>
+
+```ts
+// schema.psl excerpt + the query / command that fails
+```
+
+## Environment
+
+- Node: <version>
+- OS: <darwin/linux/win32> <version>
+- Package manager: <pnpm/npm/yarn/bun/deno> <version>
+- Database: <Postgres / Mongo> <version>
+
+## Additional context
+
+<optional — link to source skill's capability-gap entry, related
+issue number, partner extension involved>
+~~~
+
+Feature-request body shape (fields named to match `.github/ISSUE_TEMPLATE/feature_request.yml`):
+
+~~~markdown
+## What problem are you trying to solve?
+
+<paragraph — the use case or pain point this would address>
+
+## Proposed solution
+
+```ts
+// imagined usage of the API / behaviour you'd want
+```
+
+## Alternatives considered
+
+<sentence or two — what you tried with the current API and why it didn't work>
+
+## Scope and impact
+
+<which package(s) this would touch; target-specific implications>
+~~~
+
+### 5. Title (issue path only)
+
+- **Bug**: `bug(<area>): <one-line summary>` — e.g. `bug(cli): migration plan exits 0 when there is no diff`.
+- **Feature request**: `feat(<area>): <one-line summary>` — e.g. `feat(build): first-party Next.js plugin for contract emit`.
+
+Areas mirror the cluster of skills: `cli`, `contract`, `migration`, `query`, `runtime`, `build`, `error`, `docs`.
+
+### 6. Surface for confirmation (issue path only)
+
+**Never auto-submit.** The agent shows the rendered title and body to the user and asks: *"This looks good to file. Shall I submit it to GitHub?"*. Submission only happens after explicit user approval.
+
+### 7. Submit (issue path only)
+
+Preferred. Two steps:
+
+1. **Write the rendered body to a temporary file.** Use your file-write tool (the same tool you'd use to create any other file on disk) to write the body to e.g. `wip/pn-issue-body.md` or `/tmp/pn-issue-body.md`. The body content is just the markdown produced in step 4 of this workflow — no surrounding shell quoting, no heredoc.
+2. **Reference that file from `gh`.** Run:
+
+   ~~~bash
+   gh issue create \
+     --repo prisma/prisma \
+     --title "<title>" \
+     --body-file <path-from-step-1>
+   ~~~
+
+**Anti-pattern (do not do this):** inlining the body via `--body "$(cat <<EOF …)"` or `--body-file <(cat <<EOF …)`. Those one-liners reliably leak literal `cat <<'EOF'` / `EOF` markers into the issue body when the agent reuses the template verbatim with the body interpolated. Always write the body to a real file first and pass the path.
+
+If `gh` is not installed: open the prefilled new-issue URL in the browser:
+
+~~~text
+https://github.com/prisma/orm/issues/new/choose
+~~~
+
+…and instruct the user to paste the rendered body. The agent can copy the body to the clipboard via `pbcopy` (macOS), `xclip` (Linux), or by simply printing it in the chat for the user to copy.
+
+### 8. Route to Discord (Q&A / design-feedback / direct-team-contact path)
+
+When step 1 picked the Discord channel (steps 2–7 do not apply):
+
+1. **Surface the link.** Give the user the canonical invite: <https://pris.ly/discord>. Suggest the channel that fits the question:
+   - General usage / Q&A → the public `#help` channel (the invite landing page lists current channels).
+   - Extension-author / partner-integration / breaking-change-coordination questions → the public extension-authors channel, or the user can ping a maintainer directly once they're in the server.
+2. **Help draft the opening message.** Prisma's Discord is searchable; a well-framed opening message gets a faster, more useful answer. The agent drafts a short message with:
+   - One-sentence summary of what the user is trying to do.
+   - The Prisma 8 version (`pnpm ls @internal/postgres` or equivalent).
+   - A short code snippet (PSL excerpt, query, config file) where relevant — redacted the same way as a GitHub issue body (no `DATABASE_URL`, no customer schema names).
+   - The specific question the user wants answered.
+3. **Do not auto-post.** The agent surfaces the drafted message to the user — *"here's an opening message you can paste into Discord; want to adjust before sending?"* — and lets the user decide whether to paste it as-is, edit it, or pick a different framing.
+4. **Set expectations honestly.** Discord is synchronous and best-effort. Bugs and concrete feature requests should land in GitHub regardless (use the issue path); Discord is for the conversation that gets you to *"yes, this is a bug, file it"* or *"yes, this should be a feature, file it"*.
+
+### 9. Follow up
+
+- **Issue path**: record the issue URL in the user's project notes (or in the project's `wip/` if there is one) so a later upgrade or related work can reference it. If the bug is the symptom of an old version of Prisma 8, suggest an upgrade following [`upgrade-app.md`](upgrade-app.md) — many bugs are fixed in newer releases.
+- **Discord path**: once the conversation on Discord settles into a concrete bug or a concrete feature request, return to step 1 of this skill and file the issue (the Discord thread becomes the *Notes* / *Where the gap surfaces* reference in the issue body).
+
+## Common Pitfalls
+
+1. **Auto-submitting without confirmation.** Always show the body first. The user owns the public-facing artifact, not the agent.
+2. **Pasting `DATABASE_URL` or other secrets into the body.** `redact` aggressively. Replace with `postgresql://USER:PASS@HOST/DB` placeholders.
+3. **Pasting a customer's confidential domain schema.** When original model and field names would leak confidential information (product codenames, customer identifiers, regulated-data fields), rename to neutral placeholders before the body goes into a public issue. Otherwise, keep the original names — a faithful excerpt is easier for the framework team to reason about than a re-themed one. Over-renaming is its own readability cost.
+4. **Filing a documentation question as a bug.** Documentation questions belong in another skill or in a GitHub Discussion (if the repo enables them). Bugs are about the surface misbehaving.
+5. **Conflating bug + feature in one issue.** File two. Mixed issues are hard to triage and hard to close.
+6. **Filing without a version.** "I'm using Prisma 8, it's broken" without the version makes triage hopeless. The version is the cheapest piece of context to capture; always include it.
+
+## What Prisma 8 doesn't do yet
+
+- **In-product feedback channel.** No `prisma feedback` CLI command. The GitHub Issues page is the canonical surface. If you want a CLI-side feedback command, file a feature request via this skill.
+
+## Reference Files
+
+- <https://github.com/prisma/orm/issues/new/choose> — the canonical submission surface.
+- <https://cli.github.com/manual/gh_issue_create> — the `gh` command reference.
+
+## Checklist
+
+- [ ] Classified as bug or feature request (not both in one issue).
+- [ ] Environment block present: PN version, Node, package manager, OS.
+- [ ] Reproduction is minimal, public-safe, secret-free.
+- [ ] Schema fragments use original names where safe; renamed to neutral placeholders only where original names would leak confidential domain detail.
+- [ ] Title in conventional-commit form (`bug(area): …` / `feat(area): …`).
+- [ ] Body shown to the user for confirmation before submission.
+- [ ] Submitted via `gh issue create` (preferred) or via the prefilled new-issue URL.
+- [ ] Issue URL captured for future reference.
+- [ ] Suggested an upgrade ([`upgrade-app.md`](upgrade-app.md)) if the bug may already be fixed in a newer release.

package/skills/prisma-8/references/migration-model.md

@@ -0,0 +1,175 @@
+
+# Prisma 8 — The Migration Graph and Refs (Mental Model)
+
+> **Edit your data contract. Prisma handles the rest.**
+
+This reference teaches the model behind migration planning: what the migration graph is, what refs are, how `migration plan` chooses where to start, and the one silent mistake the model exists to prevent — a plan that starts from an empty database while migrations already exist. Hold this model and both authoring loops (dev-database loop, deploy-first loop) follow from it; skip it and the planner's defaults will eventually produce a migration you didn't intend.
+
+## When to Use
+
+- Deciding where the next `migration plan` should chain from.
+- `migration plan` output shows `from: (baseline)` and you didn't expect a from-scratch plan.
+- Setting up on-disk migrations for a project whose databases are managed by a deploy pipeline (Prisma Composer or your own CD) rather than by `db init` / `db update`.
+- A database already exists (marked and accurate) but the repo has no on-disk migrations for it — retrofit.
+- Questions about refs: `migration ref set` / `list` / `delete`, what the `db` ref means, `--advance-ref`, why a ref is stale.
+
+## When Not to Use
+
+- Filling placeholders, applying migrations, hash mismatches, drift recovery → `references/migrations.md`.
+- What runs on deploy, environment refs in CI, concurrent-migration conflicts → `references/migration-review.md`.
+- First-time adoption of an existing database (`contract infer` + `db sign` mechanics) → `references/quickstart.md` § *Brownfield-DB*.
+
+## Key Concepts
+
+### The graph is a static artifact
+
+The on-disk migrations under `migrations/<space>/` form a directed graph. **Each migration is an edge recording a `from` and a `to` contract storage hash** (in its `migration.json`; `from: null` denotes an edge from the empty database). Nodes are the hashes those edges mention. That is the whole structure — the graph records which contract states migrations exist between, and nothing else.
+
+Consequences worth internalising:
+
+- **No node is privileged.** There is no "current" node, no HEAD, no special tip the planner chains from. Multiple branch tips are legal (two migrations planned off the same node). Cycles are legal (a rollback edge back to an earlier hash creates one).
+- **The graph does not know where your database is.** "Where is my database" is answered by the database's **marker** (a live-DB record of "this database is at hash X") and, offline, by **refs**. Never by the graph.
+- **The graph does not know where your next migration should start.** The planner has to be told an origin. That is the entire job of refs and `--from`.
+
+### Refs — version-controlled pointers
+
+A ref is a small committed file, `migrations/<space>/refs/<name>.json` (for your app: `migrations/app/refs/<name>.json`), containing `{ hash, invariants }`. Two roles, by convention:
+
+- **The `db` ref** records which contract hash the project's dev database has been brought to. It is a **checkpoint, not a promise**: dev commands write it after the fact so the offline planner knows where dev iteration left off, without opening a database connection.
+- **Environment refs** (`staging`, `production`, …) name **the contract CD will migrate that environment to** — a forward promise the repo makes, consumed at deploy time. See `references/migration-review.md` for the deploy-side workflows.
+
+`db` is a **default name, not a magic one**. It gets no special storage, no protection; dev commands simply default to advancing a ref of that name. You can point it anywhere with `migration ref set db <hash>` and a later `db update` on the default URL will overwrite it.
+
+Manage refs with:
+
+```bash
+pnpm prisma migration ref set <name> <hash-or-ref>
+pnpm prisma migration ref list
+pnpm prisma migration ref delete <name>
+```
+
+`migration ref set` requires the target to be the `to` hash of an on-disk migration. A hash outside the graph is refused (`MIGRATION.HASH_NOT_IN_GRAPH`); a hash that appears in the graph only as a `from` — no bundle produces it — is refused too (`MIGRATION.REF_SET_BUNDLE_NOT_FOUND`). Find node hashes with `migration list`.
+
+### Who advances refs
+
+| Command | Ref advancement |
+|---|---|
+| `db init` / `db update` (default URL) | Implicitly advance `db` (override the name with `--advance-ref <name>`; suppressed whenever `--db` is passed without `--advance-ref`, regardless of the URL — even `--db $DATABASE_URL` pointing at the default database) |
+| `db sign` | Advances `db` after a successful signature (override the name with `--advance-ref <name>`; `--no-advance-ref` skips it, writing no ref and no snapshot); an existing ref is overwritten and the previous hash is reported in the human output (the JSON `advancedRef` carries name and hash only). `--db` does **not** suppress it, unlike init/update: sign never mutates the schema, and adoption is normally done via `--db` |
+| `db migrate --advance-ref <name>` | The **only** apply-time advancement |
+| plain `db migrate` | **Never advances anything** — deliberate: deploy and CI applies must not infer dev intent |
+| `migration plan` | Never advances anything — chaining discipline is yours |
+| deploys (Composer / CD) | Write the database's marker; structurally cannot and do not touch repo refs |
+
+### How `migration plan` picks its origin
+
+`migration plan` resolves its origin in exactly this order:
+
+1. Explicit `--from <ref-name | hash | hash-prefix | migration-dir | migration-dir^ | ./path | @empty>` — `@empty` names the empty database deliberately. The reserved forms `@db` and `@contract` exist in the shared ref grammar but do not resolve here: `migration plan` is offline, so `@db` (the live marker) has nothing to read, and `@contract` needs a contract hash the plan resolver does not pass. Use them with `db migrate --show` / `migration status`, not with `plan`.
+2. No `--from` → the `db` ref (`migrations/app/refs/db.json`).
+3. No `db` ref → **greenfield: the plan starts from the empty database.** On an empty graph the human output adds a muted notice beneath the summary — `No db ref set — planning from an empty database. Run db init, db update, or db sign if a database already exists.` — and the JSON document carries `fromDefaulted: true`, so this case is distinguishable from an explicit `--from @empty`.
+
+It is **offline** — it never consults a database, never reads a marker (which is why `--from @db` is not an option here). Whatever the refs on disk say is what it believes. The destination defaults to the emitted `contract.json` (`--to` overrides).
+
+The human output names the resolved origin on its `from:` line. **`from: (baseline)` means the origin resolved to nothing — the plan starts from an empty database** and will contain a create for every object in the contract.
+
+**Auto-baseline.** When the graph is *empty* and the origin resolved through a ref to a real hash (the typical first plan after `db update` cycles), the planner emits **two** bundles in one invocation — a baseline `null → ref-hash` plus the delta `ref-hash → contract` — so the ref's hash becomes a graph node and the plan can be applied. Expect two new directories in `git status`. Details and the related refusals (`MIGRATION.HASH_NOT_IN_GRAPH`, `MIGRATION.SNAPSHOT_MISSING`) are in `references/migrations.md` § *Dev → ship transition*.
+
+## The trap — a greenfield plan over existing migrations
+
+**A plan whose origin is the empty contract while migrations already exist on disk is almost always a mistake.** A full-create migration cannot do what you meant: a database that has the prior migrations applied refuses it (`MIGRATION.PATH_UNREACHABLE` — no path from its marker to the new plan's destination), and running its create statements against any populated schema fails outright. The CLI refuses this at plan time: when origin resolution falls all the way through (no `--from`, no `db` ref) and migrations exist, `migration plan` stops with `MIGRATION.PLAN_ORIGIN_UNKNOWN` instead of writing the package — the error's suggestions are the three exits below; do not reflexively take the `--from @empty` one, pick by intent.
+
+How the fall-through happens: a project that never runs `db init` / `db update` / `db sign` (the deploy-first path below) never acquires a `db` ref, so *every* default plan resolves to the empty origin. Running the dev loop with an explicit `--db` has the same effect: `db init` / `db update` with that flag never advance the ref, whatever URL it carries (`db sign` is the exception — it advances the ref with or without `--db`). The first time that is correct (it is the baseline; an empty migration graph plans with only the muted notice); every later time it is the trap the refusal catches.
+
+**Recognize a from-empty plan** that was produced anyway (an explicit `--from @empty`, or an older CLI without the refusal), at either layer:
+
+- Plan output says `from: (baseline)` — while `migrations/app/` already contains migration directories.
+- The new package's `migration.json` has `"from": null` — while sibling migrations exist.
+- The planned operations create objects you know already exist.
+
+**Three exits.** Pick by intent, delete the mistaken package directory first if one was written:
+
+1. **Set a ref to the intended origin, then re-plan with the default.** Usually the last shipped migration's `to` hash: `migration list` to find it, `migration ref set db <hash>`, `migration plan --name <slug>`. Do this when you want future plans to chain without flags.
+2. **Pass the origin explicitly:** `migration plan --from <ref-or-hash-or-migration-dir> --name <slug>`. Do this for a one-off, or when a different ref (e.g. `production`) is the honest origin.
+3. **You genuinely mean the empty origin** — a first baseline, or a deliberate rebuild of everything. Say it explicitly: `migration plan --from @empty --name <slug>`. This is the only case where `from: (baseline)` over a non-empty directory is right, and it should be rare enough to say out loud.
+
+## Workflow — the dev loop
+
+The concept: while the schema is in flux, iterate the dev database with `db init` / `db update` — they apply the contract *and* keep the `db` ref current. When the shape settles, plan: the plan chains from the ref, and the auto-baseline covers the case where the graph is still empty.
+
+```bash
+pnpm prisma db init                                     # once; advances the db ref
+pnpm prisma contract emit && pnpm prisma db update      # iterate; each advances the db ref
+pnpm prisma contract emit && pnpm prisma migration plan --name <slug>
+pnpm prisma db migrate --db $DATABASE_URL
+```
+
+After a plain `db migrate` the marker advances but the ref lags; refresh with `db update` (no-op on the DB when already current) or apply with `db migrate --advance-ref db` in the first place. Full mechanics, refusals, and recovery: `references/migrations.md` § *Dev → ship transition*.
+
+## Workflow — the deploy-first loop (Composer / CD-managed databases)
+
+The concept: the deploy pipeline owns the databases, so `db init` / `db update` never run and nothing ever advances a `db` ref for you. Deploys replay each database from its marker to the contract emitted at build time; they never write to `migrations/app/refs/`. Two disciplines keep this loop safe:
+
+**Author the baseline before the first deploy.** Before anything is deployed:
+
+```bash
+pnpm prisma contract emit
+pnpm prisma migration plan --name init      # from: (baseline) — intended, this once
+git add migrations/ && git commit
+```
+
+This is the one intended greenfield plan. With the baseline committed, the deployed database's marker always corresponds to a graph node, and every later state is reachable by planned migrations.
+
+**Chain every later plan from the last shipped contract.** Nothing advances refs in this loop, so either keep the `db` ref current yourself — after each plan, `migration ref set db <new-migration-to-hash>` (the hash is a graph node as soon as the plan is written; `migration list` shows it) — or pass `--from <last-migration-dir>` on every plan. Committing the ref together with the migration keeps teammates' default plans chaining correctly too.
+
+If you skip the chaining, the next default plan resolves to greenfield: the trap above. And note the planner accepts *any* graph-node origin without complaint — planning from a stale ref silently creates a second branch tip (legal, occasionally intended, usually not). Check `migration list` when in doubt.
+
+## Workflow — adopt a pre-existing database
+
+The concept: a database that predates Prisma 8 enters the system by describing it, not migrating it — `contract infer` derives the contract from the live schema, and after review + `contract emit`, `db sign` records the marker. Full recipe: `references/quickstart.md` § *Brownfield-DB*.
+
+```bash
+pnpm prisma contract infer --db "$DATABASE_URL" --output src/prisma/contract.prisma
+# review and re-author, then:
+pnpm prisma contract emit
+pnpm prisma db sign --db "$DATABASE_URL"                # advances the db ref even with --db
+```
+
+By default `db sign` sets the `db` ref to the signed contract's hash and stores its snapshot, so the next `migration plan` chains from the adopted schema (`--advance-ref <name>` writes another ref instead, and `--no-advance-ref` writes none; after either, set the `db` ref yourself with `migration ref set db <hash>` or pass `--from` on the next plan): the graph is still empty at that point, so the plan auto-emits the baseline `null → signed-hash`, plus a delta `signed-hash → contract` once the contract has moved on from the signed one. No baseline is written at sign time. If the graph is already non-empty and the signed hash is not a graph node, the next plan refuses with `MIGRATION.HASH_NOT_IN_GRAPH`, exactly as after `db update`.
+
+## Workflow — retrofit a database that has no on-disk migrations
+
+The concept: the database exists and its marker is accurate (hash **M**) — it was built by `db update` or signed with `db sign` in another checkout, or built by a deploy pipeline — but the migration graph doesn't reach M. (A database adopted with `db sign` in *this* checkout already has its ref set; retrofit is for the case where the ref was never set here.) The goal is to **make the graph reach the marker's hash**: once a baseline `null → M` exists, applying against the marked database is clean by construction — the runner starts at the marker, so the baseline never executes; only real deltas past M run.
+
+- **It's your dev database.** Run `db update` (default URL; no-op on the DB when the contract already matches) — it advances the `db` ref and stores the contract snapshot. The next `migration plan` auto-emits the baseline plus your delta. This is just the dev loop's dev → ship transition.
+- **It's a deployed database you must not touch.** Build the baseline offline, at the deployed contract state:
+  1. Bring the contract source back to the deployed state (check out the deployed revision of the contract file, or stash your edits), then `contract emit`.
+  2. `migration plan --name baseline` — greenfield, intended: one bundle `null → M`. Confirm its `to` matches the database (`db verify --db "$URL"` is clean at this revision).
+  3. Restore the current contract source, `contract emit`.
+  4. `migration ref set db <M>` (M is now a graph node), then `migration plan --name <slug>` — the delta `M → current`.
+
+  `db migrate` against the marked database applies only the delta.
+
+## Common Pitfalls
+
+1. **Assuming `migration plan` chains from the newest migration on disk.** It never does. The origin is `--from`, else the `db` ref, else empty. If neither exists, you get a from-scratch plan; on an empty graph the only warning is the muted `No db ref set` notice.
+2. **Expecting `migration plan` or plain `db migrate` to keep the `db` ref current.** Neither touches refs. Only `db init` / `db update` / `db sign` advance implicitly, and only `--advance-ref` advances at apply time.
+3. **Expecting a deploy to update refs.** Deploys write the database's marker; the files under `migrations/app/refs/` only change when you change them.
+4. **Reading `from: (baseline)` as informational.** Over a non-empty migrations directory it is the trap announcing itself. Stop and pick an exit before applying or committing.
+5. **`migration ref set` with a hash no on-disk migration produces.** A ref target must be the `to` hash of an on-disk migration bundle. A hash outside the graph is refused (`MIGRATION.HASH_NOT_IN_GRAPH`); a from-only graph node is refused with `MIGRATION.REF_SET_BUNDLE_NOT_FOUND`, whose fix text points at fixtures and is unhelpful here. Either way: plan the edge whose `to` is the hash first (baseline or delta), then set the ref.
+6. **Treating `db` as reserved.** It's a naming default. Setting it yourself is fine and sometimes exactly right (deploy-first chaining, retrofit); just expect dev commands on the default URL to overwrite it.
+7. **Authoring the first migration after the first deploy.** Then no graph node corresponds to what shipped, and every incremental path needs the retrofit. Baseline before the first deploy — it's one command.
+
+## What Prisma 8 doesn't do yet
+
+- **No plan-time ref advancement.** `migration plan` cannot advance a ref for you; keeping the chain current is manual (`migration ref set` after each plan, or `--from` every time). If you want a plan-time advancement flag, file a feature request via the `references/feedback.md` skill.
+
+## Checklist
+
+- [ ] Named the intended origin before planning — a ref, a hash, or a deliberate `--from @empty`.
+- [ ] Read the plan output's `from:` line and confirmed it names that origin — not `(baseline)` over an existing graph.
+- [ ] In a deploy-first project: baseline authored and committed before the first deploy; every later plan chained via the `db` ref or `--from`.
+- [ ] After each plan in a loop where nothing advances refs: advanced the `db` ref (`migration ref set db <to-hash>`) or resolved to pass `--from` next time.
+- [ ] For a marked database with no on-disk migrations: made the graph reach the marker's hash (auto-baseline via `db update` or `db sign`, or an offline baseline plan) before planning deltas.
+- [ ] Did NOT expect plain `db migrate`, `migration plan`, or a deploy to advance any ref.
+- [ ] Did NOT apply or commit a `from: (baseline)` plan without confirming the empty origin was the intent.