wip

.agents/skills/prisma-mongodb-upgrade/references/client-api-mapping.md

@@ -0,0 +1,61 @@
+# client-api-mapping
+
+How v6 Prisma Client calls map to Prisma Next's Mongo client — names map, parity does not.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+The v6 and Next client APIs look superficially similar, but none of the v6 MongoDB raw
+methods exist under their old names, aggregation moved to a different lane entirely, and
+transactions go through the driver rather than a façade wrapper. Assuming parity produces
+code that does not compile — or, in the transactions case, code that silently loses
+atomicity.
+
+## The mapping
+
+| v6 call | Prisma Next equivalent | Notes |
+|---------|------------------------|-------|
+| `prisma.user.findMany(...)` | `db.orm.users.where(...).all()` | Fluent ORM lane; storage-name keys (see `schema-contract-mapping.md`) |
+| `prisma.user.findFirst(...)` | `db.orm.users.where(...).first()` | |
+| `create` / `update` / `upsert` / `delete` / `updateMany` / `deleteMany` | `create` / `update` / `upsert` / `delete` / `updateAll` / `deleteAll` on `db.orm.<collection>` | See Prisma Next's `prisma-next-queries` skill |
+| `prisma.user.aggregate(...)`, `groupBy(...)` | **No ORM equivalent.** Use the typed aggregation-pipeline builder: `db.query.from(...).match(...).group(...).build()` | Prisma Next's `prisma-next-queries` skill covers the builder lane |
+| `$runCommandRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#runcommandraw)) | **Name does not exist in Next.** Raw lane is `mongoRaw(...)` → a raw collection with `aggregate`, `insertOne/Many`, `updateOne/Many`, `deleteOne/Many`, `findOneAndUpdate/Delete`. For arbitrary database commands, use the underlying `mongodb` driver directly — it is a user-supplied peer dependency and fully accessible | Check the installed version's raw surface |
+| `<model>.findRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#findraw)) | `mongoRaw(...)` collection reads (e.g. `aggregate` with a `$match` stage) | No direct `findRaw` name |
+| `<model>.aggregateRaw(...)` ([v6 docs](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#aggregateraw)) | `mongoRaw(...).aggregate(...)` or the typed pipeline builder | |
+| `$transaction(...)` — works on v6 with a replica set ([v6 docs](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)) | The façade does not wrap `db.transaction(...)` yet, **but the underlying `mongodb` driver is directly available** (user-supplied peer dependency): multi-document atomicity works today via driver sessions (`client.startSession()` / `session.withTransaction(...)`) on a replica set | A façade wrapper is expected soon; this row will be updated when it merges |
+| `$connect` / `$disconnect` | `connect()` / `close()` on the Mongo façade client | |
+
+## Bad
+
+```typescript
+// Assuming v6 names exist in Prisma Next:
+await db.user.$runCommandRaw({ collStats: 'users' }); // no such method
+await db.transaction(async (tx) => { ... });          // no such method on the Mongo façade
+```
+
+## Good
+
+```typescript
+// Raw lane under its Next name:
+const raw = mongoRaw(db);
+await raw.users.aggregate([{ $match: { status: 'active' } }]);
+
+// Aggregation through the typed pipeline builder:
+const stats = await db.query.from('users').group({ _id: '$role', n: { $count: {} } }).build();
+
+// Multi-document atomicity today: the mongodb driver (a direct dependency of the
+// project) exposes sessions and transactions as usual:
+const session = mongoClient.startSession();
+await session.withTransaction(async () => {
+  // ...writes...
+});
+```
+
+## References
+
+- [v6 MongoDB raw queries](https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries#raw-queries-with-mongodb)
+- [v6 replica set requirement for transactions](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)
+- Prisma Next queries + runtime skills (`skills/prisma-next-queries`, incl. its dedicated `mongo.md`; `skills/prisma-next-runtime`) — authoritative for the Next side; verified @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`

.agents/skills/prisma-mongodb-upgrade/references/decision-stay-or-migrate.md

@@ -0,0 +1,87 @@
+# decision-stay-or-migrate
+
+How to decide between migrating a MongoDB project to Prisma Next and staying on Prisma v6.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+MongoDB projects cannot follow the general "upgrade Prisma" advice: Prisma 7 has no MongoDB
+connector, so the forward path is Prisma Next. Advising an impossible v7 upgrade, or
+silently rewriting the app onto SQL, are both serious failure modes. The encouraged path is
+migrating to Prisma Next — its MongoDB support is Early Access and the Prisma team wants
+early adopters' feedback — with a deliberate stay on v6 where a hard blocker applies.
+
+## The facts the decision rests on
+
+Prisma Next side (verified against prisma/prisma-next @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`;
+status confirmed by the Prisma team 2026-07):
+
+- **MongoDB support is Early Access**, actively developed, with GA planned after Postgres.
+- The implementation is deep, not a stub: a full package family (ORM, typed
+  aggregation-pipeline builder, raw lane, driver over the official `mongodb` package),
+  first-class contract-driven migrations, and extensive tests against real in-memory MongoDB.
+- **The Mongo client façade does not wrap `db.transaction(...)` yet** — multi-document
+  atomicity is done through the MongoDB driver's session API, which is directly available
+  (the `mongodb` package is a user-supplied peer dependency). A façade wrapper is expected;
+  this skill will be updated when it merges.
+- Early Access means pre-1.0 minors can carry breaking changes, with published upgrade
+  recipes (e.g. 0.11→0.12 changed Mongo validator emission and made `mongodb` a
+  user-supplied peer dependency). Floor: MongoDB 8.0 and `mongodb@^7`.
+
+Prisma v6 side:
+
+- v6 fully supports MongoDB, including transactions on replica sets — "MongoDB only allows
+  you to start a transaction on a replica set. Prisma ORM uses transactions internally"
+  ([replica set configuration](https://www.prisma.io/docs/orm/overview/databases/mongodb#replica-set-configuration)).
+- v6 MongoDB has no Prisma Migrate; the workflow is `db push`
+  ([no support for Prisma Migrate](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate)).
+
+## Blocker checks before migrating
+
+Run these checks yourself — from the codebase, not by asking the user:
+
+- **Search the codebase for `$transaction` usage** (grep for `$transaction`). If present,
+  plan the raw-driver session equivalents before migrating (see `client-api-mapping.md`) —
+  or stay on v6 until the façade wrapper lands.
+- **Check the MongoDB server version** (must be 8.0+ for Next; v6 tolerated older).
+- **Confirm the team can absorb pre-1.0 upgrades.** Next publishes versioned upgrade recipes
+  between minors; someone has to run them. For a production app, confirm the user accepts
+  Early Access status before migrating.
+
+## Bad
+
+```text
+User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?"
+Agent: "Yes — here's the v7 upgrade guide. Step 1: install a driver adapter..."
+```
+
+Prisma 7 has no MongoDB connector; this migration is impossible and the SQL driver-adapter
+steps corrupt a working v6 setup.
+
+## Good
+
+```text
+User: "We're on Prisma 6 with MongoDB. Should we upgrade to Prisma 7?"
+Agent: "Prisma 7 does not support MongoDB — v6 is the last classic-ORM
+major for MongoDB. The path forward is Prisma Next, the successor: its MongoDB support is
+Early Access and migrating is encouraged. Let me check the codebase for blockers first —
+searching for $transaction usage and checking the MongoDB server version..."
+```
+
+## Stay-on-v6 hygiene
+
+Staying is a decision, not a default-by-neglect:
+
+- Pin `prisma` and `@prisma/client` to the latest 6.x and keep taking 6.x patches.
+- Watch Prisma release notes and security advisories for the 6.x maintenance line.
+- Keep the classic setup (`url = env("DATABASE_URL")` in the schema; `db push`; no SQL
+  driver adapters).
+- Re-evaluate when Prisma Next's MongoDB is GA, or when blockers for trying EA are resolved.
+
+## References
+
+- [Prisma Next repository](https://github.com/prisma/prisma-next)
+- [Prisma v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb)

.agents/skills/prisma-mongodb-upgrade/references/migrations-mapping.md

@@ -0,0 +1,65 @@
+# migrations-mapping
+
+How the v6 MongoDB "no migrations" story maps onto Prisma Next's first-class migration flow.
+
+## Priority
+
+HIGH
+
+## Why It Matters
+
+This is the largest workflow change in the migration — in v6, MongoDB explicitly has no
+Prisma Migrate, while in Prisma Next MongoDB participates in the full migration lifecycle.
+Teams porting a `db push` habit into Next without understanding the plan/verify/sign flow
+will fight the tooling or bypass its safety rails.
+
+## v6: `db push` only
+
+MongoDB on v6 has no Prisma Migrate and no plans to add it — "MongoDB projects do not rely
+on internal schemas" ([no support for Prisma Migrate](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate)).
+The workflow is `prisma db push` to sync indexes and unique constraints, with no migration
+history on disk.
+
+## Prisma Next: first-class, contract-driven migrations (Mongo included)
+
+Migration authoring in Next is first-class for Postgres **and Mongo** (prisma-next
+`skills/prisma-next-migrations/SKILL.md`) — MongoDB is not a push-only special case:
+
+- **Flow:** contract *emit* → diff → *plan* (writes a content-hashed migration package) →
+  *migrate* (apply in graph order) → *verify* (live schema vs destination contract) →
+  *sign* (advance the marker after a verify pass).
+- **Mongo migration ops** come from dedicated factories: `createCollection`,
+  `dropCollection`, `validatedCollection`, `setValidation`, `createIndex`, `dropIndex`,
+  `collMod`, and `dataTransform` for data backfills.
+- **Marker storage:** Next records migration state in a document in the
+  `_prisma_migrations` collection (per space) — the same collection name family v6 users
+  know from SQL, repurposed for Mongo state.
+- **DDL is not transactional on Mongo:** the runner applies operations, verifies the live
+  schema against the destination contract, and only advances the marker on a verify pass —
+  making interrupted runs resumable rather than atomic (see Prisma Next's
+  `prisma-next-migrations` skill).
+- **Push-style alternative still exists:** `db update` diffs the live database against the
+  contract and applies directly without writing a migration directory — the closest
+  analogue to the v6 `db push` habit, at the cost of no history.
+- Validators: Next emits closed `$jsonSchema` validators by default since 0.12 (prisma-next
+  `CHANGELOG.md`) — collections gain schema enforcement v6 never applied.
+
+## Bad
+
+```text
+Porting the v6 habit: run the Next equivalent of `db push` for every change in production,
+accumulating no migration history, and hand-editing collections when verification fails.
+```
+
+## Good
+
+```text
+Adopt the Next lifecycle: emit the contract, plan a migration package, apply it with
+migrate, let verify gate the marker, and sign. Reserve `db update` for local prototyping,
+mirroring how `db push` was used on v6.
+```
+
+## References
+
+- [v6: no Prisma Migrate for MongoDB](https://www.prisma.io/docs/orm/overview/databases/mongodb#no-support-for-prisma-migrate)
+- Prisma Next migrations skill (`skills/prisma-next-migrations`) — authoritative for the Next side; verified @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`

.agents/skills/prisma-mongodb-upgrade/references/schema-contract-mapping.md

@@ -0,0 +1,52 @@
+# schema-contract-mapping
+
+How v6 MongoDB schema concepts map onto Prisma Next's contract model.
+
+## Priority
+
+HIGH
+
+## Why It Matters
+
+Prisma Next does not consume the v6 `schema.prisma` as-is: the schema becomes a *contract*
+(authored in PSL or TypeScript via the contract builder), and several v6 MongoDB idioms have
+different — or deliberately absent — equivalents. Translating mechanically without knowing
+the mapping produces contracts that fail verification or, worse, silently change collection
+addressing.
+
+## The mapping
+
+| v6 concept | Prisma Next equivalent | Notes |
+|------------|------------------------|-------|
+| `datasource db { provider = "mongodb" }` + `url = env(...)` ([v6 docs](https://www.prisma.io/docs/orm/overview/databases/mongodb#example)) | `defineConfig` from `@prisma-next/mongo/config` wiring the mongo family/target/adapter/driver descriptors | Next selects MongoDB by importing the `@prisma-next/mongo` façade, not by a provider string in the schema; `prisma-next init` accepts `mongodb` as a target name |
+| `@id @default(auto()) @map("_id") @db.ObjectId` ([using ObjectId](https://www.prisma.io/docs/orm/overview/databases/mongodb#using-objectid)) | ObjectId-typed id field in the Next contract (PSL or TS builder) | Verify the exact attribute surface against the installed Next version's `prisma-next-contract` skill — the contract builder also exposes `index` and `valueObject` |
+| Composite (embedded) types — MongoDB-only in v6 ([composite types](https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/composite-types)) | Value objects / embedded shapes in the Next contract (`valueObject` in the Mongo contract builder) | Same conceptual role: documents embedded in a parent document |
+| Model names address the client (`prisma.user`) | **Collection storage names** address the ORM: `db.orm.users`, i.e. the `@@map(...)` name or the lowercased model name — not `db.orm.User` | prisma-next `skills/prisma-next/SKILL.md`, `skills/prisma-next-quickstart/SKILL.md`; the most common porting mistake |
+| Indexes declared in schema, applied by `db push` | Indexes are contract-declared and applied through migrations (`createIndex`/`dropIndex` factories) | See `migrations-mapping.md` |
+| No native polymorphism | No schema-layer polymorphism on Mongo either: `@@base`/`@@discriminator` are SQL-only in Next; model an explicit `discriminator` field | prisma-next `skills/prisma-next-contract/SKILL.md` |
+
+## Bad
+
+```typescript
+// Ported from v6 and addressed by model name:
+const user = await db.orm.User.first(); // undefined — Mongo ORM keys are storage names
+```
+
+## Good
+
+```typescript
+// Mongo ORM keys are collection storage names (@@map or lowercased model name):
+const user = await db.orm.users.first();
+```
+
+## Environment requirements
+
+Prisma Next's Mongo target requires MongoDB 8.0+ and `mongodb@^7` installed by the user as a
+peer dependency (prisma-next `CHANGELOG.md`, 0.11→0.12). v6 supports older MongoDB servers,
+so check the server version before planning a migration.
+
+## References
+
+- [v6 MongoDB schema documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb)
+- [v6 composite types (MongoDB-only)](https://www.prisma.io/docs/orm/prisma-client/special-fields-and-types/composite-types)
+- Prisma Next contract skill (`skills/prisma-next-contract`) in the prisma-next repository — authoritative for the Next side

.agents/skills/prisma-mongodb-upgrade/references/verify-cutover-checklist.md

@@ -0,0 +1,60 @@
+# verify-cutover-checklist
+
+Verification checklist for a v6 → Prisma Next cutover: the data never moves — only the code does.
+
+## Priority
+
+CRITICAL
+
+## Why It Matters
+
+A v6 → Next migration is a *client and workflow* migration against the **same MongoDB
+database** — there is no data export/import step, and introducing one (or pointing the new
+stack at a fresh database) turns a code migration into an outage. The checklist below keeps
+the cutover observable and reversible.
+
+## Ground rules
+
+- **No data moves.** The Next contract is authored to describe the existing collections;
+  both stacks read the same database during the staged phase.
+- **v6 stays runnable until cutover is verified.** Do not delete the v6 client, schema, or
+  dependencies until the checklist passes.
+
+## Checklist
+
+1. **Same database, verified:** the Next config points at the same connection string /
+   database name the v6 app uses (minus v6-specific URL parameters that the `mongodb@^7`
+   driver rejects — validate the URL with the driver first).
+2. **Server floor:** MongoDB server is 8.0+ (Next's requirement; v6 tolerated older).
+   Confirm before authoring any contract.
+3. **Contract round-trip on a copy:** on a staging copy (or `mongodb-memory-server`), emit
+   the contract, run plan → migrate → verify → sign, and confirm `verify` passes against
+   data copied from production shape. Verification failures here are contract-mapping bugs,
+   not database problems.
+4. **Index parity:** enumerate indexes on every collection (`db.collection.getIndexes()`)
+   and confirm the Next contract declares the same set — v6 `db push` may have created
+   indexes the new contract must re-declare, or verification and query performance will
+   diverge.
+5. **Validator impact assessed:** Next emits closed `$jsonSchema` validators by default;
+   confirm legacy documents (extra fields, drifted shapes) pass them on the staging copy
+   before applying to production.
+6. **Storage-name addressing audited:** every ported call site uses collection storage
+   names (`db.orm.users`), not model names (see `schema-contract-mapping.md`).
+7. **Transaction inventory mapped:** grep the v6 app for `$transaction`; each hit gets a
+   driver-session equivalent (the `mongodb` driver is directly available; the façade wrapper
+   is expected soon — see `client-api-mapping.md`).
+8. **Raw call inventory mapped:** every `$runCommandRaw` / `findRaw` / `aggregateRaw` call
+   has an explicit Next-side replacement (`mongoRaw(...)` lane or pipeline builder).
+9. **Staged read-only soak:** run the Next stack read-only against staging/production data
+   alongside v6 and compare outputs before allowing writes.
+10. **Cutover + rollback:** switch writes to Next only after the soak; keep the v6 branch
+    deployable as the rollback path. Rolling back is a code rollback — the data was never
+    moved.
+
+After cutover, install and follow Prisma Next's own skills for ongoing work (see the
+hand-off rule in `SKILL.md`).
+
+## References
+
+- [v6 MongoDB documentation](https://www.prisma.io/docs/orm/overview/databases/mongodb)
+- Prisma Next migrations + queries skills — authoritative for the Next side; verified @ `a2791c5dd59d579b4b3052942ae7f8fe5e2ee852`