turbine-orm 0.72.0 → 0.73.0

package/dist/cjs/query/compound-unique.js

@@ -41,6 +41,9 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.expandCompoundUniqueWhere = expandCompoundUniqueWhere;
+exports.assertWhereIdentifiesOneRow = assertWhereIdentifiesOneRow;
+exports.uniqueKeyNames = uniqueKeyNames;
+exports.whereIdentifiesOneRow = whereIdentifiesOneRow;
 const errors_js_1 = require("../errors.js");
 const filters_js_1 = require("./filters.js");
 const utils_js_1 = require("./utils.js");
@@ -203,3 +206,119 @@ function expandCompoundUniqueWhere(meta, where) {
     }
     return result ?? where;
 }
+/**
+ * Every column set that identifies AT MOST ONE ROW of this table.
+ *
+ * Same sources and the same partial-index rule as {@link syntheticKeyMap}, and
+ * in this module for that reason: "what identifies one row" is one question,
+ * and answering it in two places is how a compound selector comes to be
+ * accepted by the name and refused by its members (0.72.0 fixed exactly that).
+ * The difference is only the arity: a synthetic SELECTOR needs two or more
+ * columns to have a joined name, while a single-column unique identifies a row
+ * perfectly well.
+ */
+/**
+ * Throw unless `where` identifies a single row. The refusal for `findUnique` on
+ * EVERY engine, message included.
+ *
+ * Shared rather than written twice because `PowqlInterface` is a parallel
+ * implementation: two copies of a rule this specific (which sources count as
+ * unique, whether a null identifies, which keys the message lists) is how two
+ * engines come to disagree about whether a query is valid, which is the exact
+ * divergence 0.64.0 and 0.72.0 were both spent on.
+ *
+ * The message lists the keys that WOULD work, because the fix is almost always
+ * one of them and a caller cannot be expected to know which columns the
+ * database considers unique. A table with no unique key at all gets its own
+ * sentence: no `where` satisfies this, and "name a unique key" is advice that
+ * person cannot take.
+ */
+function assertWhereIdentifiesOneRow(meta, table, where) {
+    if (whereIdentifiesOneRow(meta, where ?? {}))
+        return;
+    const field = (c) => meta.reverseColumnMap[c] ?? c;
+    const keys = uniqueKeyNames(meta).map((cols) => cols.length === 1 ? `\`${field(cols[0])}\`` : `\`{ ${cols.map(field).join(', ')} }\``);
+    const advice = keys.length > 0
+        ? `Name a unique key (${keys.join(', ')}), or use \`findFirst\` if you meant "any row matching a filter".`
+        : `Table "${table}" declares no primary key and no unique constraint, so no \`where\` can identify one row ` +
+            'here. Use `findFirst` (add an `orderBy` to make which row it is deterministic).';
+    throw new errors_js_1.ValidationError(`[turbine] findUnique on "${table}" refused: the \`where\` clause does not identify a single row, ` +
+        `so this would return an arbitrary one of the rows that match. ${advice}`);
+}
+function uniqueKeyNames(meta) {
+    return dedupeColumnSets(uniqueColumnSets(meta));
+}
+/** Distinct column sets, preserving first-seen order (a PK is often also a declared unique). */
+function dedupeColumnSets(sets) {
+    const seen = new Set();
+    const out = [];
+    for (const cols of sets) {
+        const sig = cols.join('\u0000');
+        if (seen.has(sig))
+            continue;
+        seen.add(sig);
+        out.push(cols);
+    }
+    return out;
+}
+function uniqueColumnSets(meta) {
+    const sets = [];
+    if (meta.primaryKey.length > 0)
+        sets.push(meta.primaryKey);
+    for (const uc of meta.uniqueColumns)
+        if (uc.length > 0)
+            sets.push(uc);
+    for (const idx of meta.indexes) {
+        if (idx.unique && !idx.docPath && !idx.partial && idx.columns.length > 0)
+            sets.push(idx.columns);
+    }
+    return sets;
+}
+/**
+ * True when `where` pins every column of at least one unique key to a single
+ * value, so the row it names is the row it gets.
+ *
+ * Deliberately reads only the TOP LEVEL of the user's where. A unique key
+ * buried inside an `OR` does not identify a row (the other branch matches
+ * whatever it matches), and one inside an `AND` array is a shape nobody writes
+ * for a lookup by identity. Extra predicates alongside the key are fine: they
+ * can only narrow a set that already holds at most one row.
+ *
+ * A NULL is not an identity. `WHERE email IS NULL` matches every row whose
+ * email is null, which a UNIQUE constraint permits any number of, so a null
+ * value satisfies no key here even on a unique column.
+ */
+function whereIdentifiesOneRow(meta, where) {
+    const pinned = new Set();
+    for (const [key, value] of Object.entries(where)) {
+        if (!isPinnedToOneValue(value))
+            continue;
+        const column = (0, utils_js_1.resolveColumnName)(meta, key);
+        if (column !== undefined)
+            pinned.add(column);
+    }
+    if (pinned.size === 0)
+        return false;
+    return uniqueColumnSets(meta).some((cols) => cols.every((c) => pinned.has(c)));
+}
+/** A bare value, or an operator object whose `equals` is a value. */
+function isPinnedToOneValue(value) {
+    if (value === undefined || value === null)
+        return false;
+    if ((0, filters_js_1.isWhereOperator)(value)) {
+        const eq = value.equals;
+        return eq !== undefined && eq !== null;
+    }
+    // A JSON / array / vector filter narrows, it does not identify.
+    if ((0, filters_js_1.isJsonFilter)(value) || (0, filters_js_1.isArrayFilter)(value) || (0, filters_js_1.isVectorFilter)(value))
+        return false;
+    // Anything else that is a plain object is a relation filter or a sub-where,
+    // neither of which pins a column. Dates, Buffers and primitives are values.
+    return !isPlainObject(value);
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}

