turbine-orm 0.75.0 → 0.76.0

package/dist/cjs/cli/index.js

@@ -7,7 +7,7 @@
  *   turbine init                 , Initialize a Turbine project
  *   turbine generate | pull      , Introspect database and generate TypeScript types
  *   turbine migrate-from-prisma   - Parse a schema.prisma and emit a Prisma->Turbine name map + report
- *   turbine push                  - Apply schema-builder definitions to database (destructive ops gated)
+ *   turbine push                  - Apply schema-builder definitions to database (--schema-file, destructive ops gated)
  *   turbine migrate create <name> - Create a new SQL migration file (--auto | --from-diff | --recipe <name>)
  *   turbine migrate up           , Apply pending migrations
  *   turbine migrate deploy       , Apply pending migrations without prompts
@@ -60,6 +60,10 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalCommand = canonicalCommand;
+exports.knownCommands = knownCommands;
+exports.flagsForCommand = flagsForCommand;
+exports.allFlagTokens = allFlagTokens;
 exports.parseArgs = parseArgs;
 exports.usesProjectConfig = usesProjectConfig;
 exports.bootstrapCliConfig = bootstrapCliConfig;
@@ -70,10 +74,13 @@ exports.tsxInstallCommand = tsxInstallCommand;
 exports.tsxRequiredNotice = tsxRequiredNotice;
 exports.detectConsumerModuleType = detectConsumerModuleType;
 exports.planInitSteps = planInitSteps;
+exports.initSchemaTemplate = initSchemaTemplate;
 exports.gitignoreIgnoresEnv = gitignoreIgnoresEnv;
 exports.planEnvScaffold = planEnvScaffold;
 exports.scaffoldEnvForUrl = scaffoldEnvForUrl;
+exports.generatedClientImport = generatedClientImport;
 exports.initEnvNotice = initEnvNotice;
+exports.refuseSchemaFilePath = refuseSchemaFilePath;
 exports.resolveMigrateFromPrismaUrl = resolveMigrateFromPrismaUrl;
 exports.readPrismaSchemaSource = readPrismaSchemaSource;
 exports.buildMigrateDeployOptions = buildMigrateDeployOptions;
@@ -93,6 +100,7 @@ const introspect_js_1 = require("../introspect.js");
 const plan_divergence_js_1 = require("../plan-divergence.js");
 const plan_flip_probe_js_1 = require("../plan-flip-probe.js");
 const prisma_schema_fingerprint_js_1 = require("../prisma-schema-fingerprint.js");
+const utils_js_1 = require("../query/utils.js");
 const schema_js_1 = require("../schema.js");
 const schema_sql_js_1 = require("../schema-sql.js");
 const config_js_1 = require("./config.js");
