@prisma-next/cli 0.7.0 → 0.8.0

package/src/commands/init/agent-skill-install.ts

@@ -0,0 +1,130 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import type { PackageManager } from './detect-package-manager';
+import { errorInitSkillInstallFailed } from './errors';
+
+const exec = promisify(execFile);
+
+/**
+ * The npm package the agent-skill install dispatches to. Version-locked
+ * to Prisma Next via the consumer project's `package.json`; the install
+ * subprocess picks up whatever version is resolvable at install time.
+ *
+ * The skill is **always** installed at the project level — never the
+ * user level — precisely so the skill version tracks the project's
+ * Prisma Next version. A user-level (global) install of an
+ * agent-skills CLI package would have to pick a single version for
+ * every project on the host, which breaks the version-locking invariant
+ * the rest of the framework relies on (skills, CLI, runtime, and
+ * extension packs all ship at the same version per release).
+ */
+export const AGENT_SKILL_PACKAGE = '@prisma-next/agent-skill';
+
+/**
+ * The skill-install command, formatted for the project's detected
+ * package manager. `npx`/`pnpm dlx`/`bunx` are interchangeable to the
+ * user; we pick the variant that matches the rest of the install step
+ * so a single project consistently uses one runner.
+ *
+ * `--all` auto-selects every skill in the cluster and every detected
+ * agent runtime, skipping the multi-select prompts the `skills` CLI
+ * shows by default. A non-interactive scaffold step cannot present
+ * prompts, and the cluster is designed to be installed as a unit (the
+ * router skill routes between the workflow-scoped siblings). Users who
+ * want a narrower install run `npx skills add @prisma-next/agent-skill`
+ * themselves after `init` with the flags they want.
+ *
+ * Exported for unit tests so the per-PM dispatch can be asserted
+ * without a live subprocess.
+ */
+export function formatSkillInstallCommand(pm: PackageManager): string {
+  const args = ['skills', 'add', AGENT_SKILL_PACKAGE, '--all'];
+  switch (pm) {
+    case 'pnpm':
+      return `pnpm dlx ${args.join(' ')}`;
+    case 'yarn':
+      return `yarn dlx ${args.join(' ')}`;
+    case 'bun':
+      return `bunx ${args.join(' ')}`;
+    case 'deno':
+      return `deno run -A npm:${args.join(' ')}`;
+    case 'npm':
+      return `npx ${args.join(' ')}`;
+  }
+}
+
+/**
+ * Parse the project-pm-formatted command into an exec call. The
+ * format-then-parse split keeps the user-facing command string the same
+ * as the surface the structured error advertises, so a user who copies
+ * the error's `fix` line gets the same invocation that init just
+ * attempted.
+ */
+function commandToExec(command: string): {
+  readonly file: string;
+  readonly args: readonly string[];
+} {
+  const tokens = command.split(/\s+/);
+  return { file: tokens[0] ?? 'npx', args: tokens.slice(1) };
+}
+
+/**
+ * Runs the project-level skill install. Returns `{ ok: true, command }`
+ * on success; throws a structured `errorInitSkillInstallFailed` on
+ * failure. The throw is intentionally fatal — project-level skill
+ * install is unconditional (modulo `--no-skill`) and the user opted
+ * into Prisma Next by running `init`. A silent skip would defeat the
+ * onboarding-to-zero contract.
+ */
+export async function runProjectLevelSkillInstall(ctx: {
+  readonly baseDir: string;
+  readonly pm: PackageManager;
+  readonly filesWritten: readonly string[];
+}): Promise<{ readonly ok: true; readonly command: string }> {
+  const command = formatSkillInstallCommand(ctx.pm);
+  const { file, args } = commandToExec(command);
+  try {
+    await exec(file, args, { cwd: ctx.baseDir });
+    return { ok: true, command };
+  } catch (err) {
+    throw errorInitSkillInstallFailed({
+      skillInstallCommand: command,
+      filesWritten: ctx.filesWritten,
+      cause:
+        redactSecrets(readChildStderr(err)) || (err instanceof Error ? err.message : String(err)),
+    });
+  }
+}
+
+function readChildStderr(err: unknown): string {
+  if (err instanceof Error && 'stderr' in err) {
+    return String((err as { stderr: string }).stderr ?? '');
+  }
+  return '';
+}
+
+/**
+ * Strips credentials from a `scheme://user:pass@host/...` URL anywhere
+ * in `stderr`. Package-manager stderr regularly contains credentialed
+ * registry URLs (private npm registries, GitHub Packages tokens), and
+ * those bubble into the structured `errorInitSkillInstallFailed`
+ * envelope, which ends up in logs and CI output. Redact at the
+ * boundary so we never re-emit a secret.
+ *
+ * Exported for unit tests.
+ */
+export function redactSecrets(stderr: string): string {
+  if (!stderr) return stderr;
+  return stderr.replace(/([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)([^/@\s]+)@/g, '$1***@');
+}
+
+// -------------------------------------------------------------------
+// Legacy file cleanup
+// -------------------------------------------------------------------
+
+/**
+ * Hand-rolled skill stub path that init must not leave behind. Removed
+ * on every init run so a project's `.agents/skills/prisma-next/` does
+ * not shadow the published `@prisma-next/agent-skill` package.
+ */
+export const LEGACY_SKILL_FILE = '.agents/skills/prisma-next/SKILL.md';

package/src/commands/init/errors.ts

@@ -236,3 +236,35 @@ export function errorInitEmitFailed(options: {
     },
   });
 }
