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

package/README.md

@@ -15,7 +15,7 @@ The one package a MongoDB application installs. It wires the framework, the Mong
 └── @prisma/orm-toolchain      ORM command family for the `prisma` CLI, emitter, config loader
 ```
 
-`mongodb` is a peer dependency: the driver is the application's, so a single connection pool and a single BSON implementation serve both Prisma Next and any direct `mongodb` use in the same process.
+`mongodb` is a peer dependency: the driver is the application's, so a single connection pool and a single BSON implementation serve both Prisma 8 and any direct `mongodb` use in the same process.
 
 ## Entrypoints
 
@@ -48,7 +48,3 @@ This package ships no bin. The ORM commands run inside the unified `prisma` CLI,
 ## Responsibilities
 
 Composition only. Every behavior it exposes lives in the platform packages; this package chooses the default combination of them and gives it one name.
-
-## Dependencies
-
-`@prisma/orm-framework`, `@prisma/orm-family-mongo`, `@prisma/orm-target-mongo`, and `@prisma/orm-toolchain` at exact lockstep versions, plus `pathe`. `mongodb` is a peer dependency.

package/dist/contract-builder.d.mts

@@ -1,6 +1,7 @@
 import { ContractDefinition, ContractDefinition as ContractDefinition$1, ContractFactory, ContractFactory as ContractFactory$1, ContractScaffold, ContractScaffold as ContractScaffold$1, EnumMember, EnumTypeHandle, FieldBuilder, FieldReference, ModelBuilder, MongoContractResult, MongoContractResult as MongoContractResult$1, RelationBuilder, ValueObjectBuilder, field, index, member, model, rel, valueObject } from "@prisma/orm-family-mongo/contract-ts/contract-builder";
 import mongoFamilyPack from "@prisma/orm-family-mongo/family/pack";
 import mongoTargetPack from "@prisma/orm-target-mongo/target/pack";
+import "@prisma/orm-framework/contract/types";
 import "@prisma/orm-framework/components/authoring";
 import { ColumnTypeDescriptor } from "@prisma/orm-framework/components/codec";
 //#region ../../../3-extensions/mongo/dist/contract-builder.d.mts

package/dist/contract-builder.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"contract-builder.d.mts","names":[],"sources":["../../../../3-extensions/mongo/dist/contract-builder.d.mts"],"mappings":";;;;;;;KAMK,yBAAyB;KACzB,yBAAyB;KACzB,eAAe,WAAW,kBAAkB,sBAAsB,iCAAiC,iBAAiB;KACpH,uBAAuB,KAAK,qBAAqB,iBAAiB;WAC5D;WACA;;KAEN,qBAAqB,KAAK,mBAAmB,iBAAiB;WACxD;WACA;;iBAEM,qBAAqB,mBAAmB,sBAAsB,YAAY,aAAa,sBAAsB;WACnH,QAAQ;WACR,QAAQ;;iBAEF,qBAAqB,mBAAmB,0BAA0B;WACxE,SAAS;WACT,eAAe;WACf,QAAQ;GAChB,UAAU,YAAY,UAAU,SAAS,iBAAiB,QAAQ,sBAAsB,aAAa;WAC7F,QAAQ;WACR,QAAQ;;;;;;;;;;;;UAYT,aAAa,qBAAqB;WACjC,MAAM;WACN,OAAO;;KAEb,gBAAgB,yBAAyB,+CAA+C,WAAW,UAAU,QAAQ,WAAW,2BAA2B,KAAK;KAChK,eAAe,yBAAyB,+CAA+C,WAAW,UAAU,QAAQ,WAAW,mBAAmB,cAAc;KAChK,mBAAmB,yBAAyB,+CAA+C,KAAK,mBAAmB,YAAY;cACtH;;UAEJ,iBAAiB,8BAA8B,wDAAwD,qDAAqD,mBAAmB,0BAA0B;;YAEvM;;WAED,UAAU;;WAEV;;WAEA;;WAEA;aACE;aACA,OAAO;;;WAGT,QAAQ;;WAER,OAAO;;;;;WAKP,SAAS;;EAElB,IAAI,GAAG;;EAEP,OAAO,GAAG;;EAEV,UAAU,GAAG;;;;;;;;KAQV,eAAe;WACT;;;;;;;;KAQN,WAAW,mBAAmB,cAAc;WACtC;KACN,+BAA+B,aAAa,WAAW;WACjD,aAAa;IACpB;;;;;;;;KAQC,cAAc,mBAAmB,uBAAuB,2BAA2B,cAAc,KAAK,uDAAuD,0BAA0B,qBAAqB,WAAW,YAAY,YAAY,qBAAqB,WAAW,YAAY,YAAY,MAAM,MAAM,OAAO,UAAU,SAAS,YAAY,iBAAiB,MAAM,oBAAoB,WAAW,mBAAmB,WAAW,uBAAuB;;;;;;;;;;;;cAY3b,UAAU,2DAA2D"}
+{"version":3,"file":"contract-builder.d.mts","names":[],"sources":["../../../../3-extensions/mongo/dist/contract-builder.d.mts"],"mappings":";;;;;;;;KAOK,yBAAyB;KACzB,yBAAyB;KACzB,eAAe,WAAW,kBAAkB,sBAAsB,iCAAiC,iBAAiB;KACpH,uBAAuB,KAAK,qBAAqB,iBAAiB;WAC5D;WACA;;KAEN,qBAAqB,KAAK,mBAAmB,iBAAiB;WACxD;WACA;;iBAEM,qBAAqB,mBAAmB,sBAAsB,YAAY,aAAa,sBAAsB;WACnH,QAAQ;WACR,QAAQ;;iBAEF,qBAAqB,mBAAmB,0BAA0B;WACxE,SAAS;WACT,eAAe;WACf,QAAQ;GAChB,UAAU,YAAY,UAAU,SAAS,iBAAiB,QAAQ,sBAAsB,aAAa;WAC7F,QAAQ;WACR,QAAQ;;;;;;;;;;;;UAYT,aAAa,qBAAqB;WACjC,MAAM;WACN,OAAO;;KAEb,gBAAgB,yBAAyB,+CAA+C,WAAW,UAAU,QAAQ,WAAW,2BAA2B,KAAK;KAChK,eAAe,yBAAyB,+CAA+C,WAAW,UAAU,QAAQ,WAAW,mBAAmB,cAAc;KAChK,mBAAmB,yBAAyB,+CAA+C,KAAK,mBAAmB,YAAY;cACtH;;UAEJ,iBAAiB,8BAA8B,wDAAwD,qDAAqD,mBAAmB,0BAA0B;;YAEvM;;WAED,UAAU;;WAEV;;WAEA;;WAEA;aACE;aACA,OAAO;;;WAGT,QAAQ;;WAER,OAAO;;;;;WAKP,SAAS;;EAElB,IAAI,GAAG;;EAEP,OAAO,GAAG;;EAEV,UAAU,GAAG;;;;;;;;KAQV,eAAe;WACT;;;;;;;;KAQN,WAAW,mBAAmB,cAAc;WACtC;KACN,+BAA+B,aAAa,WAAW;WACjD,aAAa;IACpB;;;;;;;;KAQC,cAAc,mBAAmB,uBAAuB,2BAA2B,cAAc,KAAK,uDAAuD,0BAA0B,qBAAqB,WAAW,YAAY,YAAY,qBAAqB,WAAW,YAAY,YAAY,MAAM,MAAM,OAAO,UAAU,SAAS,YAAY,iBAAiB,MAAM,oBAAoB,WAAW,mBAAmB,WAAW,uBAAuB;;;;;;;;;;;;cAY3b,UAAU,2DAA2D"}

package/dist/utils__suppress-idle-connection-errors.d.mts

@@ -0,0 +1 @@
+export * from "@prisma/orm-framework/utils/suppress-idle-connection-errors";

package/dist/utils__suppress-idle-connection-errors.mjs

@@ -0,0 +1,2 @@
+export * from "@prisma/orm-framework/utils/suppress-idle-connection-errors";
+export {};

package/package.json

@@ -1,24 +1,25 @@
 {
   "name": "@prisma/orm-mongo",
-  "version": "8.0.0-rc.1-dev.46",
+  "version": "8.0.0-rc.10",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
-  "description": "Prisma Next for MongoDB: the one package a MongoDB application installs",
+  "description": "Prisma 8 for MongoDB: the one package a MongoDB application installs",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "dependencies": {
-    "@prisma/orm-family-mongo": "8.0.0-rc.1-dev.46",
-    "@prisma/orm-framework": "8.0.0-rc.1-dev.46",
-    "@prisma/orm-target-mongo": "8.0.0-rc.1-dev.46",
-    "@prisma/orm-toolchain": "8.0.0-rc.1-dev.46",
+    "@prisma/orm-family-mongo": "8.0.0-rc.10",
+    "@prisma/orm-framework": "8.0.0-rc.10",
+    "@prisma/orm-target-mongo": "8.0.0-rc.10",
+    "@prisma/orm-toolchain": "8.0.0-rc.10",
     "pathe": "^2.0.3"
   },
   "devDependencies": {
-    "@internal/mongo": "8.0.0-rc.1-dev.46",
-    "@repo/tsconfig": "8.0.0-rc.1-dev.46",
-    "@repo/tsdown": "8.0.0-rc.1-dev.46",
+    "@internal/mongo": "8.0.0-rc.10",
+    "@repo/tsconfig": "8.0.0-rc.10",
+    "@repo/tsdown": "8.0.0-rc.10",
     "tsdown": "0.22.14",
     "typescript": "5.9.3"
   },
@@ -112,6 +113,7 @@
     "./utils/result": "./dist/utils__result.mjs",
     "./utils/simplify-deep": "./dist/utils__simplify-deep.mjs",
     "./utils/structured-error": "./dist/utils__structured-error.mjs",
+    "./utils/suppress-idle-connection-errors": "./dist/utils__suppress-idle-connection-errors.mjs",
     "./utils/types": "./dist/utils__types.mjs",
     "./value": "./dist/value.mjs",
     "./value/mongodb-types": "./dist/value__mongodb-types.mjs",
@@ -120,12 +122,12 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/prisma/prisma.git",
+    "url": "https://github.com/prisma/orm.git",
     "directory": "packages/9-public/@prisma/orm-mongo"
   },
   "scripts": {
     "build": "tsdown",
     "lint": "biome check . --error-on-warnings",
-    "clean": "rm -rf dist src-gen"
+    "clean": "rm -rf dist src-gen skills"
   }
 }

package/skills/prisma-8/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: prisma-8
+description: >-
+  Use when working in a project that depends on @prisma/orm-postgres,
+  @prisma/orm-sqlite, or @prisma/orm-mongo (Prisma 8, formerly Prisma Next): editing
+  contract.prisma or a contract.ts builder, running `prisma contract emit`,
+  planning or applying migrations, editing migration.ts, writing db.orm /
+  db.sql / db.query queries, wiring db.ts or middleware, integrating a build
+  tool, using the Supabase extension or RLS, or reading a dotted error code
+  such as MIGRATION.HASH_MISMATCH. Use when the user asks "what is Prisma
+  8", "where do I start", or compares it to another ORM. Use when the user
+  asks to upgrade or bump Prisma 8 in an app or an extension package. Use when
+  you see @internal/* or @prisma/orm-* imports, prisma.config.ts with
+  definePrismaConfig, or contract.json / contract.d.ts. Do not use for Prisma
+  ORM 7 or earlier (schema.prisma + @prisma/client).
+metadata:
+  library: '@prisma/orm-mongo'
+  library_version: '8.0.0-rc.10'
+  version: '2026-09-12'
+---
+
+# Prisma 8 (Prisma 8)
+
+> **Edit your data contract. Prisma handles the rest.**
+
+Prisma 8 moves fast, and your training data about it is very likely outdated. This skill ships inside the installed Prisma packages, so it describes the exact version this project has — treat it and its reference files as the source of truth, over anything you remember about Prisma.
+
+## Pre-conditions
+
+Check these before acting on anything below. Halt on the first one that fails and tell the user what is missing.
+
+1. **The project is on Prisma 8.** `prisma.config.ts` exports `definePrismaConfig({ orm: ... })`, and `package.json` depends on `@prisma/orm-postgres`, `@prisma/orm-sqlite`, or `@prisma/orm-mongo`. A project with `schema.prisma` and `@prisma/client` is Prisma 7 or earlier; this skill does not apply to it, and its instructions will break such a project.
+2. **The skill matches the installed version.** Compare `metadata.library_version` in this file's frontmatter with the installed `@prisma/orm-*` version in `package.json`. If they differ, run `prisma skills sync` and re-read this file before continuing.
+3. **The contract artefacts exist.** `contract.json` and `contract.d.ts` sit next to the contract source named by `prisma.config.ts`. If they are missing or older than the source, run `prisma contract emit` first; every query and migration instruction below assumes current artefacts.
+
+**Import paths in the references.** The reference files spell façade imports as `@internal/<target>/<subpath>` and `@internal/extension-<name>/<subpath>`. In an application those packages are published as `@prisma/orm-<target>/<subpath>` (`@prisma/orm-postgres/runtime`, `@prisma/orm-mongo/config`, `@prisma/orm-sqlite/runtime`) and `@prisma/orm-extension-<name>/<subpath>` (`@prisma/orm-extension-pgvector/control`). Write the `@prisma/orm-*` name in user code; the two spellings are the same package. Paths already written as `@prisma/orm-*` in the references are exact. The `metadata.library_version` in this file's frontmatter is the version it was published with; if it does not match the project's installed Prisma packages, run `prisma skills sync` and re-read.
+
+Prisma 8 is a contract-first data layer. This skill routes every Prisma 8 task to the right reference file — open the reference before writing code; do not answer from this file alone.
+
+## The canonical model (one paragraph)
+
+You author a **data contract** (a `contract.prisma` file, or a TypeScript builder). The framework emits machine-readable artifacts (`contract.json`, `contract.d.ts`) and gives you two runtime surfaces on SQL targets: a typed SQL query builder (`db.sql.<ns>.<table>`) and a typed ORM client (`db.orm.<ns>.<Model>`). On MongoDB targets only the ORM lane exists, and its keys are collection storage names (`db.orm.users`) rather than PSL model names — [`references/queries.md`](references/queries.md) § *MongoDB ORM addressing* covers the rule. Migrations are planned from the contract diff; you review them, optionally edit the `migration.ts` for data transforms, and apply.
+
+Three steps the user does:
+
+1. **Edit your data contract.** ([`references/contract.md`](references/contract.md))
+2. **The system plans the migrations for you.** ([`references/migrations.md`](references/migrations.md))
+3. **If you need data migrations, you edit `migration.ts` and execute it.** ([`references/migrations.md`](references/migrations.md))
+
+Everything else — queries, runtime wiring, build integration, debugging, feedback — sits on top of those three.
+
+One cross-cutting migration fact: `migration plan` does **not** chain from the newest migration on disk. Its origin is `--from`, else the `db` ref, else an empty database — so a project with no ref keeps planning from scratch. Over existing migrations the CLI refuses that (`MIGRATION.PLAN_ORIGIN_UNKNOWN`) instead of writing a full-create package; choose the exit that matches your intent rather than reflexively passing `--from @empty`. [`references/migration-model.md`](references/migration-model.md) § *The trap* explains which to choose.
+
+## Routing table
+
+Open the reference whose triggers match the task. If more than one matches, open each — they are written to compose.
+
+| Task | Reference | Triggers |
+| --- | --- | --- |
+| Adopt / set up / first steps | [`references/quickstart.md`](references/quickstart.md) | new project, existing database, "what can I do with Prisma 8", "where do I start", "just ran createprisma", `npx create-prisma`, first steps, first query, `prisma orm init` greenfield setup, `contract infer` + `db sign` brownfield adoption, connect-write-read first arc, day-to-day commands (`contract emit`, `db init`, `db update`, `migration plan`, `db migrate`, `db schema`, `db verify`), flags `--target` / `--authoring` / `--schema-path` / `--probe-db` / `--output` |
+| Edit the data contract | [`references/contract.md`](references/contract.md) | schema, models, fields, attributes, relations, indexes, enums, value objects (composite types), type aliases, namespaces (Postgres schemas), cross-contract foreign keys (cross-space FK), polymorphic types (`@@discriminator` / `@@base`), extension namespaces (`pgvector.Vector(...)`, `postgis.Geometry(...)`), `prisma.config.ts` / `definePrismaConfig` / `ormConfig`, `prisma contract emit`, PSL, `contract.prisma`, `contract.ts`, `contract.json`, `contract.d.ts`, `@internal/postgres/config`, `@internal/postgres/contract-builder`, `@internal/mongo/config`, `extensions:`, pgvector, postgis, paradedb, Temporal / `temporal-polyfill` / `RUNTIME.TEMPORAL_UNAVAILABLE`, `@@control`, control policy (managed / tolerated / external / observed), soft delete, validations, callbacks |
+| Author migrations | [`references/migrations.md`](references/migrations.md) | `db update` vs `migration plan`, `db migrate`, `migration new`, `migration show`, `db update --dry-run`, `db verify`, `db sign`, data migration, `dataTransform`, placeholder sentinels in framework-rendered `migration.ts`, `MIGRATION.HASH_MISMATCH`, `MIGRATION.UNFILLED_PLACEHOLDER`, `MIGRATION.DESTRUCTIVE_CHANGES` / `--confirm <database>`, schema drift |
+| Migration graph, refs, plan origin | [`references/migration-model.md`](references/migration-model.md) | migration graph, refs, `migration ref set` / `list` / `delete`, the `db` ref, `--advance-ref`, `--no-advance-ref`, `migration plan --from`, `from: (baseline)` in plan output, greenfield / from-scratch plan, baseline, first migration before deploy (Composer / CD-managed databases), chaining migrations, retrofitting migrations onto an existing database, `MIGRATION.HASH_NOT_IN_GRAPH`, `MIGRATION.PATH_UNREACHABLE` at plan/chain time |
+| Review migrations on deploy | [`references/migration-review.md`](references/migration-review.md) | "what migrations are going to run", "what runs on deploy / merge", merge conflict, diamond convergence, concurrent migrations, migration status, ref management for CI, staging / production environment refs, `MIGRATION.MARKER_NOT_IN_HISTORY`, `MIGRATION.MISSING_INVARIANTS`, `MIGRATION.AMBIGUOUS_TARGET`, `db migrate --show` |
+| Write queries | [`references/queries.md`](references/queries.md) | query, where, select, project, orderBy, limit, offset, take, skip, include, lookup, first, all, count, aggregate, groupBy, create, update, delete, upsert, returning, transaction, `db.orm`, `db.sql`, `runtime.query(plan)` vs `runtime.execute(plan)`, `db.prepare` / prepared statements, streaming / `for await`, many-to-many `include` and nested `connect`, `and` / `or` / `not` from `@prisma/orm-postgres/orm-client`, `db.query.from(...)` (Mongo pipeline), namespace-aware accessors, `.all()` Thenable, single-use iterators (`RUNTIME.ITERATOR_CONSUMED`), target-declared aggregate types (`count`, integer `sum`, and integer `avg` are `number`; `count` and integer `sum` throw outside ±(2^53 − 1) rather than round, while `avg` is a fraction already and carries no guard; `countBigInt` / `sumBigInt` / `avgDecimal` are the lossless forms, `avgDecimal` on PostgreSQL only), drizzle-style, kysely-style. Naming types (§ *Naming model and result types*): "type of my model", "return type of a query", `ResultType`, `Scalars`, `Shape`, `models` / `Models` namespace in `contract.d.ts`, `Models.public_User`, Prisma 7 `Prisma.User` / `GetPayload` / `UserGetPayload` equivalents. Postgres/SQLite specifics: [`references/queries-postgres.md`](references/queries-postgres.md); Mongo specifics: [`references/queries-mongo.md`](references/queries-mongo.md) |
+| Wire the runtime | [`references/runtime.md`](references/runtime.md) | `db.ts`, `postgres<Contract>(...)` / `sqlite<Contract>(...)` / `mongo<Contract>(...)` façades, middleware composition (lints, budgets, cache via `@prisma/orm-extension-middleware-cache`, custom `afterQuery` middleware, `@prisma/orm-postgres/family-runtime`), `DATABASE_URL`, `.env`, connection pool / `poolOptions`, dev vs prod config, transactions, read replicas, multi-database, script won't exit / hangs, `db.close` / `pool.end`, `await using` / `[Symbol.asyncDispose]` |
+| Build-tool integration | [`references/build.md`](references/build.md) | Vite plugin (`@internal/vite-plugin-contract-emit`, Vite 7/8), `vite.config.ts`, contract emit on save, HMR / dev server, Next.js / Webpack / esbuild / Rollup / Turbopack (named gaps, not fabricated) |
+| Supabase | [`references/supabase.md`](references/supabase.md) | `@internal/extension-supabase`, RLS, row level security, policies (`policy_select` / `policy_update` / `@@rls`, `auth.uid()`), role binding (`asUser(jwt)` / `asAnon()` / `asServiceRole()`), `auth.users`, cross-space FKs to `supabase:auth.AuthUser`, JWT / JWKS (`SUPABASE_JWKS_URL`, `SUPABASE_JWT_SECRET`), `SUPABASE.JWT_INVALID`, `SUPABASE.CONFIG_INVALID`, `RoleBoundDb`, session pooler |
+| Debug an error | [`references/debug.md`](references/debug.md) | any structured error envelope (code, severity, why, fix, nextActions, meta), emit failed, query won't typecheck, query crashed, migration won't apply, `MIGRATION.HASH_MISMATCH`, `MIGRATION.RUNNER_FAILED`, `BUDGET.ROWS_EXCEEDED`, `BUDGET.TIME_EXCEEDED`, `RUNTIME.ABORTED`, `RUNTIME.TEMPORAL_UNAVAILABLE`, `PLAN.HASH_MISMATCH`, `CONTRACT.MARKER_MISSING`, `CONFIG.*` / `CLI.*` / `CONTRACT.*` / `MIGRATION.*` / `ORM.*` / `RUNTIME.*` codes, legacy `PN-*` codes, exit code 4 findings, drift, capability missing, planner conflict, EXPLAIN, query log, script won't exit / close connection |
+| Upgrade Prisma in an app | [`references/upgrade-app.md`](references/upgrade-app.md) | "upgrade Prisma", "upgrade Prisma 8", "bump Prisma 8", "move to Prisma 8 X.Y", `@internal/*` version bump in an application, per-transition upgrade instructions in [`upgrading/app/upgrades/`](upgrading/app/upgrades/), extension-pin pre-flight, `PN-UPGRADE-*` |
+| Upgrade Prisma in an extension | [`references/upgrade-extension.md`](references/upgrade-extension.md) | the same request in a package that *is* a Prisma extension (`@internal/contract` / SPI dependency, `^@.*/extension-` name), `prisma-8-check-pins`, exact-pin rule, per-transition instructions in [`upgrading/extension/upgrades/`](upgrading/extension/upgrades/) |
+| File feedback / ask the team | [`references/feedback.md`](references/feedback.md) | bug report, file an issue, feature request, missing feature, capability gap, "this is broken", surprising behaviour, Q&A / design discussion, ask the Prisma team, Prisma Discord (pris.ly/discord), extension-author questions |
+
+## Routing rules
+
+If the task clearly matches a row, open that reference directly without asking.
+
+For a vague prompt, ask **one** disambiguating question. Pick from:
+
+- *"Are you new to Prisma 8 and asking what you can do with it, or where to start?"* → [`references/quickstart.md`](references/quickstart.md) (first-touch orientation path).
+- *"Do you want to set up a new Prisma 8 project, or wire it into an existing database?"* → [`references/quickstart.md`](references/quickstart.md).
+- *"Do you want to edit your data contract (add a model / field / relation), or work with the database (migrations, queries)?"* → [`references/contract.md`](references/contract.md) vs the others.
+- *"Is this about authoring a migration, or about reviewing what's going to run on deploy?"* → [`references/migrations.md`](references/migrations.md) vs [`references/migration-review.md`](references/migration-review.md). If it's about where a plan starts, refs, or an unexpected from-scratch plan → [`references/migration-model.md`](references/migration-model.md).
+- *"Is this about wiring Prisma 8 into your build tool (Vite / Next.js / …), or about wiring `db.ts` and middleware at runtime?"* → [`references/build.md`](references/build.md) vs [`references/runtime.md`](references/runtime.md).
+- *"What error or symptom are you seeing?"* → [`references/debug.md`](references/debug.md).
+- *"Do you want to report this as a bug to the Prisma 8 team, or is this a feature request?"* → [`references/feedback.md`](references/feedback.md).
+- *"Is the project you want to upgrade an application, or a Prisma extension package?"* → [`references/upgrade-app.md`](references/upgrade-app.md) vs [`references/upgrade-extension.md`](references/upgrade-extension.md).
+
+If you still can't tell which reference applies, ask the user what they want to do. Do not guess.
+
+## Checklist
+
+- [ ] If the task matches a routing-table row, open that reference before writing code.
+- [ ] If the prompt is vague, ask one disambiguating question.
+- [ ] Do not attempt to answer from this file alone — the references carry the verified tool surface.
+- [ ] If the user describes a missing feature or a misbehaviour they want fixed, open [`references/feedback.md`](references/feedback.md).

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

@@ -0,0 +1,142 @@
+
+# Prisma 8 — Build-System Integration
+
+> **Edit your data contract. Prisma handles the rest.**
+
+This skill covers Prisma 8's build-tool plugins — the dev-server / build-system integrations that re-emit contract artifacts automatically as the user edits the contract source. Today that's [`@internal/vite-plugin-contract-emit`](https://github.com/prisma/prisma/blob/main/packages/1-framework/3-tooling/vite-plugin-contract-emit/README.md) for Vite 7 and Vite 8. Next.js, Webpack, esbuild, Rollup, and Turbopack plugins are documented under *What Prisma 8 doesn't do yet* with the workaround.
+
+**If the project is using Vite and consuming the contract, install the plugin.** There's no good reason not to — manual `prisma contract emit` during dev is friction the plugin eliminates. The agent should proactively offer the plugin whenever it sees a `vite.config.ts` in the project; the user doesn't need to ask.
+
+## When to Use
+
+- The project is using Vite (the agent sees a `vite.config.ts` or `@vitejs/*` deps) and the contract is being consumed at runtime — proactively offer the plugin.
+- User asks how to wire Prisma 8 into their Vite project.
+- User asks about Next.js integration, Webpack integration, or any other bundler — the answer is *"not yet, here's the workaround"* and the skill walks them through it.
+- User mentions: *vite plugin, vite-plugin, vite.config.ts, prismaVitePlugin, contract emit on save, HMR, hot reload contract, dev server, vite 7, vite 8*.
+- User mentions Next.js / Webpack / esbuild / Rollup / Turbopack in the context of Prisma 8 integration — the gap-listing path fires.
+
+## When Not to Use
+
+- User wants to wire `db.ts` and middleware → `references/runtime.md`.
+- User wants to file a feature request for an unbuilt bundler plugin → `references/feedback.md`.
+
+## Key Concepts
+
+- **The plugin's job is `contract emit`, on a schedule the bundler knows about.** It is *not* a runtime concern — at runtime, the application reads `contract.json` / `contract.d.ts` the same way whether the plugin emitted them or a script did. The plugin saves you the manual command during development.
+- **Vite 7 and Vite 8 only.** Peer range `^7.0.0 || ^8.0.0`. Vite 6 is not on the support matrix.
+- **`executeContractEmit` is the canonical publish path.** Custom plugins for other bundlers must also call it — never re-implement the load → emit → publish dance. The atomic-rename invariant (`contract.d.ts` renamed before `contract.json`) and the per-output FIFO queue live in `@internal/cli/control-api`.
+- **No build-time / production emission.** The Vite plugin runs in `vite dev` only. For `vite build` / production, run `prisma contract emit` from a `prebuild` script.
+
+## Workflow — Vite (the supported path)
+
+### 1. Install the plugin
+
+```bash
+pnpm add -D @internal/vite-plugin-contract-emit
+```
+
+(Or `npm install --save-dev`, `yarn add -D`, `bun add -d` — use what the project's package manager is.)
+
+### 2. Wire `vite.config.ts`
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { prismaVitePlugin } from '@internal/vite-plugin-contract-emit';
+
+export default defineConfig({
+  plugins: [prismaVitePlugin('prisma.config.ts')],
+});
+```
+
+The argument is the **path to `prisma.config.ts` relative to Vite root**. Not the path to `schema.psl` or `contract.ts` — the plugin reads the config to discover the contract source.
+
+### 3. Configure (optional)
+
+```typescript
+plugins: [
+  prismaVitePlugin('prisma.config.ts', {
+    debounceMs: 150,           // delay before re-emitting (default 150)
+    logLevel: 'info',          // 'silent' | 'info' | 'debug' (default 'info')
+  }),
+],
+```
+
+Set `logLevel: 'debug'` only while troubleshooting; default `'info'` in committed config so the dev server isn't noisy.
+
+### 4. Verify the dev loop
+
+1. Start `vite dev`.
+2. Watch for the success log: `[prisma] emitted contract.d.ts + contract.json`.
+3. Edit `prisma/schema.psl` (e.g. add a field to a model).
+4. Within ~150ms (the debounce), watch for a re-emit log line.
+5. Type-check your application code that uses the new field — should pass without restarting the dev server.
+
+If the plugin warns about *config-only watching*, see [Common Pitfalls](#common-pitfalls).
+
+### 5. CI / production builds
+
+The plugin does **not** run during `vite build`. For CI and production deploys, run `prisma contract emit` as a prebuild step:
+
+```json
+// package.json
+{
+  "scripts": {
+    "prebuild": "prisma contract emit",
+    "build": "vite build"
+  }
+}
+```
+
+`pnpm build` then runs `prebuild` automatically before `build`.
+
+## Workflow — React Router v7 Framework Mode
+
+The Vite plugin is compatible with `@react-router/dev/vite`. Both plugins are listed in `vite.config.ts`; there's no ordering constraint between them today, and the Prisma 8 plugin's re-emit fires alongside React Router's own SSR re-load.
+
+```typescript
+import { reactRouter } from '@react-router/dev/vite';
+import { prismaVitePlugin } from '@internal/vite-plugin-contract-emit';
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+    prismaVitePlugin('prisma.config.ts'),
+  ],
+});
+```
+
+See [`examples/react-router-demo`](https://github.com/prisma/prisma/tree/main/examples/react-router-demo) for the canonical configuration plus a smoke test that proves the dev loop.
+
+## Common Pitfalls
+
+1. **Pointing the plugin at `schema.psl` instead of `prisma.config.ts`.** The argument is the config path. The plugin reads the config to find the contract source.
+2. **Vite 6 or earlier.** Not supported. Upgrade Vite to 7 or 8.
+3. **The plugin warns: *"watching only the config; loader resolved inputs unavailable."*** The plugin couldn't resolve `contract.source.inputs` from the loader. The fallback watches only `prisma.config.ts` itself, so contract edits won't re-emit. Causes: the config file throws during loading; the contract source path resolves outside the Vite root. Fix the config error first, then check that the contract source path in the config is relative to (or inside) the Vite root.
+4. **Expecting `vite build` to re-emit.** It doesn't. Add a `prebuild` script.
+5. **Emit errors during dev**: the plugin surfaces them via Vite's error overlay. Read the overlay; the underlying cause is a contract authoring problem — chain to `references/debug.md` for resolution (PSL syntax, missing namespace, conflicting extensions).
+6. **Re-installing dependencies without the plugin's peer-range move.** When PN bumps the plugin's peer range, you must re-run `pnpm install` so the lockfile picks up the new range. A stale lockfile keeps the old plugin and produces confusing version mismatch warnings.
+
+## What Prisma 8 doesn't do yet
+
+- **Next.js plugin.** No first-party `@internal/next-plugin-*` exists. Workaround: run `prisma contract emit` from a `prebuild` script in `package.json` and run it manually during development when the contract changes. Many Next.js projects also run a dev-time `tsx --watch` against a small script that calls the CLI on contract-source change. If you want a first-party Next.js plugin, file a feature request via the `references/feedback.md` skill.
+- **Webpack, esbuild, Rollup, Turbopack plugins.** None exist yet as first-party. Workaround: the canonical `executeContractEmit` surface lives in `@internal/cli/control-api` — a small per-bundler plugin can call it from the bundler's prebuild hook, but PN doesn't ship one for you. The `vite-plugin-contract-emit` source is the reference implementation if you want to write one yourself. If you want a first-party plugin for your bundler, file a feature request via the `references/feedback.md` skill.
+- **`vite build` integration.** The plugin runs in `vite dev` only. Workaround: a `prebuild` script that runs `prisma contract emit`. If you want the plugin to also run during `vite build`, file a feature request via the `references/feedback.md` skill.
+- **Vite 6 or earlier.** Not on the support matrix. Workaround: upgrade Vite to 7 or 8. If you have a hard reason to stay on Vite 6, file a feature request via the `references/feedback.md` skill.
+
+## Reference Files
+
+- The plugin's own README: <https://github.com/prisma/prisma/blob/main/packages/1-framework/3-tooling/vite-plugin-contract-emit/README.md> — support matrix, full API surface, architecture diagram, the *canonical publish path* warning for custom plugin authors.
+- ADR 008 (Dev Auto-Emit, CI Explicit Emit) — the rationale for splitting dev-time auto-emit from the explicit CI / build step.
+- ADR 032 (Dev Auto-Emit Integration) — the plugin's integration contract with the CLI control API.
+
+## Checklist
+
+- [ ] Plugin pointed at `prisma.config.ts` (not the contract source).
+- [ ] Vite version 7 or 8 (`pnpm ls vite`).
+- [ ] `vite dev` log shows the initial emit on server start.
+- [ ] Editing the contract source triggers a re-emit log line.
+- [ ] `prebuild` script (or equivalent) runs `prisma contract emit` for CI / production builds.
+- [ ] No `vite build` expectation that the plugin will run.
+- [ ] For non-Vite bundlers: surfaced the *What PN doesn't do yet* entry and routed the user to `references/feedback.md` if they want first-party support.
+- [ ] Did NOT confabulate a `@internal/next-plugin-contract-emit` package or any other bundler-specific plugin that doesn't exist.