@@ -114,11 +122,227 @@ const ui_js_1 = require("./ui.js");
  * rather than "you forgot the recipe name".
  */
 function failArg(message, ...hints) {
-    (0, ui_js_1.banner)();
+    (0, ui_js_1.errorBanner)();
     (0, ui_js_1.error)(message);
     for (const hint of hints)
-        console.log(`  ${(0, ui_js_1.dim)(hint)}`);
-    (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)((0, ui_js_1.dim)(hint));
+    (0, ui_js_1.errorLine)();
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// The flag surface, as data
+// ---------------------------------------------------------------------------
+/**
+ * Long flags accepted by EVERY command.
+ *
+ * Deliberately generous: these are connection/output overrides and diagnostics,
+ * so accepting one where it happens to be inert costs nothing. Nothing that
+ * changes what a command DOES to your data belongs here, which is why
+ * `--dry-run`, `--allow-destructive`, `--fix` and `--yes` are all per-command
+ * below.
+ */
+const GLOBAL_FLAGS = [
+    '--url',
+    '--out',
+    '--schema',
+    '--include',
+    '--exclude',
+    '--verbose',
+    '--force',
+    '--help',
+];
+/**
+ * The flags each command accepts, BEYOND {@link GLOBAL_FLAGS}. Long spellings
+ * only; short forms come from {@link FLAG_ALIAS}.
+ *
+ * This table is the CLI's flag surface as data, for the same reason
+ * `query/option-surface.ts` is the query surface as data: an unknown flag used
+ * to be DISCARDED by the parser's `default:` branch, so `push --dry-runn`
+ * executed for real, `migrate create x --autoo` wrote an empty template and
+ * reported success, and `doctor --fixx` wrote nothing and exited 0. A typo in a
+ * safety flag silently disarmed the safety. Every entry here is cross-checked
+ * against the parser's own `case` labels by
+ * `src/test/cli-unknown-flags.test.ts`, so adding a flag to one and not the
+ * other fails the build rather than stranding it.
+ */
+const COMMAND_FLAGS = {
+    init: ['--yes', '--schema-file', '--skip-schema', '--with-schema', '--skip-seed', '--skip-push', '--skip-generate'],
+    generate: [
+        '--zod',
+        '--include-views',
+        '--no-timestamp',
+        '--import-ext',
+        '--keep-column-names',
+        '--legacy-to-many-uniques',
+        '--allow-empty',
+    ],
+    'migrate-from-prisma': ['--no-db', '--if-db', '--allow-partial', '--no-timestamp'],
+    push: ['--schema-file', '--dry-run', '--allow-destructive'],
+    migrate: [
+        '--schema-file',
+        '--auto',
+        '--from-diff',
+        '--recipe',
+        '--step',
+        '--dry-run',
+        '--allow-drift',
+        '--allow-destructive',
+    ],
+    seed: [],
+    status: [],
+    doctor: [
+        '--fix',
+        '--json',
+        '--no-concurrently',
+        '--unused',
+        '--audit',
+        '--min-scans',
+        '--metrics-url',
+        '--no-plan-divergence',
+        '--allow-pooler',
+    ],
+    studio: ['--port', '--host', '--no-open', '--allow-remote', '--write', '--show-pii', '--demo'],
+    mcp: [],
+    observe: ['--port', '--host', '--no-open', '--allow-remote', '--metrics-url'],
+    skill: ['--print', '--agents', '--dir'],
+    help: [],
+    version: [],
+};
+/** Command spellings that dispatch to another command's handler. */
+const COMMAND_ALIASES = {
+    gen: 'generate',
+    g: 'generate',
+    pull: 'generate',
+    migration: 'migrate',
+    m: 'migrate',
+    s: 'seed',
+    info: 'status',
+};
+/**
+ * Long flag to its alternative spelling, for MATCHING and for display.
+ *
+ * Kept out of {@link COMMAND_FLAGS} so a command lists each flag once: the
+ * "valid flags" block a rejection prints reads as one flag per idea, with its
+ * short form attached, rather than as a list twice as long.
+ */
+const FLAG_ALIAS = {
+    '--url': '-u',
+    '--out': '-o',
+    '--schema': '-s',
+    '--step': '-n',
+    '--yes': '-y',
+    '--force': '-f',
+    '--verbose': '-v',
+    '--help': '-h',
+    '--import-ext': '--import-extension',
+};
+/**
+ * The canonical name of `command`, or undefined when nothing dispatches it.
+ *
+ * @internal exported for tests.
+ */
+function canonicalCommand(command) {
+    const resolved = COMMAND_ALIASES[command] ?? command;
+    return resolved in COMMAND_FLAGS ? resolved : undefined;
+}
+/** Every command name a user could reasonably have meant, canonical spellings only. */
+function knownCommands() {
+    return Object.keys(COMMAND_FLAGS);
+}
+/**
+ * The long flags `command` accepts (its own, then the global ones), or
+ * undefined when the command itself is unrecognized.
+ *
+ * An unknown command returns undefined rather than an empty list on purpose:
+ * `turbine genrate --url ...` should be told the COMMAND is misspelled, not
+ * handed a flag error for a flag that is perfectly valid on the command it
+ * meant.
+ *
+ * @internal exported for tests.
+ */
+function flagsForCommand(command) {
+    const canonical = canonicalCommand(command);
+    if (canonical === undefined)
+        return undefined;
+    return { own: COMMAND_FLAGS[canonical] ?? [], global: GLOBAL_FLAGS };
+}
+/** Every token (long + alias) `command` accepts, or undefined for an unknown command. */
+function acceptedFlagTokens(command) {
+    const flags = flagsForCommand(command);
+    if (!flags)
+        return undefined;
+    const tokens = new Set();
+    for (const flag of [...flags.own, ...flags.global]) {
+        tokens.add(flag);
+        const alias = FLAG_ALIAS[flag];
+        if (alias)
+            tokens.add(alias);
+    }
+    return tokens;
+}
+/**
+ * Every flag token any command accepts, long spellings and aliases alike.
+ *
+ * Exists for `src/test/cli-arg-safety.test.ts`, which cross-checks it against
+ * the `case` labels in {@link parseArgs} in both directions. A flag in the
+ * parser but in no command's list is unreachable (the validator rejects it
+ * before the case runs); a flag in a list with no case is accepted and then
+ * silently ignored, which is the bug this whole surface exists to end.
+ *
+ * @internal exported for tests.
+ */
+function allFlagTokens() {
+    const tokens = new Set();
+    for (const command of knownCommands()) {
+        for (const token of acceptedFlagTokens(command) ?? [])
+            tokens.add(token);
+    }
+    return tokens;
+}
+/** `--url` rendered for the help block: `--url, -u`. */
+function displayFlag(flag) {
+    const alias = FLAG_ALIAS[flag];
+    return alias ? `${flag}, ${alias}` : flag;
+}
+/**
+ * Reject the unknown flags on a recognized command, naming the closest real one.
+ *
+ * `closestName` rather than `suggestKey`: the second pass `suggestKey` adds is a
+ * camelCase-word-subsequence match, which does nothing for kebab-case flags.
+ * Long spellings ONLY are offered as candidates, because `nameCloseness` scores
+ * substring containment above edit distance and every short flag is a substring
+ * of something: `--no-opn` contains `-o`, which would otherwise outrank the
+ * `--no-open` the user obviously meant.
+ */
+function failUnknownFlags(command, unknown) {
+    const flags = flagsForCommand(command);
+    const canonical = canonicalCommand(command) ?? command;
+    (0, ui_js_1.errorBanner)();
+    const plural = unknown.length > 1 ? 's' : '';
+    (0, ui_js_1.error)(`Unknown flag${plural} for ${(0, ui_js_1.cyan)(`turbine ${canonical}`)}: ${unknown.map((f) => (0, ui_js_1.bold)(f)).join(' ')}`);
+    (0, ui_js_1.errorLine)();
+    if (flags) {
+        for (const flag of unknown) {
+            const suggestion = (0, utils_js_1.closestName)(flag, [...flags.own, ...flags.global]);
+            if (!suggestion)
+                continue;
+            // With one bad flag the headline already names it; with several, each
+            // suggestion has to say which flag it is about.
+            const subject = unknown.length > 1 ? `${(0, ui_js_1.bold)(flag)} ${ui_js_1.symbols.arrow} ` : '';
+            (0, ui_js_1.errorLine)(`${subject}${(0, ui_js_1.dim)('Did you mean')} ${(0, ui_js_1.cyan)(displayFlag(suggestion))}${(0, ui_js_1.dim)('?')}`);
+        }
+        if (flags.own.length > 0) {
+            (0, ui_js_1.errorLine)();
+            (0, ui_js_1.errorLine)((0, ui_js_1.dim)(`Flags for ${canonical}:`));
+            (0, ui_js_1.errorLine)(`  ${flags.own.map(displayFlag).join('  ')}`);
+        }
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)((0, ui_js_1.dim)('Flags for every command:'));
+        (0, ui_js_1.errorLine)(`  ${flags.global.map(displayFlag).join('  ')}`);
+    }
+    (0, ui_js_1.errorLine)();
+    (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Run')} ${(0, ui_js_1.cyan)(`npx turbine ${canonical} --help`)} ${(0, ui_js_1.dim)('for the full list.')}`);
+    (0, ui_js_1.errorLine)();
     process.exit(1);
 }
 function parseArgs(argv = process.argv.slice(2)) {
@@ -133,9 +357,20 @@ function parseArgs(argv = process.argv.slice(2)) {
         result.subcommand = args[i];
         i++;
     }
+    // The flags this command accepts. `undefined` means the COMMAND is unknown,
+    // in which case nothing here validates flags: main() reports the misspelled
+    // command instead, which is the actual problem.
+    const accepted = acceptedFlagTokens(result.command);
+    const unknownFlags = [];
     for (; i < args.length; i++) {
         const arg = args[i];
         const next = args[i + 1];
+        // Checked BEFORE the switch, and on the same cursor, so a flag's VALUE
+        // (`--step -1`, `--host -x`) is consumed by its own case and never reaches
+        // this test. A bare `-`-prefixed token that is not a flag reaches it and is
+        // rejected: no command takes a negative-number positional.
+        if (accepted && arg.startsWith('-') && !accepted.has(arg))
+            unknownFlags.push(arg);
         switch (arg) {
             case '--url':
             case '-u':
@@ -152,6 +387,10 @@ function parseArgs(argv = process.argv.slice(2)) {
                 result.schema = next;
                 i++;
                 break;
+            case '--schema-file':
+                result.schemaFile = next;
+                i++;
+                break;
             case '--include':
                 result.include = next?.split(',');
                 i++;
@@ -323,6 +562,10 @@ function parseArgs(argv = process.argv.slice(2)) {
                 break;
         }
     }
+    // Reported once, after the whole line is parsed, so two typos on one command
+    // are two lines of one error rather than two runs of the CLI.
+    if (unknownFlags.length > 0)
+        failUnknownFlags(result.command, unknownFlags);
     return result;
 }
 // ---------------------------------------------------------------------------
@@ -333,35 +576,35 @@ function parseArgs(argv = process.argv.slice(2)) {
  * Called when we know we need to load a `.ts` file but the loader isn't available.
  */
 function failMissingTsLoader(filePath, reason) {
-    (0, ui_js_1.newline)();
+    (0, ui_js_1.errorLine)();
     (0, ui_js_1.error)(`Cannot load TypeScript file: ${filePath}`);
-    (0, ui_js_1.newline)();
+    (0, ui_js_1.errorLine)();
     if (reason === 'unsupported') {
-        console.log(`  ${(0, ui_js_1.dim)('Your Node.js version does not support')} ${(0, ui_js_1.cyan)('module.register()')}.`);
-        console.log(`  ${(0, ui_js_1.dim)('Upgrade to Node.js')} ${(0, ui_js_1.cyan)('20.6+')} ${(0, ui_js_1.dim)('or use a')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('/')} ${(0, ui_js_1.cyan)('.mjs')} ${(0, ui_js_1.dim)('config file.')}`);
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Your Node.js version does not support')} ${(0, ui_js_1.cyan)('module.register()')}.`);
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Upgrade to Node.js')} ${(0, ui_js_1.cyan)('20.6+')} ${(0, ui_js_1.dim)('or use a')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('/')} ${(0, ui_js_1.cyan)('.mjs')} ${(0, ui_js_1.dim)('config file.')}`);
     }
     else if (reason === 'failed') {
         // tsx IS installed but registering its loader threw. Report the real
         // cause, telling the user to install tsx here would be a misdiagnosis.
-        console.log(`  ${(0, ui_js_1.dim)('tsx is installed, but registering its TypeScript loader failed:')}`);
-        (0, ui_js_1.newline)();
-        console.log(`    ${(0, loader_js_1.getTsLoaderError)() ?? '(unknown error)'}`);
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Try upgrading tsx:')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx@latest')}${(0, ui_js_1.dim)(', or rename your file to')} ${(0, ui_js_1.cyan)('.mjs')}.`);
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('tsx is installed, but registering its TypeScript loader failed:')}`);
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`  ${(0, loader_js_1.getTsLoaderError)() ?? '(unknown error)'}`);
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Try upgrading tsx:')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx@latest')}${(0, ui_js_1.dim)(', or rename your file to')} ${(0, ui_js_1.cyan)('.mjs')}.`);
     }
     else {
-        console.log(`  ${(0, ui_js_1.dim)('Loading .ts config / schema files requires')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to be installed.')}`);
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Install it as a dev dependency:')}`);
-        console.log(`    ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
-        console.log(`    ${(0, ui_js_1.dim)('or')}`);
-        console.log(`    ${(0, ui_js_1.cyan)('pnpm add -D tsx')}`);
-        console.log(`    ${(0, ui_js_1.dim)('or')}`);
-        console.log(`    ${(0, ui_js_1.cyan)('yarn add -D tsx')}`);
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Alternatively, rename your file to')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('or')} ${(0, ui_js_1.cyan)('.mjs')}.`);
-    }
-    (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Loading .ts config / schema files requires')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to be installed.')}`);
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Install it as a dev dependency:')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('or')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.cyan)('pnpm add -D tsx')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('or')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.cyan)('yarn add -D tsx')}`);
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Alternatively, rename your file to')} ${(0, ui_js_1.cyan)('.js')} ${(0, ui_js_1.dim)('or')} ${(0, ui_js_1.cyan)('.mjs')}.`);
+    }
+    (0, ui_js_1.errorLine)();
     process.exit(1);
 }
 // ---------------------------------------------------------------------------
