@constructive-io/graphql-codegen 4.14.3 → 4.15.0

package/esm/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/esm/core/codegen/docs-utils.js

@@ -1,4 +1,4 @@
-import { getScalarFields, getPrimaryKeyInfo } from './utils';
+import { getScalarFields, getPrimaryKeyInfo, getWritableFieldNames } from './utils';
 const CONSTRUCTIVE_LOGO_URL = 'https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg';
 const CONSTRUCTIVE_REPO = 'https://github.com/constructive-io/constructive';
 export function getReadmeHeader(title) {
@@ -60,12 +60,154 @@ export function formatTypeRef(t) {
     }
     return t.name ?? 'unknown';
 }
-export function getEditableFields(table) {
+export function getEditableFields(table, typeRegistry) {
     const pk = getPrimaryKeyInfo(table)[0];
+    const writableFields = getWritableFieldNames(table, typeRegistry);
     return 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.
+ */
+export function getSearchFields(table, typeRegistry) {
+    const writableFields = getWritableFieldNames(table, typeRegistry);
+    if (writableFields === null)
+        return [];
+    const pk = getPrimaryKeyInfo(table)[0];
+    return 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.
+ */
+export function categorizeSpecialFields(table, typeRegistry) {
+    const allFields = 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.
+ */
+export 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.
+ */
+export 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/esm/core/codegen/hooks-docs-generator.js

@@ -1,6 +1,6 @@
 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';
+import { getTableNames, getScalarFields, getPrimaryKeyInfo, getListQueryHookName, getSingleQueryHookName, getCreateMutationHookName, getUpdateMutationHookName, getDeleteMutationHookName, hasValidPrimaryKey, ucFirst, lcFirst, } from './utils';
 function getCustomHookName(op) {
     if (op.kind === 'query') {
         return `use${ucFirst(op.name)}Query`;
@@ -117,17 +117,19 @@ export function generateHooksReadme(tables, customOperations) {
 }
 export 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';");
@@ -138,123 +140,22 @@ export 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 } = getTableNames(table);
-        const pk = getPrimaryKeyInfo(table)[0];
-        const scalarFields = getScalarFields(table);
-        lines.push(`### HOOK: ${getListQueryHookName(table)}`);
-        lines.push('');
-        lines.push(`${table.description || `List all ${pluralName}`}.`);
-        lines.push('');
-        lines.push('```');
-        lines.push(`TYPE: query`);
-        lines.push(`USAGE: ${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}: ${fieldTypeToTs(f.type)}`);
-        }
-        lines.push('}>>');
-        lines.push('```');
-        lines.push('');
-        if (hasValidPrimaryKey(table)) {
-            lines.push(`### HOOK: ${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: ${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}: ${fieldTypeToTs(f.type)}`);
-            }
-            lines.push('}>');
-            lines.push('```');
-            lines.push('');
-        }
-        lines.push(`### HOOK: ${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 } = ${getCreateMutationHookName(table)}({ selection: { fields: { ... } } })`);
-        lines.push('');
-        lines.push('OUTPUT: UseMutationResult');
-        lines.push('```');
-        lines.push('');
-        if (hasValidPrimaryKey(table)) {
-            lines.push(`### HOOK: ${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 } = ${getUpdateMutationHookName(table)}({ selection: { fields: { ... } } })`);
-            lines.push('');
-            lines.push('OUTPUT: UseMutationResult');
-            lines.push('```');
-            lines.push('');
-            lines.push(`### HOOK: ${getDeleteMutationHookName(table)}`);
-            lines.push('');
-            lines.push(`${table.description || `Delete a ${singularName}`}.`);
-            lines.push('');
-            lines.push('```');
-            lines.push('TYPE: mutation');
-            lines.push(`USAGE: const { mutate } = ${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}: ${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/esm/core/codegen/orm/docs-generator.js

@@ -1,6 +1,6 @@
 import { toKebabCase } from 'komoji';
-import { buildSkillFile, buildSkillReference, formatArgType, getEditableFields, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, } from '../docs-utils';
-import { getScalarFields, getTableNames, getPrimaryKeyInfo, lcFirst, fieldTypeToTs, } from '../utils';
+import { buildSkillFile, buildSkillReference, formatArgType, getEditableFields, categorizeSpecialFields, buildSpecialFieldsMarkdown, getReadmeHeader, getReadmeFooter, gqlTypeToJsonSchemaType, } from '../docs-utils';
+import { getScalarFields, getTableNames, getPrimaryKeyInfo, lcFirst, } from '../utils';
 export function generateOrmReadme(tables, customOperations) {
     const lines = [];
     lines.push(...getReadmeHeader('ORM Client'));
@@ -64,6 +64,8 @@ export function generateOrmReadme(tables, customOperations) {
             lines.push(`const deleted = await db.${singularName}.delete({ where: { ${pk.name}: '<value>' } }).execute();`);
             lines.push('```');
             lines.push('');
+            const ormSpecialGroups = categorizeSpecialFields(table);
+            lines.push(...buildSpecialFieldsMarkdown(ormSpecialGroups));
         }
     }
     if (customOperations.length > 0) {
@@ -107,17 +109,19 @@ export function generateOrmReadme(tables, customOperations) {
 }
 export 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';");
@@ -128,88 +132,22 @@ export 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 } = getTableNames(table);
-        const pk = getPrimaryKeyInfo(table)[0];
-        const scalarFields = getScalarFields(table);
-        const editableFields = 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}: ${fieldTypeToTs(f.type)}${isPk ? ' (primary key)' : ''}`);
-        }
-        lines.push('');
-        lines.push('EDITABLE FIELDS:');
-        for (const f of editableFields) {
-            lines.push(`  ${f.name}: ${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}: ${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',
@@ -353,11 +291,17 @@ export function generateOrmSkills(tables, customOperations, targetName) {
         const modelName = lcFirst(singularName);
         const refName = toKebabCase(singularName);
         referenceNames.push(refName);
+        const ormSkillSpecialGroups = 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: 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-codegen",
-  "version": "4.14.3",
+  "version": "4.15.0",
   "description": "GraphQL SDK generator for Constructive databases with React Query hooks",
   "keywords": [
     "graphql",
@@ -56,26 +56,26 @@
     "@0no-co/graphql.web": "^1.1.2",
     "@babel/generator": "^7.29.1",
     "@babel/types": "^7.29.0",
-    "@constructive-io/graphql-query": "^3.6.0",
-    "@constructive-io/graphql-types": "^3.3.2",
-    "@inquirerer/utils": "^3.3.1",
-    "@pgpmjs/core": "^6.6.2",
+    "@constructive-io/graphql-query": "^3.6.2",
+    "@constructive-io/graphql-types": "^3.3.4",
+    "@inquirerer/utils": "^3.3.4",
+    "@pgpmjs/core": "^6.6.4",
     "ajv": "^8.18.0",
     "deepmerge": "^4.3.1",
     "find-and-require-package-json": "^0.9.1",
-    "gql-ast": "^3.3.2",
-    "graphile-schema": "^1.6.0",
-    "graphql": "^16.13.0",
+    "gql-ast": "^3.3.3",
+    "graphile-schema": "^1.6.2",
+    "graphql": "16.13.0",
     "inflekt": "^0.3.3",
-    "inquirerer": "^4.5.2",
+    "inquirerer": "^4.7.0",
     "jiti": "^2.6.1",
     "komoji": "^0.8.1",
-    "oxfmt": "^0.36.0",
-    "pg-cache": "^3.3.2",
-    "pg-env": "^1.7.2",
-    "pgsql-client": "^3.5.2",
-    "pgsql-seed": "^2.5.2",
-    "undici": "^7.22.0"
+    "oxfmt": "^0.40.0",
+    "pg-cache": "^3.3.4",
+    "pg-env": "^1.7.3",
+    "pgsql-client": "^3.5.4",
+    "pgsql-seed": "^2.5.4",
+    "undici": "^7.24.3"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.0.0",
@@ -95,11 +95,11 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^22.19.11",
     "@types/react": "^19.2.14",
-    "jest": "^30.2.0",
+    "jest": "^30.3.0",
     "react": "^19.2.4",
     "ts-jest": "^29.2.5",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "edb69fc817642476636394a89b47293b6a0c7c43"
+  "gitHead": "8afe6b19da82facbe5f3365762ba52888af5b3c9"
 }