@constructive-io/graphql-codegen 4.7.3 → 4.8.1

package/core/codegen/cli/command-map-generator.js

@@ -48,6 +48,25 @@ function createNamedImportDeclaration(moduleSpecifier, namedImports, typeOnly =
     decl.importKind = typeOnly ? 'type' : 'value';
     return decl;
 }
+/**
+ * Build the command handler function type:
+ * (argv: Partial<Record<string, unknown>>, prompter: Inquirerer, options: CLIOptions) => Promise<void>
+ * This matches the actual exported handler signatures from table/custom command files.
+ */
+function buildCommandHandlerType() {
+    const argvParam = t.identifier('argv');
+    argvParam.typeAnnotation = t.tsTypeAnnotation(t.tsTypeReference(t.identifier('Partial'), t.tsTypeParameterInstantiation([
+        t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([
+            t.tsStringKeyword(),
+            t.tsUnknownKeyword(),
+        ])),
+    ])));
+    const prompterParam = t.identifier('prompter');
+    prompterParam.typeAnnotation = t.tsTypeAnnotation(t.tsTypeReference(t.identifier('Inquirerer')));
+    const optionsParam = t.identifier('options');
+    optionsParam.typeAnnotation = t.tsTypeAnnotation(t.tsTypeReference(t.identifier('CLIOptions')));
+    return t.tsFunctionType(null, [argvParam, prompterParam, optionsParam], t.tsTypeAnnotation(t.tsTypeReference(t.identifier('Promise'), t.tsTypeParameterInstantiation([t.tsVoidKeyword()]))));
+}
 function generateCommandMap(tables, customOperations, toolName) {
     const statements = [];
     statements.push(createNamedImportDeclaration('inquirerer', [
@@ -74,18 +93,17 @@ function generateCommandMap(tables, customOperations, toolName) {
         statements.push(createImportDeclaration(`./commands/${kebab}`, importName));
     }
     const mapProperties = commandEntries.map((entry) => t.objectProperty(t.stringLiteral(entry.kebab), t.identifier(entry.importName)));
-    const createCommandMapFunc = t.variableDeclaration('const', [
-        t.variableDeclarator(t.identifier('createCommandMap'), t.arrowFunctionExpression([], t.objectExpression(mapProperties))),
-    ]);
-    const createCommandMapAnnotation = t.tsTypeAnnotation(t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([
-        t.tsStringKeyword(),
-        t.tsFunctionType(null, [], t.tsTypeAnnotation(t.tsAnyKeyword())),
-    ])));
+    // Build command handler type matching actual handler signature:
+    // (argv: Partial<Record<string, unknown>>, prompter: Inquirerer, options: CLIOptions) => Promise<void>
+    const commandHandlerType = buildCommandHandlerType();
     const createCommandMapId = t.identifier('createCommandMap');
     createCommandMapId.typeAnnotation = t.tsTypeAnnotation(t.tsParenthesizedType(t.tsFunctionType(null, [], t.tsTypeAnnotation(t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([
         t.tsStringKeyword(),
-        t.tsFunctionType(null, [], t.tsTypeAnnotation(t.tsUnknownKeyword())),
+        commandHandlerType,
     ]))))));
+    const createCommandMapFunc = t.variableDeclaration('const', [
+        t.variableDeclarator(createCommandMapId, t.arrowFunctionExpression([], t.objectExpression(mapProperties))),
+    ]);
     statements.push(createCommandMapFunc);
     const usageLines = [
         '',
@@ -152,7 +170,7 @@ function generateCommandMap(tables, customOperations, toolName) {
                     ]),
                 ]))),
             ]),