@@ -410,20 +653,20 @@ async function bootstrapCliConfig(args, overrides) {
 function requireUrl(config, options = {}) {
     if (!config.url) {
         (0, ui_js_1.error)('No database URL provided.');
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Set it in one of these ways:')}`);
-        console.log(`    ${(0, ui_js_1.dim)('1.')} Add ${(0, ui_js_1.cyan)('url')} to ${(0, ui_js_1.cyan)('turbine.config.ts')}`);
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Set it in one of these ways:')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('1.')} Add ${(0, ui_js_1.cyan)('url')} to ${(0, ui_js_1.cyan)('turbine.config.ts')}`);
         // .env auto-load needs Node 20.12+ (process.loadEnvFile); be honest below it.
         const envFileNote = typeof process.loadEnvFile === 'function' ? '(auto-loaded)' : '(needs Node 20.12+ to auto-load)';
-        console.log(`    ${(0, ui_js_1.dim)('2.')} Set ${(0, ui_js_1.cyan)('DATABASE_URL')} in your environment or a ${(0, ui_js_1.cyan)('.env')} file ${(0, ui_js_1.dim)(envFileNote)}`);
-        console.log(`    ${(0, ui_js_1.dim)('3.')} Pass ${(0, ui_js_1.cyan)('--url')} flag`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('2.')} Set ${(0, ui_js_1.cyan)('DATABASE_URL')} in your environment or a ${(0, ui_js_1.cyan)('.env')} file ${(0, ui_js_1.dim)(envFileNote)}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('3.')} Pass ${(0, ui_js_1.cyan)('--url')} flag`);
         const vars = options.datasourceVars ?? [];
         if (vars.length > 0) {
             const list = vars.map((v) => (0, ui_js_1.cyan)(v)).join(', ');
             const plural = vars.length > 1 ? 'these variables' : 'this variable';
-            console.log(`    ${(0, ui_js_1.dim)('4.')} Set ${list} ${(0, ui_js_1.dim)(`(${plural}, declared by your schema.prisma datasource, ${vars.length > 1 ? 'are' : 'is'} unset)`)}`);
+            (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('4.')} Set ${list} ${(0, ui_js_1.dim)(`(${plural}, declared by your schema.prisma datasource, ${vars.length > 1 ? 'are' : 'is'} unset)`)}`);
         }
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     return config.url;
@@ -432,7 +675,7 @@ async function loadSchemaFile(schemaFile) {
     const absPath = (0, node_path_1.resolve)(schemaFile);
     if (!(0, node_fs_1.existsSync)(absPath)) {
         (0, ui_js_1.error)(`Schema file not found: ${schemaFile}`);
-        console.log(`  ${(0, ui_js_1.dim)('Create one with:')} ${(0, ui_js_1.cyan)('turbine init')}`);
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Create one with:')} ${(0, ui_js_1.cyan)('turbine init')}`);
         process.exit(1);
     }
     // If this is a TypeScript file, ensure the tsx ESM loader is registered
@@ -461,11 +704,11 @@ async function loadSchemaFile(schemaFile) {
     catch (err) {
         (0, ui_js_1.error)(`Failed to load schema file: ${schemaFile}`);
         if (err instanceof Error) {
-            console.log(`  ${(0, ui_js_1.dim)(err.message)}`);
+            (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)(err.message)}`);
             // If the error is the classic ERR_UNKNOWN_FILE_EXTENSION, give a hint.
             if (err.message.includes('ERR_UNKNOWN_FILE_EXTENSION') || err.message.includes('Unknown file extension')) {
-                (0, ui_js_1.newline)();
-                console.log(`  ${(0, ui_js_1.dim)('Hint: install')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to load .ts files:')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
+                (0, ui_js_1.errorLine)();
+                (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Hint: install')} ${(0, ui_js_1.cyan)('tsx')} ${(0, ui_js_1.dim)('to load .ts files:')} ${(0, ui_js_1.cyan)('npm install --save-dev tsx')}`);
             }
             printCjsHintIfApplicable(err);
         }
@@ -484,9 +727,9 @@ function printCjsHintIfApplicable(err) {
     if (msg.includes('ERR_REQUIRE_ESM') ||
         msg.includes('require() of ES Module') ||
         msg.includes('Cannot require() ES Module')) {
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Hint: add')} ${(0, ui_js_1.cyan)('"type": "module"')} ${(0, ui_js_1.dim)('to your')} ${(0, ui_js_1.cyan)('package.json')}${(0, ui_js_1.dim)('.')}`);
-        console.log(`  ${(0, ui_js_1.dim)('Turbine is an ESM package; without it, Node/tsx tries to')} ${(0, ui_js_1.cyan)('require()')} ${(0, ui_js_1.dim)('it and fails.')}`);
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Hint: add')} ${(0, ui_js_1.cyan)('"type": "module"')} ${(0, ui_js_1.dim)('to your')} ${(0, ui_js_1.cyan)('package.json')}${(0, ui_js_1.dim)('.')}`);
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Turbine is an ESM package; without it, Node/tsx tries to')} ${(0, ui_js_1.cyan)('require()')} ${(0, ui_js_1.dim)('it and fails.')}`);
     }
 }
 /**
@@ -788,7 +1031,54 @@ export default defineSeed(async (db) => {
   console.log('Done!');
 });
 `;
-const INIT_SCHEMA_TEMPLATE = `/**
+/**
+ * The starter schema, with two real tables and a foreign key between them.
+ *
+ * Scaffolded ONLY when the target database has no tables of its own (see
+ * {@link initSchemaTemplate}). An all-commented-out schema next to an empty
+ * database is a dead end: `push` reports "Database already in sync",
+ * `generate` refuses to emit an empty client, and the next-steps text ends up
+ * describing a `db.users` that does not exist. Two tables rather than one
+ * because the relation is what the very next query in the quickstart reads.
+ */
+const INIT_SCHEMA_EXAMPLE = `/**
+ * Turbine schema definition
+ *
+ * Define your database schema in TypeScript.
+ * Use \`npx turbine push\` to sync it to your database, then
+ * \`npx turbine generate\` to emit the typed client.
+ *
+ * This starter is a working example. Rename it, edit it, or replace it
+ * entirely: nothing here is special to Turbine.
+ *
+ * @see https://turbineorm.dev
+ */
+
+import { defineSchema } from 'turbine-orm';
+
+export default defineSchema({
+  users: {
+    id: { type: 'serial', primaryKey: true },
+    email: { type: 'text', notNull: true, unique: true },
+    name: { type: 'text', notNull: true },
+    created_at: { type: 'timestamptz', notNull: true, default: 'NOW()' },
+  },
+  posts: {
+    id: { type: 'serial', primaryKey: true },
+    user_id: { type: 'integer', notNull: true, references: 'users.id' },
+    title: { type: 'text', notNull: true },
+    published: { type: 'boolean', notNull: true, default: 'false' },
+    created_at: { type: 'timestamptz', notNull: true, default: 'NOW()' },
+  },
+});
+`;
+/**
+ * The starter schema with nothing defined, for the one case where a real
+ * example could collide: `init --with-schema` beside a database that already
+ * has tables. There, an example `users` table is a schema diff against
+ * somebody's real data, so the file stays a comment.
+ */
+const INIT_SCHEMA_PLACEHOLDER = `/**
  * Turbine schema definition
  *
  * Define your database schema in TypeScript.
@@ -800,15 +1090,27 @@ const INIT_SCHEMA_TEMPLATE = `/**
 import { defineSchema } from 'turbine-orm';
 
 export default defineSchema({
-  // Example:
+  // Your database already has tables, so this file starts empty on purpose:
+  // \`turbine push\` applies exactly what is declared here. Describe the tables
+  // you want Turbine to own, or run \`npx turbine generate\` to work from the
+  // database as it already is.
+  //
   // users: {
   //   id: { type: 'serial', primaryKey: true },
   //   email: { type: 'text', notNull: true, unique: true },
   //   name: { type: 'text', notNull: true },
-  //   created_at: { type: 'timestamp', default: 'NOW()' },
+  //   created_at: { type: 'timestamptz', notNull: true, default: 'NOW()' },
   // },
 });
 `;
+/**
+ * Which starter schema to scaffold.
+ *
+ * @internal exported for tests.
+ */
+function initSchemaTemplate(dbHasTables) {
+    return dbHasTables ? INIT_SCHEMA_PLACEHOLDER : INIT_SCHEMA_EXAMPLE;
+}
 /**
  * Does this `.gitignore` text already ignore `.env`?
  *
@@ -961,12 +1263,15 @@ function ensureInitScaffoldDirs(config) {
         }
     }
 }
-function writeInitSchemaTemplate(config) {
+function writeInitSchemaTemplate(config, dbHasTables) {
     const schemaDir = (0, node_path_1.dirname)(config.schemaFile);
     if (schemaDir && !(0, node_fs_1.existsSync)(schemaDir))
         (0, node_fs_1.mkdirSync)(schemaDir, { recursive: true });
-    (0, node_fs_1.writeFileSync)(config.schemaFile, INIT_SCHEMA_TEMPLATE, 'utf-8');
+    (0, node_fs_1.writeFileSync)(config.schemaFile, initSchemaTemplate(dbHasTables), 'utf-8');
     (0, ui_js_1.success)(`Created ${(0, ui_js_1.cyan)(config.schemaFile)}`);
+    if (!dbHasTables) {
+        console.log(`  ${(0, ui_js_1.dim)('It defines a')} ${(0, ui_js_1.cyan)('users')} ${(0, ui_js_1.dim)('and a')} ${(0, ui_js_1.cyan)('posts')} ${(0, ui_js_1.dim)('table to start from.')}`);
+    }
 }
 function writeInitSeedTemplate(seedFilePath) {
     const seedDir = (0, node_path_1.dirname)(seedFilePath);
@@ -1016,6 +1321,28 @@ async function runInitPush(config, url) {
         (0, ui_js_1.success)(`Applied ${(0, ui_js_1.bold)(String(result.statementsExecuted))} statement(s)`);
     }
 }
+/**
+ * The exact import line for the generated client, extension included.
+ *
+ * `import { turbine } from './generated/turbine'` is a hard TypeScript error
+ * (TS2834) under `moduleResolution: NodeNext`, which is what this package ships
+ * and what its own tsconfig uses: a relative import needs an explicit file
+ * extension, and NodeNext does no directory-index resolution either. The
+ * generator has always appended the extension to its OWN sibling imports; the
+ * line printed at the reader was the one place it never reached.
+ *
+ * The extension comes from {@link resolveImportExtension}, the same resolver the
+ * generator runs, so the printed line matches the files just written rather
+ * than a second guess about the consumer's tsconfig. Under bundler resolution
+ * it resolves to `''` and the directory form is correct as-is.
+ *
+ * @internal exported for tests.
+ */
+function generatedClientImport(config) {
+    const dir = `./${config.out.replace(/^\.\//, '').replace(/\/+$/, '')}`;
+    const { ext } = (0, generate_js_1.resolveImportExtension)(config.out, config.importExtension);
+    return `import { turbine } from '${ext === '' ? dir : `${dir}/index${ext}`}';`;
+}
 /** Introspect the database and generate the typed client. */
 async function runInitGenerate(config, url) {
     const spinner = new ui_js_1.Spinner('Introspecting database').start();
@@ -1027,16 +1354,22 @@ async function runInitGenerate(config, url) {
             exclude: config.exclude.length ? config.exclude : undefined,
             relationNames: config.relationNames,
         });
-        spinner.succeed(`Found ${(0, ui_js_1.bold)(String(Object.keys(schema.tables).length))} tables`);
+        const tableNames = Object.keys(schema.tables);
+        spinner.succeed(`Found ${(0, ui_js_1.bold)(String(tableNames.length))} tables`);
         const genSpinner = new ui_js_1.Spinner('Generating TypeScript client').start();
         const result = (0, generate_js_1.generate)({ schema, outDir: config.out, connectionString: url });
         genSpinner.succeed(`Generated ${(0, ui_js_1.bold)(String(result.files.length))} files to ${(0, ui_js_1.cyan)(`${config.out}/`)}`);
+        // The accessor name the generator emits is snakeToCamel of the table name
+        // (generate.ts, generateIndex), so this is the spelling that autocompletes.
+        const first = tableNames[0];
+        return { tableCount: tableNames.length, sampleAccessor: first ? (0, schema_js_1.snakeToCamel)(first) : undefined };
     }
     catch (err) {
         spinner.fail('Could not generate client');
         if (err instanceof Error)
-            console.log(`  ${(0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.message))}`);
+            (0, ui_js_1.errorLine)((0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.message)));
         (0, ui_js_1.info)(`Run generation later with: ${(0, ui_js_1.cyan)('npx turbine generate')}`);
+        return { tableCount: null };
     }
 }
 /** Run the seed file. */