+
+/**
+ * The project-level agent-skill install (`npx skills add
+ * @prisma-next/agent-skill`) failed after a successful dependency
+ * install + emit. The project's scaffold remains on disk; the user
+ * can either fix the underlying issue (network, registry, PATH) and
+ * run the install command manually, or re-run `init --no-skill` to
+ * proceed without the skill.
+ *
+ * Non-rolling-back, matching the existing install/emit failure
+ * semantics. Maps to exit code `6 = SKILL_INSTALL_FAILED`.
+ */
+export function errorInitSkillInstallFailed(options: {
+  readonly skillInstallCommand: string;
+  readonly filesWritten: readonly string[];
+  readonly cause: string;
+}): CliStructuredError {
+  return new CliStructuredError('5013', 'Failed to install @prisma-next/agent-skill', {
+    domain: 'CLI',
+    why: `\`${options.skillInstallCommand}\` exited with an error: ${options.cause}`,
+    fix:
+      'Either:\n' +
+      `  - Re-run \`prisma-next init --no-skill${options.filesWritten.length > 0 ? ' --force' : ''}\` to skip the skill install for this run, or\n` +
+      `  - Fix the underlying issue (network, npm registry, \`npx skills\` on PATH) and install manually:\n      ${options.skillInstallCommand}`,
+    docsUrl: 'https://prisma-next.dev/docs/cli/init#agent-skill',
+    meta: {
+      filesWritten: options.filesWritten,
+      skillInstallCommand: options.skillInstallCommand,
+      cause: options.cause,
+    },
+  });
+}

package/src/commands/init/exit-codes.ts