-            t.expressionStatement(t.assignmentExpression('=', t.identifier('command'), t.memberExpression(t.identifier('answer'), t.identifier('command')))),
+            t.expressionStatement(t.assignmentExpression('=', t.identifier('command'), t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('command')), t.tsStringKeyword()))),
         ])),
         t.variableDeclaration('const', [
             t.variableDeclarator(t.identifier('commandFn'), t.memberExpression(t.identifier('commandMap'), t.identifier('command'), true)),
@@ -223,8 +241,15 @@ function generateMultiTargetCommandMap(input) {
         }
     }
     const mapProperties = commandEntries.map((entry) => t.objectProperty(t.stringLiteral(entry.kebab), t.identifier(entry.importName)));
+    // Build command handler type matching actual handler signature
+    const multiTargetCommandHandlerType = buildCommandHandlerType();
+    const multiTargetCreateCommandMapId = t.identifier('createCommandMap');
+    multiTargetCreateCommandMapId.typeAnnotation = t.tsTypeAnnotation(t.tsParenthesizedType(t.tsFunctionType(null, [], t.tsTypeAnnotation(t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([
+        t.tsStringKeyword(),
+        multiTargetCommandHandlerType,
+    ]))))));
     const createCommandMapFunc = t.variableDeclaration('const', [
-        t.variableDeclarator(t.identifier('createCommandMap'), t.arrowFunctionExpression([], t.objectExpression(mapProperties))),
+        t.variableDeclarator(multiTargetCreateCommandMapId, t.arrowFunctionExpression([], t.objectExpression(mapProperties))),
     ]);
     statements.push(createCommandMapFunc);
     const usageLines = [
@@ -298,7 +323,7 @@ function generateMultiTargetCommandMap(input) {
                     ]),
                 ]))),
             ]),
-            t.expressionStatement(t.assignmentExpression('=', t.identifier('command'), t.memberExpression(t.identifier('answer'), t.identifier('command')))),
+            t.expressionStatement(t.assignmentExpression('=', t.identifier('command'), t.tsAsExpression(t.memberExpression(t.identifier('answer'), t.identifier('command')), t.tsStringKeyword()))),
         ])),
         t.variableDeclaration('const', [
             t.variableDeclarator(t.identifier('commandFn'), t.memberExpression(t.identifier('commandMap'), t.identifier('command'), true)),

package/core/codegen/cli/custom-command-generator.js

@@ -101,22 +101,33 @@ function buildDefaultSelectString(returnType, isMutation) {
     }
     return '';
 }
-function buildOrmCustomCall(opKind, opName, argsExpr, selectExpr, hasArgs = true) {
+function buildOrmCustomCall(opKind, opName, argsExpr, selectExpr, hasArgs = true, selectTypeName) {
     const callArgs = [];
+    // Helper: wrap { select } and cast to `{ select: XxxSelect }` via `unknown`.
+    // The ORM method's second parameter is `{ select: S } & StrictSelect<S, XxxSelect>`.
+    // We import the concrete Select type (e.g. CheckPasswordPayloadSelect) and cast
+    // `{ select: selectFields } as unknown as { select: XxxSelect }` so TS infers
+    // `S = XxxSelect` and StrictSelect is satisfied.
+    const castSelectWrapper = (sel) => {
+        const selectObj = t.objectExpression([
+            t.objectProperty(t.identifier('select'), sel),
+        ]);
+        if (!selectTypeName)
+            return selectObj;
+        return t.tsAsExpression(t.tsAsExpression(selectObj, t.tsUnknownKeyword()), t.tsTypeLiteral([
+            t.tsPropertySignature(t.identifier('select'), t.tsTypeAnnotation(t.tsTypeReference(t.identifier(selectTypeName)))),
+        ]));
+    };
     if (hasArgs) {
-        // Operation has arguments: pass args as first param, select as second
+        // Operation has arguments: pass args as first param, select as second.
         callArgs.push(argsExpr);
         if (selectExpr) {
-            callArgs.push(t.objectExpression([
-                t.objectProperty(t.identifier('select'), selectExpr),
-            ]));
+            callArgs.push(castSelectWrapper(selectExpr));
         }
     }
     else if (selectExpr) {
-        // No arguments: pass { select } as the only param (ORM signature)
-        callArgs.push(t.objectExpression([
-            t.objectProperty(t.identifier('select'), selectExpr),
-        ]));
+        // No arguments: pass { select } as the only param (ORM signature).
+        callArgs.push(castSelectWrapper(selectExpr));
     }
     return t.callExpression(t.memberExpression(t.callExpression(t.memberExpression(t.memberExpression(t.identifier('client'), t.identifier(opKind)), t.identifier(opName)), callArgs), t.identifier('execute')), []);
 }
@@ -152,6 +163,18 @@ function generateCustomCommand(op, options) {
     if (utilsImports.length > 0) {
         statements.push(createImportDeclaration(utilsPath, utilsImports));
     }
+    // Import the Variables type for this operation from the ORM query/mutation module.
+    // Custom operations define their own Variables types (e.g. CheckPasswordVariables)
+    // in the ORM layer. We import and cast CLI answers to this type for proper typing.
+    if (op.args.length > 0) {
+        const variablesTypeName = `${(0, utils_1.ucFirst)(op.name)}Variables`;
+        // Commands are at cli/commands/xxx.ts (no target) or cli/commands/{target}/xxx.ts (with target).
+        // ORM query/mutation is at orm/{opKind}/ — two or three levels up from commands.
+        const ormOpPath = options?.targetName
+            ? `../../../orm/${opKind}`
+            : `../../orm/${opKind}`;
+        statements.push(createImportDeclaration(ormOpPath, [variablesTypeName], true));
+    }
     const questionsArray = op.args.length > 0
         ? (0, arg_mapper_1.buildQuestionsArray)(op.args)
         : t.arrayExpression([]);
@@ -189,10 +212,16 @@ function generateCustomCommand(op, options) {
             ])),
         ]));
     }
