@prisma-next/cli 0.7.0 → 0.8.0-dev.1

package/dist/{output-B16Kefzx.mjs → output-BVj6a971.mjs}

@@ -95,15 +95,15 @@ function buildNextSteps(options) {
 		steps.push(`2. Emit the contract: \`${options.emitCommand}\``);
 		steps.push(`3. Edit your schema at ${options.schemaPath}, then re-run the emit command.`);
 		steps.push("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.");
+		steps.push("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(`2. Edit your schema at ${options.schemaPath}, then re-run \`${options.emitCommand}\`.`);
 		steps.push("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.");
+		steps.push("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;
 }
 //#endregion
 export { renderInitOutro as i, buildNextSteps as n, formatInitJson as r, InitOutputSchema as t };
 
-//# sourceMappingURL=output-B16Kefzx.mjs.map
+//# sourceMappingURL=output-BVj6a971.mjs.map

package/dist/{output-B16Kefzx.mjs.map → output-BVj6a971.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"output-B16Kefzx.mjs","names":[],"sources":["../src/commands/init/output.ts"],"sourcesContent":["import { type } from 'arktype';\nimport type { GlobalFlags } from '../../utils/global-flags';\nimport type { TerminalUI } from '../../utils/terminal-ui';\n\n/**\n * arktype schema for the structured success document `init --json` writes\n * to stdout (FR1.5). The same shape backs the human-readable outro\n * renderer (FR10), so the two output modes carry identical information.\n *\n * `target` is normalised to the user-facing flag value (`mongodb` rather\n * than the internal `mongo`) so consumers can round-trip the document\n * straight into a follow-up `--target` invocation.\n *\n * The `ok: true` literal is the documented success/error discriminator —\n * see [Style Guide § JSON Semantics](../../../../../../../docs/CLI%20Style%20Guide.md#json-semantics).\n * Error envelopes (`CliErrorEnvelope`) carry `ok: false` so consumers can\n * branch with `if (doc.ok)` without inspecting the rest of the structure.\n */\nexport const InitOutputSchema = type({\n  ok: 'true',\n  target: \"'postgres'|'mongodb'\",\n  authoring: \"'psl'|'typescript'\",\n  schemaPath: 'string',\n  filesWritten: 'string[]',\n  /**\n   * FR9.1 — files removed from disk during this run. Populated only on\n   * re-init when previously-emitted contract artefacts (`contract.json`,\n   * `contract.d.ts`, `start-/end-contract.*`, `ops.json`,\n   * `migration.json`) were left behind by an earlier run. Empty on a\n   * green-field init.\n   */\n  filesDeleted: 'string[]',\n  packagesInstalled: {\n    skipped: 'boolean',\n    deps: 'string[]',\n    devDeps: 'string[]',\n  },\n  contractEmitted: 'boolean',\n  nextSteps: 'string[]',\n  warnings: 'string[]',\n});\n\nexport type InitOutput = typeof InitOutputSchema.infer;\n\n/**\n * Serialises the output document for `--json`. Sorted keys are not enforced\n * — `JSON.stringify` preserves insertion order, and the schema field order\n * is the documented order, which matches what users will see when they\n * `jq .` the result.\n */\nexport function formatInitJson(output: InitOutput): string {\n  return JSON.stringify(output, null, 2);\n}\n\n/**\n * Renders the human-readable outro on stderr (FR10.1). Re-uses the same\n * data structure as the JSON output so the two stay in lock-step.\n *\n * Warnings come before \"Next steps\" because they describe state the user\n * needs to be aware of before acting on the next-steps list.\n */\nexport function renderInitOutro(ui: TerminalUI, output: InitOutput, flags: GlobalFlags): void {\n  if (flags.quiet || flags.json) {\n    return;\n  }\n\n  for (const warning of output.warnings) {\n    ui.warn(warning);\n  }\n\n  const lines: string[] = [];\n  lines.push(`Target:    ${output.target}`);\n  lines.push(`Authoring: ${output.authoring}`);\n  lines.push(`Schema:    ${output.schemaPath}`);\n  lines.push('');\n  lines.push('Files written:');\n  for (const file of output.filesWritten) {\n    lines.push(`  • ${file}`);\n  }\n\n  if (output.filesDeleted.length > 0) {\n    lines.push('');\n    lines.push('Files deleted (stale contract artefacts):');\n    for (const file of output.filesDeleted) {\n      lines.push(`  • ${file}`);\n    }\n  }\n\n  if (!output.packagesInstalled.skipped) {\n    lines.push('');\n    lines.push('Packages installed:');\n    for (const dep of output.packagesInstalled.deps) {\n      lines.push(`  • ${dep}`);\n    }\n    for (const dep of output.packagesInstalled.devDeps) {\n      lines.push(`  • ${dep} (dev)`);\n    }\n  }\n\n  lines.push('');\n  lines.push('Next steps:');\n  for (const step of output.nextSteps) {\n    lines.push(`  ${step}`);\n  }\n\n  ui.note(lines.join('\\n'), 'Done');\n}\n\n/**\n * Builds the `nextSteps` array from the resolved scaffold state. Steps are\n * ordered by the workflow a user needs to follow: configure connection →\n * (emit if not yet done) → run a starter query → docs / agent skill.\n *\n * The strings are stable and human-readable; agents wanting to act on them\n * should match on substrings (e.g. \"DATABASE_URL\") rather than exact text,\n * since copy may evolve.\n */\nexport function buildNextSteps(options: {\n  readonly target: 'postgres' | 'mongodb';\n  readonly contractEmitted: boolean;\n  readonly emitCommand: string;\n  readonly schemaPath: string;\n}): string[] {\n  const steps: string[] = [];\n  steps.push('1. Set DATABASE_URL in your environment (export it or add it to .env).');\n  if (!options.contractEmitted) {\n    steps.push(`2. Emit the contract: \\`${options.emitCommand}\\``);\n    steps.push(`3. Edit your schema at ${options.schemaPath}, then re-run the emit command.`);\n    steps.push(\n      '4. Open prisma-next.md for a quick reference on how to write your first typed query.',\n    );\n    steps.push(\n      '5. The .agents/skills/prisma-next/SKILL.md file is wired up for AI-coding agents in this project.',\n    );\n  } else {\n    steps.push(\n      `2. Edit your schema at ${options.schemaPath}, then re-run \\`${options.emitCommand}\\`.`,\n    );\n    steps.push(\n      '3. Open prisma-next.md for a quick reference on how to write your first typed query.',\n    );\n    steps.push(\n      '4. The .agents/skills/prisma-next/SKILL.md file is wired up for AI-coding agents in this project.',\n    );\n  }\n  return steps;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,MAAa,mBAAmB,KAAK;CACnC,IAAI;CACJ,QAAQ;CACR,WAAW;CACX,YAAY;CACZ,cAAc;;;;;;;;CAQd,cAAc;CACd,mBAAmB;EACjB,SAAS;EACT,MAAM;EACN,SAAS;EACV;CACD,iBAAiB;CACjB,WAAW;CACX,UAAU;CACX,CAAC;;;;;;;AAUF,SAAgB,eAAe,QAA4B;CACzD,OAAO,KAAK,UAAU,QAAQ,MAAM,EAAE;;;;;;;;;AAUxC,SAAgB,gBAAgB,IAAgB,QAAoB,OAA0B;CAC5F,IAAI,MAAM,SAAS,MAAM,MACvB;CAGF,KAAK,MAAM,WAAW,OAAO,UAC3B,GAAG,KAAK,QAAQ;CAGlB,MAAM,QAAkB,EAAE;CAC1B,MAAM,KAAK,cAAc,OAAO,SAAS;CACzC,MAAM,KAAK,cAAc,OAAO,YAAY;CAC5C,MAAM,KAAK,cAAc,OAAO,aAAa;CAC7C,MAAM,KAAK,GAAG;CACd,MAAM,KAAK,iBAAiB;CAC5B,KAAK,MAAM,QAAQ,OAAO,cACxB,MAAM,KAAK,OAAO,OAAO;CAG3B,IAAI,OAAO,aAAa,SAAS,GAAG;EAClC,MAAM,KAAK,GAAG;EACd,MAAM,KAAK,4CAA4C;EACvD,KAAK,MAAM,QAAQ,OAAO,cACxB,MAAM,KAAK,OAAO,OAAO;;CAI7B,IAAI,CAAC,OAAO,kBAAkB,SAAS;EACrC,MAAM,KAAK,GAAG;EACd,MAAM,KAAK,sBAAsB;EACjC,KAAK,MAAM,OAAO,OAAO,kBAAkB,MACzC,MAAM,KAAK,OAAO,MAAM;EAE1B,KAAK,MAAM,OAAO,OAAO,kBAAkB,SACzC,MAAM,KAAK,OAAO,IAAI,QAAQ;;CAIlC,MAAM,KAAK,GAAG;CACd,MAAM,KAAK,cAAc;CACzB,KAAK,MAAM,QAAQ,OAAO,WACxB,MAAM,KAAK,KAAK,OAAO;CAGzB,GAAG,KAAK,MAAM,KAAK,KAAK,EAAE,OAAO;;;;;;;;;;;AAYnC,SAAgB,eAAe,SAKlB;CACX,MAAM,QAAkB,EAAE;CAC1B,MAAM,KAAK,yEAAyE;CACpF,IAAI,CAAC,QAAQ,iBAAiB;EAC5B,MAAM,KAAK,2BAA2B,QAAQ,YAAY,IAAI;EAC9D,MAAM,KAAK,0BAA0B,QAAQ,WAAW,iCAAiC;EACzF,MAAM,KACJ,uFACD;EACD,MAAM,KACJ,oGACD;QACI;EACL,MAAM,KACJ,0BAA0B,QAAQ,WAAW,kBAAkB,QAAQ,YAAY,KACpF;EACD,MAAM,KACJ,uFACD;EACD,MAAM,KACJ,oGACD;;CAEH,OAAO"}
+{"version":3,"file":"output-BVj6a971.mjs","names":[],"sources":["../src/commands/init/output.ts"],"sourcesContent":["import { type } from 'arktype';\nimport type { GlobalFlags } from '../../utils/global-flags';\nimport type { TerminalUI } from '../../utils/terminal-ui';\n\n/**\n * arktype schema for the structured success document `init --json` writes\n * to stdout (FR1.5). The same shape backs the human-readable outro\n * renderer (FR10), so the two output modes carry identical information.\n *\n * `target` is normalised to the user-facing flag value (`mongodb` rather\n * than the internal `mongo`) so consumers can round-trip the document\n * straight into a follow-up `--target` invocation.\n *\n * The `ok: true` literal is the documented success/error discriminator —\n * see [Style Guide § JSON Semantics](../../../../../../../docs/CLI%20Style%20Guide.md#json-semantics).\n * Error envelopes (`CliErrorEnvelope`) carry `ok: false` so consumers can\n * branch with `if (doc.ok)` without inspecting the rest of the structure.\n */\nexport const InitOutputSchema = type({\n  ok: 'true',\n  target: \"'postgres'|'mongodb'\",\n  authoring: \"'psl'|'typescript'\",\n  schemaPath: 'string',\n  filesWritten: 'string[]',\n  /**\n   * FR9.1 — files removed from disk during this run. Populated only on\n   * re-init when previously-emitted contract artefacts (`contract.json`,\n   * `contract.d.ts`, `start-/end-contract.*`, `ops.json`,\n   * `migration.json`) were left behind by an earlier run. Empty on a\n   * green-field init.\n   */\n  filesDeleted: 'string[]',\n  packagesInstalled: {\n    skipped: 'boolean',\n    deps: 'string[]',\n    devDeps: 'string[]',\n  },\n  contractEmitted: 'boolean',\n  nextSteps: 'string[]',\n  warnings: 'string[]',\n});\n\nexport type InitOutput = typeof InitOutputSchema.infer;\n\n/**\n * Serialises the output document for `--json`. Sorted keys are not enforced\n * — `JSON.stringify` preserves insertion order, and the schema field order\n * is the documented order, which matches what users will see when they\n * `jq .` the result.\n */\nexport function formatInitJson(output: InitOutput): string {\n  return JSON.stringify(output, null, 2);\n}\n\n/**\n * Renders the human-readable outro on stderr (FR10.1). Re-uses the same\n * data structure as the JSON output so the two stay in lock-step.\n *\n * Warnings come before \"Next steps\" because they describe state the user\n * needs to be aware of before acting on the next-steps list.\n */\nexport function renderInitOutro(ui: TerminalUI, output: InitOutput, flags: GlobalFlags): void {\n  if (flags.quiet || flags.json) {\n    return;\n  }\n\n  for (const warning of output.warnings) {\n    ui.warn(warning);\n  }\n\n  const lines: string[] = [];\n  lines.push(`Target:    ${output.target}`);\n  lines.push(`Authoring: ${output.authoring}`);\n  lines.push(`Schema:    ${output.schemaPath}`);\n  lines.push('');\n  lines.push('Files written:');\n  for (const file of output.filesWritten) {\n    lines.push(`  • ${file}`);\n  }\n\n  if (output.filesDeleted.length > 0) {\n    lines.push('');\n    lines.push('Files deleted (stale contract artefacts):');\n    for (const file of output.filesDeleted) {\n      lines.push(`  • ${file}`);\n    }\n  }\n\n  if (!output.packagesInstalled.skipped) {\n    lines.push('');\n    lines.push('Packages installed:');\n    for (const dep of output.packagesInstalled.deps) {\n      lines.push(`  • ${dep}`);\n    }\n    for (const dep of output.packagesInstalled.devDeps) {\n      lines.push(`  • ${dep} (dev)`);\n    }\n  }\n\n  lines.push('');\n  lines.push('Next steps:');\n  for (const step of output.nextSteps) {\n    lines.push(`  ${step}`);\n  }\n\n  ui.note(lines.join('\\n'), 'Done');\n}\n\n/**\n * Builds the `nextSteps` array from the resolved scaffold state. Steps are\n * ordered by the workflow a user needs to follow: configure connection →\n * (emit if not yet done) → run a starter query → docs / agent skill.\n *\n * The strings are stable and human-readable; agents wanting to act on them\n * should match on substrings (e.g. \"DATABASE_URL\") rather than exact text,\n * since copy may evolve.\n */\nexport function buildNextSteps(options: {\n  readonly target: 'postgres' | 'mongodb';\n  readonly contractEmitted: boolean;\n  readonly emitCommand: string;\n  readonly schemaPath: string;\n}): string[] {\n  const steps: string[] = [];\n  steps.push('1. Set DATABASE_URL in your environment (export it or add it to .env).');\n  if (!options.contractEmitted) {\n    steps.push(`2. Emit the contract: \\`${options.emitCommand}\\``);\n    steps.push(`3. Edit your schema at ${options.schemaPath}, then re-run the emit command.`);\n    steps.push(\n      '4. Open prisma-next.md for a quick reference on how to write your first typed query.',\n    );\n    steps.push(\n      '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.',\n    );\n  } else {\n    steps.push(\n      `2. Edit your schema at ${options.schemaPath}, then re-run \\`${options.emitCommand}\\`.`,\n    );\n    steps.push(\n      '3. Open prisma-next.md for a quick reference on how to write your first typed query.',\n    );\n    steps.push(\n      '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.',\n    );\n  }\n  return steps;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAkBA,MAAa,mBAAmB,KAAK;CACnC,IAAI;CACJ,QAAQ;CACR,WAAW;CACX,YAAY;CACZ,cAAc;;;;;;;;CAQd,cAAc;CACd,mBAAmB;EACjB,SAAS;EACT,MAAM;EACN,SAAS;EACV;CACD,iBAAiB;CACjB,WAAW;CACX,UAAU;CACX,CAAC;;;;;;;AAUF,SAAgB,eAAe,QAA4B;CACzD,OAAO,KAAK,UAAU,QAAQ,MAAM,EAAE;;;;;;;;;AAUxC,SAAgB,gBAAgB,IAAgB,QAAoB,OAA0B;CAC5F,IAAI,MAAM,SAAS,MAAM,MACvB;CAGF,KAAK,MAAM,WAAW,OAAO,UAC3B,GAAG,KAAK,QAAQ;CAGlB,MAAM,QAAkB,EAAE;CAC1B,MAAM,KAAK,cAAc,OAAO,SAAS;CACzC,MAAM,KAAK,cAAc,OAAO,YAAY;CAC5C,MAAM,KAAK,cAAc,OAAO,aAAa;CAC7C,MAAM,KAAK,GAAG;CACd,MAAM,KAAK,iBAAiB;CAC5B,KAAK,MAAM,QAAQ,OAAO,cACxB,MAAM,KAAK,OAAO,OAAO;CAG3B,IAAI,OAAO,aAAa,SAAS,GAAG;EAClC,MAAM,KAAK,GAAG;EACd,MAAM,KAAK,4CAA4C;EACvD,KAAK,MAAM,QAAQ,OAAO,cACxB,MAAM,KAAK,OAAO,OAAO;;CAI7B,IAAI,CAAC,OAAO,kBAAkB,SAAS;EACrC,MAAM,KAAK,GAAG;EACd,MAAM,KAAK,sBAAsB;EACjC,KAAK,MAAM,OAAO,OAAO,kBAAkB,MACzC,MAAM,KAAK,OAAO,MAAM;EAE1B,KAAK,MAAM,OAAO,OAAO,kBAAkB,SACzC,MAAM,KAAK,OAAO,IAAI,QAAQ;;CAIlC,MAAM,KAAK,GAAG;CACd,MAAM,KAAK,cAAc;CACzB,KAAK,MAAM,QAAQ,OAAO,WACxB,MAAM,KAAK,KAAK,OAAO;CAGzB,GAAG,KAAK,MAAM,KAAK,KAAK,EAAE,OAAO;;;;;;;;;;;AAYnC,SAAgB,eAAe,SAKlB;CACX,MAAM,QAAkB,EAAE;CAC1B,MAAM,KAAK,yEAAyE;CACpF,IAAI,CAAC,QAAQ,iBAAiB;EAC5B,MAAM,KAAK,2BAA2B,QAAQ,YAAY,IAAI;EAC9D,MAAM,KAAK,0BAA0B,QAAQ,WAAW,iCAAiC;EACzF,MAAM,KACJ,uFACD;EACD,MAAM,KACJ,uKACD;QACI;EACL,MAAM,KACJ,0BAA0B,QAAQ,WAAW,kBAAkB,QAAQ,YAAY,KACpF;EACD,MAAM,KACJ,uFACD;EACD,MAAM,KACJ,uKACD;;CAEH,OAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma-next/cli",
-  "version": "0.7.0",
+  "version": "0.8.0-dev.1",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
@@ -14,6 +14,14 @@
   "dependencies": {
     "@clack/prompts": "^1.3.0",
     "@dagrejs/dagre": "^3.0.0",
+    "@prisma-next/config": "0.8.0-dev.1",
+    "@prisma-next/contract": "0.8.0-dev.1",
+    "@prisma-next/emitter": "0.8.0-dev.1",
+    "@prisma-next/errors": "0.8.0-dev.1",
+    "@prisma-next/framework-components": "0.8.0-dev.1",
+    "@prisma-next/migration-tools": "0.8.0-dev.1",
+    "@prisma-next/psl-printer": "0.8.0-dev.1",
+    "@prisma-next/utils": "0.8.0-dev.1",
     "arktype": "^2.1.29",
     "c12": "^3.3.4",
     "clipanion": "4.0.0-rc.4",
@@ -26,29 +34,21 @@
     "pathe": "^2.0.3",
     "string-width": "^8.2.1",
     "strip-ansi": "^7.2.0",
-    "wrap-ansi": "^10.0.0",
-    "@prisma-next/config": "0.7.0",
-    "@prisma-next/contract": "0.7.0",
-    "@prisma-next/emitter": "0.7.0",
-    "@prisma-next/errors": "0.7.0",
-    "@prisma-next/framework-components": "0.7.0",
-    "@prisma-next/migration-tools": "0.7.0",
-    "@prisma-next/psl-printer": "0.7.0",
-    "@prisma-next/utils": "0.7.0"
+    "wrap-ansi": "^10.0.0"
   },
   "devDependencies": {
+    "@prisma-next/sql-contract": "0.8.0-dev.1",
+    "@prisma-next/sql-contract-emitter": "0.8.0-dev.1",
+    "@prisma-next/sql-contract-ts": "0.8.0-dev.1",
+    "@prisma-next/sql-operations": "0.8.0-dev.1",
+    "@prisma-next/sql-runtime": "0.8.0-dev.1",
+    "@prisma-next/test-utils": "0.8.0-dev.1",
+    "@prisma-next/tsconfig": "0.8.0-dev.1",
+    "@prisma-next/tsdown": "0.8.0-dev.1",
     "@types/node": "24.10.4",
     "tsdown": "0.22.0",
     "typescript": "5.9.3",
-    "vitest": "4.1.5",
-    "@prisma-next/sql-contract": "0.7.0",
-    "@prisma-next/sql-contract-emitter": "0.7.0",
-    "@prisma-next/sql-contract-ts": "0.7.0",
-    "@prisma-next/sql-operations": "0.7.0",
-    "@prisma-next/sql-runtime": "0.7.0",
-    "@prisma-next/test-utils": "0.7.0",
-    "@prisma-next/tsconfig": "0.7.0",
-    "@prisma-next/tsdown": "0.7.0"
+    "vitest": "4.1.5"
   },
   "exports": {
     ".": {

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/src/commands/migration-plan.ts

@@ -289,10 +289,21 @@ async function executeMigrationPlanCommand(
   // declaredButUnmigrated precheck always passes here.
   const stack = createControlStack(config);
   const familyInstance = config.family.create(stack);
+  let validatedAppContract: Contract;
+  try {
+    validatedAppContract = familyInstance.validateContract(toContractJson);
+  } catch (error) {
+    return notOk(
+      errorContractValidationFailed(
+        `Contract validation failed: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: contractPathAbsolute } },
+      ),
+    );
+  }
   const aggregateResult = await buildContractSpaceAggregate({
     targetId: config.target.targetId,
     migrationsDir,
-    appContract: toContractJson,
+    appContract: validatedAppContract,
     extensionPacks: config.extensionPacks ?? [],
     validateContract: (json: unknown) => familyInstance.validateContract(json),
   });

package/src/control-api/client.ts

@@ -269,12 +269,15 @@ class ControlClientImpl implements ControlClient {
     });
 
     try {
-      // Delegate to family instance schemaVerify method
-      const result = await familyInstance.schemaVerify({
-        driver,
+      // Introspect the live schema, then verify the contract against
+      // it. Composing the two primitives here keeps the family
+      // interface a single synchronous verifier and gives callers
+      // (and tests) explicit control over the introspected schema.
+      const schema = await familyInstance.introspect({ driver, contract });
+      const result = familyInstance.verifySchema({
         contract,
+        schema,
         strict: options.strict ?? false,
-        contractPath: '',
         frameworkComponents,
       });
 
@@ -662,6 +665,10 @@ class ControlClientImpl implements ControlClient {
         enrichedIR,
         this.stack!,
         this.options.family.emission,
+        {
+          serializeContract: (contract) =>
+            this.options.target.contractSerializer.serializeContract(contract),
+        },
       );
 
       onProgress?.({