@@ -60,3 +60,13 @@ export const INIT_EXIT_INSTALL_FAILED = 4;
  * emit` manually.
  */
 export const INIT_EXIT_EMIT_FAILED = 5;
+
+/**
+ * The project-level `@prisma-next/agent-skill` install (`npx skills add
+ * @prisma-next/agent-skill`) failed after a successful dependency
+ * install + emit. The scaffolded project files remain on disk; the
+ * user can fix the underlying issue (network, registry reachability,
+ * `npx skills` not on PATH) and run the install manually, or re-run
+ * `init` with `--no-skill` to skip it.
+ */
+export const INIT_EXIT_SKILL_INSTALL_FAILED = 6;

package/src/commands/init/index.ts

@@ -11,6 +11,7 @@ import {
   INIT_EXIT_INTERNAL_ERROR,
   INIT_EXIT_OK,
   INIT_EXIT_PRECONDITION,
+  INIT_EXIT_SKILL_INSTALL_FAILED,
   INIT_EXIT_USER_ABORTED,
 } from './exit-codes';
 
@@ -33,6 +34,7 @@ interface InitCommandOptions extends CommonCommandOptions {
   readonly probeDb?: boolean;
   readonly strictProbe?: boolean;
   readonly install?: boolean;
+  readonly skill?: boolean;
 }
 
 export function createInitCommand(): Command {
@@ -52,7 +54,8 @@ export function createInitCommand(): Command {
       `  ${INIT_EXIT_PRECONDITION}   PRECONDITION          Bad flags / missing prerequisite (e.g. no package.json).\n` +
       `  ${INIT_EXIT_USER_ABORTED}   USER_ABORTED          User cancelled an interactive prompt.\n` +
       `  ${INIT_EXIT_INSTALL_FAILED}   INSTALL_FAILED        Dependency installation failed (init-specific).\n` +
-      `  ${INIT_EXIT_EMIT_FAILED}   EMIT_FAILED           \`contract emit\` failed after install (init-specific).`,
+      `  ${INIT_EXIT_EMIT_FAILED}   EMIT_FAILED           \`contract emit\` failed after install (init-specific).\n` +
+      `  ${INIT_EXIT_SKILL_INSTALL_FAILED}   SKILL_INSTALL_FAILED  Agent-skill install failed (re-run with --no-skill to skip).`,
   );
   setCommandExamples(command, [
     'prisma-next init',
@@ -60,6 +63,7 @@ export function createInitCommand(): Command {
     'prisma-next init --yes --target mongodb --authoring typescript --json',
     'prisma-next init --yes --force --target postgres --authoring psl  # overwrite an existing scaffold',
     'prisma-next init --no-install                                       # skip pnpm/npm install + emit',
+    'prisma-next init --no-skill                                         # skip the agent-skill install (air-gapped / restricted env)',
   ]);
 
   return addGlobalOptions(command)
@@ -83,6 +87,10 @@ export function createInitCommand(): Command {
       'Treat a failed --probe-db as fatal (no-op without --probe-db; init is offline-by-default)',
     )
     .option('--no-install', 'Skip dependency installation and contract emission')
+    .option(
+      '--no-skill',
+      'Skip the @prisma-next/agent-skill install (air-gapped CI, restricted registries, etc.)',
+    )
     .action(async (options: InitCommandOptions) => {
       const { runInit } = await import('./init');
       const flags = parseGlobalFlags(options);

package/src/commands/init/init.ts

@@ -7,6 +7,11 @@ import { CliStructuredError } from '../../utils/cli-errors';
 import { formatErrorJson, formatErrorOutput } from '../../utils/formatters/errors';
 import type { GlobalFlags } from '../../utils/global-flags';
 import { TerminalUI } from '../../utils/terminal-ui';
+import {
+  formatSkillInstallCommand,
+  LEGACY_SKILL_FILE,
+  runProjectLevelSkillInstall,
+} from './agent-skill-install';
 import {
   detectPackageManager,
   formatAddArgs,
@@ -29,6 +34,7 @@ import {
   INIT_EXIT_INTERNAL_ERROR,
   INIT_EXIT_OK,
   INIT_EXIT_PRECONDITION,
+  INIT_EXIT_SKILL_INSTALL_FAILED,
   INIT_EXIT_USER_ABORTED,
 } from './exit-codes';
 import { mergeGitattributes, requiredGitattributesLines } from './hygiene-gitattributes';
@@ -48,7 +54,6 @@ import {
 } from './output';
 import { type ProbeOutcome, type ProbeOverrides, probeServerVersion } from './probe-db';
 import { findStaleArtefacts, removeDependency } from './reinit-cleanup';
-import { agentSkillMd } from './templates/agent-skill';
 import { configFile, dbFile, starterSchema, targetPackageName } from './templates/code-templates';
 import { envExampleContent, envFileContent, MIN_SERVER_VERSION } from './templates/env';
 import { quickReferenceMd } from './templates/quick-reference';
@@ -72,6 +77,15 @@ interface InstallReport {
   readonly deps: readonly string[];
   readonly devDeps: readonly string[];
   readonly warnings: readonly string[];
+  /**
+   * The package manager that actually ran. Equal to the detected `pm`
+   * on the common path; differs when the FR7.2 pnpm → npm fallback
+   * fired, in which case it's `'npm'`. Threaded into the agent-skill
+   * install so the runner stays consistent with the install we just
+   * ran — re-trying through `pnpm dlx` when `pnpm install` just failed
+   * for workspace/catalog reasons would fail again for the same reason.
+   */
+  readonly effectivePm: PackageManager;
 }
 
 /**
@@ -156,10 +170,6 @@ export async function runInit(
       path: 'prisma-next.md',
       content: quickReferenceMd(inputs.target, inputs.authoring, inputs.schemaPath, pkgRun),
     },
-    {
-      path: '.agents/skills/prisma-next/SKILL.md',
-      content: agentSkillMd(inputs.target, inputs.authoring, inputs.schemaPath, pkgRun),
-    },
     { path: '.env.example', content: envExampleContent(inputs.target) },
   ];
 
@@ -172,6 +182,14 @@ export async function runInit(
   // and missing-on-disk-at-write-time is tolerated.
   const filesToDelete: string[] = inputs.reinit ? [...findStaleArtefacts(baseDir, schemaDir)] : [];
 
+  // `init` delegates the skill to `npx skills add @prisma-next/agent-skill`,
+  // so a hand-rolled `.agents/skills/prisma-next/SKILL.md` in the project
+  // would shadow the published package. Queue it for deletion on every
+  // run (not gated on `--reinit`).
+  if (existsSync(join(baseDir, LEGACY_SKILL_FILE))) {
+    filesToDelete.push(LEGACY_SKILL_FILE);
+  }
+
   // FR3.2: a real `.env` is only written when the user opted in. Never
   // overwrite an existing `.env` — secrets live there and clobbering
   // them is the most damaging possible side-effect of `init`.
@@ -416,6 +434,51 @@ export async function runInit(
     }
   }
 
+  // Agent-skill install. Project-level is unconditional modulo
+  // `--no-skill`. We deliberately do **not** offer a user-level
+  // (global) install path: the skill's behaviour and surface track
+  // the project's Prisma Next version, and a host-wide install would
+  // have to pick a single version for every project on the machine,
+  // which breaks the version-locking invariant the rest of the
+  // framework relies on. A project-level failure is fatal
+  // (`INIT_EXIT_SKILL_INSTALL_FAILED`).
+  //
+  // Runs after install + emit because (1) `node_modules` is in place,
+  // so any consumers downstream are coherent, and (2) the user has
+  // seen the scaffolding succeed before this network-bound step
+  // potentially fails. We skip the install when the user passed
+  // `--no-install` for the same reason — no `node_modules` means the
+  // workspace isn't ready to consume the skill yet anyway.
+  const manualProjectSkillCommand = formatSkillInstallCommand(install.effectivePm);
+  if (!inputs.installProjectSkill) {
+    warnings.push(
+      `Skipped @prisma-next/agent-skill install (--no-skill). To install later, run \`${manualProjectSkillCommand}\` in this project.`,
+    );
+  } else if (install.skipped) {
+    warnings.push(
+      `Skipped @prisma-next/agent-skill install because --no-install was passed. Once you run install manually, register the skill with \`${manualProjectSkillCommand}\`.`,
+    );
+  } else {
+    const spinner = ui.spinner();
+    spinner.start('Registering @prisma-next/agent-skill with the agent runtime...');
+    try {
+      const project = await runProjectLevelSkillInstall({
+        baseDir,
+        pm: install.effectivePm,
+        filesWritten,
+      });
+      spinner.stop(
+        `Registered @prisma-next/agent-skill (project level) — ran \`${project.command}\``,
+      );
+    } catch (error) {
+      spinner.stop('Agent-skill install failed');
+      if (CliStructuredError.is(error)) {
+        return emitError(ui, flags, error);
+      }
+      throw error;
+    }
+  }
+
   const output: InitOutput = {
     ok: true,
     target: inputs.target === 'mongo' ? 'mongodb' : 'postgres',
@@ -525,6 +588,8 @@ export function exitCodeForError(error: { readonly code: string }): number {
       return INIT_EXIT_EMIT_FAILED;
     case '5009': // invalid output document — internal bug in prisma-next
       return INIT_EXIT_INTERNAL_ERROR;
+    case '5013': // agent-skill install failed
+      return INIT_EXIT_SKILL_INSTALL_FAILED;
     default:
       // Any unexpected code is treated as an internal bug rather than
       // mis-routed to PRECONDITION. Adding a new code requires an
@@ -646,7 +711,7 @@ async function runInstall(ctx: {
         'Manual steps',
       );
     }
-    return { skipped: true, deps: [], devDeps: [], warnings: catalogWarnings };
+    return { skipped: true, deps: [], devDeps: [], warnings: catalogWarnings, effectivePm: pm };
   }
 
   const exec = promisify(execFile);
@@ -661,7 +726,7 @@ async function runInstall(ctx: {
   try {
     await runPair(pm);
     spinner.stop(`Installed ${allPackages}`);
-    return { skipped: false, deps, devDeps, warnings: catalogWarnings };
+    return { skipped: false, deps, devDeps, warnings: catalogWarnings, effectivePm: pm };
   } catch (err) {
     const stderrText = redactSecrets(readChildStderr(err));
 
@@ -693,6 +758,7 @@ async function runInstall(ctx: {
           // catalog-honour warning to avoid a contradictory message
           // pair.
           warnings: [fallbackWarning],
+          effectivePm: 'npm',
         };
       } catch (npmErr) {
         spinner.stop('Installation failed');

package/src/commands/init/inputs.ts

@@ -31,6 +31,13 @@ export interface InitFlagOptions {
   readonly probeDb?: boolean;
   readonly strictProbe?: boolean;
   readonly install?: boolean;
+  /**
+   * `--no-skill` — skip the project-level skill install entirely.
+   * Documented escape hatch for air-gapped CI, restricted registries,
+   * and any environment where `npx skills` is
+   * not reachable.
+   */
+  readonly skill?: boolean;
 }
 
 /**
@@ -61,6 +68,14 @@ export interface ResolvedInitInputs {
    * is added separately via the install step.
    */
   readonly removePreviousFacade: string | null;
+  /**
+   * Whether to run `npx skills add @prisma-next/agent-skill` at the
+   * project level after install + emit. True by default; `--no-skill`
+   * sets it to `false`. The skill is always project-level (never
+   * user-level / global) so its version stays locked to the project's
+   * Prisma Next version — see `agent-skill-install.ts`.
+   */
+  readonly installProjectSkill: boolean;
 }
 
 const TARGET_ALIASES: ReadonlyMap<string, TargetId> = new Map([
@@ -161,6 +176,13 @@ export async function resolveInitInputs(ctx: {
     autoAcceptPrompts,
   });
 
+  // Skill-install gating. `--no-skill` (commander parses
+  // `options.skill === false`) is the only escape hatch; otherwise
+  // project-level install is unconditional. The skill is always
+  // installed at the project level so its version tracks the
+  // project's Prisma Next release.
+  const installProjectSkill = options.skill !== false;
+
   return {
     target: finalTarget,
     authoring: finalAuthoring,
@@ -171,6 +193,7 @@ export async function resolveInitInputs(ctx: {
     strictProbe: Boolean(options.strictProbe),
     reinit,
     removePreviousFacade,
+    installProjectSkill,
   };
 }
 

package/src/commands/init/output.ts

@@ -130,7 +130,7 @@ export function buildNextSteps(options: {
       '4. Open prisma-next.md for a quick reference on how to write your first typed query.',
     );
     steps.push(
-      '5. The .agents/skills/prisma-next/SKILL.md file is wired up for AI-coding agents in this project.',
+      '5. @prisma-next/agent-skill is registered with your agent runtime — open the project in your IDE and ask the agent to add a model, run a query, or plan a migration.',
     );
   } else {
     steps.push(
@@ -140,7 +140,7 @@ export function buildNextSteps(options: {
       '3. Open prisma-next.md for a quick reference on how to write your first typed query.',
     );
     steps.push(
-      '4. The .agents/skills/prisma-next/SKILL.md file is wired up for AI-coding agents in this project.',
+      '4. @prisma-next/agent-skill is registered with your agent runtime — open the project in your IDE and ask the agent to add a model, run a query, or plan a migration.',
     );
   }
   return steps;

package/src/commands/init/templates/code-templates.ts

@@ -253,7 +253,10 @@ export function dbFile(target: TargetId): string {
 import type { Contract } from './contract.d';
 import contractJson from './contract.json' with { type: 'json' };
 
-export const db = postgres<Contract>({ contractJson });
+export const db = postgres<Contract>({
+  contractJson,
+  url: process.env['DATABASE_URL']!,
+});
 `;
   }
 

package/dist/agent-skill-mongo.md

@@ -1,138 +0,0 @@
-# Prisma Next — project skill
-
-This project uses **Prisma Next** with **MongoDB** via `@prisma-next/mongo`. Prisma Next lets the user define data models in a contract file and query them with a fully typed ORM.
-
-## Files
-
-- **Contract**: `{{schemaPath}}` ({{authoringLabel}} authoring) — the user's data models. Edit this to add or change models.
-- **Config**: `prisma-next.config.ts` — tells the CLI where the contract is and how to connect to the database. Loads `.env` via `dotenv/config`.
-- **Database client**: `{{schemaDir}}/db.ts` — `import { db } from '{{dbImportPath}}'`. This is the entry point for all queries.
-- **Generated files** (do not edit by hand):
-  - `{{schemaDir}}/contract.json` — compiled contract, used at runtime
-  - `{{schemaDir}}/contract.d.ts` — TypeScript types for the contract, used for autocomplete and type checking
-
-## Commands
-
-- `{{pkgRun}} contract emit` — regenerate `contract.json` and `contract.d.ts` after changing the contract
-- `{{pkgRun}} db init` — bootstrap a database to match the contract (creates collections, indexes, constraints). Additive only — won't drop existing structures.
-- `{{pkgRun}} db update` — update the database to match the current contract. Prompts for confirmation on destructive changes. Use `--dry-run` to preview.
-- `{{pkgRun}} migration plan` — create a new migration from contract changes (offline, no database needed). Use `--name <slug>` to name it.
-- `{{pkgRun}} migration apply` — apply pending migrations to the database
-- `{{pkgRun}} migration status` — show which migrations are applied and which are pending
-- `{{pkgRun}} migration show <name>` — show details of a specific migration
-
-## How to write queries
-
-Use the ORM (`db.orm`). Each root accessor is the lowercased plural form emitted by `prisma-next contract emit` (typically the `@@map`-ped collection name) — for `model User { @@map("users") }` use `db.orm.users`, for `model Post { @@map("posts") }` use `db.orm.posts`. The Mongo facade has no raw-SQL surface. Two escape hatches exist for cases the ORM can't express; both are covered under "Escape hatches" below.
-
-```typescript
-import { db } from '{{dbImportPath}}';
-
-// Find one record
-const user = await db.orm.users
-  .where({ email: 'alice@example.com' })
-  .first();
-// Returns { _id: ObjectId; email: string; ... } | null
-
-// Find multiple records — `.all()` returns an AsyncIterableResult, consume
-// either as an async iterable (below) or by `await`ing it to materialise an Array.
-for await (const user of db.orm.users
-  .select('_id', 'email')
-  .take(10)
-  .all()) {
-  // Each `user` is { _id: ObjectId; email: string }
-}
-// Returns AsyncIterableResult<{ _id: ObjectId; email: string }>
-
-// Filter, order, limit
-const recentPosts = await db.orm.posts
-  .where({ authorId: userId })
-  .orderBy({ createdAt: -1 })
-  .select('_id', 'title', 'createdAt')
-  .take(50)
-  .all();
-
-// Include relations (reference relations only — embedded relations come back automatically)
-const usersWithPosts = await db.orm.users
-  .select('_id', 'email')
-  .include('posts')
-  .take(10)
-  .all();
-```
-
-### Key ORM methods
-
-- `.where({ field: value, ... })` — filter records by an equality object. Pass a raw filter expression for `$gt`/`$in`/`$regex` etc.
-- `.select('field1', 'field2', ...)` — pick which fields to return
-- `.orderBy({ field: 1 | -1 })` — sort results (1 = ascending, -1 = descending)
-- `.take(n)` / `.skip(n)` — limit and offset
-- `.all()` — execute and return all matching records as an `AsyncIterableResult`
-- `.first()` — execute with limit 1 and return the first matching row, or `null`
-- `.include('relationName')` — eager-load a reference relation (`$lookup`); embedded relations are already part of the row
-- `.variant('VariantName')` — narrow a polymorphic collection to a discriminator value
-
-## Escape hatches
-
-The ORM covers the common cases. When you genuinely need something it can't express, prefer these — in order — over reaching for `db.runtime()` (which is an internal executor surface, not a `mongodb`-driver handle):
-
-1. **Typed raw aggregations — `db.query`.** The facade exposes a `db.query` builder that runs aggregation pipelines through the same runtime + middleware + codec stack as `db.orm`, so results stay typed against the contract. Use this for `$lookup`/`$facet`/`$graphLookup`/window-function pipelines that the ORM doesn't surface.
-
-2. **Direct `mongodb` driver control — `mongoClient` binding.** If you need a raw `MongoClient` (e.g. for transactions, change streams, sessions, or a driver feature Prisma Next doesn't expose), construct one yourself and pass it to `mongo({ mongoClient, dbName, contractJson })`. Your code keeps the `MongoClient` reference and uses it directly, while the same `db` object still gives you the typed ORM surface:
-
-   ```typescript
-   import { MongoClient } from 'mongodb';
-   import mongo from '@prisma-next/mongo/runtime';
-   import type { Contract } from './contract.d';
-   import contractJson from './contract.json' with { type: 'json' };
-
-   const client = new MongoClient(process.env['DATABASE_URL']!);
-   await client.connect();
-
-   export const db = mongo<Contract>({ contractJson, mongoClient: client, dbName: 'mydb' });
-
-   const session = client.startSession();
-   try {
-     await session.withTransaction(async () => {
-       await db.orm.users.createAll([{ /* ... */ }]);
-     });
-   } finally {
-     await session.endSession();
-   }
-   ```
-
-## Rules
-
-- **Never hand-edit** `contract.json` or `contract.d.ts`. Always regenerate them with `contract emit`.
-- **Always emit after contract changes.** When you modify `{{schemaPath}}`, run `{{pkgRun}} contract emit` before writing any code that depends on the new or changed models.
-- **Don't restructure `db.ts`.** It's scaffolded by init and works as-is. `db` connects lazily on the first query — there is no `db.connect(...)` step.
-- **Root accessors are emitter-driven.** Use the lowercased plural collection name (e.g. `db.orm.users`, `db.orm.posts`) — not the PascalCase model name. Re-run `{{pkgRun}} contract emit` if a new model's accessor isn't appearing on `db.orm`.
-- **Connection string** is `DATABASE_URL` in `.env`. If the user reports connection errors, check this value and the `.env` file.
-- **Transactions and change streams** require a MongoDB **replica set**. The Mongo facade does not yet expose `db.transaction(...)` — for now, use the `mongoClient` escape hatch above to drive transactions/sessions directly. See the quick reference for dev-environment options; the typed transaction API is tracked under [TML-2313](https://linear.app/prisma-company/issue/TML-2313/mongo-dev-replica-set-story-is-missing-transactions-change-streams).
-- **Don't reach for `db.runtime()`** as an escape hatch. It returns the internal executor (`MongoRuntime`), not a `mongodb` `MongoClient` or `Db`. Use `db.query` for raw aggregations and the `mongoClient` binding for direct driver control.
-
-## Workflow for common tasks
-
-**User wants to add a new model or field:**
-1. Edit `{{schemaPath}}`
-2. Run `{{pkgRun}} contract emit`
-3. Write query code using `db.orm.<collection>` (lowercased plural, see Rules above)
-
-**User wants to query data:**
-1. Import `db` from `{{dbImportPath}}`
-2. Use `db.orm.<collection>` with `.where()`, `.select()`, `.all()`, `.first()`, etc.
-
-**User wants to set up or change the database connection:**
-1. Edit `DATABASE_URL` in `.env`
-2. The config file (`prisma-next.config.ts`) reads it automatically via `dotenv/config`
-
-**User wants to set up the database for the first time:**
-1. Run `{{pkgRun}} db init`
-
-**User wants to update the database after changing the contract:**
-1. Quick path: `{{pkgRun}} db update` — compares the database to the contract and applies changes directly
-2. Migration path (for production workflows):
-   - `{{pkgRun}} migration plan --name describe-the-change` — creates a migration
-   - `{{pkgRun}} migration apply` — applies pending migrations
-
-**User wants to check what migrations need to be applied:**
-1. Run `{{pkgRun}} migration status`