@@ -1260,6 +1593,10 @@ async function cmdInit(args, config) {
     (0, ui_js_1.newline)();
     // TypeScript files this run actually created: they drive the tsx heads-up below.
     const tsFilesWritten = [];
+    // What the generate step produced, if it ran. The next-steps text is derived
+    // from this rather than assumed, so it cannot promise a `db.users` the
+    // generated client does not have.
+    let generated = { tableCount: null };
     // Execute the plan in order. `run` proceeds; `prompt` asks; `skip` reports.
     for (const step of plan) {
         if (step.action === 'skip') {
@@ -1287,7 +1624,7 @@ async function cmdInit(args, config) {
                 break;
             }
             case 'schema':
-                writeInitSchemaTemplate(config);
+                writeInitSchemaTemplate(config, state.dbHasTables === true);
                 if ((0, loader_js_1.needsTsLoader)(config.schemaFile))
                     tsFilesWritten.push(config.schemaFile);
                 break;
@@ -1300,7 +1637,7 @@ async function cmdInit(args, config) {
                 await runInitPush(config, url);
                 break;
             case 'generate':
-                await runInitGenerate(config, url);
+                generated = await runInitGenerate(config, url);
                 break;
             case 'seed-run':
                 await runInitSeed(config);
@@ -1339,20 +1676,84 @@ async function cmdInit(args, config) {
         if (!tsxMissing && !(0, loader_js_1.canResolveTsx)()) {
             console.log(`     ${(0, ui_js_1.dim)('Note: the TypeScript config requires')} ${(0, ui_js_1.cyan)('tsx')}: ${(0, ui_js_1.cyan)(tsxInstallCommand(detectPackageManager()))}`);
         }
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('3.')} Create migrations: ${(0, ui_js_1.cyan)('npx turbine migrate create <name>')}`);
+        console.log(`  ${(0, ui_js_1.dim)('4.')} Run migrations:    ${(0, ui_js_1.cyan)('npx turbine migrate up')}`);
+        console.log(`  ${(0, ui_js_1.dim)('5.')} Seed your database: ${(0, ui_js_1.cyan)('npx turbine seed')}`);
+    }
+    else if (generated.tableCount === null || generated.tableCount === 0) {
+        // There is no typed client to import: either generate did not run (push /
+        // generate declined or skipped), or it ran against a database with no
+        // tables and emitted a client with no accessors. Printing
+        // `await db.users.findMany()` here is the single most misleading line the
+        // CLI produces, because the reader has no way to know it cannot work.
+        console.log(`  ${(0, ui_js_1.dim)('1.')} Describe your tables in ${(0, ui_js_1.cyan)(config.schemaFile)}`);
+        console.log(`  ${(0, ui_js_1.dim)('2.')} Create them:         ${(0, ui_js_1.cyan)('npx turbine push')}`);
+        console.log(`  ${(0, ui_js_1.dim)('3.')} Emit the client:     ${(0, ui_js_1.cyan)('npx turbine generate')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Until a table exists, the generated client has no table accessors, so')}`);
+        console.log(`  ${(0, ui_js_1.dim)('there is nothing to import yet. Working from a database you already')}`);
+        console.log(`  ${(0, ui_js_1.dim)('have? Skip step 1 and run')} ${(0, ui_js_1.cyan)('npx turbine generate')} ${(0, ui_js_1.dim)('on its own.')}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('Nothing to connect to yet?')} ${(0, ui_js_1.cyan)('npx turbine studio --demo')} ${(0, ui_js_1.dim)('needs no database.')}`);
     }
     else {
+        const accessor = generated.sampleAccessor ?? 'users';
         console.log(`  ${(0, ui_js_1.dim)('1.')} Import the generated client:`);
-        console.log(`     ${(0, ui_js_1.cyan)(`import { turbine } from './${config.out.replace('./', '')}';`)}`);
+        console.log(`     ${(0, ui_js_1.cyan)(generatedClientImport(config))}`);
         (0, ui_js_1.newline)();
         console.log(`  ${(0, ui_js_1.dim)('2.')} Create a connection and query:`);
         console.log(`     ${(0, ui_js_1.dim)('const db = turbine();')}`);
-        console.log(`     ${(0, ui_js_1.dim)('const users = await db.users.findMany();')}`);
+        console.log(`     ${(0, ui_js_1.dim)(`const rows = await db.${accessor}.findMany();`)}`);
+        (0, ui_js_1.newline)();
+        console.log(`  ${(0, ui_js_1.dim)('3.')} Create migrations: ${(0, ui_js_1.cyan)('npx turbine migrate create <name>')}`);
+        console.log(`  ${(0, ui_js_1.dim)('4.')} Run migrations:    ${(0, ui_js_1.cyan)('npx turbine migrate up')}`);
+        console.log(`  ${(0, ui_js_1.dim)('5.')} Seed your database: ${(0, ui_js_1.cyan)('npx turbine seed')}`);
     }
     (0, ui_js_1.newline)();
-    console.log(`  ${(0, ui_js_1.dim)('3.')} Create migrations: ${(0, ui_js_1.cyan)('npx turbine migrate create <name>')}`);
-    console.log(`  ${(0, ui_js_1.dim)('4.')} Run migrations:    ${(0, ui_js_1.cyan)('npx turbine migrate up')}`);
-    console.log(`  ${(0, ui_js_1.dim)('5.')} Seed your database: ${(0, ui_js_1.cyan)('npx turbine seed')}`);
-    (0, ui_js_1.newline)();
+}
+// ---------------------------------------------------------------------------
+// `--schema` is the namespace, `--schema-file` is the file
+// ---------------------------------------------------------------------------
+/**
+ * Refuse a `schema` that is plainly a FILE PATH, on every command that reads it
+ * as a Postgres namespace.
+ *
+ * `--schema` / `-s` sets the namespace to introspect (default `public`). The
+ * defineSchema() file is a different idea entirely, and mistaking the two is
+ * silent on every command that used to accept it: `generate` introspects
+ * `WHERE table_schema = './turbine/schema.ts'` and matches nothing, and `push`
+ * reads `config.schemaFile` instead and reports
+ * "Schema file not found: ./turbine/schema.ts", naming a path the reader never
+ * typed while their schema file sits in the directory they ran it from.
+ *
+ * The check was written for `generate` and wired into `generate` alone, which is
+ * how `push`, the command whose flag name the mistake is actually about, kept
+ * the bad error. It is one function called from every `--schema` command now,
+ * for the same reason `resolveColumnName` is one function: two copies of a rule
+ * is how two commands come to disagree about whether an argument is valid.
+ *
+ * @internal exported for tests.
+ */
+function refuseSchemaFilePath(config, options = {}) {
+    if (!(0, config_js_1.looksLikeSchemaFilePath)(config.schema))
+        return;
+    (0, ui_js_1.error)(`The ${(0, ui_js_1.cyan)('--schema')} value looks like a file path: ${(0, ui_js_1.cyan)(config.schema)}`);
+    (0, ui_js_1.errorLine)();
+    (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Did you mean')} ${(0, ui_js_1.cyan)(`--schema-file ${config.schema}`)}${(0, ui_js_1.dim)('?')}`);
+    (0, ui_js_1.errorLine)();
+    (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('--schema is the Postgres schema NAME to read')} ${(0, ui_js_1.dim)('(default:')} ${(0, ui_js_1.cyan)('public')}${(0, ui_js_1.dim)(').')}`);
+    (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('--schema-file is the path to your')} ${(0, ui_js_1.cyan)('defineSchema()')} ${(0, ui_js_1.dim)('file')} ${(0, ui_js_1.dim)(`(default: ${config.schemaFile}).`)}`);
+    (0, ui_js_1.errorLine)();
+    (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Or set it once in')} ${(0, ui_js_1.cyan)('turbine.config.ts')}${(0, ui_js_1.dim)(':')}`);
+    (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.green)('schema:')} ${(0, ui_js_1.cyan)("'public'")}${(0, ui_js_1.dim)(",       // or omit, reads the 'public' schema")}`);
+    (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.green)('schemaFile:')} ${(0, ui_js_1.cyan)(`'${config.schema}'`)}${(0, ui_js_1.dim)(', // your defineSchema() file (used by `turbine push`)')}`);
+    if (options.escapeHatch) {
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Re-run with')} ${(0, ui_js_1.cyan)(options.escapeHatch)} ${(0, ui_js_1.dim)('to use this literal schema name anyway.')}`);
+    }
+    (0, ui_js_1.errorLine)();
+    process.exit(1);
 }
 // ---------------------------------------------------------------------------
 // Command: generate (pull)
@@ -1361,24 +1762,11 @@ async function cmdGenerate(args, config) {
     (0, ui_js_1.banner)();
     const url = requireUrl(config);
     const startTime = performance.now();
-    // Guard: `schema` is the Postgres NAMESPACE to introspect (default `public`),
-    // NOT the path to your schema-builder file, that goes in `schemaFile`. If the
-    // configured `schema` looks like a file path, introspection would silently
-    // match zero tables and emit an empty client. Fail loudly instead.
-    if (!args.allowEmpty && (0, config_js_1.looksLikeSchemaFilePath)(config.schema)) {
-        (0, ui_js_1.error)(`The "schema" option looks like a file path: ${(0, ui_js_1.cyan)(config.schema)}`);
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('"schema" is the Postgres schema NAME to introspect')} ${(0, ui_js_1.dim)('(default:')} ${(0, ui_js_1.cyan)('public')}${(0, ui_js_1.dim)(').')}`);
-        console.log(`  ${(0, ui_js_1.dim)('The path to your defineSchema() file belongs in')} ${(0, ui_js_1.cyan)('schemaFile')}${(0, ui_js_1.dim)('.')}`);
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Fix your')} ${(0, ui_js_1.cyan)('turbine.config.ts')}${(0, ui_js_1.dim)(':')}`);
-        console.log(`    ${(0, ui_js_1.green)('schema:')} ${(0, ui_js_1.cyan)("'public'")}${(0, ui_js_1.dim)(",       // or omit, introspects the 'public' schema")}`);
-        console.log(`    ${(0, ui_js_1.green)('schemaFile:')} ${(0, ui_js_1.cyan)(`'${config.schema}'`)}${(0, ui_js_1.dim)(', // your defineSchema() file (used by `turbine push`)')}`);
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Re-run with')} ${(0, ui_js_1.cyan)('--allow-empty')} ${(0, ui_js_1.dim)('to introspect this literal schema name anyway.')}`);
-        (0, ui_js_1.newline)();
-        process.exit(1);
-    }
+    // `--allow-empty` is generate's documented escape hatch for introspecting a
+    // literal schema name that happens to look like a path, so it SKIPS the
+    // refusal rather than merely being named by it.
+    if (args.allowEmpty !== true)
+        refuseSchemaFilePath(config, { escapeHatch: '--allow-empty' });
     (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
     (0, ui_js_1.label)('Schema', config.schema);
     (0, ui_js_1.label)('Output', config.out);
@@ -1412,15 +1800,15 @@ async function cmdGenerate(args, config) {
     if (tableNames.length === 0 && !args.allowEmpty) {
         (0, ui_js_1.newline)();
         (0, ui_js_1.error)(`Introspection matched 0 tables in schema ${(0, ui_js_1.cyan)(config.schema)}, refusing to generate an empty client.`);
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Common causes:')}`);
-        console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.cyan)('schema')} ${(0, ui_js_1.dim)('points at the wrong Postgres namespace')} ${(0, ui_js_1.dim)('(it is the schema NAME, default')} ${(0, ui_js_1.cyan)('public')}${(0, ui_js_1.dim)(').')}`);
-        console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.dim)('You meant to set')} ${(0, ui_js_1.cyan)('schemaFile')} ${(0, ui_js_1.dim)('(your defineSchema() file), not')} ${(0, ui_js_1.cyan)('schema')}${(0, ui_js_1.dim)('.')}`);
-        console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.cyan)('include')}/${(0, ui_js_1.cyan)('exclude')} ${(0, ui_js_1.dim)('filtered out every table.')}`);
-        console.log(`    ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.dim)('The database has no tables yet, run')} ${(0, ui_js_1.cyan)('turbine push')} ${(0, ui_js_1.dim)('or a migration first.')}`);
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('If an empty client is genuinely what you want, re-run with')} ${(0, ui_js_1.cyan)('--allow-empty')}${(0, ui_js_1.dim)('.')}`);
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Common causes:')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.cyan)('schema')} ${(0, ui_js_1.dim)('points at the wrong Postgres namespace')} ${(0, ui_js_1.dim)('(it is the schema NAME, default')} ${(0, ui_js_1.cyan)('public')}${(0, ui_js_1.dim)(').')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.dim)('You meant to set')} ${(0, ui_js_1.cyan)('schemaFile')} ${(0, ui_js_1.dim)('(your defineSchema() file), not')} ${(0, ui_js_1.cyan)('schema')}${(0, ui_js_1.dim)('.')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.cyan)('include')}/${(0, ui_js_1.cyan)('exclude')} ${(0, ui_js_1.dim)('filtered out every table.')}`);
+        (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('•')} ${(0, ui_js_1.dim)('The database has no tables yet, run')} ${(0, ui_js_1.cyan)('turbine push')} ${(0, ui_js_1.dim)('or a migration first.')}`);
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('If an empty client is genuinely what you want, re-run with')} ${(0, ui_js_1.cyan)('--allow-empty')}${(0, ui_js_1.dim)('.')}`);
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     // Print table summary
@@ -1458,9 +1846,11 @@ async function cmdGenerate(args, config) {
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Usage:')}`);
     (0, ui_js_1.newline)();
-    console.log(`  ${(0, ui_js_1.cyan)(`import { turbine } from './${config.out.replace('./', '')}';`)}`);
+    console.log(`  ${(0, ui_js_1.cyan)(generatedClientImport(config))}`);
     console.log(`  ${(0, ui_js_1.dim)('const db = turbine({ connectionString: process.env.DATABASE_URL });')}`);
-    console.log(`  ${(0, ui_js_1.dim)('const user = await db.users.findUnique({ where: { id: 1 } });')}`);
+    // Name a table the client just emitted rather than a hardcoded `users`.
+    const sampleAccessor = (0, schema_js_1.snakeToCamel)(tableNames[0] ?? 'users');
+    console.log(`  ${(0, ui_js_1.dim)(`const row = await db.${sampleAccessor}.findFirst();`)}`);
     (0, ui_js_1.newline)();
 }
 /**
@@ -1520,10 +1910,10 @@ async function cmdMigrateFromPrisma(args, config) {
     }
     if (!(0, node_fs_1.existsSync)(prismaPath)) {
         (0, ui_js_1.error)(`Prisma schema not found: ${(0, ui_js_1.cyan)(prismaPath)}`);
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Point at it with')} ${(0, ui_js_1.cyan)('--schema <path>')} ${(0, ui_js_1.dim)('(a .prisma file, or a directory of them;')}`);
-        console.log(`  ${(0, ui_js_1.dim)('default: prisma/schema.prisma, then prisma/schema/).')}`);
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Point at it with')} ${(0, ui_js_1.cyan)('--schema <path>')} ${(0, ui_js_1.dim)('(a .prisma file, or a directory of them;')}`);
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('default: prisma/schema.prisma, then prisma/schema/).')}`);
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     // Parse (fatal only on a construct we must understand).
@@ -1534,8 +1924,8 @@ async function cmdMigrateFromPrisma(args, config) {
     catch (err) {
         (0, ui_js_1.newline)();
         (0, ui_js_1.error)(`Could not read ${(0, ui_js_1.cyan)(prismaPath)}`);
-        console.log(`  ${(0, ui_js_1.red)(err instanceof Error ? err.message : String(err))}`);
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.red)(err instanceof Error ? err.message : String(err))}`);
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     let ast;
@@ -1546,8 +1936,8 @@ async function cmdMigrateFromPrisma(args, config) {
         if (err instanceof prisma_schema_js_1.PrismaParseError) {
             (0, ui_js_1.newline)();
             (0, ui_js_1.error)(`Could not parse ${(0, ui_js_1.cyan)(prismaPath)}`);
-            console.log(`  ${(0, ui_js_1.red)(err.message)}`);
-            (0, ui_js_1.newline)();
+            (0, ui_js_1.errorLine)(`${(0, ui_js_1.red)(err.message)}`);
+            (0, ui_js_1.errorLine)();
             process.exit(1);
         }
         throw err;
@@ -1626,7 +2016,7 @@ async function cmdMigrateFromPrisma(args, config) {
     const rel = (0, node_path_1.relative)(process.cwd(), outDir);
     if (rel.startsWith('..') || (0, node_path_1.resolve)(rel) !== outDir) {
         (0, ui_js_1.error)(`Output directory must be within the project root. Got: ${config.out}`);
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
@@ -1690,6 +2080,7 @@ async function cmdMigrateFromPrisma(args, config) {
 // ---------------------------------------------------------------------------
 async function cmdPush(args, config) {
     (0, ui_js_1.banner)();
+    refuseSchemaFilePath(config);
     const url = requireUrl(config);
     (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
     (0, ui_js_1.label)('Schema file', config.schemaFile);
@@ -1870,34 +2261,37 @@ async function cmdMigrate(args, config) {
             break;
         default:
             (0, ui_js_1.error)(`Unknown migrate subcommand: ${sub}`);
-            console.log(`  ${(0, ui_js_1.dim)('Run')} ${(0, ui_js_1.cyan)('npx turbine migrate help')} ${(0, ui_js_1.dim)('for usage.')}`);
+            (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Run')} ${(0, ui_js_1.cyan)('npx turbine migrate help')} ${(0, ui_js_1.dim)('for usage.')}`);
             process.exit(1);
     }
 }
 async function cmdMigrateCreate(args, config) {
     (0, ui_js_1.banner)();
+    // `--auto` / `--from-diff` diff the schema FILE against the namespace, so both
+    // halves of the confusion are live on this one command.
+    refuseSchemaFilePath(config);
     const name = args.positional[0];
     if (!name) {
         (0, ui_js_1.error)('Migration name is required.');
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Usage:')} ${(0, ui_js_1.cyan)('npx turbine migrate create <name>')}`);
-        console.log(`  ${(0, ui_js_1.dim)('Example:')} ${(0, ui_js_1.cyan)('npx turbine migrate create add_users_table')}`);
-        console.log(`  ${(0, ui_js_1.dim)('Auto:')}    ${(0, ui_js_1.cyan)('npx turbine migrate create my_change --auto')}`);
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Usage:')} ${(0, ui_js_1.cyan)('npx turbine migrate create <name>')}`);
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Example:')} ${(0, ui_js_1.cyan)('npx turbine migrate create add_users_table')}`);
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Auto:')}    ${(0, ui_js_1.cyan)('npx turbine migrate create my_change --auto')}`);
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     // The scaffold strategies each own the file body, so combining them is
     // ambiguous. Refuse up front (before any of the strategy blocks run).
     if (args.fromDiff && args.recipe) {
         (0, ui_js_1.error)('--from-diff cannot be combined with --recipe.');
-        console.log(`  ${(0, ui_js_1.dim)('Pick one: --from-diff generates from the schema diff, --recipe scaffolds a pattern.')}`);
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Pick one: --from-diff generates from the schema diff, --recipe scaffolds a pattern.')}`);
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     if (args.fromDiff && args.auto) {
         (0, ui_js_1.error)('--from-diff cannot be combined with --auto.');
-        console.log(`  ${(0, ui_js_1.dim)('Both generate from the schema diff; --from-diff also flags destructive statements.')}`);
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Both generate from the schema diff; --from-diff also flags destructive statements.')}`);
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     if (args.auto) {
@@ -2051,12 +2445,12 @@ async function cmdMigrateCreate(args, config) {
     if (args.recipe) {
         if (!migrate_js_1.MIGRATION_RECIPES[args.recipe]) {
             (0, ui_js_1.error)(`Unknown migration recipe: ${args.recipe}`);
-            (0, ui_js_1.newline)();
-            console.log(`  ${(0, ui_js_1.dim)('Available recipes:')}`);
+            (0, ui_js_1.errorLine)();
+            (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Available recipes:')}`);
             for (const [key, recipe] of Object.entries(migrate_js_1.MIGRATION_RECIPES)) {
-                console.log(`    ${(0, ui_js_1.cyan)(key)}  ${(0, ui_js_1.dim)(recipe.description)}`);
+                (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.cyan)(key)}  ${(0, ui_js_1.dim)(recipe.description)}`);
             }
-            (0, ui_js_1.newline)();
+            (0, ui_js_1.errorLine)();
             process.exit(1);
         }
         const file = (0, migrate_js_1.createMigration)(config.migrationsDir, name, undefined, { recipe: args.recipe });
@@ -2254,11 +2648,11 @@ async function cmdMigrateDeploy(args, config) {
     if (plan.mismatches.length > 0) {
         if (!args.allowDrift) {
             (0, ui_js_1.error)('Deploy blocked by migration drift');
-            (0, ui_js_1.newline)();
+            (0, ui_js_1.errorLine)();
             for (const line of (0, migrate_js_1.formatChecksumMismatchError)(plan.mismatches).split('\n')) {
-                console.log(`  ${line.replace('[turbine] ', '')}`);
+                (0, ui_js_1.errorLine)(`${line.replace('[turbine] ', '')}`);
             }
-            (0, ui_js_1.newline)();
+            (0, ui_js_1.errorLine)();
             process.exit(1);
         }
         (0, ui_js_1.warn)('--allow-drift is set: checksum validation is DISABLED for this deploy.');
@@ -2589,6 +2983,7 @@ async function cmdSeed(_args, config) {
 // ---------------------------------------------------------------------------
 async function cmdStatus(_args, config) {
     (0, ui_js_1.banner)();
+    refuseSchemaFilePath(config);
     const url = requireUrl(config);
     (0, ui_js_1.label)('Database', (0, ui_js_1.redactUrl)(url));
     (0, ui_js_1.label)('Schema', config.schema);
@@ -2728,6 +3123,7 @@ function refusePoolerConnection(url, args) {
 }
 async function cmdDoctor(args, config) {
     const jsonMode = args.json === true;
+    refuseSchemaFilePath(config);
     const url = requireUrl(config);
     // Before the banner, before introspect, before any pool is constructed.
     refusePoolerConnection(url, args);
@@ -3475,6 +3871,9 @@ function isLoopbackHost(host) {
 async function cmdStudio(args, config) {
     (0, ui_js_1.banner)();
     const demo = args.demo === true;
+    // Demo mode reads no namespace at all, so there is nothing to mistake there.
+    if (!demo)
+        refuseSchemaFilePath(config);
     // Demo mode is self-contained (seeded in-memory database), so it never needs
     // a DATABASE_URL. The placeholder is only used for display.
     const url = demo ? 'demo://in-memory' : requireUrl(config);
@@ -3491,10 +3890,10 @@ async function cmdStudio(args, config) {
     if (!isLoopbackHost(host)) {
         if (!args.allowRemote) {
             (0, ui_js_1.error)(`Studio refuses to bind to ${(0, ui_js_1.yellow)(host)} without ${(0, ui_js_1.cyan)('--allow-remote')}.`);
-            (0, ui_js_1.newline)();
-            console.log(`  ${(0, ui_js_1.dim)('Loopback only by default')} ${(0, ui_js_1.dim)('(127.0.0.1, localhost, ::1).')}`);
-            console.log(`  ${(0, ui_js_1.dim)('Pass')} ${(0, ui_js_1.cyan)('--allow-remote')} ${(0, ui_js_1.dim)('to opt in to network exposure.')}`);
-            (0, ui_js_1.newline)();
+            (0, ui_js_1.errorLine)();
+            (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Loopback only by default')} ${(0, ui_js_1.dim)('(127.0.0.1, localhost, ::1).')}`);
+            (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Pass')} ${(0, ui_js_1.cyan)('--allow-remote')} ${(0, ui_js_1.dim)('to opt in to network exposure.')}`);
+            (0, ui_js_1.errorLine)();
             process.exit(1);
         }
         // warn() prints; it returns void. Wrapping it in console.log() printed a
@@ -3602,6 +4001,7 @@ async function cmdStudio(args, config) {
 // Command: mcp, read-only JSON-RPC stdio server
 // ---------------------------------------------------------------------------
 async function cmdMcp(_args, config) {
+    refuseSchemaFilePath(config);
     const url = requireUrl(config);
     await (0, mcp_js_1.runMcpServer)({
         url,
@@ -3620,10 +4020,10 @@ async function cmdObserve(args) {
     const url = process.env.TURBINE_OBSERVE_URL;
     if (!url) {
         (0, ui_js_1.error)('TURBINE_OBSERVE_URL environment variable is required for the observe command.');
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Set it to the Postgres connection string where metrics are stored.')}`);
-        console.log(`  ${(0, ui_js_1.dim)('Example:')} ${(0, ui_js_1.cyan)('TURBINE_OBSERVE_URL=postgres://... npx turbine observe')}`);
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Set it to the Postgres connection string where metrics are stored.')}`);
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Example:')} ${(0, ui_js_1.cyan)('TURBINE_OBSERVE_URL=postgres://... npx turbine observe')}`);
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     const port = args.port ?? 4984;
@@ -3638,10 +4038,10 @@ async function cmdObserve(args) {
     if (!isLoopbackHost(host)) {
         if (!args.allowRemote) {
             (0, ui_js_1.error)(`Observe refuses to bind to ${(0, ui_js_1.yellow)(host)} without ${(0, ui_js_1.cyan)('--allow-remote')}.`);
-            (0, ui_js_1.newline)();
-            console.log(`  ${(0, ui_js_1.dim)('Loopback only by default')} ${(0, ui_js_1.dim)('(127.0.0.1, localhost, ::1).')}`);
-            console.log(`  ${(0, ui_js_1.dim)('Pass')} ${(0, ui_js_1.cyan)('--allow-remote')} ${(0, ui_js_1.dim)('to opt in to network exposure.')}`);
-            (0, ui_js_1.newline)();
+            (0, ui_js_1.errorLine)();
+            (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Loopback only by default')} ${(0, ui_js_1.dim)('(127.0.0.1, localhost, ::1).')}`);
+            (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Pass')} ${(0, ui_js_1.cyan)('--allow-remote')} ${(0, ui_js_1.dim)('to opt in to network exposure.')}`);
+            (0, ui_js_1.errorLine)();
             process.exit(1);
         }
         // warn() prints and returns void; see the same guard in cmdStudio.
@@ -3706,6 +4106,8 @@ function showSubcommandHelp(command) {
         doctor: showDoctorHelp,
         studio: showStudioHelp,
         mcp: showMcpHelp,
+        observe: showObserveHelp,
+        skill: showSkillHelp,
     };
     const fn = helpMap[command];
     if (fn) {
@@ -3733,6 +4135,7 @@ function showInitHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}   Postgres connection string to embed in config`);
     console.log(`    ${(0, ui_js_1.cyan)('--force, -f')}        Overwrite existing config file`);
     console.log(`    ${(0, ui_js_1.cyan)('--yes, -y')}          Accept every step's default (non-interactive)`);
+    console.log(`    ${(0, ui_js_1.cyan)('--schema-file')} ${(0, ui_js_1.dim)('<path>')} Where to scaffold the schema file ${(0, ui_js_1.dim)('(default: ./turbine/schema.ts)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-schema')}      Don't create the starter schema file`);
     console.log(`    ${(0, ui_js_1.cyan)('--with-schema')}      Create it even if the database already has tables`);
     console.log(`    ${(0, ui_js_1.cyan)('--skip-seed')}        Don't create the seed file or run the seed`);
@@ -3813,8 +4216,11 @@ function showPushHelp() {
     console.log(`  Reads your ${(0, ui_js_1.cyan)('turbine/schema.ts')} file, diffs against the live database,`);
     console.log(`  and applies CREATE/ALTER statements.`);
     (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.dim)('Note:')} the file is ${(0, ui_js_1.cyan)('--schema-file')}${(0, ui_js_1.dim)('.')} ${(0, ui_js_1.cyan)('--schema')} ${(0, ui_js_1.dim)('is the Postgres namespace to write into.')}`);
+    (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}   Postgres connection string`);
+    console.log(`    ${(0, ui_js_1.cyan)('--schema-file')} ${(0, ui_js_1.dim)('<path>')} Your ${(0, ui_js_1.cyan)('defineSchema()')} file ${(0, ui_js_1.dim)('(default: ./turbine/schema.ts)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}          Show SQL without executing`);
     console.log(`    ${(0, ui_js_1.cyan)('--allow-destructive')} Skip the interactive confirmation for data-destroying statements ${(0, ui_js_1.dim)('(CI)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--verbose, -v')}      Show detailed output`);
@@ -3836,6 +4242,7 @@ function showMigrateHelp() {
     (0, ui_js_1.newline)();
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}   Postgres connection string`);
+    console.log(`    ${(0, ui_js_1.cyan)('--schema-file')} ${(0, ui_js_1.dim)('<path>')} Your ${(0, ui_js_1.cyan)('defineSchema()')} file, for ${(0, ui_js_1.cyan)('--auto')} / ${(0, ui_js_1.cyan)('--from-diff')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--auto')}            Auto-generate UP/DOWN SQL from schema diff ${(0, ui_js_1.dim)('(create only)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--from-diff')}       Generate from schema diff, flagging destructive statements ${(0, ui_js_1.dim)('(create only)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--recipe')} ${(0, ui_js_1.dim)('<name>')}   Scaffold a sanctioned migration pattern ${(0, ui_js_1.dim)('(create only, e.g. backfill)')}`);
@@ -3988,6 +4395,51 @@ function showMcpHelp() {
     console.log(`    ${(0, ui_js_1.cyan)('--exclude')} ${(0, ui_js_1.dim)('<tables>')}    Comma-separated tables to exclude`);
     (0, ui_js_1.newline)();
 }
+function showObserveHelp() {
+    (0, ui_js_1.banner)();
+    console.log(`  ${(0, ui_js_1.bold)('turbine observe')}, Query metrics dashboard`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Usage:')}`);
+    console.log(`    TURBINE_OBSERVE_URL=postgres://... npx turbine observe ${(0, ui_js_1.dim)('[options]')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  Reads the ${(0, ui_js_1.cyan)('_turbine_metrics')} table written by ${(0, ui_js_1.cyan)('db.$observe()')} and serves`);
+    console.log(`  per-minute count / avg / p50 / p95 / p99 / error aggregates. Read-only,`);
+    console.log(`  loopback-bound, behind a random per-session token, same model as Studio.`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.dim)('The connection string comes from')} ${(0, ui_js_1.cyan)('TURBINE_OBSERVE_URL')}${(0, ui_js_1.dim)(', not')} ${(0, ui_js_1.cyan)('DATABASE_URL')}${(0, ui_js_1.dim)(':')}`);
+    console.log(`  ${(0, ui_js_1.dim)('metrics are meant to live in a different database from the one they measure.')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--port')} ${(0, ui_js_1.dim)('<n>')}            HTTP port ${(0, ui_js_1.dim)('(default: 4984)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--host')} ${(0, ui_js_1.dim)('<addr>')}         Bind address ${(0, ui_js_1.dim)('(default: 127.0.0.1)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--no-open')}             Don't auto-open the browser`);
+    console.log(`    ${(0, ui_js_1.cyan)('--allow-remote')}        Allow a non-loopback ${(0, ui_js_1.cyan)('--host')} ${(0, ui_js_1.dim)('(refused without it)')}`);
+    (0, ui_js_1.newline)();
+}
+function showSkillHelp() {
+    (0, ui_js_1.banner)();
+    console.log(`  ${(0, ui_js_1.bold)('turbine skill')}, Install the agent query skill`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Usage:')}`);
+    console.log(`    npx turbine skill ${(0, ui_js_1.dim)('[options]')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  Writes ${(0, ui_js_1.cyan)('.claude/skills/turbine-orm/SKILL.md')}: how to write Turbine queries,`);
+    console.log(`  for a coding agent working in this project. The file ships in the package`);
+    console.log(`  rather than being generated here, and every factual claim in it is executed`);
+    console.log(`  against a live database on each release.`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--print')}               Write the skill to stdout instead of installing it`);
+    console.log(`    ${(0, ui_js_1.cyan)('--agents')}              Print the AGENTS.md / CLAUDE.md instructions block`);
+    console.log(`    ${(0, ui_js_1.cyan)('--dir')} ${(0, ui_js_1.dim)('<path>')}          Skills root to install into ${(0, ui_js_1.dim)('(default: .claude/skills)')}`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.bold)('Examples:')}`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine skill`);
+    console.log(`    ${(0, ui_js_1.dim)('$')} npx turbine skill --agents >> AGENTS.md`);
+    (0, ui_js_1.newline)();
+    console.log(`  ${(0, ui_js_1.dim)('Also worth connecting:')} ${(0, ui_js_1.cyan)('npx turbine mcp')}${(0, ui_js_1.dim)(', the read-only MCP server.')}`);
+    (0, ui_js_1.newline)();
+}
 // ---------------------------------------------------------------------------
 // Help
 // ---------------------------------------------------------------------------
@@ -4018,7 +4470,8 @@ function showHelp() {
     console.log(`  ${(0, ui_js_1.bold)('Options:')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--url, -u')} ${(0, ui_js_1.dim)('<url>')}      Postgres connection string`);
     console.log(`    ${(0, ui_js_1.cyan)('--out, -o')} ${(0, ui_js_1.dim)('<dir>')}      Output directory ${(0, ui_js_1.dim)('(default: ./generated/turbine)')}`);
-    console.log(`    ${(0, ui_js_1.cyan)('--schema, -s')} ${(0, ui_js_1.dim)('<name>')}  Postgres schema ${(0, ui_js_1.dim)('(default: public)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--schema, -s')} ${(0, ui_js_1.dim)('<name>')}  Postgres schema NAME to read ${(0, ui_js_1.dim)('(default: public)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('--schema-file')} ${(0, ui_js_1.dim)('<path>')} Your ${(0, ui_js_1.cyan)('defineSchema()')} file ${(0, ui_js_1.dim)('(push / migrate --auto / init)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('--include')} ${(0, ui_js_1.dim)('<tables>')}   Comma-separated tables to include`);
     console.log(`    ${(0, ui_js_1.cyan)('--exclude')} ${(0, ui_js_1.dim)('<tables>')}   Comma-separated tables to exclude`);
     console.log(`    ${(0, ui_js_1.cyan)('--dry-run')}            Show SQL without executing`);
@@ -4136,9 +4589,9 @@ function cmdSkill(args) {
     const source = root ? (0, node_path_1.resolve)(root, 'skills', 'turbine-orm', 'SKILL.md') : undefined;
     if (!source || !(0, node_fs_1.existsSync)(source)) {
         (0, ui_js_1.error)('Could not find the packaged skill inside turbine-orm.');
-        (0, ui_js_1.newline)();
-        console.log(`  ${(0, ui_js_1.dim)('Read it online instead:')} ${(0, ui_js_1.cyan)('https://turbineorm.dev/ai-agents')}`);
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)();
+        (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Read it online instead:')} ${(0, ui_js_1.cyan)('https://turbineorm.dev/ai-agents')}`);
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
     const body = (0, node_fs_1.readFileSync)(source, 'utf8');
@@ -4236,6 +4689,7 @@ async function main() {
         url: args.url,
         out: args.out,
         schema: args.schema,
+        schemaFile: args.schemaFile,
         include: args.include,
         exclude: args.exclude,
         importExtension: args.importExtension,
@@ -4312,50 +4766,60 @@ async function main() {
             case 'skill':
                 cmdSkill(args);
                 break;
-            default:
+            default: {
                 (0, ui_js_1.error)(`Unknown command: ${(0, ui_js_1.bold)(args.command)}`);
-                (0, ui_js_1.newline)();
-                console.log(`  ${(0, ui_js_1.dim)('Run')} ${(0, ui_js_1.cyan)('npx turbine help')} ${(0, ui_js_1.dim)('for available commands.')}`);
-                (0, ui_js_1.newline)();
+                (0, ui_js_1.errorLine)();
+                // Only canonical spellings are offered. `nameCloseness` scores substring
+                // containment above edit distance, so including the one-letter aliases
+                // would answer "genrate" with "g" (contained, score 501) instead of
+                // "generate" (one edit away, score 99).
+                const suggestion = (0, utils_js_1.closestName)(args.command, knownCommands());
+                if (suggestion) {
+                    (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Did you mean')} ${(0, ui_js_1.cyan)(`turbine ${suggestion}`)}${(0, ui_js_1.dim)('?')}`);
+                    (0, ui_js_1.errorLine)();
+                }
+                (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Run')} ${(0, ui_js_1.cyan)('npx turbine help')} ${(0, ui_js_1.dim)('for available commands.')}`);
+                (0, ui_js_1.errorLine)();
                 process.exit(1);
+            }
         }
     }
     catch (err) {
         if (err instanceof Error) {
             if (err.message.includes('ECONNREFUSED') || err.message.includes('connection')) {
-                (0, ui_js_1.newline)();
+                (0, ui_js_1.errorLine)();
                 (0, ui_js_1.error)(`Could not connect to database`);
-                console.log(`  ${(0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.message))}`);
-                (0, ui_js_1.newline)();
-                console.log(`  ${(0, ui_js_1.dim)('Check that:')}`);
-                console.log(`    ${(0, ui_js_1.dim)('1.')} Your database is running`);
-                console.log(`    ${(0, ui_js_1.dim)('2.')} The connection string is correct`);
-                console.log(`    ${(0, ui_js_1.dim)('3.')} Network/firewall allows the connection`);
+                (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.message))}`);
+                (0, ui_js_1.errorLine)();
+                (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)('Check that:')}`);
+                (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('1.')} Your database is running`);
+                (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('2.')} The connection string is correct`);
+                (0, ui_js_1.errorLine)(`  ${(0, ui_js_1.dim)('3.')} Network/firewall allows the connection`);
             }
             else if (err.message.includes('authentication')) {
-                (0, ui_js_1.newline)();
+                (0, ui_js_1.errorLine)();
                 (0, ui_js_1.error)(`Authentication failed`);
-                console.log(`  ${(0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.message))}`);
+                (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.message))}`);
             }
             else if (err.message.includes('does not exist')) {
-                (0, ui_js_1.newline)();
+                (0, ui_js_1.errorLine)();
                 (0, ui_js_1.error)(`Database or schema not found`);
-                console.log(`  ${(0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.message))}`);
+                (0, ui_js_1.errorLine)(`${(0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.message))}`);
             }
             else {
-                (0, ui_js_1.newline)();
+                (0, ui_js_1.errorLine)();
                 (0, ui_js_1.error)((0, ui_js_1.redactUrl)(err.message));
                 if (args.verbose && err.stack) {
-                    (0, ui_js_1.newline)();
-                    console.log((0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.stack)));
+                    (0, ui_js_1.errorLine)();
+                    console.error((0, ui_js_1.dim)((0, ui_js_1.redactUrl)(err.stack)));
                 }
             }
         }
         else {
-            (0, ui_js_1.newline)();
+            (0, ui_js_1.errorLine)();
             (0, ui_js_1.error)(`Unexpected error: ${(0, ui_js_1.redactUrl)(String(err))}`);
         }
-        (0, ui_js_1.newline)();
+        (0, ui_js_1.errorLine)();
         process.exit(1);
     }
 }