+    // Cast args to the specific Variables type for this operation.
+    // The ORM expects typed variables (e.g. CheckPasswordVariables), and CLI
+    // prompt answers are Record<string, unknown>. We cast through `unknown`
+    // first because Record<string, unknown> doesn't directly overlap with
+    // Variables types that have specific property types (like `input: SomeInput`).
+    const variablesTypeName = `${(0, utils_1.ucFirst)(op.name)}Variables`;
     const argsExpr = op.args.length > 0
-        ? (hasInputObjectArg
+        ? t.tsAsExpression(t.tsAsExpression(hasInputObjectArg
             ? t.identifier('parsedAnswers')
-            : t.identifier('answers'))
+            : t.identifier('answers'), t.tsUnknownKeyword()), t.tsTypeReference(t.identifier(variablesTypeName)))
         : t.objectExpression([]);
     // For OBJECT return types, generate runtime select from --select flag
     // For scalar return types, no select is needed
@@ -202,14 +231,31 @@ function generateCustomCommand(op, options) {
         // Generate: const selectFields = buildSelectFromPaths(argv.select ?? 'defaultFields')
         bodyStatements.push(t.variableDeclaration('const', [
             t.variableDeclarator(t.identifier('selectFields'), t.callExpression(t.identifier('buildSelectFromPaths'), [
-                t.logicalExpression('??', t.memberExpression(t.identifier('argv'), t.identifier('select')), t.stringLiteral(defaultSelect)),
+                t.logicalExpression('??', t.tsAsExpression(t.memberExpression(t.identifier('argv'), t.identifier('select')), t.tsStringKeyword()), t.stringLiteral(defaultSelect)),
             ])),
         ]));
         selectExpr = t.identifier('selectFields');
     }
