@prisma-next/cli 0.10.0 → 0.11.0-dev.1

package/src/commands/contract-emit.ts

@@ -20,10 +20,10 @@ import {
 } from '../utils/formatters/emit';
 import { formatStyledHeader, formatSuccessMessage } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { createProgressAdapter } from '../utils/progress-adapter';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface ContractEmitOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -159,8 +159,8 @@ export function createContractEmitCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: ContractEmitOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const startTime = Date.now();
 
       const result = await executeContractEmitCommand(options, flags, ui, startTime);

package/src/commands/contract-infer.ts

@@ -10,9 +10,9 @@ import {
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 import { resolveContractInferOutputPath } from './contract-infer-paths';
 import {
   type InspectLiveSchemaOptions,
@@ -39,10 +39,10 @@ interface ContractInferSuccessResult {
 
 async function executeContractInferCommand(
   options: ContractInferOptions,
+  flags: GlobalFlags,
   ui: TerminalUI,
   startTime: number,
 ): Promise<Result<ContractInferSuccessResult, CliStructuredError>> {
-  const flags = parseGlobalFlags(options);
   const inspectResult = await inspectLiveSchema(options, flags, ui, startTime, {
     commandName: 'contract infer',
     description: 'Infer a PSL contract from the live database schema',
@@ -104,7 +104,7 @@ export function createContractInferCommand(): Command {
   );
   setCommandExamples(command, [
     'prisma-next contract infer --db $DATABASE_URL',
-    'prisma-next contract infer --db $DATABASE_URL --output ./prisma/contract.prisma',
+    'prisma-next contract infer --db $DATABASE_URL --output ./src/prisma/contract.prisma',
     'prisma-next contract infer --db $DATABASE_URL --json',
   ]);
   addGlobalOptions(command)
@@ -112,11 +112,11 @@ export function createContractInferCommand(): Command {
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .option('--output <path>', 'Write the inferred PSL contract to the specified path')
     .action(async (options: ContractInferOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const startTime = Date.now();
 
-      const result = await executeContractInferCommand(options, ui, startTime);
+      const result = await executeContractInferCommand(options, flags, ui, startTime);
       const exitCode = handleResult(result, flags, ui, (value) => {
         if (flags.json) {
           ui.output(JSON.stringify(value, null, 2));

package/src/commands/db-init.ts

@@ -24,13 +24,13 @@ import {
   formatMigrationPlanOutput,
   type MigrationCommandResult,
 } from '../utils/formatters/migrations';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import {
   addMigrationCommandOptions,
   prepareMigrationContext,
 } from '../utils/migration-command-scaffold';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 type DbInitOptions = MigrationCommandOptions;
 
@@ -80,9 +80,17 @@ function mapDbInitFailure(failure: DbInitFailure): CliStructuredError {
   }
 
   if (failure.code === 'RUNNER_FAILED') {
+    const runnerCode =
+      typeof failure.meta?.['runnerErrorCode'] === 'string'
+        ? failure.meta['runnerErrorCode']
+        : undefined;
+    const fix =
+      runnerCode === 'LEGACY_MARKER_SHAPE'
+        ? 'Legacy marker-table shape detected. Drop `prisma_contract.marker` (Postgres) or `_prisma_marker` (SQLite) and re-run `prisma-next db init` to recreate it with the current per-space schema.'
+        : 'Fix the schema mismatch (db init is additive-only), or drop/reset the database and re-run `prisma-next db init`';
     return errorRunnerFailed(failure.summary, {
       why: failure.why ?? 'Migration runner failed',
-      fix: 'Fix the schema mismatch (db init is additive-only), or drop/reset the database and re-run `prisma-next db init`',
+      fix,
       ...(failure.meta
         ? { meta: { code: 'RUNNER_FAILED', ...failure.meta } }
         : { meta: { code: 'RUNNER_FAILED' } }),
@@ -222,10 +230,10 @@ export function createDbInitCommand(): Command {
   ]);
   addMigrationCommandOptions(command);
   command.action(async (options: DbInitOptions) => {
-    const flags = parseGlobalFlags(options);
+    const flags = parseGlobalFlagsOrExit(options);
     const startTime = Date.now();
 
-    const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+    const ui = createTerminalUI(flags);
 
     const result = await executeDbInitCommand(options, flags, ui, startTime);
 

package/src/commands/db-schema.ts

@@ -6,9 +6,9 @@ import {
   setCommandExamples,
 } from '../utils/command-helpers';
 import { formatIntrospectJson, formatIntrospectOutput } from '../utils/formatters/verify';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI } from '../utils/terminal-ui';
 import {
   type InspectLiveSchemaOptions,
   type InspectLiveSchemaResult,
@@ -46,8 +46,8 @@ export function createDbSchemaCommand(): Command {
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: InspectLiveSchemaOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const startTime = Date.now();
 
       const result = await inspectLiveSchema(options, flags, ui, startTime, {

package/src/commands/db-sign.ts

@@ -40,10 +40,10 @@ import {
   formatSignOutput,
 } from '../utils/formatters/verify';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { createProgressAdapter } from '../utils/progress-adapter';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface DbSignOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -270,7 +270,7 @@ export function createDbSignCommand(): Command {
       'Contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
     )
     .action(async (positionalContract: string | undefined, options: DbSignOptions) => {
-      const flags = parseGlobalFlags(options);
+      const flags = parseGlobalFlagsOrExit(options);
 
       if (positionalContract && options.contract) {
         process.stderr.write(
@@ -280,7 +280,7 @@ export function createDbSignCommand(): Command {
         return;
       }
 
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const ui = createTerminalUI(flags);
 
       const result = await executeDbSignCommand(positionalContract, options, flags, ui);
 

package/src/commands/db-update.ts

@@ -33,13 +33,13 @@ import {
   formatMigrationPlanOutput,
   type MigrationCommandResult,
 } from '../utils/formatters/migrations';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import {
   addMigrationCommandOptions,
   prepareMigrationContext,
 } from '../utils/migration-command-scaffold';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface DbUpdateOptions extends MigrationCommandOptions {
   readonly to?: string;
@@ -54,9 +54,17 @@ function mapDbUpdateFailure(failure: DbUpdateFailure): CliStructuredError {
   }
 
   if (failure.code === 'RUNNER_FAILED') {
+    const runnerCode =
+      typeof failure.meta?.['runnerErrorCode'] === 'string'
+        ? failure.meta['runnerErrorCode']
+        : undefined;
+    const fix =
+      runnerCode === 'LEGACY_MARKER_SHAPE'
+        ? 'Legacy marker-table shape detected. Drop `prisma_contract.marker` (Postgres) or `_prisma_marker` (SQLite) and re-run `prisma-next db init` to recreate it with the current per-space schema.'
+        : 'Inspect the reported conflict, reconcile schema drift if needed, then re-run `prisma-next db update`';
     return errorRunnerFailed(failure.summary, {
       why: failure.why ?? 'Migration runner failed',
-      fix: 'Inspect the reported conflict, reconcile schema drift if needed, then re-run `prisma-next db update`',
+      fix,
       ...ifDefined('meta', failure.meta),
     });
   }
@@ -238,10 +246,10 @@ export function createDbUpdateCommand(): Command {
     'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
   );
   command.action(async (options: DbUpdateOptions) => {
-    const flags = parseGlobalFlags(options);
+    const flags = parseGlobalFlagsOrExit(options);
     const startTime = Date.now();
 
-    const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+    const ui = createTerminalUI(flags);
 
     let result = await executeDbUpdateCommand(options, flags, ui, startTime);
 

package/src/commands/db-verify.ts

@@ -47,10 +47,10 @@ import {
   formatVerifyOutput,
 } from '../utils/formatters/verify';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { createProgressAdapter } from '../utils/progress-adapter';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface DbVerifyOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -331,7 +331,7 @@ function wrapVerifyError(
   contractPathAbsolute: string,
   modeLabel: string,
 ): Result<never, CliStructuredError> {
-  if (error instanceof CliStructuredError) {
+  if (CliStructuredError.is(error)) {
     return notOk(error);
   }
   if (error instanceof ContractValidationError) {
@@ -529,8 +529,8 @@ export function createDbVerifyCommand(): Command {
       false,
     )
     .action(async (options: DbVerifyOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       const modeResult = resolveDbVerifyMode(options);
       if (!modeResult.ok) {

package/src/commands/init/detect-package-manager.ts

@@ -56,6 +56,21 @@ export function formatRunCommand(pm: PackageManager, bin: string, args: string):
   return `${pm} ${bin} ${args}`;
 }
 
+export function formatRunScriptCommand(pm: PackageManager, scriptName: string): string {
+  switch (pm) {
+    case 'deno':
+      return `deno task ${scriptName}`;
+    case 'bun':
+      return `bun run ${scriptName}`;
+    case 'pnpm':
+      return `pnpm run ${scriptName}`;
+    case 'yarn':
+      return `yarn run ${scriptName}`;
+    default:
+      return `npm run ${scriptName}`;
+  }
+}
+
 export function formatAddArgs(pm: PackageManager, packages: string[]): string[] {
   if (pm === 'deno') {
     return ['add', ...packages.map((p) => `npm:${p}`)];

package/src/commands/init/errors.ts

@@ -69,6 +69,37 @@ export function errorInitInvalidFlagValue(options: {
   });
 }
 
+/**
+ * `--authoring` and `--schema-path` disagree on file extension (e.g. PSL
+ * authoring with a `.ts` path). Surfaces before any scaffold files are
+ * written so the project tree stays untouched.
+ */
+export function errorInitAuthoringSchemaPathMismatch(options: {
+  readonly authoring: 'psl' | 'typescript';
+  readonly schemaPath: string;
+  readonly actualExtension: string;
+  readonly expectedExtension: string;
+}): CliStructuredError {
+  const expectedAuthoring = options.expectedExtension === '.ts' ? 'typescript' : 'psl';
+  return new CliStructuredError('5014', 'Authoring and schema path do not match', {
+    domain: 'CLI',
+    why:
+      `\`--authoring ${options.authoring}\` requires a schema file ending in ${options.expectedExtension}, ` +
+      `but \`--schema-path ${options.schemaPath}\` ends in ${options.actualExtension}.`,
+    fix:
+      `Use a matching pair, for example \`--authoring ${expectedAuthoring} --schema-path <path>${options.expectedExtension}\`, ` +
+      'or change `--authoring` to match the path you supplied. ' +
+      'You can also omit `--schema-path` to use the default for the chosen authoring.',
+    docsUrl: 'https://prisma-next.dev/docs/cli/init',
+    meta: {
+      authoring: options.authoring,
+      schemaPath: options.schemaPath,
+      actualExtension: options.actualExtension,
+      expectedExtension: options.expectedExtension,
+    },
+  });
+}
+
 /**
  * The user cancelled an interactive prompt (Ctrl-C, escape, declined a
  * selection). Distinct from `errorInitReinitNeedsForce` because that path
@@ -238,7 +269,7 @@ export function errorInitEmitFailed(options: {
 }
 
 /**
- * The project-level agent-skill install (`npx skills add
+ * The project-level skills install (`npx skills add
  * prisma/prisma-next#v<version>`) 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
@@ -260,7 +291,7 @@ export function errorInitSkillInstallFailed(options: {
       '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',
+    docsUrl: 'https://prisma-next.dev/docs/cli/init#skills',
     meta: {
       filesWritten: options.filesWritten,
       skillInstallCommand: options.skillInstallCommand,

package/src/commands/init/hygiene-gitattributes.ts

@@ -20,7 +20,7 @@ import type { TargetId } from './templates/code-templates';
  * `db/contract.json linguist-generated` — not the workspace-glob form
  * `<glob>/contract.json` (which would over-match any unrelated
  * `contract.json` the user has elsewhere) and not the absolute
- * `prisma/contract.json` (which would silently break for a non-default
+ * `DEFAULT_CONTRACT_SOURCE_DIR/contract.json` (which would silently break for a non-default
  * schema path).
  */
 const ARTEFACT_FILENAMES: readonly string[] = [
@@ -59,7 +59,7 @@ export function requiredGitattributesLines(
  *
  * Equivalence is exact-line: a user-customised line like
  * `prisma/*.json linguist-generated` is *not* recognised as covering
- * `prisma/contract.json linguist-generated`. We accept that
+ * `DEFAULT_CONTRACT_SOURCE_DIR/contract.json linguist-generated`. We accept that
  * over-specification — preserving the user's broad pattern *and*
  * appending the narrow one — because the narrow lines are what the
  * acceptance criteria pin (FR3.4 AC).

package/src/commands/init/index.ts

@@ -4,7 +4,8 @@ import {
   setCommandDescriptions,
   setCommandExamples,
 } from '../../utils/command-helpers';
-import { type CommonCommandOptions, parseGlobalFlags } from '../../utils/global-flags';
+import { type CommonCommandOptions, parseGlobalFlagsOrExit } from '../../utils/global-flags';
+import { fireTelemetryAfterInitConsent } from '../../utils/telemetry';
 import {
   INIT_EXIT_EMIT_FAILED,
   INIT_EXIT_INSTALL_FAILED,
@@ -14,6 +15,7 @@ import {
   INIT_EXIT_SKILL_INSTALL_FAILED,
   INIT_EXIT_USER_ABORTED,
 } from './exit-codes';
+import { defaultSchemaPath } from './templates/code-templates';
 
 /**
  * Commander.js parsed options for `init`. The init-specific options live
@@ -63,7 +65,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)',
+    'prisma-next init --no-skill                                         # skip the skills install (air-gapped / restricted env)',
   ]);
 
   return addGlobalOptions(command)
@@ -71,7 +73,7 @@ export function createInitCommand(): Command {
     .option('--authoring <style>', 'Schema authoring style: psl or typescript')
     .option(
       '--schema-path <path>',
-      'Where to write the starter schema (default: prisma/contract.prisma)',
+      `Where to write the starter schema (default: ${defaultSchemaPath('psl')})`,
     )
     .option('--force', 'Overwrite an existing scaffold without prompting')
     .option(
@@ -91,15 +93,22 @@ export function createInitCommand(): Command {
       '--no-skill',
       'Skip Prisma Next skills install (air-gapped CI, restricted registries, etc.)',
     )
-    .action(async (options: InitCommandOptions) => {
+    .action(async (options: InitCommandOptions, actionCommand: Command) => {
       const { runInit } = await import('./init');
-      const flags = parseGlobalFlags(options);
+      const flags = parseGlobalFlagsOrExit(options);
       const canPrompt = deriveCanPrompt({
         flagsInteractive: flags.interactive,
         optionInteractive: options.interactive,
         stdinIsTTY: Boolean(process.stdin.isTTY),
       });
-      const exitCode = await runInit(process.cwd(), { options, flags, canPrompt });
+      const exitCode = await runInit(process.cwd(), {
+        options,
+        flags,
+        canPrompt,
+        afterFirstTelemetryConsent: (inputs) => {
+          fireTelemetryAfterInitConsent(actionCommand, { databaseTarget: inputs.target });
+        },
+      });
       process.exit(exitCode);
     });
 }

package/src/commands/init/init.ts

@@ -6,14 +6,7 @@ import { basename, dirname, isAbsolute, join } from 'pathe';
 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 {
-  DEFAULT_AGENT_SKILL_SOURCES,
-  formatClaudeSkillInstallCommand,
-  formatSkillInstallCommand,
-  LEGACY_SKILL_FILE,
-  runProjectLevelSkillInstall,
-} from './agent-skill-install';
+import { createTerminalUI, type TerminalUI } from '../../utils/terminal-ui';
 import {
   detectPackageManager,
   formatAddArgs,
@@ -56,9 +49,16 @@ import {
 } from './output';
 import { type ProbeOutcome, type ProbeOverrides, probeServerVersion } from './probe-db';
 import { findStaleArtefacts, removeDependency } from './reinit-cleanup';
+import {
+  DEFAULT_SKILL_SOURCES,
+  formatSkillInstallCommand,
+  LEGACY_SKILL_FILE,
+  runProjectLevelSkillInstall,
+} from './skill-install';
 import { configFile, dbFile, starterSchema, targetPackageName } from './templates/code-templates';
 import { envExampleContent, envFileContent, MIN_SERVER_VERSION } from './templates/env';
 import { quickReferenceMd } from './templates/quick-reference';
+import { minimalProjectReadmeMd } from './templates/readme';
 import { defaultTsConfig, mergeTsConfig, TsConfigParseError } from './templates/tsconfig';
 
 interface FileEntry {
@@ -81,11 +81,11 @@ interface InstallReport {
   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.
+   * on the common path; differs when the pnpm → npm fallback fired, in
+   * which case it's `'npm'`. Threaded into the skills 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;
 }
@@ -95,7 +95,7 @@ interface InstallReport {
  * structured CLI errors raised at every phase (input resolution, install,
  * emit) and renders them via the same UI surface as success output
  * (`--json` to stdout, human to stderr). Exit codes follow the documented
- * stable set in `./exit-codes.ts` (FR1.6) and the
+ * stable set in `./exit-codes.ts` and the
  * [Style Guide § Exit Codes](../../../../../../../docs/CLI%20Style%20Guide.md#exit-codes).
  *
  * Layered for testability: the action handler in `./index.ts` is
@@ -113,6 +113,11 @@ export async function runInit(
      * mode) — see [Style Guide § Interactivity](../../../../../../../docs/CLI%20Style%20Guide.md#interactivity).
      */
     readonly canPrompt: boolean;
+    /**
+     * Called once after the first affirmative telemetry consent is persisted.
+     * Failures are swallowed by the caller; init success must not depend on telemetry.
+     */
+    readonly afterFirstTelemetryConsent?: (inputs: ResolvedInitInputs) => void | Promise<void>;
     /**
      * FR8.3 — test-only seam for the optional database version probe.
      * Production callers omit this; tests inject stub `probePostgres` /
@@ -124,8 +129,8 @@ export async function runInit(
     readonly probeOverrides?: ProbeOverrides;
   },
 ): Promise<number> {
-  const { options, flags, canPrompt, probeOverrides } = runOptions;
-  const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+  const { options, flags, canPrompt, probeOverrides, afterFirstTelemetryConsent } = runOptions;
+  const ui = createTerminalUI(flags);
   const warnings: string[] = [];
   const filesWritten: string[] = [];
   const filesDeleted: string[] = [];
@@ -144,6 +149,14 @@ export async function runInit(
     throw error;
   }
 
+  if (inputs.enableTelemetry === true && afterFirstTelemetryConsent !== undefined) {
+    try {
+      await afterFirstTelemetryConsent(inputs);
+    } catch {
+      // telemetry is best-effort and must never affect init
+    }
+  }
+
   const pm = await detectPackageManager(baseDir);
   const pkgRun = formatRunCommand(pm, 'prisma-next', '').trimEnd();
 
@@ -336,6 +349,26 @@ export async function runInit(
     }
   }
 
+  if (existsSync(join(baseDir, 'src/index.ts'))) {
+    if (!existsSync(join(baseDir, 'README.md'))) {
+      const rawName =
+        parsedPackageJson !== null && typeof parsedPackageJson['name'] === 'string'
+          ? parsedPackageJson['name']
+          : basename(baseDir);
+      filesToWrite.push({
+        path: 'README.md',
+        content: minimalProjectReadmeMd(
+          inputs.target,
+          inputs.schemaPath,
+          sanitisePackageName(rawName),
+          pm,
+        ),
+      });
+    } else {
+      warnings.push('README.md already exists; leaving it untouched.');
+    }
+  }
+
   // -----------------------------------------------------------------
   // Write phase — every input has been parsed and every merged file is
   // staged. From here on, failures are only possible at the
@@ -445,25 +478,20 @@ export async function runInit(
   // 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 manualProjectSkillCommands = DEFAULT_AGENT_SKILL_SOURCES.flatMap((source) => [
-    formatSkillInstallCommand(install.effectivePm, source),
-    formatClaudeSkillInstallCommand(install.effectivePm, source),
-  ]);
+  // Runs after the install + emit phase when those steps are enabled,
+  // but is not coupled to them: the skills are pulled directly from
+  // the Prisma Next GitHub repo and do not require `node_modules`.
+  // `--no-install` therefore skips only dependency installation and
+  // contract emission; `--no-skill` is the explicit escape hatch for
+  // skipping skills.
+  const manualProjectSkillCommands = DEFAULT_SKILL_SOURCES.map((source) =>
+    formatSkillInstallCommand({ pm: install.effectivePm, source }),
+  );
   const manualProjectSkillSummary = manualProjectSkillCommands.map((c) => `\`${c}\``).join(' && ');
   let skillRegistered = false;
   if (!inputs.installProjectSkill) {
     warnings.push(
-      `Skipped Prisma Next agent-skill install (--no-skill). To install the skills later, run: ${manualProjectSkillSummary}`,
-    );
-  } else if (install.skipped) {
-    warnings.push(
-      `Skipped Prisma Next agent-skill install because --no-install was passed. After you run install manually, install the skills with: ${manualProjectSkillSummary}`,
+      `Skipped Prisma Next skills install (--no-skill). To install the skills later, run: ${manualProjectSkillSummary}`,
     );
   } else {
     const spinner = ui.spinner();
@@ -588,6 +616,7 @@ export function exitCodeForError(error: { readonly code: string }): number {
     case '5010': // invalid manifest (malformed package.json) — precondition
     case '5011': // invalid tsconfig (unparseable JSONC) — precondition
     case '5012': // probe failed under --strict-probe — precondition
+    case '5014': // --authoring / --schema-path extension mismatch — precondition
       return INIT_EXIT_PRECONDITION;
     case '5006': // user aborted interactive prompt
       return INIT_EXIT_USER_ABORTED;
@@ -597,7 +626,7 @@ 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
+    case '5013': // skill install failed
       return INIT_EXIT_SKILL_INSTALL_FAILED;
     default:
       // Any unexpected code is treated as an internal bug rather than