@prisma/orm-mongo 8.0.0-rc.4-dev.17 → 8.0.0-rc.5-dev.1

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

@@ -0,0 +1,251 @@
+
+# Prisma Next — 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 Next skill's *What Prisma Next 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 Next?"*.
+
+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/prisma-next/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-next-*` 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 Next (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-next-*` 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 Next 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/prisma-next/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/prisma-next/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` or `#prisma-next` channel (channel naming evolves; 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 Next 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 Next, 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 Next, it's broken" without the version makes triage hopeless. The version is the cheapest piece of context to capture; always include it.
+
+## What Prisma Next doesn't do yet
+
+- **In-product feedback channel.** No `prisma-next 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/prisma-next/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-review.md

@@ -0,0 +1,224 @@
+
+# Prisma Next — Migration Review (Deployment + Concurrency)
+
+> **Edit your data contract. Prisma handles the rest.**
+
+This skill is about *reviewing* migrations, not authoring them. It covers the questions that come up at deploy time and when multiple developers are landing migrations concurrently.
+
+The skill teaches *the system's mental model* — what a ref is, what a marker is, what the migration graph is — and shows how to ask the system for its state. It does **not** prescribe rigid step-by-step procedures: most "review" questions are answered by understanding the model and querying the right thing. Rigid procedures are reserved for the rare case where there's literally one safe path.
+
+## When to Use
+
+- User asks *"what migrations will run when I merge this?"* or *"what's about to run on deploy?"*.
+- User hit a concurrent-migration conflict (`main` advanced while their branch was open).
+- User wants to wire up a `staging` / `production` ref so CI can deploy against it.
+- User wants to run a migration against an environment that isn't the local dev DB.
+- User asks about CI integration for migrations.
+
+## When Not to Use
+
+- User wants to *author* a migration → `references/migrations.md`.
+- User wants to fix a hash-mismatch / drift in a single env → `references/migrations.md` (re-plan path) or `references/debug.md` (envelope-driven).
+- User wants to edit the contract → `references/contract.md`.
+
+## Key Concepts — the navigation model
+
+**Every migration question is a navigation from an *origin* to a *destination*.** Once you have this model, the rest of the skill is just "which command asks the system about which navigation."
+
+### Origin
+
+The **origin** is the database's *current contract hash*. The database carries a row in PN's marker table that records *"this database is at hash X"*. When the CLI runs online (a `--db <url>` is provided, or `db.connection` is set in `prisma.config.ts`), PN reads the marker and that hash is the origin. Offline (no DB connection), the origin is unknown — many commands degrade to listing the on-disk migrations and skip the per-edge applied/pending status.
+
+A live DB is therefore the authoritative source of origin. The "recorded marker" in any other artifact (refs, local cache, your assumptions) is a working copy that can drift; the live DB never does.
+
+### Destination
+
+The **destination** is the contract hash you want the database to be at. Two ways to name a destination:
+
+- **A `--to <name>`** — a named pointer to a hash, stored under `migrations/app/refs/<name>`. Refs are named after environments by convention (`staging`, `production`) to communicate *"this is where production is expected to be"*. The ref itself is just a hash + an optional set of required invariants; it has nothing to do with which database you connect to.
+- **The current contract head** — implicit when no `--to` is passed. This is the hash of the current `contract.json` on disk.
+
+`--to staging` does **not** mean "connect to the staging database." It means "navigate the database I connected to (via `--db` or config) toward whatever hash this ref points at." Database selection is orthogonal: pass `--db $STAGING_DATABASE_URL` to actually point at staging.
+
+### The migration graph
+
+The on-disk migrations form a directed graph: **nodes are contract hashes; edges are migrations.** Each migration declares a `from` hash and a `to` hash. A migration applies only when the database's current marker matches its `from` hash; running it advances the marker to its `to` hash.
+
+`migration status` queries the graph for the path from origin to destination and reports per-edge status:
+
+- **applied** — on the path from `EMPTY_CONTRACT_HASH` to the marker (history).
+- **pending** — on the path from the marker to the destination (what would run).
+- **unreachable** — on the path from `EMPTY_CONTRACT_HASH` to the destination, but the marker is on a different branch and won't reach it without first re-routing.
+
+### Diagnostic codes
+
+`migration status` emits structured diagnostics on the result envelope (`diagnostics[].code`) so the agent can branch on the code rather than parsing the prose summary. Each diagnostic also carries `severity` (`warn` or `info`), a human `message`, and `hints` — the same hints the CLI prints under the summary line.
+
+| Code | Severity | Meaning in the navigation model | Next move |
+|---|---|---|---|
+| `MIGRATION.UP_TO_DATE` | info | Marker = destination; no edges to walk. | Nothing to do. |
+| `MIGRATION.DATABASE_BEHIND` | info | Marker is an ancestor of the destination; N pending edges in between. | `db migrate --to <name> --db $URL`. |
+| `MIGRATION.MISSING_INVARIANTS` | info | Marker reached destination structurally but missing required invariants the ref declares. | `db migrate --to <name> --db $URL` to take a path that covers them. |
+| `MIGRATION.NO_MARKER` | warn | Online, but the database has no marker row — never initialised. | `db migrate --db $URL` (first apply writes the marker). |
+| `MIGRATION.MARKER_NOT_IN_HISTORY` | warn | Online; marker hash is not a node in the graph. The database was changed outside the migration system. | Decide which side is truth: `db sign` (accept DB as truth), `db update` (push contract to DB), `contract infer` (re-derive contract from DB), or `db verify` (inspect first). **Not** the same as `MIGRATION.MARKER_MISMATCH`: `MARKER_NOT_IN_HISTORY` is emitted during the runner's graph walk when the live marker is off the path being traversed; `MARKER_MISMATCH` fires earlier, at the CLI pre-DDL gate, when the marker hash is not a graph node at all. |
+| `MIGRATION.DIVERGED` | warn | Multiple valid leaves; the destination is ambiguous. | Pass `--to <name>`, or `migration ref set <name> <hash>` to create one. |
+| `CONTRACT.AHEAD` | warn | Contract head is not in the graph — the contract was edited without re-planning. | `migration plan` to extend the graph. |
+| `CONTRACT.UNREADABLE` | warn | `contract.json` couldn't be read. | `contract emit` to regenerate it. |
+
+### Graph-tree output
+
+`migration status` (and `migration list`) render the migration graph as a colored lane tree in the terminal. Two flags control the rendering:
+
+- `--legend` — prints the key for the tree glyphs and lane colors before the tree.
+- `--ascii` — replaces box-drawing glyphs with pipe-safe ASCII characters (useful in CI logs or environments that don't support Unicode).
+
+Both flags are also available on `migration list` and `migration graph`. `migration log` supports `--ascii` only (it renders a flat chronological table, not a tree).
+
+### Plan- and apply-time diagnostics
+
+These codes surface on `migration plan`, `migration ref set`, and `db migrate` — not on `migration status`. See [Migration System § Recovery affordances](../../docs/architecture%20docs/subsystems/7.%20Migration%20System.md#recovery-affordances) and [ADR 218](../../docs/architecture%20docs/adrs/ADR%20218%20-%20Refs%20with%20paired%20contract%20snapshots%20and%20universal%20graph-node%20invariant.md).
+
+| Code | When | Meaning | Next move |
+|---|---|---|---|
+| `MIGRATION.HASH_NOT_IN_GRAPH` | `migration plan` (non-empty graph) or `migration ref set` | Resolved hash is not a node in the on-disk migration graph — typical when the default `db` ref points past the graph tip after dev-only `db update` cycles. | `migration plan --from <reachable-ref>` (e.g. `--from production`); or realign the ref with `migration ref set db <graph-node-hash>`. |
+| `MIGRATION.SNAPSHOT_MISSING` | `migration plan` | A named ref has no pointer file (`<name>.json`), and the hash being resolved isn't a node in the migration graph either. | `migration ref set <name> <hash>` to create the ref, `db update --advance-ref <name>` to advance it, or pass a hash that is a graph node. |
+| `MIGRATION.MARKER_MISMATCH` | `db migrate` (pre-DDL, before the runner) | Live DB marker hash is not a graph node — drift the offline planner cannot see. | `migration plan --from <graph-tip>` if the marker is canonical; `migration ref set db <marker-hash>` if the on-disk graph is canonical; investigate out-of-band applies. |
+| `MIGRATION.PATH_UNREACHABLE` | `db migrate` (path resolution) | No migration path from the current marker to the resolved target in the on-disk graph. | Read the improved `fix` payload — it names `fromHash` / `targetHash` and suggests `migration plan --from <from> --to <target>`; run `migration list` to inspect the graph. |
+
+A CI gate should read `diagnostics` from `--json` output and decide based on `severity` plus `code`; see *Workflow — CI* below for the structure.
+
+## Workflow — *"What's about to run on deploy?"*
+
+The user asks: *"I'm about to merge this PR. What migrations are going to run when I deploy to staging?"*
+
+This is the navigation question: **origin** = staging's live marker; **destination** = the ref `staging` (or the contract head if you haven't set one). Ask the system:
+
+```bash
+pnpm prisma migration status --to staging --db "$STAGING_DATABASE_URL"
+```
+
+The command:
+
+1. Reads the staging DB's marker (the origin).
+2. Resolves `staging` to a contract hash (the destination).
+3. Renders the path between them as an ordered list of migrations, with per-edge `applied` / `pending` / `unreachable` status, and an explicit summary line of the form *"N migration(s) behind ref 'staging'"*.
+4. Prints a header that names the config, migrations directory, the active ref, and the database connection (masked) — so the framing is visible in the output.
+
+If you omit `--db`, the command runs offline: it lists the migrations on disk but cannot tell you what's applied, because it has no origin. That's fine for *"what's on this branch?"*; it's not fine for *"what's about to run on staging?"* — for that you need staging's live marker.
+
+If you omit `--to`, the destination defaults to the contract head — which answers *"is this branch's contract reachable from the database, and how?"*, not *"what runs on deploy"*. Pass the ref explicitly when the question is about a specific environment.
+
+`migration status` summarises each pending migration's operations by class (`additive`, `widening`, `data`, `destructive`) and reports a destructive-op count when destructive operations are present. Surface that count to the user before they merge or deploy — destructive operations are the class that warrants manual review.
+
+## Workflow — *"What state is each environment at?"*
+
+Just `migration status --db $URL` for each environment's DB. The marker (origin) comes back from the DB itself; the summary line tells you whether the environment is at the contract head, at a named ref, ahead of head, or on a divergent branch.
+
+## Concept — concurrent migrations on the same branch point
+
+This used to be called *diamond convergence* in some PN docs; the situation is the same regardless of the label.
+
+**What's happening.** Two topic branches each authored a migration off the same parent contract hash. The first branch merges to `main`; the destination ref (e.g. `production`) advances to that branch's `to` hash. Your branch's migration still has its `from` hash pointing at the *old* parent. The migration graph, after rebase, no longer has a clean path through your migration:
+
+- Your migration's `from` is no longer an ancestor of the new head.
+- Or your migration's `from` is reachable, but the path through your migration arrives at a hash that's not the union of both branches' changes.
+
+Either way, the on-disk plan is stale.
+
+**Resolution.** The on-disk plan is stale because its `from` hash is no longer the head of the graph; apply the cluster's standard *edit → plan → apply* loop to the post-rebase state and the planner produces a fresh migration whose `from` matches the new head.
+
+**The one thing the planner can't do for you** is port custom data-transform logic from the abandoned `migration.ts` into the new one — schema deltas are derived from the contract, but any hand-written `data` operations are yours to carry across before applying. There is no separate "revalidate" step, no special "diamond apply" flow.
+
+## Workflow — set, list, get, delete refs
+
+Refs are small artifacts. There's no per-environment lifecycle; you just point a name at a hash.
+
+```bash
+pnpm prisma migration ref set production <contract-hash>
+pnpm prisma migration ref list
+# `migration ref get` was removed — use `migration ref list` and filter by name
+pnpm prisma migration ref list | grep production
+pnpm prisma migration ref delete production
+```
+
+`migration ref set` writes a file at `migrations/app/refs/<name>` carrying the hash and any required invariants. Refs are commit-friendly artifacts — keep them in git; the team agrees on what `production` points at the same way they agree on what `main` is.
+
+## Workflow — apply a migration against an environment
+
+```bash
+pnpm prisma db migrate --to production --db "$PRODUCTION_DATABASE_URL"
+```
+
+The destination is the ref's hash; the origin is the production DB's live marker. The command computes the path between them and applies each pending migration in order, advancing the marker.
+
+`--db` is the environment selection knob. `--to` is the destination-hash knob. They're independent.
+
+## Concept — ref-mismatch on CI / deploy
+
+CI reports: *"the recorded ref `production` is at hash X; the live DB is at hash Y."*
+
+The mismatch is a fact about *two pieces of state that disagree*. The investigation is the same regardless of which piece is wrong:
+
+- **DB ahead of the ref.** Someone applied a migration outside CI without updating the ref in git. Re-record the ref with `prisma migration ref set <ref-name> <db-marker-hash>` (commit + push); then audit how the out-of-band apply happened.
+- **DB behind the ref.** A previous deploy was rolled back, or the DB was restored from an older backup. Either re-apply forward with `prisma db migrate --to <ref-name> --db $URL`, or re-route the ref backward to match what's actually deployed with `prisma migration ref set <ref-name> <db-marker-hash>`. The choice is the user's — name both options.
+- **DB on a different branch.** An out-of-band schema change (manual SQL, ad-hoc migration) wrote something the migration graph doesn't model. Run `prisma db verify` to inspect the drift, then either `prisma contract infer` to re-derive the contract from the database, or edit the contract and run `prisma migration plan` so the database is the eventual destination.
+
+`migration ref set` to silently align the ref with whatever the DB happens to be at is almost never the right move. It papers over drift that you'll pay for later.
+
+## Workflow — CI: verify a branch can advance the target environment
+
+The gate is `migration status --to <env> --db $URL`: it computes the path from the live marker to the ref and reports it, without mutating anything. There is no `--dry-run` flag on `db migrate`; the inspect / gate step is `migration status`.
+
+For a human-readable ordered preview of the migration path before applying, use `db migrate --show --db $URL`. For applied history after a deploy, use `migration log --db $URL` (flat chronological table).
+
+```yaml
+- name: Verify staging is reachable
+  run: |
+    pnpm prisma migration status \
+      --to staging --db "$STAGING_DATABASE_URL" --json > status.json
+    node -e '
+      const s = JSON.parse(require("fs").readFileSync("status.json", "utf8"));
+      const warns = (s.diagnostics ?? []).filter(d => d.severity === "warn");
+      if (warns.length) {
+        console.error("Blocking diagnostics:", warns);
+        process.exit(1);
+      }
+    '
+- name: Apply
+  run: pnpm prisma db migrate --to staging --db "$STAGING_DATABASE_URL"
+```
+
+`migration status` exits non-zero only on hard errors (unreadable migrations directory, unsatisfiable invariants, unreconstructable history). Diagnostics like `MIGRATION.MARKER_NOT_IN_HISTORY`, `MIGRATION.DIVERGED`, `CONTRACT.AHEAD`, and `MIGRATION.NO_MARKER` are reported on the result envelope with `severity: 'warn'` but the process exits `0` — the agent (or a CI gate) must inspect `diagnostics[]` and fail the build itself. Use `--json` so the gate parses a structured shape rather than the human summary.
+
+`db migrate` is interactive-free and has no destructive-op confirmation prompt — the safety rails that prompt for destructive changes live on `db update` (see the `references/migrations.md` skill). Whatever the planner put in the migration graph is what `db migrate` runs; review happens at `migration plan` and at `migration status` time, before the apply step.
+
+## Common Pitfalls
+
+1. **Reading `migration status` without `--to` for a deploy question.** That asks *"can this branch's contract reach the head?"*, not *"what's about to run on staging?"*. Always pass the ref when the question is about a specific environment.
+2. **Reading `migration status` without `--db` for a deploy question.** Without a live DB, you have no origin. The output lists what's on disk; it can't say what's applied on the environment. Pass `--db $URL` for any high-stakes question.
+3. **Confusing the ref with a DB connection.** `--to staging` selects the destination hash, not the database. Pass both `--to` and `--db` explicitly.
+4. **Treating diamond convergence as a special procedure.** It's not. It's the normal *edit → plan → apply* loop applied to the post-rebase state. The only extra step is *"port any data-transform logic from your old `migration.ts` over."*
+5. **Running `migration ref set` to silence a CI mismatch without understanding the cause.** That can mask out-of-band changes or rollback drift. Investigate first.
+
+## What Prisma Next doesn't do yet
+
+- **Per-environment migration ordering beyond the default chain.** If you need staging to skip a migration that production requires (or vice versa), the supported path is to author the per-env divergence as separate migrations and gate them in your deploy script. If you want first-class per-env routing, file a feature request via the `references/feedback.md` skill.
+- **A built-in side-by-side "branch diff" view.** There is a full-graph render (`migration graph`) that shows branches, but no `git diff`-style comparison between two branches' migration sets. Workaround: run `migration status` on each branch and `diff` the output. If you want a built-in branch-comparison view, file a feature request via the `references/feedback.md` skill.
+
+## Reference Files
+
+This skill is intentionally body-only; the underlying CLI reference (`prisma migration status --help`, `prisma db migrate --help`, `prisma migration ref --help`) is the authoritative surface for flag-level detail. When in doubt, run `--help` and read the actual command's description rather than guessing from this skill.
+
+## Checklist
+
+- [ ] Named both the **origin** (live DB marker) and the **destination** (ref or contract head) for the question the user asked.
+- [ ] Passed `--db $URL` whenever the question involves a specific environment.
+- [ ] Passed `--to <name>` whenever the question is about deploying *to* a named environment, not just *from* the current branch's head.
+- [ ] Read the `migration status` header (it names config, ref, database) and the summary line (it names the origin/destination distance) before reading the per-edge list.
+- [ ] For concurrent-migration conflicts: re-applied the *core* workflow (edit → plan → apply) rather than following a memorised "diamond convergence" procedure. Ported any data-transform logic from the abandoned `migration.ts` over.
+- [ ] For a ref-mismatch: investigated *which* piece of state is wrong (DB ahead, DB behind, DB on a divergent branch). Did NOT `migration ref set` to silence the mismatch.
+- [ ] Surfaced the destructive-op count from `migration status` (the only operation class that warrants manual review pre-deploy) before the user merges or deploys.
+- [ ] In CI: parsed `migration status --json` `diagnostics[]` and gated on `severity === 'warn'`; did NOT rely on a `--dry-run` flag on `db migrate` (no such flag exists).
+- [ ] Did NOT confuse `--to` with database selection (`--to` picks the destination hash; `--db` picks the database).
+- [ ] Did NOT use `--ref` (removed; use `--to`).
+- [ ] Did NOT confabulate a "branch diff" CLI subcommand, a `migration revalidate` step, or any other API the skill above doesn't reference.