package/dist/cjs/query/option-surface.d.ts

@@ -108,4 +108,26 @@ export declare const ALL_OPTION_TABLES: Readonly<Record<string, Readonly<Record<
 export declare function applyNativeOptions(table: Readonly<Record<string, OptionKind>>, src: Record<string, unknown>, dst: Record<string, unknown>): void;
 /** The keys of `table` with the given kind, as a set. */
 export declare function optionKeysOfKind(table: Readonly<Record<string, OptionKind>>, ...kinds: OptionKind[]): string[];
+/**
+ * Dev-mode warning for a key that is not part of the operation's option
+ * surface, and is therefore doing nothing.
+ *
+ * The motivating case is `include`. It is Prisma's word for `with`, it is what
+ * a model or a developer coming from Prisma reaches for first, and an
+ * unrecognized key is simply ignored: the query runs, returns rows, and the
+ * relation the caller asked for is absent. No error, no empty array, just a
+ * missing key on every row. A cross-model eval measured this as the single
+ * largest source of confidently-wrong queries against Turbine, and every one of
+ * them looked like a success from inside the process.
+ *
+ * A WARNING and never an error, deliberately. Refusing an unknown key would
+ * break `findMany({ ...someOptionsBag })`, which is ordinary code, and the
+ * option surface grows: a caller pinned to an older minor would have their
+ * working query start throwing. A warning costs a correct program nothing and
+ * tells an incorrect one exactly what happened.
+ *
+ * Dev-only, once per `table.operation.key` per process, and total: the whole
+ * body is wrapped, because a diagnostic must never be the reason a query fails.
+ */
+export declare function warnUnknownQueryOptions(table: string, operation: string, args: unknown): void;
 export {};

package/dist/cjs/query/option-surface.js

