@constructive-io/graphql-codegen 4.7.3 → 4.8.1

package/esm/core/codegen/cli/table-command-generator.js

@@ -1,8 +1,7 @@
 import * as t from '@babel/types';
 import { toKebabCase } from 'komoji';
 import { generateCode } from '../babel-ast';
-import { getGeneratedFileHeader, getPrimaryKeyInfo, getScalarFields, getTableNames, ucFirst, } from '../utils';
-import { getCreateInputTypeName } from '../utils';
+import { getGeneratedFileHeader, getPrimaryKeyInfo, getScalarFields, getTableNames, ucFirst, lcFirst, getCreateInputTypeName, getPatchTypeName, } from '../utils';
 function createImportDeclaration(moduleSpecifier, namedImports, typeOnly = false) {
     const specifiers = namedImports.map((name) => t.importSpecifier(t.identifier(name), t.identifier(name)));
     const decl = t.importDeclaration(specifiers, t.stringLiteral(moduleSpecifier));
@@ -14,6 +13,60 @@ function createImportDeclaration(moduleSpecifier, namedImports, typeOnly = false
  * This is used at runtime for type coercion (string CLI args → proper types).
  * e.g., { name: 'string', isActive: 'boolean', position: 'int', status: 'enum' }
  */
+/**
+ * Returns a t.TSType node for the appropriate TypeScript type assertion
+ * based on a field's GraphQL type. Used to cast `cleanedData.fieldName`
+ * to the correct type expected by the ORM.
+ */
+/**
+ * Known GraphQL scalar types. Anything not in this set is an enum or custom type.
+ */
+const KNOWN_SCALARS = new Set([
+    'String', 'Boolean', 'Int', 'BigInt', 'Float', 'UUID',
+    'JSON', 'GeoJSON', 'Datetime', 'Date', 'Time', 'Cursor',
+    'BigFloat', 'Interval',
+]);
+/**
+ * Returns true if the GraphQL type is a known scalar.
+ * Non-scalar types (enums, custom input types) need different handling.
+ */
+function isKnownScalar(gqlType) {
+    return KNOWN_SCALARS.has(gqlType.replace(/!/g, ''));
+}
+function getTsTypeForField(field) {
+    const gqlType = field.type.gqlType.replace(/!/g, '');
+    // For non-scalar types (enums, custom types), return null to signal
+    // that no type assertion should be emitted — the value will be passed
+    // without casting, which avoids "string is not assignable to EnumType" errors.
+    if (!isKnownScalar(gqlType)) {
+        return null;
+    }
+    // Determine the base scalar type
+    // Note: ORM input types flatten array fields to their scalar base type
+    // (e.g., _uuid[] in PG -> string in the ORM input), so we do NOT wrap
+    // in tsArrayType here.
+    switch (gqlType) {
+        case 'Boolean':
+            return t.tsBooleanKeyword();
+        case 'Int':
+        case 'BigInt':
+        case 'Float':
+        case 'BigFloat':
+            return t.tsNumberKeyword();
+        case 'JSON':
+        case 'GeoJSON':
+            return t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([
+                t.tsStringKeyword(),
+                t.tsUnknownKeyword(),
+            ]));
+        case 'Interval':
+            // IntervalInput is a complex type, skip assertion
+            return null;
+        case 'UUID':
+        default:
+            return t.tsStringKeyword();
+    }
+}
 function buildFieldSchemaObject(table) {
     const fields = getScalarFields(table);
     return t.objectExpression(fields.map((f) => {
@@ -126,8 +179,11 @@ function buildGetHandler(table, targetName) {
         t.objectProperty(t.identifier('message'), t.stringLiteral(pk.name)),
         t.objectProperty(t.identifier('required'), t.booleanLiteral(true)),
     ]);
+    const pkTsType = pk.gqlType === 'Int' || pk.gqlType === 'BigInt'
+        ? t.tsNumberKeyword()
+        : t.tsStringKeyword();
     const ormArgs = t.objectExpression([
-        t.objectProperty(t.identifier(pk.name), t.memberExpression(t.identifier('answers'), t.identifier(pk.name))),
+        t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), pkTsType)),
         t.objectProperty(t.identifier('select'), selectObj),
     ]);
     const tryBody = [
@@ -153,19 +209,16 @@ function buildGetHandler(table, targetName) {
  * Looks up the CreateXInput -> inner input type (e.g. DatabaseInput) in the
  * TypeRegistry and checks each field's defaultValue from introspection.
  */
-function getFieldsWithDefaults(table, typeRegistry) {
-    const fieldsWithDefaults = new Set();
-    if (!typeRegistry)
-        return fieldsWithDefaults;
-    // Look up the CreateXInput type (e.g. CreateDatabaseInput)
-    const createInputTypeName = getCreateInputTypeName(table);
-    const createInputType = typeRegistry.get(createInputTypeName);
-    if (!createInputType?.inputFields)
-        return fieldsWithDefaults;
-    // The CreateXInput has an inner field (e.g. "database" of type DatabaseInput)
-    // Find the inner input type that contains the actual field definitions
-    for (const inputField of createInputType.inputFields) {
-        // The inner field's type name is the actual input type (e.g. DatabaseInput)
+/**
+ * Resolve the inner input type from a CreateXInput or UpdateXInput type.
+ * The CreateXInput has an inner field (e.g. "database" of type DatabaseInput)
+ * that contains the actual field definitions.
+ */
+function resolveInnerInputType(inputTypeName, typeRegistry) {
+    const inputType = typeRegistry.get(inputTypeName);
+    if (!inputType?.inputFields)
+        return null;
+    for (const inputField of inputType.inputFields) {
         const innerTypeName = inputField.type.name
             || inputField.type.ofType?.name
             || inputField.type.ofType?.ofType?.name;
@@ -174,29 +227,70 @@ function getFieldsWithDefaults(table, typeRegistry) {
         const innerType = typeRegistry.get(innerTypeName);
         if (!innerType?.inputFields)
             continue;
-        // Check each field in the inner input type for defaultValue
-        for (const field of innerType.inputFields) {
-            if (field.defaultValue !== undefined) {
-                fieldsWithDefaults.add(field.name);
-            }
-            // Also check if the field is NOT wrapped in NON_NULL (nullable = has default or is optional)
-            if (field.type.kind !== 'NON_NULL') {
-                fieldsWithDefaults.add(field.name);
-            }
+        const fields = new Set(innerType.inputFields.map((f) => f.name));
+        return { name: innerTypeName, fields };
+    }
+    return null;
+}
+function getFieldsWithDefaults(table, typeRegistry) {
+    const fieldsWithDefaults = new Set();
+    if (!typeRegistry)
+        return fieldsWithDefaults;
+    const createInputTypeName = getCreateInputTypeName(table);
+    const resolved = resolveInnerInputType(createInputTypeName, typeRegistry);
+    if (!resolved)
+        return fieldsWithDefaults;
+    const innerType = typeRegistry.get(resolved.name);
+    if (!innerType?.inputFields)
+        return fieldsWithDefaults;
+    for (const field of innerType.inputFields) {
+        if (field.defaultValue !== undefined) {
+            fieldsWithDefaults.add(field.name);
+        }
+        if (field.type.kind !== 'NON_NULL') {
+            fieldsWithDefaults.add(field.name);
         }
     }
     return fieldsWithDefaults;
 }
-function buildMutationHandler(table, operation, targetName, typeRegistry) {
+/**
+ * Get the set of field names that actually exist in the create/update input type.
+ * Fields not in this set (e.g. computed fields like searchTsvRank, hashUuid)
+ * should be excluded from the data object in create/update handlers.
+ */
+function getWritableFieldNames(table, typeRegistry) {
+    if (!typeRegistry)
+        return null;
+    const createInputTypeName = getCreateInputTypeName(table);
+    const resolved = resolveInnerInputType(createInputTypeName, typeRegistry);
+    return resolved?.fields ?? null;
+}
+function buildMutationHandler(table, operation, targetName, typeRegistry, ormTypes) {
     const { singularName } = getTableNames(table);
     const pkFields = getPrimaryKeyInfo(table);
     const pk = pkFields[0];
-    const editableFields = getScalarFields(table).filter((f) => f.name !== pk.name &&
-        f.name !== 'nodeId' &&
-        f.name !== 'createdAt' &&
-        f.name !== 'updatedAt');
+    // Get the set of writable field names from the type registry
+    // This filters out computed fields (e.g. searchTsvRank, hashUuid) that exist
+    // on the entity type but not on the create/update input type.
+    const writableFields = getWritableFieldNames(table, typeRegistry);
     // Get fields that have defaults from introspection (for create operations)
     const fieldsWithDefaults = getFieldsWithDefaults(table, typeRegistry);
+    // For create: include fields that are in the create input type.
+    // For update/delete: always exclude the PK (it goes in `where`, not `data`).
+    // The ORM input-types generator always excludes these fields from create inputs
+    // (see EXCLUDED_MUTATION_FIELDS in input-types-generator.ts). We must match this
+    // to avoid generating data properties that don't exist on the ORM create type.
+    // For non-'id' PKs (e.g. NodeTypeRegistry.name), we allow them in create data
+    // since they are user-provided natural keys that DO appear in the create input.
+    const ORM_EXCLUDED_FIELDS = ['id', 'createdAt', 'updatedAt', 'nodeId'];
+    const editableFields = getScalarFields(table).filter((f) => 
+    // For update/delete: always exclude PK (it goes in `where`, not `data`)
+    // For create: exclude PK only if it's in the ORM exclusion list (e.g. 'id')
+    (f.name !== pk.name || (operation === 'create' && !ORM_EXCLUDED_FIELDS.includes(pk.name))) &&
+        // Always exclude ORM-excluded fields (except PK which is handled above)
+        (f.name === pk.name || !ORM_EXCLUDED_FIELDS.includes(f.name)) &&
+        // If we have type registry info, only include fields that exist in the input type
+        (writableFields === null || writableFields.has(f.name)));
     const questions = [];
     if (operation === 'update' || operation === 'delete') {
         questions.push(t.objectExpression([
@@ -225,27 +319,36 @@ function buildMutationHandler(table, operation, targetName, typeRegistry) {
         ])
         : buildSelectObject(table);
     let ormArgs;
+    // Build data properties without individual type assertions.
+    // Instead, we build a plain object from cleanedData and cast the entire
+    // data value through `unknown` to bridge the type gap between
+    // Record<string, unknown> and the ORM's specific input type.
+    // This handles scalars, enums (string literal unions like ObjectCategory),
+    // and array fields uniformly without needing to import each type.
+    const buildDataProps = () => editableFields.map((f) => t.objectProperty(t.identifier(f.name), t.memberExpression(t.identifier('cleanedData'), t.identifier(f.name))));
     if (operation === 'create') {
-        const dataProps = editableFields.map((f) => t.objectProperty(t.identifier(f.name), t.memberExpression(t.identifier('cleanedData'), t.identifier(f.name)), false, true));
         ormArgs = t.objectExpression([
-            t.objectProperty(t.identifier('data'), t.objectExpression(dataProps)),
+            t.objectProperty(t.identifier('data'), t.objectExpression(buildDataProps())),
             t.objectProperty(t.identifier('select'), selectObj),
         ]);
     }
     else if (operation === 'update') {
-        const dataProps = editableFields.map((f) => t.objectProperty(t.identifier(f.name), t.memberExpression(t.identifier('cleanedData'), t.identifier(f.name)), false, true));
         ormArgs = t.objectExpression([
             t.objectProperty(t.identifier('where'), t.objectExpression([
-                t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), t.tsStringKeyword())),
+                t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), pk.gqlType === 'Int' || pk.gqlType === 'BigInt'
+                    ? t.tsNumberKeyword()
+                    : t.tsStringKeyword())),
             ])),
-            t.objectProperty(t.identifier('data'), t.objectExpression(dataProps)),
+            t.objectProperty(t.identifier('data'), t.objectExpression(buildDataProps())),
             t.objectProperty(t.identifier('select'), selectObj),
         ]);
     }
     else {
         ormArgs = t.objectExpression([
             t.objectProperty(t.identifier('where'), t.objectExpression([
-                t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), t.tsStringKeyword())),
+                t.objectProperty(t.identifier(pk.name), t.tsAsExpression(t.memberExpression(t.identifier('answers'), t.identifier(pk.name)), pk.gqlType === 'Int' || pk.gqlType === 'BigInt'
+                    ? t.tsNumberKeyword()
+                    : t.tsStringKeyword())),
             ])),
             t.objectProperty(t.identifier('select'), selectObj),
         ]);
@@ -262,11 +365,25 @@ function buildMutationHandler(table, operation, targetName, typeRegistry) {
         ]),
     ];
     if (operation !== 'delete') {
+        // Build stripUndefined call and cast to the proper ORM input type
+        // so that property accesses on cleanedData are correctly typed.
+        const stripUndefinedCall = t.callExpression(t.identifier('stripUndefined'), [
+            t.identifier('answers'),
+            t.identifier('fieldSchema'),
+        ]);
+        let cleanedDataExpr = stripUndefinedCall;
+        if (ormTypes) {
+            if (operation === 'create') {
+                // cleanedData as CreateXxxInput['fieldName']
+                cleanedDataExpr = t.tsAsExpression(stripUndefinedCall, t.tsIndexedAccessType(t.tsTypeReference(t.identifier(ormTypes.createInputTypeName)), t.tsLiteralType(t.stringLiteral(ormTypes.innerFieldName))));
+            }
+            else if (operation === 'update') {
+                // cleanedData as XxxPatch
+                cleanedDataExpr = t.tsAsExpression(stripUndefinedCall, t.tsTypeReference(t.identifier(ormTypes.patchTypeName)));
+            }
+        }
         tryBody.push(t.variableDeclaration('const', [
-            t.variableDeclarator(t.identifier('cleanedData'), t.callExpression(t.identifier('stripUndefined'), [
-                t.identifier('answers'),
-                t.identifier('fieldSchema'),
-            ])),
+            t.variableDeclarator(t.identifier('cleanedData'), cleanedDataExpr),
         ]));
     }
     tryBody.push(buildGetClientStatement(targetName), t.variableDeclaration('const', [
@@ -294,25 +411,60 @@ export function generateTableCommand(table, options) {
     statements.push(createImportDeclaration(executorPath, ['getClient']));
     const utilsPath = options?.targetName ? '../../utils' : '../utils';
     statements.push(createImportDeclaration(utilsPath, ['coerceAnswers', 'stripUndefined']));
+    statements.push(createImportDeclaration(utilsPath, ['FieldSchema'], true));
+    // Import ORM input types for proper type assertions in mutation handlers.
+    // These types ensure that cleanedData is cast to the correct ORM input type
+    // (e.g., CreateAppPermissionInput['appPermission'] for create, AppPermissionPatch for update)
+    // instead of remaining as Record<string, unknown>.
+    const createInputTypeName = getCreateInputTypeName(table);
+    const patchTypeName = getPatchTypeName(table);
+    const innerFieldName = lcFirst(table.name);
+    // Commands are at cli/commands/xxx.ts (no target) or cli/commands/{target}/xxx.ts (with target).
+    // ORM input-types is at orm/input-types.ts — two or three levels up from commands.
+    const inputTypesPath = options?.targetName
+        ? `../../../orm/input-types`
+        : `../../orm/input-types`;
+    statements.push(createImportDeclaration(inputTypesPath, [createInputTypeName, patchTypeName], true));
     // Generate field schema for type coercion
+    // Use explicit FieldSchema type annotation so TS narrows string literals to FieldType
+    const fieldSchemaId = t.identifier('fieldSchema');
+    fieldSchemaId.typeAnnotation = t.tsTypeAnnotation(t.tsTypeReference(t.identifier('FieldSchema')));
     statements.push(t.variableDeclaration('const', [
-        t.variableDeclarator(t.identifier('fieldSchema'), buildFieldSchemaObject(table)),
+        t.variableDeclarator(fieldSchemaId, buildFieldSchemaObject(table)),
     ]));
-    const subcommands = ['list', 'get', 'create', 'update', 'delete'];
+    // Determine which operations the ORM model supports for this table.
+    // Most tables have `one: null` simply because there's no dedicated GraphQL
+    // findOne query, but the ORM still generates `findOne` using the PK.
+    // The only tables WITHOUT `findOne` are pure record types from SQL functions
+    // (e.g. GetAllRecord, OrgGetManagersRecord) which have no update/delete either.
+    // We detect these by checking: if one, update, AND delete are all null, it's a
+    // read-only record type with no `findOne`.
+    const hasUpdate = table.query?.update !== undefined && table.query?.update !== null;
+    const hasDelete = table.query?.delete !== undefined && table.query?.delete !== null;
+    const hasGet = table.query?.one !== null || hasUpdate || hasDelete;
+    const subcommands = ['list'];
+    if (hasGet)
+        subcommands.push('get');
+    subcommands.push('create');
+    if (hasUpdate)
+        subcommands.push('update');
+    if (hasDelete)
+        subcommands.push('delete');
     const usageLines = [
         '',
         `${commandName} <command>`,
         '',
         'Commands:',
         `  list                  List all ${singularName} records`,
-        `  get                   Get a ${singularName} by ID`,
-        `  create                Create a new ${singularName}`,
-        `  update                Update an existing ${singularName}`,
-        `  delete                Delete a ${singularName}`,
-        '',
-        '  --help, -h            Show this help message',
-        '',
     ];
+    if (hasGet)
+        usageLines.push(`  get                   Get a ${singularName} by ID`);
+    usageLines.push(`  create                Create a new ${singularName}`);
+    if (hasUpdate)
+        usageLines.push(`  update                Update an existing ${singularName}`);
+    if (hasDelete)
+        usageLines.push(`  delete                Delete a ${singularName}`);
+    usageLines.push('', '  --help, -h            Show this help message', '');
     statements.push(t.variableDeclaration('const', [
         t.variableDeclarator(t.identifier('usage'), t.stringLiteral(usageLines.join('\n'))),
     ]));
@@ -350,7 +502,7 @@ export function generateTableCommand(table, options) {
                 ]))),
             ]),
             t.returnStatement(t.callExpression(t.identifier('handleTableSubcommand'), [
-                t.memberExpression(t.identifier('answer'), t.identifier('subcommand')),
+                t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('subcommand')), t.tsStringKeyword()),
                 t.identifier('newArgv'),
                 t.identifier('prompter'),
             ])),