+    // Derive the Select type name from the operation's return type.
+    // e.g. CheckPasswordPayload → CheckPasswordPayloadSelect
+    // This is used to cast { select } to the proper type for StrictSelect.
+    let selectTypeName;
+    if (isObjectReturn) {
+        const baseReturnType = unwrapType(op.returnType);
+        if (baseReturnType.name) {
+            selectTypeName = `${baseReturnType.name}Select`;
+        }
+    }
+    // Import the Select type from orm/input-types if we have one
+    if (selectTypeName) {
+        const inputTypesPath = options?.targetName
+            ? `../../../orm/input-types`
+            : `../../orm/input-types`;
+        statements.push(createImportDeclaration(inputTypesPath, [selectTypeName], true));
+    }
     const hasArgs = op.args.length > 0;
     bodyStatements.push(t.variableDeclaration('const', [
-        t.variableDeclarator(t.identifier('result'), t.awaitExpression(buildOrmCustomCall(opKind, op.name, argsExpr, selectExpr, hasArgs))),
+        t.variableDeclarator(t.identifier('result'), t.awaitExpression(buildOrmCustomCall(opKind, op.name, argsExpr, selectExpr, hasArgs, selectTypeName))),
     ]));
     if (options?.saveToken) {
         bodyStatements.push(t.ifStatement(t.logicalExpression('&&', t.memberExpression(t.identifier('argv'), t.identifier('saveToken')), t.identifier('result')), t.blockStatement([

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

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

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

@@ -525,12 +525,16 @@ function getCliMcpTools(tables, customOperations, toolName) {
     }
     return tools;
 }
-function generateSkills(tables, customOperations, toolName) {
+function generateSkills(tables, customOperations, toolName, targetName) {
     const files = [];
+    const skillName = `cli-${targetName}`;
+    const referenceNames = [];
+    // Context reference
+    referenceNames.push('context');
     files.push({
-        fileName: 'skills/context.md',
-        content: (0, docs_utils_1.buildSkillFile)({
-            name: `${toolName}-context`,
+        fileName: `${skillName}/references/context.md`,
+        content: (0, docs_utils_1.buildSkillReference)({
+            title: 'Context Management',
             description: `Manage API endpoint contexts for ${toolName}`,
             usage: [
                 `${toolName} context create <name> --endpoint <url>`,
@@ -554,10 +558,12 @@ function generateSkills(tables, customOperations, toolName) {
             ],
         }),
     });
+    // Auth reference
+    referenceNames.push('auth');
     files.push({
-        fileName: 'skills/auth.md',
-        content: (0, docs_utils_1.buildSkillFile)({
-            name: `${toolName}-auth`,
+        fileName: `${skillName}/references/auth.md`,
+        content: (0, docs_utils_1.buildSkillReference)({
+            title: 'Authentication',
             description: `Manage authentication tokens for ${toolName}`,
             usage: [
                 `${toolName} auth set-token <token>`,
@@ -576,15 +582,17 @@ function generateSkills(tables, customOperations, toolName) {
             ],
         }),
     });
+    // Table references
     for (const table of tables) {
         const { singularName } = (0, utils_1.getTableNames)(table);
         const kebab = (0, komoji_1.toKebabCase)(singularName);
         const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
         const editableFields = (0, docs_utils_1.getEditableFields)(table);
+        referenceNames.push(kebab);
         files.push({
-            fileName: `skills/${kebab}.md`,
-            content: (0, docs_utils_1.buildSkillFile)({
-                name: `${toolName}-${kebab}`,
+            fileName: `${skillName}/references/${kebab}.md`,
+            content: (0, docs_utils_1.buildSkillReference)({
+                title: singularName,
                 description: `CRUD operations for ${table.name} records via ${toolName} CLI`,
                 usage: [
                     `${toolName} ${kebab} list`,
@@ -608,29 +616,21 @@ function generateSkills(tables, customOperations, toolName) {
                         description: `Get a ${singularName} by ${pk.name}`,
                         code: [`${toolName} ${kebab} get --${pk.name} <value>`],
                     },
-                    {
-                        description: `Update a ${singularName}`,
-                        code: [
-                            `${toolName} ${kebab} update --${pk.name} <value> --${editableFields[0]?.name || 'field'} "new-value"`,
-                        ],
-                    },
-                    {
-                        description: `Delete a ${singularName}`,
-                        code: [`${toolName} ${kebab} delete --${pk.name} <value>`],
-                    },
                 ],
             }),
         });
     }
+    // Custom operation references
     for (const op of customOperations) {
         const kebab = (0, komoji_1.toKebabCase)(op.name);
         const usage = op.args.length > 0
             ? `${toolName} ${kebab} ${op.args.map((a) => `--${a.name} <value>`).join(' ')}`
             : `${toolName} ${kebab}`;
+        referenceNames.push(kebab);
         files.push({
-            fileName: `skills/${kebab}.md`,
-            content: (0, docs_utils_1.buildSkillFile)({
-                name: `${toolName}-${kebab}`,
+            fileName: `${skillName}/references/${kebab}.md`,
+            content: (0, docs_utils_1.buildSkillReference)({
+                title: op.name,
                 description: op.description || `Execute the ${op.name} ${op.kind}`,
                 usage: [usage],
                 examples: [
@@ -642,6 +642,39 @@ function generateSkills(tables, customOperations, toolName) {
             }),
         });
     }
+    // Overview SKILL.md
+    const tableKebabs = tables.slice(0, 5).map((t) => (0, komoji_1.toKebabCase)((0, utils_1.getTableNames)(t).singularName));
+    files.push({
+        fileName: `${skillName}/SKILL.md`,
+        content: (0, docs_utils_1.buildSkillFile)({
+            name: skillName,
+            description: `CLI tool (${toolName}) for the ${targetName} API — provides CRUD commands for ${tables.length} tables and ${customOperations.length} custom operations`,
+            usage: [
+                `# Context management`,
+                `${toolName} context create <name> --endpoint <url>`,
+                `${toolName} context use <name>`,
+                '',
+                `# Authentication`,
+                `${toolName} auth set-token <token>`,
+                '',
+                `# CRUD for any table (e.g. ${tableKebabs[0] || 'model'})`,
+                `${toolName} ${tableKebabs[0] || 'model'} list`,
+                `${toolName} ${tableKebabs[0] || 'model'} get --id <value>`,
+                `${toolName} ${tableKebabs[0] || 'model'} create --<field> <value>`,
+            ],
+            examples: [
+                {
+                    description: 'Set up and query',
+                    code: [
+                        `${toolName} context create local --endpoint http://localhost:5000/graphql`,
+                        `${toolName} context use local`,
+                        `${toolName} auth set-token <token>`,
+                        `${toolName} ${tableKebabs[0] || 'model'} list`,
+                    ],
+                },
+            ],
+        }, referenceNames),
+    });
     return files;
 }
 function generateMultiTargetReadme(input) {
@@ -1268,22 +1301,26 @@ function getMultiTargetCliMcpTools(input) {
 function generateMultiTargetSkills(input) {
     const { toolName, builtinNames, targets } = input;
     const files = [];
-    const contextUsage = [
-        `${toolName} ${builtinNames.context} create <name>`,
-        `${toolName} ${builtinNames.context} list`,
-        `${toolName} ${builtinNames.context} use <name>`,
-        `${toolName} ${builtinNames.context} current`,
-        `${toolName} ${builtinNames.context} delete <name>`,
-    ];
+    // Generate one skill per target, plus a shared cli-common skill for context/auth
+    const commonSkillName = 'cli-common';
+    const commonReferenceNames = [];
     const contextCreateFlags = targets
         .map((t) => `--${t.name}-endpoint <url>`)
         .join(' ');
+    // Context reference
+    commonReferenceNames.push('context');
     files.push({
-        fileName: `skills/${builtinNames.context}.md`,
-        content: (0, docs_utils_1.buildSkillFile)({
-            name: `${toolName}-${builtinNames.context}`,
+        fileName: `${commonSkillName}/references/context.md`,
+        content: (0, docs_utils_1.buildSkillReference)({
+            title: 'Context Management',
             description: `Manage API endpoint contexts for ${toolName} (multi-target: ${targets.map((t) => t.name).join(', ')})`,
-            usage: contextUsage,
+            usage: [
+                `${toolName} ${builtinNames.context} create <name>`,
+                `${toolName} ${builtinNames.context} list`,
+                `${toolName} ${builtinNames.context} use <name>`,
+                `${toolName} ${builtinNames.context} current`,
+                `${toolName} ${builtinNames.context} delete <name>`,
+            ],
             examples: [
                 {
                     description: 'Create a context for local development (accept all defaults)',
@@ -1299,20 +1336,15 @@ function generateMultiTargetSkills(input) {
                         `${toolName} ${builtinNames.context} use production`,
                     ],
                 },
-                {
-                    description: 'List and switch contexts',
-                    code: [
-                        `${toolName} ${builtinNames.context} list`,
-                        `${toolName} ${builtinNames.context} use staging`,
-                    ],
-                },
             ],
         }),
     });
+    // Auth reference
+    commonReferenceNames.push('auth');
     files.push({
-        fileName: `skills/${builtinNames.auth}.md`,
-        content: (0, docs_utils_1.buildSkillFile)({
-            name: `${toolName}-${builtinNames.auth}`,
+        fileName: `${commonSkillName}/references/auth.md`,
+        content: (0, docs_utils_1.buildSkillReference)({
+            title: 'Authentication',
             description: `Manage authentication tokens for ${toolName} (shared across all targets)`,
             usage: [
                 `${toolName} ${builtinNames.auth} set-token <token>`,
@@ -1331,17 +1363,48 @@ function generateMultiTargetSkills(input) {
             ],
         }),
     });
+    // Common SKILL.md
+    files.push({
+        fileName: `${commonSkillName}/SKILL.md`,
+        content: (0, docs_utils_1.buildSkillFile)({
+            name: commonSkillName,
+            description: `Shared CLI utilities for ${toolName} — context management and authentication across targets: ${targets.map((t) => t.name).join(', ')}`,
+            usage: [
+                `# Context management`,
+                `${toolName} ${builtinNames.context} create <name>`,
+                `${toolName} ${builtinNames.context} use <name>`,
+                '',
+                `# Authentication`,
+                `${toolName} ${builtinNames.auth} set-token <token>`,
+                `${toolName} ${builtinNames.auth} status`,
+            ],
+            examples: [
+                {
+                    description: 'Set up and authenticate',
+                    code: [
+                        `${toolName} ${builtinNames.context} create local`,
+                        `${toolName} ${builtinNames.context} use local`,
+                        `${toolName} ${builtinNames.auth} set-token <token>`,
+                    ],
+                },
+            ],
+        }, commonReferenceNames),
+    });
+    // Generate one skill per target with table/op references
     for (const tgt of targets) {
+        const tgtSkillName = `cli-${tgt.name}`;
+        const tgtReferenceNames = [];
         for (const table of tgt.tables) {
             const { singularName } = (0, utils_1.getTableNames)(table);
             const kebab = (0, komoji_1.toKebabCase)(singularName);
             const pk = (0, utils_1.getPrimaryKeyInfo)(table)[0];
             const editableFields = (0, docs_utils_1.getEditableFields)(table);
             const cmd = `${tgt.name}:${kebab}`;
+            tgtReferenceNames.push(kebab);
             files.push({
-                fileName: `skills/${tgt.name}-${kebab}.md`,
-                content: (0, docs_utils_1.buildSkillFile)({
-                    name: `${toolName}-${cmd}`,
+                fileName: `${tgtSkillName}/references/${kebab}.md`,
+                content: (0, docs_utils_1.buildSkillReference)({
+                    title: singularName,
                     description: `CRUD operations for ${table.name} records via ${toolName} CLI (${tgt.name} target)`,
                     usage: [
                         `${toolName} ${cmd} list`,
@@ -1361,10 +1424,6 @@ function generateMultiTargetSkills(input) {
                                 `${toolName} ${cmd} create ${editableFields.map((f) => `--${f.name} "value"`).join(' ')}`,
                             ],
                         },
-                        {
-                            description: `Get a ${singularName} by ${pk.name}`,
-                            code: [`${toolName} ${cmd} get --${pk.name} <value>`],
-                        },
                     ],
                 }),
             });
@@ -1379,10 +1438,11 @@ function generateMultiTargetSkills(input) {
             if (tgt.isAuthTarget && op.kind === 'mutation') {
                 usageLines.push(`${baseUsage} --save-token`);
             }
+            tgtReferenceNames.push(kebab);
             files.push({
-                fileName: `skills/${tgt.name}-${kebab}.md`,
-                content: (0, docs_utils_1.buildSkillFile)({
-                    name: `${toolName}-${cmd}`,
+                fileName: `${tgtSkillName}/references/${kebab}.md`,
+                content: (0, docs_utils_1.buildSkillReference)({
+                    title: op.name,
                     description: `${op.description || `Execute the ${op.name} ${op.kind}`} (${tgt.name} target)`,
                     usage: usageLines,
                     examples: [
@@ -1394,6 +1454,29 @@ function generateMultiTargetSkills(input) {
                 }),
             });
         }
+        // Target SKILL.md
+        const firstKebab = tgt.tables.length > 0
+            ? (0, komoji_1.toKebabCase)((0, utils_1.getTableNames)(tgt.tables[0]).singularName)
+            : 'model';
+        files.push({
+            fileName: `${tgtSkillName}/SKILL.md`,
+            content: (0, docs_utils_1.buildSkillFile)({
+                name: tgtSkillName,
+                description: `CLI commands for the ${tgt.name} API target — ${tgt.tables.length} tables and ${tgt.customOperations.length} custom operations via ${toolName}`,
+                usage: [
+                    `# CRUD for ${tgt.name} tables (e.g. ${firstKebab})`,
+                    `${toolName} ${tgt.name}:${firstKebab} list`,
+                    `${toolName} ${tgt.name}:${firstKebab} get --id <value>`,
+                    `${toolName} ${tgt.name}:${firstKebab} create --<field> <value>`,
+                ],
+                examples: [
+                    {
+                        description: `Query ${tgt.name} records`,
+                        code: [`${toolName} ${tgt.name}:${firstKebab} list`],
+                    },
+                ],
+            }, tgtReferenceNames),
+        });
     }
     return files;
 }

package/core/codegen/cli/executor-generator.js

@@ -86,9 +86,16 @@ function generateExecutorFile(toolName, options) {
                 ])),
             ])),
         ])),
-        t.variableDeclaration('const', [
-            t.variableDeclarator(t.identifier('headers'), t.objectExpression([])),
-        ]),
+        (() => {
+            const headersId = t.identifier('headers');
+            headersId.typeAnnotation = t.tsTypeAnnotation(t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([
+                t.tsStringKeyword(),
+                t.tsStringKeyword(),
+            ])));
+            return t.variableDeclaration('const', [
+                t.variableDeclarator(headersId, t.objectExpression([])),
+            ]);
+        })(),
         t.ifStatement(t.callExpression(t.memberExpression(t.identifier('store'), t.identifier('hasValidCredentials')), [t.memberExpression(t.identifier('ctx'), t.identifier('name'))]), t.blockStatement([
             t.variableDeclaration('const', [
                 t.variableDeclarator(t.identifier('creds'), t.callExpression(t.memberExpression(t.identifier('store'), t.identifier('getCredentials')), [t.memberExpression(t.identifier('ctx'), t.identifier('name'))])),
@@ -193,9 +200,16 @@ function generateMultiTargetExecutorFile(toolName, targets, options) {
                 ], [t.identifier('targetName')]),
             ])),
         ])),
-        t.variableDeclaration('const', [
-            t.variableDeclarator(t.identifier('headers'), t.objectExpression([])),
-        ]),
+        (() => {
+            const headersId = t.identifier('headers');
+            headersId.typeAnnotation = t.tsTypeAnnotation(t.tsTypeReference(t.identifier('Record'), t.tsTypeParameterInstantiation([
+                t.tsStringKeyword(),
+                t.tsStringKeyword(),
+            ])));
+            return t.variableDeclaration('const', [
+                t.variableDeclarator(headersId, t.objectExpression([])),
+            ]);
+        })(),
         t.variableDeclaration('let', [
             t.variableDeclarator(t.identifier('endpoint'), t.stringLiteral('')),
         ]),