@constructive-io/graphql-codegen 4.14.4 → 4.15.0

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

@@ -35,7 +35,42 @@ export declare function getReadmeFooter(): string[];
 export declare function resolveDocsConfig(docs: DocsConfig | boolean | undefined): DocsConfig;
 export declare function formatArgType(arg: CleanOperation['args'][number]): string;
 export declare function formatTypeRef(t: CleanOperation['args'][number]['type']): string;
-export declare function getEditableFields(table: CleanTable): CleanField[];
+export declare function getEditableFields(table: CleanTable, typeRegistry?: TypeRegistry): CleanField[];
+/**
+ * Identify search/computed fields on a table — fields present in the GraphQL
+ * type but NOT in the create input type. These are plugin-added fields like
+ * trgm similarity scores, tsvector ranks, searchScore, etc.
+ */
+export declare function getSearchFields(table: CleanTable, typeRegistry?: TypeRegistry): CleanField[];
+export interface SpecialFieldGroup {
+    /** Category key */
+    category: 'geospatial' | 'embedding' | 'search';
+    /** Human-readable label */
+    label: string;
+    /** One-line description of this category */
+    description: string;
+    /** Fields belonging to this category */
+    fields: CleanField[];
+}
+/**
+ * Categorize "special" fields on a table into PostGIS, pgvector, and
+ * Unified Search groups.  Returns only non-empty groups.
+ *
+ * The function inspects ALL scalar fields (not just computed ones) so that
+ * real columns (geometry, vector, tsvector) are also surfaced with
+ * descriptive context in generated docs.
+ */
+export declare function categorizeSpecialFields(table: CleanTable, typeRegistry?: TypeRegistry): SpecialFieldGroup[];
+/**
+ * Build markdown lines describing special fields for README-style docs.
+ * Returns empty array when there are no special fields.
+ */
+export declare function buildSpecialFieldsMarkdown(groups: SpecialFieldGroup[]): string[];
+/**
+ * Build plain-text lines describing special fields for AGENTS-style docs.
+ * Returns empty array when there are no special fields.
+ */
+export declare function buildSpecialFieldsPlain(groups: SpecialFieldGroup[]): string[];
 /**
  * Represents a flattened argument for docs/skills generation.
  * INPUT_OBJECT args are expanded to dot-notation fields.

package/core/codegen/docs-utils.js

@@ -6,6 +6,10 @@ exports.resolveDocsConfig = resolveDocsConfig;
 exports.formatArgType = formatArgType;
 exports.formatTypeRef = formatTypeRef;
 exports.getEditableFields = getEditableFields;
+exports.getSearchFields = getSearchFields;
+exports.categorizeSpecialFields = categorizeSpecialFields;
+exports.buildSpecialFieldsMarkdown = buildSpecialFieldsMarkdown;
+exports.buildSpecialFieldsPlain = buildSpecialFieldsPlain;
 exports.cleanTypeName = cleanTypeName;
 exports.flattenArgs = flattenArgs;
 exports.flattenedArgsToFlags = flattenedArgsToFlags;
@@ -74,12 +78,154 @@ function formatTypeRef(t) {
     }
     return t.name ?? 'unknown';
 }
-function getEditableFields(table) {
+function getEditableFields(table, typeRegistry) {
     const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
+    const writableFields = (0, utils_1.getWritableFieldNames)(table, typeRegistry);
     return (0, utils_1.getScalarFields)(table).filter((f) => f.name !== pk.name &&
         f.name !== 'nodeId' &&
         f.name !== 'createdAt' &&
-        f.name !== 'updatedAt');
+        f.name !== 'updatedAt' &&
+        // When a TypeRegistry is available, filter out computed/plugin-added
+        // fields (e.g. search scores, trgm similarity) that aren't real columns
+        (writableFields === null || writableFields.has(f.name)));
+}
+/**
+ * Identify search/computed fields on a table — fields present in the GraphQL
+ * type but NOT in the create input type. These are plugin-added fields like
+ * trgm similarity scores, tsvector ranks, searchScore, etc.
+ */
+function getSearchFields(table, typeRegistry) {
+    const writableFields = (0, utils_1.getWritableFieldNames)(table, typeRegistry);
+    if (writableFields === null)
+        return [];
+    const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
+    return (0, utils_1.getScalarFields)(table).filter((f) => f.name !== pk.name &&
+        f.name !== 'nodeId' &&
+        f.name !== 'createdAt' &&
+        f.name !== 'updatedAt' &&
+        !writableFields.has(f.name));
+}
+function isPostGISField(f) {
+    const pgType = f.type.pgType?.toLowerCase();
+    if (pgType === 'geometry' || pgType === 'geography')
+        return true;
+    const gql = f.type.gqlType;
+    if (/^(GeoJSON|GeographyPoint|GeographyLineString|GeographyPolygon|GeometryPoint|GeometryLineString|GeometryPolygon|GeographyMulti|GeometryMulti|GeometryCollection|GeographyCollection)/i.test(gql))
+        return true;
+    return false;
+}
+function isEmbeddingField(f) {
+    const pgType = f.type.pgType?.toLowerCase();
+    if (pgType === 'vector')
+        return true;
+    if (/embedding$/i.test(f.name) && f.type.isArray && f.type.gqlType === 'Float')
+        return true;
+    return false;
+}
+function isTsvectorField(f) {
+    const pgType = f.type.pgType?.toLowerCase();
+    return pgType === 'tsvector';
+}
+function isSearchComputedField(f) {
+    if (f.name === 'searchScore')
+        return true;
+    if (/TrgmSimilarity$/.test(f.name))
+        return true;
+    if (/TsvectorRank$/.test(f.name))
+        return true;
+    if (/Bm25Score$/.test(f.name))
+        return true;
+    return false;
+}
+/**
+ * Categorize "special" fields on a table into PostGIS, pgvector, and
+ * Unified Search groups.  Returns only non-empty groups.
+ *
+ * The function inspects ALL scalar fields (not just computed ones) so that
+ * real columns (geometry, vector, tsvector) are also surfaced with
+ * descriptive context in generated docs.
+ */
+function categorizeSpecialFields(table, typeRegistry) {
+    const allFields = (0, utils_1.getScalarFields)(table);
+    const computedFields = getSearchFields(table, typeRegistry);
+    const computedSet = new Set(computedFields.map((f) => f.name));
+    const geospatial = [];
+    const embedding = [];
+    const search = [];
+    for (const f of allFields) {
+        if (isPostGISField(f)) {
+            geospatial.push(f);
+        }
+        else if (isEmbeddingField(f)) {
+            embedding.push(f);
+        }
+        else if (isTsvectorField(f)) {
+            search.push(f);
+        }
+        else if (computedSet.has(f.name) && isSearchComputedField(f)) {
+            search.push(f);
+        }
+    }
+    const groups = [];
+    if (geospatial.length > 0) {
+        groups.push({
+            category: 'geospatial',
+            label: 'PostGIS geospatial fields',
+            description: 'Geographic/geometric columns managed by PostGIS. Supports spatial queries (distance, containment, intersection) via the Unified Search API PostGIS adapter.',
+            fields: geospatial,
+        });
+    }
+    if (embedding.length > 0) {
+        groups.push({
+            category: 'embedding',
+            label: 'pgvector embedding fields',
+            description: 'High-dimensional vector columns for semantic similarity search. Query via the Unified Search API pgvector adapter using cosine, L2, or inner-product distance.',
+            fields: embedding,
+        });
+    }
+    if (search.length > 0) {
+        groups.push({
+            category: 'search',
+            label: 'Unified Search API fields',
+            description: 'Fields provided by the Unified Search plugin. Includes full-text search (tsvector/BM25), trigram similarity scores, and the combined searchScore. Computed fields are read-only and cannot be set in create/update operations.',
+            fields: search,
+        });
+    }
+    return groups;
+}
+/**
+ * Build markdown lines describing special fields for README-style docs.
+ * Returns empty array when there are no special fields.
+ */
+function buildSpecialFieldsMarkdown(groups) {
+    if (groups.length === 0)
+        return [];
+    const lines = [];
+    for (const g of groups) {
+        const fieldList = g.fields.map((f) => `\`${f.name}\``).join(', ');
+        lines.push(`> **${g.label}:** ${fieldList}`);
+        lines.push(`> ${g.description}`);
+        lines.push('');
+    }
+    return lines;
+}
+/**
+ * Build plain-text lines describing special fields for AGENTS-style docs.
+ * Returns empty array when there are no special fields.
+ */
+function buildSpecialFieldsPlain(groups) {
+    if (groups.length === 0)
+        return [];
+    const lines = [];
+    lines.push('SPECIAL FIELDS:');
+    for (const g of groups) {
+        lines.push(`  [${g.label}]`);
+        lines.push(`  ${g.description}`);
+        for (const f of g.fields) {
+            lines.push(`    ${f.name}: ${cleanTypeName(f.type.gqlType)}`);
+        }
+    }
+    return lines;
 }
 function unwrapNonNull(typeRef) {
     if (typeRef.kind === 'NON_NULL' && typeRef.ofType) {

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

@@ -123,17 +123,19 @@ function generateHooksReadme(tables, customOperations) {
 }
 function generateHooksAgentsDocs(tables, customOperations) {
     const lines = [];
-    lines.push('# React Query Hooks - Agent Reference');
+    const tableCount = tables.length;
+    const customOpCount = customOperations.length;
+    lines.push('# React Query Hooks');
     lines.push('');
     lines.push('<!-- @constructive-io/graphql-codegen - DO NOT EDIT -->');
-    lines.push('> This document is structured for LLM/agent consumption.');
     lines.push('');
-    lines.push('## OVERVIEW');
+    lines.push('## Stack');
     lines.push('');
-    lines.push('React Query hooks wrapping ORM operations for data fetching and mutations.');
-    lines.push('All query hooks return `UseQueryResult`. All mutation hooks return `UseMutationResult`.');
+    lines.push('- React Query hooks wrapping ORM operations (TypeScript)');
+    lines.push(`- ${tableCount} table${tableCount !== 1 ? 's' : ''}${customOpCount > 0 ? `, ${customOpCount} custom operation${customOpCount !== 1 ? 's' : ''}` : ''}`);
+    lines.push('- Query hooks return `UseQueryResult`, mutation hooks return `UseMutationResult`');
     lines.push('');
-    lines.push('## SETUP');
+    lines.push('## Quick Start');
     lines.push('');
     lines.push('```typescript');
     lines.push("import { configure } from './hooks';");
@@ -144,123 +146,22 @@ function generateHooksAgentsDocs(tables, customOperations) {
     lines.push('// Wrap app in <QueryClientProvider client={queryClient}>');
     lines.push('```');
     lines.push('');
-    lines.push('## HOOKS');
+    lines.push('## Resources');
+    lines.push('');
+    lines.push(`- **Full API reference:** [README.md](./README.md) — hook docs for all ${tableCount} tables`);
+    lines.push('- **Schema types:** [types.ts](./types.ts)');
+    lines.push('- **Hooks module:** [hooks.ts](./hooks.ts)');
+    lines.push('');
+    lines.push('## Conventions');
+    lines.push('');
+    lines.push('- Query hooks: `use<PluralName>Query`, `use<SingularName>Query`');
+    lines.push('- Mutation hooks: `useCreate<Name>Mutation`, `useUpdate<Name>Mutation`, `useDelete<Name>Mutation`');
+    lines.push('- All hooks accept a `selection` parameter to pick fields');
+    lines.push('');
+    lines.push('## Boundaries');
+    lines.push('');
+    lines.push('All files in this directory are generated. Do not edit manually.');
     lines.push('');
-    for (const table of tables) {
-        const { singularName, pluralName } = (0, utils_1.getTableNames)(table);
-        const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
-        const scalarFields = (0, utils_1.getScalarFields)(table);
-        lines.push(`### HOOK: ${(0, utils_1.getListQueryHookName)(table)}`);
-        lines.push('');
-        lines.push(`${table.description || `List all ${pluralName}`}.`);
-        lines.push('');
-        lines.push('```');
-        lines.push(`TYPE: query`);
-        lines.push(`USAGE: ${(0, utils_1.getListQueryHookName)(table)}({ selection: { fields: { ... } } })`);
-        lines.push('');
-        lines.push('INPUT:');
-        lines.push('  selection: { fields: Record<string, boolean> } - Fields to select');
-        lines.push('');
-        lines.push('OUTPUT: UseQueryResult<Array<{');
-        for (const f of scalarFields) {
-            lines.push(`  ${f.name}: ${(0, utils_1.fieldTypeToTs)(f.type)}`);
-        }
-        lines.push('}>>');
-        lines.push('```');
-        lines.push('');
-        if ((0, utils_1.hasValidPrimaryKey)(table)) {
-            lines.push(`### HOOK: ${(0, utils_1.getSingleQueryHookName)(table)}`);
-            lines.push('');
-            lines.push(`${table.description || `Get a single ${singularName} by ${pk.name}`}.`);
-            lines.push('');
-            lines.push('```');
-            lines.push(`TYPE: query`);
-            lines.push(`USAGE: ${(0, utils_1.getSingleQueryHookName)(table)}({ ${pk.name}: '<value>', selection: { fields: { ... } } })`);
-            lines.push('');
-            lines.push('INPUT:');
-            lines.push(`  ${pk.name}: ${pk.tsType} (required)`);
-            lines.push('  selection: { fields: Record<string, boolean> } - Fields to select');
-            lines.push('');
-            lines.push('OUTPUT: UseQueryResult<{');
-            for (const f of scalarFields) {
-                lines.push(`  ${f.name}: ${(0, utils_1.fieldTypeToTs)(f.type)}`);
-            }
-            lines.push('}>');
-            lines.push('```');
-            lines.push('');
-        }
-        lines.push(`### HOOK: ${(0, utils_1.getCreateMutationHookName)(table)}`);
-        lines.push('');
-        lines.push(`${table.description || `Create a new ${singularName}`}.`);
-        lines.push('');
-        lines.push('```');
-        lines.push('TYPE: mutation');
-        lines.push(`USAGE: const { mutate } = ${(0, utils_1.getCreateMutationHookName)(table)}({ selection: { fields: { ... } } })`);
-        lines.push('');
-        lines.push('OUTPUT: UseMutationResult');
-        lines.push('```');
-        lines.push('');
-        if ((0, utils_1.hasValidPrimaryKey)(table)) {
-            lines.push(`### HOOK: ${(0, utils_1.getUpdateMutationHookName)(table)}`);
-            lines.push('');
-            lines.push(`${table.description || `Update an existing ${singularName}`}.`);
-            lines.push('');
-            lines.push('```');
-            lines.push('TYPE: mutation');
-            lines.push(`USAGE: const { mutate } = ${(0, utils_1.getUpdateMutationHookName)(table)}({ selection: { fields: { ... } } })`);
-            lines.push('');
-            lines.push('OUTPUT: UseMutationResult');
-            lines.push('```');
-            lines.push('');
-            lines.push(`### HOOK: ${(0, utils_1.getDeleteMutationHookName)(table)}`);
-            lines.push('');
-            lines.push(`${table.description || `Delete a ${singularName}`}.`);
-            lines.push('');
-            lines.push('```');
-            lines.push('TYPE: mutation');
-            lines.push(`USAGE: const { mutate } = ${(0, utils_1.getDeleteMutationHookName)(table)}({})`);
-            lines.push('');
-            lines.push('OUTPUT: UseMutationResult');
-            lines.push('```');
-            lines.push('');
-        }
-    }
-    if (customOperations.length > 0) {
-        lines.push('## CUSTOM OPERATION HOOKS');
-        lines.push('');
-        for (const op of customOperations) {
-            const hookName = getCustomHookName(op);
-            lines.push(`### HOOK: ${hookName}`);
-            lines.push('');
-            lines.push(op.description || op.name);
-            lines.push('');
-            lines.push('```');
-            lines.push(`TYPE: ${op.kind}`);
-            if (op.args.length > 0) {
-                if (op.kind === 'mutation') {
-                    lines.push(`USAGE: const { mutate } = ${hookName}()`);
-                    lines.push(`  mutate({ ${op.args.map((a) => `${a.name}: <value>`).join(', ')} })`);
-                }
-                else {
-                    lines.push(`USAGE: ${hookName}({ ${op.args.map((a) => `${a.name}: <value>`).join(', ')} })`);
-                }
-                lines.push('');
-                lines.push('INPUT:');
-                for (const arg of op.args) {
-                    lines.push(`  ${arg.name}: ${(0, docs_utils_1.formatArgType)(arg)}`);
-                }
-            }
-            else {
-                lines.push(`USAGE: ${hookName}()`);
-                lines.push('');
-                lines.push('INPUT: none');
-            }
-            lines.push('');
-            lines.push(`OUTPUT: ${op.kind === 'query' ? 'UseQueryResult' : 'UseMutationResult'}`);
-            lines.push('```');
-            lines.push('');
-        }
-    }
     return {
         fileName: 'AGENTS.md',
         content: lines.join('\n'),

package/core/codegen/orm/docs-generator.js

@@ -70,6 +70,8 @@ function generateOrmReadme(tables, customOperations) {
             lines.push(`const deleted = await db.${singularName}.delete({ where: { ${pk.name}: '<value>' } }).execute();`);
             lines.push('```');
             lines.push('');
+            const ormSpecialGroups = (0, docs_utils_1.categorizeSpecialFields)(table);
+            lines.push(...(0, docs_utils_1.buildSpecialFieldsMarkdown)(ormSpecialGroups));
         }
     }
     if (customOperations.length > 0) {
@@ -113,17 +115,19 @@ function generateOrmReadme(tables, customOperations) {
 }
 function generateOrmAgentsDocs(tables, customOperations) {
     const lines = [];
-    lines.push('# ORM Client - Agent Reference');
+    const tableCount = tables.length;
+    const customOpCount = customOperations.length;
+    lines.push('# ORM Client');
     lines.push('');
     lines.push('<!-- @constructive-io/graphql-codegen - DO NOT EDIT -->');
-    lines.push('> This document is structured for LLM/agent consumption.');
     lines.push('');
-    lines.push('## OVERVIEW');
+    lines.push('## Stack');
     lines.push('');
-    lines.push('Prisma-like ORM client for interacting with a GraphQL API.');
-    lines.push('All methods return a query builder. Call `.execute()` to run the query.');
+    lines.push('- Prisma-like ORM client for a GraphQL API (TypeScript)');
+    lines.push(`- ${tableCount} model${tableCount !== 1 ? 's' : ''}${customOpCount > 0 ? `, ${customOpCount} custom operation${customOpCount !== 1 ? 's' : ''}` : ''}`);
+    lines.push('- All methods return a query builder; call `.execute()` to run');
     lines.push('');
-    lines.push('## SETUP');
+    lines.push('## Quick Start');
     lines.push('');
     lines.push('```typescript');
     lines.push("import { createClient } from './orm';");
@@ -134,88 +138,22 @@ function generateOrmAgentsDocs(tables, customOperations) {
     lines.push('});');
     lines.push('```');
     lines.push('');
-    lines.push('## MODELS');
+    lines.push('## Resources');
     lines.push('');
-    for (const table of tables) {
-        const { singularName } = (0, utils_1.getTableNames)(table);
-        const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
-        const scalarFields = (0, utils_1.getScalarFields)(table);
-        const editableFields = (0, docs_utils_1.getEditableFields)(table);
-        lines.push(`### MODEL: ${singularName}`);
-        lines.push('');
-        lines.push(`Access: \`db.${singularName}\``);
-        lines.push('');
-        lines.push('```');
-        lines.push('METHODS:');
-        lines.push(`  db.${singularName}.findMany({ select, where?, orderBy?, first?, offset? })`);
-        lines.push(`  db.${singularName}.findOne({ ${pk.name}, select })`);
-        lines.push(`  db.${singularName}.create({ data: { ${editableFields.map((f) => f.name).join(', ')} }, select })`);
-        lines.push(`  db.${singularName}.update({ where: { ${pk.name} }, data, select })`);
-        lines.push(`  db.${singularName}.delete({ where: { ${pk.name} } })`);
-        lines.push('');
-        lines.push('FIELDS:');
-        for (const f of scalarFields) {
-            const isPk = f.name === pk.name;
-            lines.push(`  ${f.name}: ${(0, utils_1.fieldTypeToTs)(f.type)}${isPk ? ' (primary key)' : ''}`);
-        }
-        lines.push('');
-        lines.push('EDITABLE FIELDS:');
-        for (const f of editableFields) {
-            lines.push(`  ${f.name}: ${(0, utils_1.fieldTypeToTs)(f.type)}`);
-        }
-        lines.push('');
-        lines.push('OUTPUT: Promise<JSON>');
-        lines.push(`  findMany: [{ ${scalarFields.map((f) => f.name).join(', ')} }]`);
-        lines.push(`  findOne:  { ${scalarFields.map((f) => f.name).join(', ')} }`);
-        lines.push(`  create:   { ${scalarFields.map((f) => f.name).join(', ')} }`);
-        lines.push(`  update:   { ${scalarFields.map((f) => f.name).join(', ')} }`);
-        lines.push(`  delete:   { ${pk.name} }`);
-        lines.push('```');
-        lines.push('');
-    }
-    if (customOperations.length > 0) {
-        lines.push('## CUSTOM OPERATIONS');
-        lines.push('');
-        for (const op of customOperations) {
-            const accessor = op.kind === 'query' ? 'query' : 'mutation';
-            lines.push(`### OPERATION: ${op.name}`);
-            lines.push('');
-            lines.push(op.description || op.name);
-            lines.push('');
-            lines.push('```');
-            lines.push(`TYPE: ${op.kind}`);
-            lines.push(`ACCESS: db.${accessor}.${op.name}`);
-            if (op.args.length > 0) {
-                lines.push(`USAGE: db.${accessor}.${op.name}({ ${op.args.map((a) => `${a.name}: <value>`).join(', ')} }).execute()`);
-                lines.push('');
-                lines.push('INPUT:');
-                for (const arg of op.args) {
-                    lines.push(`  ${arg.name}: ${(0, docs_utils_1.formatArgType)(arg)}`);
-                }
-            }
-            else {
-                lines.push(`USAGE: db.${accessor}.${op.name}().execute()`);
-                lines.push('');
-                lines.push('INPUT: none');
-            }
-            lines.push('');
-            lines.push('OUTPUT: Promise<JSON>');
-            lines.push('```');
-            lines.push('');
-        }
-    }
-    lines.push('## PATTERNS');
+    lines.push(`- **Full API reference:** [README.md](./README.md) — model docs for all ${tableCount} tables`);
+    lines.push('- **Schema types:** [types.ts](./types.ts)');
+    lines.push('- **ORM client:** [orm.ts](./orm.ts)');
     lines.push('');
-    lines.push('```typescript');
-    lines.push('// All methods require .execute() to run');
-    lines.push('const result = await db.modelName.findMany({ select: { id: true } }).execute();');
+    lines.push('## Conventions');
     lines.push('');
-    lines.push('// Select specific fields');
-    lines.push('const partial = await db.modelName.findMany({ select: { id: true, name: true } }).execute();');
+    lines.push('- Access models via `db.<ModelName>` (e.g. `db.User`)');
+    lines.push('- CRUD methods: `findMany`, `findOne`, `create`, `update`, `delete`');
+    lines.push('- Always call `.execute()` to run the query');
+    lines.push('- Custom operations via `db.query.<name>` or `db.mutation.<name>`');
     lines.push('');
-    lines.push('// Filter with where clause');
-    lines.push("const filtered = await db.modelName.findMany({ select: { id: true }, where: { name: 'test' } }).execute();");
-    lines.push('```');
+    lines.push('## Boundaries');
+    lines.push('');
+    lines.push('All files in this directory are generated. Do not edit manually.');
     lines.push('');
     return {
         fileName: 'AGENTS.md',
@@ -359,11 +297,17 @@ function generateOrmSkills(tables, customOperations, targetName) {
         const modelName = (0, utils_1.lcFirst)(singularName);
         const refName = (0, komoji_1.toKebabCase)(singularName);
         referenceNames.push(refName);
+        const ormSkillSpecialGroups = (0, docs_utils_1.categorizeSpecialFields)(table);
+        const ormSkillBaseDesc = table.description || `ORM operations for ${table.name} records`;
+        const ormSkillSpecialDesc = ormSkillSpecialGroups.length > 0
+            ? ormSkillBaseDesc + '\n\n' +
+                ormSkillSpecialGroups.map((g) => `**${g.label}:** ${g.fields.map((f) => `\`${f.name}\``).join(', ')}\n${g.description}`).join('\n\n')
+            : ormSkillBaseDesc;
         files.push({
             fileName: `${skillName}/references/${refName}.md`,
             content: (0, docs_utils_1.buildSkillReference)({
                 title: singularName,
-                description: table.description || `ORM operations for ${table.name} records`,
+                description: ormSkillSpecialDesc,
                 language: 'typescript',
                 usage: [
                     `db.${modelName}.findMany({ select: { id: true } }).execute()`,

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

@@ -3,7 +3,7 @@ import type { GeneratedDocFile, McpTool } from '../docs-utils';
 export { resolveDocsConfig } from '../docs-utils';
 export type { GeneratedDocFile, McpTool } from '../docs-utils';
 export declare function generateReadme(tables: CleanTable[], customOperations: CleanOperation[], toolName: string, registry?: TypeRegistry): GeneratedDocFile;
-export declare function generateAgentsDocs(tables: CleanTable[], customOperations: CleanOperation[], toolName: string, registry?: TypeRegistry): GeneratedDocFile;
+export declare function generateAgentsDocs(tables: CleanTable[], customOperations: CleanOperation[], toolName: string, _registry?: TypeRegistry): GeneratedDocFile;
 export declare function getCliMcpTools(tables: CleanTable[], customOperations: CleanOperation[], toolName: string, registry?: TypeRegistry): McpTool[];
 export declare function generateSkills(tables: CleanTable[], customOperations: CleanOperation[], toolName: string, targetName: string, registry?: TypeRegistry): GeneratedDocFile[];
 export interface MultiTargetDocsInput {