@@ -372,11 +524,15 @@ export function generateTableCommand(table, options) {
         buildSubcommandSwitch(subcommands, 'handle', 'usage'),
     ]), false, true));
     const tn = options?.targetName;
+    const ormTypes = { createInputTypeName, patchTypeName, innerFieldName };
     statements.push(buildListHandler(table, tn));
-    statements.push(buildGetHandler(table, tn));
-    statements.push(buildMutationHandler(table, 'create', tn, options?.typeRegistry));
-    statements.push(buildMutationHandler(table, 'update', tn, options?.typeRegistry));
-    statements.push(buildMutationHandler(table, 'delete', tn, options?.typeRegistry));
+    if (hasGet)
+        statements.push(buildGetHandler(table, tn));
+    statements.push(buildMutationHandler(table, 'create', tn, options?.typeRegistry, ormTypes));
+    if (hasUpdate)
+        statements.push(buildMutationHandler(table, 'update', tn, options?.typeRegistry, ormTypes));
+    if (hasDelete)
+        statements.push(buildMutationHandler(table, 'delete', tn, options?.typeRegistry, ormTypes));
     const header = getGeneratedFileHeader(`CLI commands for ${table.name}`);
     const code = generateCode(statements);
     return {

package/esm/core/codegen/docs-utils.d.ts

@@ -20,6 +20,16 @@ export interface SkillDefinition {
     }[];
     language?: string;
 }
