@chemx/create-chemx 26.9.25-943 → 26.9.28-276

package/cli/audit/ast-visitors.js

@@ -23,12 +23,18 @@ export const createAstVisitors = ({ relativePath, violations, hookRegistry, conf
       const isCustomHook = isCustomHookFunction(astPath);
 
       // Pillar 3: Hook Saturation
+      const CONTROLLER_WRAPPER_EXCLUSIONS = new Set([
+        'useSharedStatusController',
+        'useSharedController',
+        'useController'
+      ]);
       let hookCount = 0;
       astPath.traverse({
         CallExpression(callPath) {
           const callee = callPath.node.callee;
           if (t.isIdentifier(callee) && /^use[A-Z0-9]/.test(callee.name)) {
-            if (callPath.getFunctionParent() === astPath) {
+            const isExcluded = CONTROLLER_WRAPPER_EXCLUSIONS.has(callee.name);
+            if (!isExcluded && callPath.getFunctionParent() === astPath) {
               hookCount += 1;
             }
           }

package/cli/audit/extended-text-patterns.js

@@ -32,7 +32,10 @@ const JAVASCRIPT_URL_TEMPLATE_PATTERN = /\b(?:href|src|action|formaction)\s*=\s*
 /**
  * Pillar 10: Check for co-located test files for molecule capsules.
  */
-export const checkMoleculeCoLocatedTest = (filePath, relativePath, violations) => {
+export const checkMoleculeCoLocatedTest = (filePath, relativePath, violations, config = {}) => {
+  const enforceColocated = config.enforceColocatedTests ?? (config.profile === 'atomic-strict');
+  if (!enforceColocated) return;
+
   const baseName = path.basename(filePath);
   const ext = path.extname(filePath);
 
@@ -194,8 +197,8 @@ export const checkControllerViewContract = (filePath, relativePath, content, vio
   }
 };
 
-export const checkExtendedTextPatterns = (content, lines, relativePath, filePath, violations) => {
-  checkMoleculeCoLocatedTest(filePath, relativePath, violations);
+export const checkExtendedTextPatterns = (content, lines, relativePath, filePath, violations, config = {}) => {
+  checkMoleculeCoLocatedTest(filePath, relativePath, violations, config);
   checkControllerViewContract(filePath, relativePath, content, violations);
 
   const isTestFile = /\.(test|spec)\.[jt]sx?$/.test(filePath)

package/cli/audit/prompts.js

@@ -66,7 +66,7 @@ export const formatGroupedPromptViolations = (violations = [], options = {}) =>
 export const buildAgentCommandsSection = () => [
   '### AI AGENT DISCOVERY & REFACTORING COMMANDS:',
   '- Claim Work: Run `chemx team task list --status=queued` and claim via `chemx team task claim <id> --as=@coder`.',
-  '- Inspect Target: Run `chemx read <target_path> --outline` to inspect AST signatures without token bloat.',
+  '- Inspect Target: Run `chemx read <target_path> --outline` for AST signatures or `--outline --enrich` for signatures + logic flow without token bloat.',
   '- Verify & Auto-Resolve: Run `chemx verify`. Clean files auto-reconcile tasks to done in SQLite.',
   '- MCP Invocations: If invoking via MCP, pass command string directly via `chemx({ command: "..." })`.'
 ].join('\n');

package/cli/audit/rules-helpers.js

@@ -17,7 +17,13 @@ export const countLogicalOperators = (node) => {
 export const extractParseableCode = (content, ext) => {
   if (ext === '.vue') {
     const scriptMatch = content.match(/<script\b[^>]*>([\s\S]*?)<\/script>/i);
-    return scriptMatch ? scriptMatch[1] : '';
+    if (!scriptMatch) return '';
+    const scriptStartIndex = scriptMatch.index || 0;
+    const preScript = content.slice(0, scriptStartIndex);
+    const openTag = scriptMatch[0].match(/<script\b[^>]*>/i)?.[0] || '';
+    const preContent = preScript + openTag;
+    const leadingNewlines = preContent.split('\n').length - 1;
+    return '\n'.repeat(leadingNewlines) + scriptMatch[1];
   }
   return content;
 };

package/cli/audit/rules.js

@@ -107,7 +107,7 @@ export const auditCode = (content, filePath, relativePath, options = {}) => {
   checkSlopTextPatterns(content, lines, relativePath, violations);
 
   // Pillars 8-11: Extended Fast Checks (A11y, Security secrets, Fake tests, Co-located specs)
-  checkExtendedTextPatterns(content, lines, relativePath, filePath, violations);
+  checkExtendedTextPatterns(content, lines, relativePath, filePath, violations, config);
 
   const lang = getLanguageForFile(filePath);
   if (lang?.id === 'csharp') {

package/cli/commands/cmd-router.js

@@ -75,6 +75,16 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       await runSearch(rawArgs.slice(1), true);
       break;
     }
+    case 'trace': {
+      const { runTraceCli } = await import('../search-commands-graph.js');
+      await runTraceCli(rawArgs.slice(1), true);
+      break;
+    }
+    case 'backtrace': {
+      const { runBacktraceCli } = await import('../search-commands-graph.js');
+      await runBacktraceCli(rawArgs.slice(1), true);
+      break;
+    }
     case 'build':
     case 'run':
     case 'wrap': {
@@ -166,9 +176,10 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
     case 'g':
     case 'gen':
     case 'generate':
-    case 'capsule': {
+    case 'capsule':
+    case 'jig': {
       const { runGenerateWizard } = await import('../scaffold.js');
-      await runGenerateWizard(rawArgs.slice(1));
+      await runGenerateWizard(rawArgs);
       break;
     }
     case 'badge':
@@ -201,6 +212,13 @@ export const dispatchCommand = async (firstArg, rawArgs, runAudit, getPackageVer
       await runTypecheckAudit(rawArgs.slice(1), true);
       break;
     }
+    case 'lint':
+    case 'check:lint':
+    case 'eslint': {
+      const { runLintAudit } = await import('../verify-lint.js');
+      await runLintAudit(rawArgs.slice(1), true);
+      break;
+    }
     case 'test':
     case 'tests':
     case 'check:test': {

package/cli/commands-schema.js

@@ -16,7 +16,9 @@ export const COMMANDS_SCHEMA = [
       { flag: '-i, --inspect', desc: 'Inspect props and hooks without full source' },
       { flag: '--tier=<tier>', desc: 'Filter by tier: atom, molecule, organism, hook, view' },
       { flag: '--blast-radius', desc: 'Map direct consumers, transitive dependents & impacted tiers (aliases: --blast, --impact)' },
-      { flag: '--max-depth=<N>', desc: 'Max depth for blast radius traversal (default: 5)' },
+      { flag: '--trace', desc: 'Forward call trace: downstream functions invoked by target' },
+      { flag: '--backtrace', desc: 'Reverse backtrace: upstream callers and causal paths leading to target' },
+      { flag: '--max-depth=<N>', desc: 'Max depth for blast radius / trace traversal (default: 5)' },
       { flag: '--semantic', desc: 'Concept search via vector cosine similarity' },
       { flag: '--hybrid', desc: 'Blended BM25 keyword + Vector RRF ranking' },
       { flag: '--hazards', desc: 'Query architectural rule violations directly (flags: --rule=<id>, --critical)' },
@@ -26,6 +28,8 @@ export const COMMANDS_SCHEMA = [
     examples: [
       'npx chemx search "badge"',
       'pnpm q a-button --blast-radius --json',
+      'pnpm q useUserCardController --trace',
+      'pnpm q handleAction --backtrace',
       'pnpm q "button click handler" --semantic',
       'pnpm q "useAttentionCardController" --hybrid --json',
       'pnpm q "useTheme" --inspect',
@@ -34,13 +38,18 @@ export const COMMANDS_SCHEMA = [
   },
   {
     name: 'read',
-    aliases: ['view'],
+    aliases: ['view', 'r'],
     usage: 'npx chemx read <file> [options]',
-    summary: 'Token-minified file reader with AST outline extraction.',
-    description: 'Extracts structural AST outlines, stripped comments, line ranges, or targeted symbol declarations to minimize LLM context token consumption.',
+    summary: 'Token-minified file reader with AST outline and logic extraction.',
+    description: 'Extracts structural AST outlines, logic skeletons, stripped comments, line ranges, or targeted symbol declarations to minimize LLM context token consumption.',
     flags: [
-      { flag: '--outline', desc: 'Signatures only (80%+ token savings)' },
-      { flag: '--symbol=<name>', desc: 'Target a specific symbol definition' },
+      { flag: '--outline, -o', desc: 'Signatures only (80%+ token savings)' },
+      { flag: '--logic, -l', desc: 'AST logic skeleton: control flow, guards, and mutations without decorative syntax' },
+      { flag: '--template, -t', desc: 'Extract template markup only (Vue/Svelte/JSX)' },
+      { flag: '--enrich', desc: 'Append compacted logic skeleton after outline (free-lunch overlay). Compose with --outline for signatures + logic in one call.' },
+      { flag: '--trace=<name>', desc: 'Append forward call trace card inline (requires --enrich)' },
+      { flag: '--backtrace=<name>', desc: 'Append reverse caller chain card inline (requires --enrich)' },
+      { flag: '--symbol=<name>, -s', desc: 'Target a specific symbol definition' },
       { flag: '--connections', desc: 'Include caller graph and dependent references alongside symbol' },
       { flag: '--strip-comments', desc: 'Remove all code comments' },
       { flag: '--compact', desc: 'Remove blank lines and indentation' },
@@ -50,10 +59,42 @@ export const COMMANDS_SCHEMA = [
     ],
     examples: [
       'npx chemx read src/store.ts --outline',
+      'npx chemx read src/controller.ts --outline --enrich',
+      'npx chemx read src/card.vue --outline --enrich --trace=handleSubmit',
+      'npx chemx read src/controller.ts --logic',
+      'npx chemx read src/card.vue --template',
       'npx chemx read api.ts --symbol=login --connections',
       'npx chemx read src/ui/atoms/a-button/types.d.ts --symbol=ButtonVariant'
     ]
   },
+  {
+    name: 'trace',
+    usage: 'npx chemx trace <symbol> [options]',
+    summary: 'Forward call trace: inspects downstream function invocations.',
+    description: 'Maps the execution tree of functions, services, and external APIs called by the target symbol.',
+    flags: [
+      { flag: '--max-depth=<N>', desc: 'Max depth for call trace traversal (default: 3)' },
+      { flag: '--json', desc: 'Output call tree as minified JSON' }
+    ],
+    examples: [
+      'npx chemx trace useCartController',
+      'npx chemx trace handleCheckout --json'
+    ]
+  },
+  {
+    name: 'backtrace',
+    usage: 'npx chemx backtrace <symbol> [options]',
+    summary: 'Reverse call backtrace: maps upstream caller chains leading to target.',
+    description: 'Traces the causal path of how user interactions, components, and views trigger the target symbol.',
+    flags: [
+      { flag: '--max-depth=<N>', desc: 'Max depth for backtrace traversal (default: 5)' },
+      { flag: '--json', desc: 'Output causal path as minified JSON' }
+    ],
+    examples: [
+      'npx chemx backtrace handleCheckout',
+      'npx chemx backtrace postOrder --json'
+    ]
+  },
   {
     name: 'patch',
     aliases: ['edit'],
@@ -178,6 +219,24 @@ export const COMMANDS_SCHEMA = [
       'pnpm chemx verify --json'
     ]
   },
+  {
+    name: 'lint',
+    aliases: ['check:lint', 'eslint'],
+    usage: 'npx chemx lint [path] [options]',
+    summary: 'Token-conserving linter runner and tree-formatter with automatic fix.',
+    description: 'Executes ESLint with token-efficient diagnostics, target scoping, and automatic --fix support.',
+    flags: [
+      { flag: '--fix', desc: 'Automatically fix fixable lint and tree-formatting errors' },
+      { flag: '--json', desc: 'Output structured diagnostics as JSON for AI agents' },
+      { flag: '--raw', desc: 'Do not capture or format output' }
+    ],
+    examples: [
+      'npx chemx lint',
+      'npx chemx lint --fix',
+      'npx chemx lint apps/youmeos/components/blueprints/desktop/u-desktop.vue --fix',
+      'pnpm chemx lint --json'
+    ]
+  },
   {
     name: 'pillars',
     aliases: ['config:pillars', 'rules'],

package/cli/config/loader.js

@@ -25,6 +25,7 @@ const normalizeRuleKeys = (rules = {}) => {
     'max-prop-count': 'maxPropCount',
     'prefer-design-tokens': 'preferDesignTokens',
     'enforce-file-length': 'enforceFileLength',
+    'enforce-colocated-tests': 'enforceColocatedTests',
     'rule-of-three-abstractions': 'ruleOfThreeAbstractions',
     'ai-slop-detection': 'aiSlopDetection',
     'max-line-count-warning': 'maxLineCountWarning'

package/cli/config/profiles.js

@@ -14,6 +14,7 @@ export const PROFILES = {
     maxPropCount: 7,
     preferDesignTokens: 'warning',
     enforceFileLength: false,
+    enforceColocatedTests: false,
     ruleOfThreeAbstractions: true,
     aiSlopDetection: 'critical',
     maxLineCountWarning: 250
@@ -28,6 +29,7 @@ export const PROFILES = {
     maxPropCount: 5,
     preferDesignTokens: 'error',
     enforceFileLength: true,
+    enforceColocatedTests: true,
     ruleOfThreeAbstractions: false,
     aiSlopDetection: 'critical',
     maxLineCountWarning: 100
@@ -42,6 +44,7 @@ export const PROFILES = {
     maxPropCount: 12,
     preferDesignTokens: 'off',
     enforceFileLength: false,
+    enforceColocatedTests: false,
     ruleOfThreeAbstractions: true,
     aiSlopDetection: 'medium',
     maxLineCountWarning: 500

package/cli/friction-fixes.spec.js

@@ -0,0 +1,96 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { handleChemx } from './mcp/tools.js';
+import { auditCode } from './audit/rules.js';
+
+test('Friction 1: team_task add and team task add persist task rows', async () => {
+  const resCmd = await handleChemx({ command: 'team task add CLI Task Test' });
+  assert.ok(resCmd && resCmd.id, 'Expected task object with id from team task add');
+  assert.strictEqual(resCmd.title, 'CLI Task Test');
+
+  const resCmd2 = await handleChemx({ command: 'team_task add Direct SubCmd Task' });
+  assert.ok(resCmd2 && resCmd2.id, 'Expected task object with id from team_task add');
+  assert.strictEqual(resCmd2.title, 'Direct SubCmd Task');
+
+  const resInfer = await handleChemx({ action: 'team_task', params: { title: 'Inferred Add Task' } });
+  assert.ok(resInfer && resInfer.id, 'Expected task object with id when title is given');
+  assert.strictEqual(resInfer.title, 'Inferred Add Task');
+});
+
+test('Friction 2: patch handles all parameter aliases and command strings', async () => {
+  const testFile = path.resolve('test-patch-spec.txt');
+  fs.writeFileSync(testFile, 'line 1\nOLD_STRING\nline 3\n');
+
+  try {
+    await handleChemx({ action: 'patch', params: { path: 'test-patch-spec.txt', target: 'OLD_STRING', replace: 'NEW_STRING_1' } });
+    assert.strictEqual(fs.readFileSync(testFile, 'utf8'), 'line 1\nNEW_STRING_1\nline 3\n');
+
+    await handleChemx({ action: 'patch', params: { path: 'test-patch-spec.txt', search: 'NEW_STRING_1', replacement: 'NEW_STRING_2' } });
+    assert.strictEqual(fs.readFileSync(testFile, 'utf8'), 'line 1\nNEW_STRING_2\nline 3\n');
+
+    await handleChemx({ action: 'patch', params: { path: 'test-patch-spec.txt', targetContent: 'NEW_STRING_2', replacementContent: 'FINAL_STRING' } });
+    assert.strictEqual(fs.readFileSync(testFile, 'utf8'), 'line 1\nFINAL_STRING\nline 3\n');
+  } finally {
+    if (fs.existsSync(testFile)) fs.unlinkSync(testFile);
+  }
+});
+
+test('Friction 3: Vue file AST line numbers match file line numbers exactly', () => {
+  const vueContent = [
+    '<template>',
+    '  <div>',
+    '    <p>Line 3</p>',
+    '    <p>Line 4</p>',
+    '    <p>Line 5</p>',
+    '    <p>Line 6</p>',
+    '    <p>Line 7</p>',
+    '    <p>Line 8</p>',
+    '    <p>Line 9</p>',
+    '    <p>Line 10</p>',
+    '  </div>',
+    '</template>',
+    '',
+    '<script setup lang="ts">',
+    'const cond = a && b && c;',
+    '</script>'
+  ].join('\n');
+
+  const recorded = [];
+  const fakeReg = { record: (type, sig, loc) => recorded.push({ type, sig, loc }) };
+  auditCode(vueContent, 'SampleVue.vue', 'SampleVue.vue', { patternRegistry: fakeReg });
+
+  const condRec = recorded.find((r) => r.type === 'PREDICATE_LOGIC');
+  assert.ok(condRec, 'Expected PREDICATE_LOGIC recorded');
+  assert.strictEqual(condRec.loc.line, 15, 'Expected condition on line 15');
+});
+
+test('Friction 4: HOOK_SATURATION excludes canonical controller return wrappers', () => {
+  const hookCode = [
+    'export function useMyComposable() {',
+    '  const a = useA();',
+    '  const b = useB();',
+    '  const c = useC();',
+    '  const d = useD();',
+    '  const e = useE();',
+    '  return useSharedStatusController({ a, b, c, d, e });',
+    '}'
+  ].join('\n');
+
+  const hookViolations = auditCode(hookCode, 'useMyComposable.ts', 'src/useMyComposable.ts');
+  const hookSat = hookViolations.filter((v) => v.rule === 'HOOK_SATURATION');
+  assert.strictEqual(hookSat.length, 0, 'useSharedStatusController should not trigger HOOK_SATURATION');
+});
+
+test('Friction 5: TEST_MISSING_COLOCATED is gated by profile', () => {
+  const compCode = '<template><button>Click</button></template>';
+
+  const defaultViolations = auditCode(compCode, 'src/components/molecules/m-button.vue', 'src/components/molecules/m-button.vue', { config: { profile: 'pragmatic' } });
+  const testMissingDefault = defaultViolations.filter((v) => v.rule === 'TEST_MISSING_COLOCATED');
+  assert.strictEqual(testMissingDefault.length, 0, 'Pragmatic profile should not flag TEST_MISSING_COLOCATED');
+
+  const strictViolations = auditCode(compCode, 'src/components/molecules/m-button.vue', 'src/components/molecules/m-button.vue', { config: { profile: 'atomic-strict' } });
+  const testMissingStrict = strictViolations.filter((v) => v.rule === 'TEST_MISSING_COLOCATED');
+  assert.strictEqual(testMissingStrict.length, 1, 'Atomic-strict profile should flag TEST_MISSING_COLOCATED');
+});

package/cli/generator-help.js

@@ -12,18 +12,29 @@ export const printGenerateHelp = () => {
     `  ${CYAN}npx chemx generate${RESET} <name> [options]`,
     `  ${CYAN}npx chemx generate${RESET} <tier> <name> [options]`,
     '',
-    `${BOLD}TIERS${RESET}`,
-    `  ${CYAN}atom${RESET} (a-)       Foundational UI elements (raw HTML permitted)`,
+    `${BOLD}TIERS & JIG KINDS${RESET}`,
     `  ${CYAN}molecule${RESET} (m-)   Groups of atoms (no raw HTML, co-located controller)`,
+    `  ${CYAN}atom${RESET} (a-)       Foundational UI elements (raw HTML permitted)`,
     `  ${CYAN}organism${RESET} (o-)   Complex feature modules`,
     `  ${CYAN}hook${RESET} (use-)     Domain state / headless composables (< 5 return properties)`,
     `  ${CYAN}view${RESET} (v-)       Declarative Table-of-Contents views`,
+    `  ${CYAN}service${RESET}        Domain service / API client with Result tuples and spec`,
+    `  ${CYAN}route${RESET}          HTTP API route handler with schema validation and test`,
+    `  ${CYAN}store${RESET}          State store / reactive machine with discriminated unions`,
+    `  ${CYAN}repo${RESET}           Database repository with CRUD methods and Result tuples`,
+    `  ${CYAN}util${RESET}           Pure stateless utility functions with test spec`,
+    `  ${CYAN}spec${RESET}           Isolated unit test spec for an existing target`,
     '',
     `${BOLD}OPTIONS${RESET}`,
-    `  ${CYAN}--tier=<tier>${RESET}                    Specify component tier`,
+    `  ${CYAN}--tier=<tier>${RESET}                    Specify component tier (atom, molecule, organism, hook, view)`,
+    `  ${CYAN}--jig=<kind>${RESET}                     Specify programmatic file kind (service, route, store, repo, util, spec)`,
     `  ${CYAN}--framework=<react|vue|svelte>${RESET}  Framework flavor (default: auto-detected or react)`,
-    `  ${CYAN}--dir=<path>${RESET}                     Target directory (default: src/components/<tier>s)`,
+    `  ${CYAN}--dir=<path>${RESET}                     Target directory (default: src/components/<tier>s or src/<kind>s)`,
     `  ${CYAN}--desc="<text>"${RESET}                  Describe functionality to tailor archetype and state`,
+    `  ${CYAN}--methods="<m1,m2>"${RESET}              Method names or signatures for service/repo/store`,
+    `  ${CYAN}--state="<s1,s2>"${RESET}                State property definitions for store or controller`,
+    `  ${CYAN}--routes="<r1,r2>"${RESET}               Route definitions for API route jig (e.g. GET /items, POST /items)`,
+    `  ${CYAN}--schema="<json>"${RESET}                Structured JSON schema definition payload`,
     `  ${CYAN}--dry-run${RESET}                        Preview planned files and lines without touching disk`,
     `  ${CYAN}--lean${RESET}                           Generate minimal capsule without controller/spec`,
     `  ${CYAN}--json${RESET}                           Output result as minified JSON`,
@@ -32,14 +43,23 @@ export const printGenerateHelp = () => {
     '',
     `${BOLD}EXAMPLES${RESET}`,
     `  ${CYAN}npx chemx generate m-task-list --framework=react${RESET}`,
-    `  ${CYAN}npx chemx generate m-task-list --desc="add, toggle, remove items"${RESET}`,
-    `  ${CYAN}npx chemx generate m-task-list --dry-run${RESET}`,
+    `  ${CYAN}npx chemx generate --jig=service payment-gateway --methods="processCharge,refund"${RESET}`,
+    `  ${CYAN}npx chemx jig route api-orders --routes="GET /orders, POST /orders"${RESET}`,
+    `  ${CYAN}npx chemx jig store session-machine --desc="user authentication lifecycle"${RESET}`,
     `  ${CYAN}npx chemx generate hook use-task-filter${RESET}`,
     `  ${CYAN}npx chemx generate view v-user-profile${RESET}`,
     '',
+    `${BOLD}TOKEN ECONOMICS & AGENT JIG${RESET}`,
+    `  ${DIM}Thesis:        Passing a 30-50 token parameter payload to chemx generate / jig replaces${RESET}`,
+    `  ${DIM}               1,000-2,500 output tokens of repetitive TypeScript, SCSS, and spec boilerplate.${RESET}`,
+    `  ${DIM}Reduction:     90%+ fewer LLM output tokens consumed per component, service, or route.${RESET}`,
+    `  ${DIM}Invariants:    Guarantees <100 LOC limits, Result tuples, 2-stage booleans, zero synthetic data,${RESET}`,
+    `  ${DIM}               and co-located unit test specs without LLM syntax drift or hallucination.${RESET}`,
+    '',
     `${BOLD}LINE LIMITS${RESET}`,
     `  ${DIM}Molecule capsule template:  < 100 lines (outer bound)${RESET}`,
     `  ${DIM}Co-located controller hook: < 100 lines (pure reactive state)${RESET}`,
+    `  ${DIM}Domain service / repo:      < 100 lines (stateless or cohesive atomic class)${RESET}`,
     `  ${DIM}Table of Contents view:     10-20 lines (declarative slot assembly)${RESET}`,
     ''
   ];

package/cli/generator-jig-cli.js

@@ -0,0 +1,67 @@
+import { createJigFiles, normalizeJigKind, JIG_KINDS } from './generator-jig.js';
+
+export const handleJigCli = ({ rawArgs, positional, rawName, dirArg, descArg, isDryRun, isJson }) => {
+  const jigFlag = (rawArgs.find((a) => a.startsWith('--jig=')) || '').split('=')[1];
+  const kindFlag = (rawArgs.find((a) => a.startsWith('--kind=')) || '').split('=')[1];
+
+  let resolvedKind = jigFlag || kindFlag;
+  let resolvedName = rawName;
+
+  if (!resolvedKind && positional[0] && JIG_KINDS.has(positional[0].toLowerCase())) {
+    resolvedKind = positional[0].toLowerCase();
+    resolvedName = positional[1] || rawName;
+  } else if (positional[0] && positional[0].toLowerCase() === 'jig') {
+    resolvedKind = positional[1];
+    resolvedName = positional[2] || rawName;
+  }
+  resolvedKind = normalizeJigKind(resolvedKind || 'service');
+
+  const methodsArg = (rawArgs.find((a) => a.startsWith('--methods=')) || '').replace(/^--methods=/, '');
+  const stateArg = (rawArgs.find((a) => a.startsWith('--state=')) || '').replace(/^--state=/, '');
+  const routesArg = (rawArgs.find((a) => a.startsWith('--routes=')) || '').replace(/^--routes=/, '');
+  const presetArg = (rawArgs.find((a) => a.startsWith('--preset=')) || '').replace(/^--preset=/, '');
+  const schemaArg = (rawArgs.find((a) => a.startsWith('--schema=')) || '').replace(/^--schema=/, '');
+
+  let schemaData = {};
+  if (schemaArg) {
+    try {
+      schemaData = JSON.parse(schemaArg);
+    } catch {
+      // ignore JSON parse error
+    }
+  }
+
+  const jigRes = createJigFiles({
+    kind: schemaData.kind || resolvedKind,
+    name: schemaData.name || resolvedName || `sample-${resolvedKind}`,
+    dir: dirArg,
+    preset: presetArg,
+    methods: schemaData.methods || methodsArg,
+    state: schemaData.state || stateArg,
+    routes: schemaData.routes || routesArg,
+    desc: descArg || schemaData.desc,
+    dryRun: isDryRun,
+    cwd: process.cwd()
+  });
+
+  if (isJson) {
+    process.stdout.write(JSON.stringify(jigRes) + '\n');
+    return jigRes;
+  }
+
+  if (jigRes.dryRun) {
+    process.stdout.write(`\n\x1b[1m\x1b[33m[DRY RUN]\x1b[0m Would generate programmatic jig (${jigRes.kind}) at \x1b[36m${jigRes.relativeDir}/\x1b[0m:\n`);
+    for (const f of jigRes.previews || []) {
+      process.stdout.write(`  \x1b[33m•\x1b[0m ${f.file} (${f.lines} lines)\n`);
+    }
+    process.stdout.write('\n\x1b[2mDry run complete. No files were written to disk.\x1b[0m\n\n');
+    return jigRes;
+  }
+
+  process.stdout.write(`\n\x1b[1m\x1b[32m✔ Successfully generated programmatic jig (${jigRes.kind}):\x1b[0m \x1b[36m${jigRes.relativeDir}/\x1b[0m\n`);
+  for (const f of jigRes.filesCreated) {
+    process.stdout.write(`  \x1b[32m✔\x1b[0m ${f}\n`);
+  }
+  process.stdout.write('\n\x1b[2mChemical X Standards verified: < 100 lines per file, Result tuples, co-located spec tests.\x1b[0m\n\n');
+  return jigRes;
+};