@@ -56,6 +56,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ALL_OPTION_TABLES = exports.GROUP_BY_OPTIONS = exports.AGGREGATE_OPTIONS = exports.COUNT_OPTIONS = exports.UPSERT_OPTIONS = exports.DELETE_MANY_OPTIONS = exports.DELETE_OPTIONS = exports.UPDATE_MANY_OPTIONS = exports.UPDATE_OPTIONS = exports.CREATE_MANY_OPTIONS = exports.CREATE_OPTIONS = exports.FIND_MANY_STREAM_OPTIONS = exports.FIND_MANY_OPTIONS = exports.FIND_UNIQUE_OPTIONS = void 0;
 exports.applyNativeOptions = applyNativeOptions;
 exports.optionKeysOfKind = optionKeysOfKind;
+exports.warnUnknownQueryOptions = warnUnknownQueryOptions;
+// Runtime imports, and the only ones in this file: the unknown-key warning at
+// the bottom needs the once-per-process registry and the name suggester. Both
+// are leaves that do not import this module, so the type-only shape of
+// everything above is unaffected.
+const utils_js_1 = require("./utils.js");
+const warn_registry_js_1 = require("./warn-registry.js");
 exports.FIND_UNIQUE_OPTIONS = {
     where: 'prisma',
     select: 'prisma',
@@ -84,7 +91,13 @@ exports.FIND_MANY_OPTIONS = {
     omit: 'prisma',
     orderBy: 'prisma',
     cursor: 'prisma',
+    // `take` and `skip` are Prisma's own spellings and core accepts them as
+    // aliases, but they stay hand-translated because Prisma gives them meanings
+    // core does not have: a NEGATIVE `take` pages from the end, and `skip: 1`
+    // beside a `cursor` is the exclusive-pagination idiom. Forwarding either
+    // verbatim would hand core a number that means something else.
     take: 'prisma',
+    skip: 'prisma',
     distinct: 'prisma',
     relationLoadStrategy: 'prisma',
     with: 'nativeAlias',
@@ -231,3 +244,81 @@ function applyNativeOptions(table, src, dst) {
 function optionKeysOfKind(table, ...kinds) {
     return Object.keys(table).filter((k) => kinds.includes(table[k]));
 }
+// ---------------------------------------------------------------------------
+// Unknown-key diagnostic
+// ---------------------------------------------------------------------------
+/**
+ * The operations a caller can invoke, mapped to the table that describes their
+ * legal keys. The `*OrThrow` and `findFirst` variants take the same args as the
+ * method they are built on, so they share its table rather than getting a copy
+ * that could drift from it.
+ */
+const OPERATION_TABLE = {
+    ...exports.ALL_OPTION_TABLES,
+    findFirst: exports.FIND_MANY_OPTIONS,
+    findFirstOrThrow: exports.FIND_MANY_OPTIONS,
+    findUniqueOrThrow: exports.FIND_UNIQUE_OPTIONS,
+    findManyStreamBatches: exports.FIND_MANY_STREAM_OPTIONS,
+};
+/**
+ * Prisma spellings that name a real Turbine option under a different word.
+ *
+ * Only spellings whose Turbine equivalent EXISTS belong here: the message tells
+ * the caller what to write instead, so a key with no equivalent would produce
+ * advice that does not work. `take` / `skip` were once on this list and are now
+ * accepted outright.
+ */
+const PRISMA_SPELLING = {
+    include: 'with',
+};
+/**
+ * Dev-mode warning for a key that is not part of the operation's option
+ * surface, and is therefore doing nothing.
+ *
+ * The motivating case is `include`. It is Prisma's word for `with`, it is what
+ * a model or a developer coming from Prisma reaches for first, and an
+ * unrecognized key is simply ignored: the query runs, returns rows, and the
+ * relation the caller asked for is absent. No error, no empty array, just a
+ * missing key on every row. A cross-model eval measured this as the single
+ * largest source of confidently-wrong queries against Turbine, and every one of
+ * them looked like a success from inside the process.
+ *
+ * A WARNING and never an error, deliberately. Refusing an unknown key would
+ * break `findMany({ ...someOptionsBag })`, which is ordinary code, and the
+ * option surface grows: a caller pinned to an older minor would have their
+ * working query start throwing. A warning costs a correct program nothing and
+ * tells an incorrect one exactly what happened.
+ *
+ * Dev-only, once per `table.operation.key` per process, and total: the whole
+ * body is wrapped, because a diagnostic must never be the reason a query fails.
+ */
+function warnUnknownQueryOptions(table, operation, args) {
+    if (process.env.NODE_ENV === 'production')
+        return;
+    if (args === null || typeof args !== 'object' || Array.isArray(args))
+        return;
+    const known = OPERATION_TABLE[operation];
+    if (!known)
+        return;
+    try {
+        for (const key of Object.keys(args)) {
+            // `{ ...maybeOptions }` routinely materializes keys with no value.
+            // Nothing is being ignored when the value is undefined.
+            if (args[key] === undefined)
+                continue;
+            if (Object.hasOwn(known, key))
+                continue;
+            if (!(0, warn_registry_js_1.shouldWarnOnce)(warn_registry_js_1.WARN_NS.unknownQueryOption, `${table}.${operation}.${key}`))
+                continue;
+            const prismaSpelling = PRISMA_SPELLING[key];
+            const suggestion = prismaSpelling ?? (0, utils_js_1.suggestKey)(key, Object.keys(known));
+            const because = prismaSpelling ? ` Turbine spells this "${prismaSpelling}".` : '';
+            console.warn(`[turbine] unknown option "${key}" in ${table}.${operation}(), it is ignored.${because}` +
+                (!prismaSpelling && suggestion ? ` Did you mean "${suggestion}"?` : ''));
+        }
+    }
+    catch {
+        // Key enumeration is the only thing that can fail here (a Proxy whose
+        // ownKeys throws), and it must not take the query with it.
+    }
+}

package/dist/cjs/query/types.d.ts

@@ -629,8 +629,22 @@ export interface FindManyArgs<T, R extends object = {}, W extends TypedWithClaus
     with?: W;
     /** Cursor-based pagination: start after this row */
     cursor?: Partial<T>;
-    /** Number of records to take (used with cursor) */
+    /**
+     * Prisma's spelling of {@link FindManyArgs.limit}. Folded into `limit` before
+     * anything reads it; passing both with different values is a
+     * `ValidationError`.
+     */
     take?: number;
+    /**
+     * Prisma's spelling of {@link FindManyArgs.offset}. Folded into `offset`
+     * before anything reads it; passing both with different values is a
+     * `ValidationError`.
+     *
+     * Accepted since 0.73.0. Before that `take` was recognized and `skip` was
+     * not, so the Prisma pair `{ take, skip }` silently returned the first page
+     * however far the caller thought they had paged.
+     */
+    skip?: number;
     /** De-duplicate results by specified fields */
     distinct?: (keyof T & string)[];
     /** Query timeout in milliseconds. Rejects with an error if exceeded. */

package/dist/cjs/query/utils.d.ts

@@ -728,3 +728,26 @@ export declare function warnRedundantSortTerm(table: string, clause: string, dro
  */
 export declare function selectNamesNothingMessage(table: string): string;
 export declare function selectOmitExclusiveMessage(table: string): string;
+/**
+ * The Prisma pagination aliases, folded into Turbine's own spelling ONCE,
+ * before anything reads them.
+ *
+ * Turbine's names are `limit` / `offset`; Prisma's are `take` / `skip`. `take`
+ * was accepted and `skip` was not, which is the worst of the three possible
+ * states: `{ take: 20, skip: 40 }` is what a Prisma habit writes, it looks
+ * accepted because half of it is, and the query silently returns page one
+ * forever. An unknown key is at least inert on its own; a HALF-recognized pair
+ * changes the answer.
+ *
+ * Folded here rather than read at each site deliberately. `take` used to be
+ * handled by six separate `args?.take ?? args?.limit` reads, one of which is
+ * the SQL-cache FINGERPRINT, so adding `skip` the same way would have meant
+ * teaching six places about it and a miss in the fingerprint is not a missing
+ * feature, it is two different pages sharing one cached statement. Normalizing
+ * up front leaves `limit` / `offset` as the single authority and the aliases
+ * cease to exist below this line.
+ *
+ * Returns the SAME object when neither alias is present, so the common path
+ * allocates nothing.
+ */
+export declare function normalizePagination<A extends object | undefined>(args: A): A;

package/dist/cjs/query/utils.js

@@ -49,7 +49,9 @@ exports.relationInProjectionMessage = relationInProjectionMessage;
 exports.warnRedundantSortTerm = warnRedundantSortTerm;
 exports.selectNamesNothingMessage = selectNamesNothingMessage;
 exports.selectOmitExclusiveMessage = selectOmitExclusiveMessage;
+exports.normalizePagination = normalizePagination;
 const pg_1 = __importDefault(require("pg"));
+const errors_js_1 = require("../errors.js");
 const schema_js_1 = require("../schema.js");
 const warn_registry_js_1 = require("./warn-registry.js");
 // ---------------------------------------------------------------------------
@@ -1539,3 +1541,58 @@ function selectOmitExclusiveMessage(table) {
     return (`[turbine] "select" and "omit" are mutually exclusive (on table "${table}"). ` +
         `A select already lists exactly the fields you want.`);
 }
+/**
+ * The Prisma pagination aliases, folded into Turbine's own spelling ONCE,
+ * before anything reads them.
+ *
+ * Turbine's names are `limit` / `offset`; Prisma's are `take` / `skip`. `take`
+ * was accepted and `skip` was not, which is the worst of the three possible
+ * states: `{ take: 20, skip: 40 }` is what a Prisma habit writes, it looks
+ * accepted because half of it is, and the query silently returns page one
+ * forever. An unknown key is at least inert on its own; a HALF-recognized pair
+ * changes the answer.
+ *
+ * Folded here rather than read at each site deliberately. `take` used to be
+ * handled by six separate `args?.take ?? args?.limit` reads, one of which is
+ * the SQL-cache FINGERPRINT, so adding `skip` the same way would have meant
+ * teaching six places about it and a miss in the fingerprint is not a missing
+ * feature, it is two different pages sharing one cached statement. Normalizing
+ * up front leaves `limit` / `offset` as the single authority and the aliases
+ * cease to exist below this line.
+ *
+ * Returns the SAME object when neither alias is present, so the common path
+ * allocates nothing.
+ */
+function normalizePagination(args) {
+    if (!args)
+        return args;
+    const a = args;
+    if (a.take === undefined && a.skip === undefined)
+        return args;
+    const out = { ...args };
+    if (a.take !== undefined) {
+        assertAliasAgrees('take', a.take, 'limit', a.limit);
+        out.limit = a.take;
+        delete out.take;
+    }
+    if (a.skip !== undefined) {
+        assertAliasAgrees('skip', a.skip, 'offset', a.offset);
+        out.offset = a.skip;
+        delete out.skip;
+    }
+    return out;
+}
+/**
+ * Both spellings of one bound, disagreeing. Refused rather than resolved: the
+ * old `take ?? limit` silently preferred one of the two numbers the caller
+ * wrote, and there is no reading of `{ limit: 10, take: 5 }` that makes one of
+ * them the intended answer. Equal values are accepted, since there is nothing
+ * to choose between.
+ */
+function assertAliasAgrees(alias, aliasValue, native, nativeValue) {
+    if (nativeValue === undefined || nativeValue === aliasValue)
+        return;
+    throw new errors_js_1.ValidationError(`[turbine] "${alias}" and "${native}" are the same option and were given different values ` +
+        `(${alias}: ${String(aliasValue)}, ${native}: ${String(nativeValue)}). ` +
+        `"${alias}" is Prisma's spelling of "${native}"; pass one of them.`);
+}

package/dist/cli/index.d.ts

@@ -18,6 +18,7 @@
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
  *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
+ *   turbine skill                 - Install the agent query skill (--print, --agents, --dir <path>)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate
@@ -113,6 +114,12 @@ export interface CliArgs {
      * not be turned into a failed install.
      */
     ifDb?: boolean;
+    /** `skill --print`: write the skill to stdout instead of installing it. */
+    print?: boolean;
+    /** `skill --agents`: print the AGENTS.md instructions block instead. */
+    agents?: boolean;
+    /** `skill --dir <path>`: the skills root to install into (default `.claude/skills`). */
+    dir?: string;
 }
 export declare function parseArgs(argv?: string[]): CliArgs;
 /**

package/dist/cli/index.js

@@ -18,6 +18,7 @@
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                  , Start read-only MCP server over JSON-RPC stdio
  *   turbine observe              , Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
+ *   turbine skill                 - Install the agent query skill (--print, --agents, --dir <path>)
  *
  * Usage:
  *   DATABASE_URL=postgres://... npx turbine generate
@@ -171,6 +172,17 @@ export function parseArgs(argv = process.argv.slice(2)) {
             case '--allow-pooler':
                 result.allowPooler = true;
                 break;
+            // `turbine skill`
+            case '--print':
+                result.print = true;
+                break;
+            case '--agents':
+                result.agents = true;
+                break;
+            case '--dir':
+                result.dir = next;
+                i++;
+                break;
             case '--zod':
                 result.zod = true;
                 break;
@@ -3945,6 +3957,7 @@ function showHelp() {
     console.log(`    ${cyan('studio')}             Launch local read-only web UI ${dim('(--write for writes, --demo for a sample DB)')}`);
     console.log(`    ${cyan('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${cyan('observe')}            Launch metrics dashboard ${dim('(requires TURBINE_OBSERVE_URL)')}`);
+    console.log(`    ${cyan('skill')}              Install the agent query skill ${dim('(--print, --agents, --dir <path>)')}`);
     newline();
     console.log(`  ${bold('Options:')}`);
     console.log(`    ${cyan('--url, -u')} ${dim('<url>')}      Postgres connection string`);
@@ -3995,6 +4008,103 @@ function showHelp() {
     newline();
 }
 // ---------------------------------------------------------------------------
+// Agent skill
+// ---------------------------------------------------------------------------
+/**
+ * turbine-orm's own package root, found by walking up from the running script.
+ *
+ * `process.argv[1]` rather than `import.meta.url` so the same source compiles
+ * for both the ESM and CJS builds, and realpath first because `npx turbine`
+ * runs through a `node_modules/.bin` symlink whose dirname is the CONSUMER's
+ * tree, where this package.json does not exist.
+ */
+function ownPackageRoot() {
+    try {
+        let entry = process.argv[1] ?? '';
+        try {
+            entry = realpathSync(entry);
+        }
+        catch {
+            // keep the raw path if realpath fails (e.g. deleted cwd)
+        }
+        let dir = dirname(entry);
+        for (let i = 0; i < 6; i++) {
+            const candidate = resolve(dir, 'package.json');
+            if (existsSync(candidate)) {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf8'));
+                if (pkg.name === 'turbine-orm')
+                    return dir;
+            }
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return undefined;
+}
+/** The instructions block for a project's AGENTS.md / CLAUDE.md. */
+const AGENTS_SNIPPET = `## Database access (Turbine ORM)
+
+- Queries go through the generated client. Read \`generated/turbine/types.ts\` for
+  the entity and input types before writing one; the names there are the truth.
+- Relations are \`with\`, never Prisma's \`include\`. An unrecognized option is
+  ignored, so an \`include\` returns rows with the relation missing.
+- \`select\` and \`omit\` name columns only. A relation named in \`select\` throws.
+- \`findUnique\` needs a unique key. Use \`findFirst\` for "any row matching a
+  filter", with an \`orderBy\` if which row matters.
+- Re-run \`npx turbine generate\` after any schema change, then \`tsc --noEmit\`:
+  an invalid query is a type error, so the type checker is the fastest reviewer.
+- Never write \`includePii: true\`, \`skipGlobalFilters: true\` or
+  \`allowFullTableScan: true\`. Those options take an imported \`UNSAFE\` symbol and
+  nothing else; any other value throws.
+- Full query reference: https://turbineorm.dev/llms.txt
+`;
+/**
+ * Install the packaged query-writing skill into the project.
+ *
+ * The skill is a file in the published tarball rather than something generated
+ * here, so what an agent reads is exactly what the repository tests: every
+ * factual claim in it is executed against a live database by
+ * `evals/src/verify-skill.ts` on each release.
+ */
+function cmdSkill(args) {
+    if (args.agents === true) {
+        console.log(AGENTS_SNIPPET);
+        return;
+    }
+    const root = ownPackageRoot();
+    const source = root ? resolve(root, 'skills', 'turbine-orm', 'SKILL.md') : undefined;
+    if (!source || !existsSync(source)) {
+        error('Could not find the packaged skill inside turbine-orm.');
+        newline();
+        console.log(`  ${dim('Read it online instead:')} ${cyan('https://turbineorm.dev/ai-agents')}`);
+        newline();
+        process.exit(1);
+    }
+    const body = readFileSync(source, 'utf8');
+    if (args.print === true) {
+        process.stdout.write(body);
+        return;
+    }
+    const skillsDir = args.dir ?? join('.claude', 'skills');
+    const target = resolve(process.cwd(), skillsDir, 'turbine-orm', 'SKILL.md');
+    const existed = existsSync(target);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, body);
+    newline();
+    success(`${existed ? 'Updated' : 'Installed'} the Turbine query skill`);
+    console.log(`  ${dim(relative(process.cwd(), target))}`);
+    newline();
+    console.log(`  ${dim('Also worth doing:')}`);
+    console.log(`    ${dim('-')} connect the read-only MCP server: ${cyan('npx turbine mcp')}`);
+    console.log(`    ${dim('-')} add the instructions block to AGENTS.md: ${cyan('npx turbine skill --agents')}`);
+    newline();
+}
+// ---------------------------------------------------------------------------
 // Version
 // ---------------------------------------------------------------------------
 function showVersion() {
@@ -4143,6 +4253,9 @@ async function main() {
             case 'observe':
                 await cmdObserve(args);
                 break;
+            case 'skill':
+                cmdSkill(args);
+                break;
             default:
                 error(`Unknown command: ${bold(args.command)}`);
                 newline();

package/dist/powql.d.ts

@@ -148,10 +148,11 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      */
     private get capabilities();
     /**
-     * The `limit` a query actually emits: the explicit `limit`, Prisma's `take`
-     * alias, then the client-level `defaultLimit`. Shared by {@link buildFind} and
-     * the {@link findMany} zero short-circuit so the two can never disagree about
-     * which limit is in force.
+     * The `limit` a query actually emits: the explicit `limit`, then the
+     * client-level `defaultLimit`. Prisma's `take` alias is already folded into
+     * `limit` by `normalizeArgs`, so there is one spelling by the time this runs.
+     * Shared by {@link buildFind} and the {@link findMany} zero short-circuit so
+     * the two can never disagree about which limit is in force.
      */
     private effectiveLimit;
     /**
@@ -186,7 +187,19 @@ export declare class PowqlInterface<T extends object = Record<string, unknown>>
      * which is the divergence class the projection resolver already cost.
      */
     private withDeclaredRelationNames;
+    /**
+     * Caller args in canonical form: declared relation spellings, and `take` /
+     * `skip` folded into `limit` / `offset`.
+     *
+     * Same composition as `QueryInterface.normalizeArgs` and here for the same
+     * reason the method above is here: nothing about a parallel implementation
+     * makes a core rule arrive on its own, and an engine that reads `take` but
+     * not `skip` pages differently from one that reads both.
+     */
+    private normalizeArgs;
     private assertNoForceCustomPlan;
+    /** See query/compound-unique.ts: one rule and one message across engines. */
+    private assertIdentifiesOneRow;
     private assertPagination;
     /** A predicate that is always false, the empty-`in` / contradiction sentinel. */
     private alwaysFalse;