+export interface SkillReferenceDefinition {
+    title: string;
+    description: string;
+    usage: string[];
+    examples: {
+        description: string;
+        code: string[];
+    }[];
+    language?: string;
+}
 export declare function getReadmeHeader(title: string): string[];
 export declare function getReadmeFooter(): string[];
 export declare function resolveDocsConfig(docs: DocsConfig | boolean | undefined): DocsConfig;
@@ -27,4 +37,5 @@ export declare function formatArgType(arg: CleanOperation['args'][number]): stri
 export declare function formatTypeRef(t: CleanOperation['args'][number]['type']): string;
 export declare function getEditableFields(table: CleanTable): CleanField[];
 export declare function gqlTypeToJsonSchemaType(gqlType: string): string;
-export declare function buildSkillFile(skill: SkillDefinition): string;
+export declare function buildSkillFile(skill: SkillDefinition, referenceNames?: string[]): string;
+export declare function buildSkillReference(ref: SkillReferenceDefinition): string;

package/esm/core/codegen/docs-utils.js

@@ -79,9 +79,15 @@ export function gqlTypeToJsonSchemaType(gqlType) {
             return 'string';
     }
 }
-export function buildSkillFile(skill) {
+export function buildSkillFile(skill, referenceNames) {
     const lang = skill.language ?? 'bash';
     const lines = [];
+    // YAML frontmatter (Agent Skills format)
+    lines.push('---');
+    lines.push(`name: ${skill.name}`);
+    lines.push(`description: ${skill.description}`);
+    lines.push('---');
+    lines.push('');
     lines.push(`# ${skill.name}`);
     lines.push('');
     lines.push('<!-- @constructive-io/graphql-codegen - DO NOT EDIT -->');
@@ -108,5 +114,46 @@ export function buildSkillFile(skill) {
         lines.push('```');
         lines.push('');
     }
+    if (referenceNames && referenceNames.length > 0) {
+        lines.push('## References');
+        lines.push('');
+        lines.push('See the `references/` directory for detailed per-entity API documentation:');
+        lines.push('');
+        for (const name of referenceNames) {
+            lines.push(`- [${name}](references/${name}.md)`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export function buildSkillReference(ref) {
+    const lang = ref.language ?? 'bash';
+    const lines = [];
+    lines.push(`# ${ref.title}`);
+    lines.push('');
+    lines.push('<!-- @constructive-io/graphql-codegen - DO NOT EDIT -->');
+    lines.push('');
+    lines.push(ref.description);
+    lines.push('');
+    lines.push('## Usage');
+    lines.push('');
+    lines.push(`\`\`\`${lang}`);
+    for (const u of ref.usage) {
+        lines.push(u);
+    }
+    lines.push('```');
+    lines.push('');
+    lines.push('## Examples');
+    lines.push('');
+    for (const ex of ref.examples) {
+        lines.push(`### ${ex.description}`);
+        lines.push('');
+        lines.push(`\`\`\`${lang}`);
+        for (const cmd of ex.code) {
+            lines.push(cmd);
+        }
+        lines.push('```');
+        lines.push('');
+    }
     return lines.join('\n');
 }

package/esm/core/codegen/hooks-docs-generator.d.ts

@@ -3,4 +3,4 @@ import type { GeneratedDocFile, McpTool } from './docs-utils';
 export declare function generateHooksReadme(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
 export declare function generateHooksAgentsDocs(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
 export declare function getHooksMcpTools(tables: CleanTable[], customOperations: CleanOperation[]): McpTool[];
-export declare function generateHooksSkills(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile[];
+export declare function generateHooksSkills(tables: CleanTable[], customOperations: CleanOperation[], targetName: string): GeneratedDocFile[];

package/esm/core/codegen/hooks-docs-generator.js

@@ -1,4 +1,5 @@
-import { buildSkillFile, formatArgType, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, } from './docs-utils';
+import { toKebabCase } from 'komoji';
+import { buildSkillFile, buildSkillReference, formatArgType, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, } from './docs-utils';
 import { getTableNames, getScalarFields, getPrimaryKeyInfo, getListQueryHookName, getSingleQueryHookName, getCreateMutationHookName, getUpdateMutationHookName, getDeleteMutationHookName, hasValidPrimaryKey, ucFirst, lcFirst, fieldTypeToTs, } from './utils';
 function getCustomHookName(op) {
     if (op.kind === 'query') {
@@ -371,8 +372,11 @@ export function getHooksMcpTools(tables, customOperations) {
     }
     return tools;
 }
-export function generateHooksSkills(tables, customOperations) {
+export function generateHooksSkills(tables, customOperations, targetName) {
     const files = [];
+    const skillName = `hooks-${targetName}`;
+    const referenceNames = [];
+    // Generate reference files for each table
     for (const table of tables) {
         const { singularName, pluralName } = getTableNames(table);
         const pk = getPrimaryKeyInfo(table)[0];
@@ -380,10 +384,12 @@ export function generateHooksSkills(tables, customOperations) {
         const selectFields = scalarFields
             .map((f) => `${f.name}: true`)
             .join(', ');
+        const refName = toKebabCase(singularName);
+        referenceNames.push(refName);
         files.push({
-            fileName: `skills/${lcFirst(singularName)}.md`,
-            content: buildSkillFile({
-                name: `hooks-${lcFirst(singularName)}`,
+            fileName: `${skillName}/references/${refName}.md`,
+            content: buildSkillReference({
+                title: singularName,
                 description: table.description || `React Query hooks for ${table.name} data operations`,
                 language: 'typescript',
                 usage: [
@@ -423,15 +429,18 @@ export function generateHooksSkills(tables, customOperations) {
             }),
         });
     }
+    // Generate reference files for custom operations
     for (const op of customOperations) {
         const hookName = getCustomHookName(op);
         const callArgs = op.args.length > 0
             ? `{ ${op.args.map((a) => `${a.name}: '<value>'`).join(', ')} }`
             : '';
+        const refName = toKebabCase(op.name);
+        referenceNames.push(refName);
         files.push({
-            fileName: `skills/${op.name}.md`,
-            content: buildSkillFile({
-                name: `hooks-${op.name}`,
+            fileName: `${skillName}/references/${refName}.md`,
+            content: buildSkillReference({
+                title: op.name,
                 description: op.description ||
                     `React Query ${op.kind} hook for ${op.name}`,
                 language: 'typescript',
@@ -458,5 +467,36 @@ export function generateHooksSkills(tables, customOperations) {
             }),
         });
     }
+    // Generate the overview SKILL.md
+    const hookExamples = tables.slice(0, 3).map((t) => getListQueryHookName(t));
+    files.push({
+        fileName: `${skillName}/SKILL.md`,
+        content: buildSkillFile({
+            name: skillName,
+            description: `React Query hooks for the ${targetName} API — provides typed query and mutation hooks for ${tables.length} tables and ${customOperations.length} custom operations`,
+            language: 'typescript',
+            usage: [
+                `// Import hooks`,
+                `import { ${hookExamples[0] || 'useModelQuery'} } from './hooks';`,
+                '',
+                `// Query hooks: use<Model>Query, use<Model>sQuery`,
+                `// Mutation hooks: useCreate<Model>Mutation, useUpdate<Model>Mutation, useDelete<Model>Mutation`,
+                '',
+                `const { data, isLoading } = ${hookExamples[0] || 'useModelQuery'}({`,
+                `  selection: { fields: { id: true } },`,
+                `});`,
+            ],
+            examples: [
+                {
+                    description: 'Query records',
+                    code: [
+                        `const { data, isLoading } = ${hookExamples[0] || 'useModelQuery'}({`,
+                        '  selection: { fields: { id: true } },',
+                        '});',
+                    ],
+                },
+            ],
+        }, referenceNames),
+    });
     return files;
 }

package/esm/core/codegen/orm/docs-generator.d.ts

@@ -3,4 +3,4 @@ import type { GeneratedDocFile, McpTool } from '../docs-utils';
 export declare function generateOrmReadme(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
 export declare function generateOrmAgentsDocs(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile;
 export declare function getOrmMcpTools(tables: CleanTable[], customOperations: CleanOperation[]): McpTool[];
-export declare function generateOrmSkills(tables: CleanTable[], customOperations: CleanOperation[]): GeneratedDocFile[];
+export declare function generateOrmSkills(tables: CleanTable[], customOperations: CleanOperation[], targetName: string): GeneratedDocFile[];