@chemx/starter-kit 26.9.25-943 → 26.9.26-253

package/cli/index.js

@@ -68,6 +68,7 @@ export const runWriterCli    = async (...a) => (await import('./patcher.js')).ru
 export const writeFile       = async (...a) => (await import('./patcher.js')).writeFile(...a);
 export const runTeamCli      = async (...a) => (await import('./team/index.js')).runTeamCli(...a);
 export const runTrend        = async (...a) => (await import('./trend.js')).runTrend(...a);
+export const runLintAudit    = async (...a) => (await import('./verify-lint.js')).runLintAudit(...a);
 export const runPillarsWizard = async (...a) => (await import('./pillars-wizard.js')).runPillarsWizard(...a);
 export const runTesseract    = async (...a) => (await import('./tesseract.js')).runTesseract(...a);
 export { handleError, withErrorCatcher, publishIssue };
@@ -78,10 +79,11 @@ export { handleError, withErrorCatcher, publishIssue };
 
 export const ALLOWED_COMMANDS = new Set([
   'search', 'q', 'query', 'find',
+  'trace', 'backtrace',
   'read', 'view', 'r',
   'patch', 'edit',
   'write',
-  'generate', 'g', 'gen', 'capsule', 'add',
+  'generate', 'g', 'gen', 'capsule', 'add', 'jig',
   'explode', 'unpack',
   'audit',
   'trend', 'trends',
@@ -93,6 +95,7 @@ export const ALLOWED_COMMANDS = new Set([
   'mcp', 'mcp-server', 'server', 'install-mcp', 'setup-mcp',
   'build', 'run', 'wrap',
   'typecheck', 'check:types', 'tsc',
+  'lint', 'check:lint', 'eslint',
   'test', 'tests', 'check:test',
   'check',
   'badge', 'badges',

package/cli/installer-templates.js

@@ -98,15 +98,20 @@ elif command -v npx >/dev/null 2>&1; then
 fi
 
 if [ -n "\$AUDIT_BIN" ]; then
-  printf "%s[Chemical X] Verifying architectural health (Min Grade: %s, Min Score: %s)...%s\\n" "\$C_BLUE" "\$MIN_GRADE" "\$MIN_SCORE" "\$C_RESET"
-  if ! \$AUDIT_BIN audit --git --min-grade="\$MIN_GRADE" --min-score="\$MIN_SCORE" --non-interactive < /dev/null; then
+  if [ "\$CHEMX_VERBOSE" = "1" ]; then
+    printf "%s[Chemical X] Verifying architectural health (Min Grade: %s, Min Score: %s)...%s\\n" "\$C_BLUE" "\$MIN_GRADE" "\$MIN_SCORE" "\$C_RESET"
+  fi
+  if ! AUDIT_OUT=\$(eval "\$AUDIT_BIN audit --git --min-grade=\$MIN_GRADE --min-score=\$MIN_SCORE --non-interactive" < /dev/null 2>&1); then
     printf "\\n%s%s[Chemical X] Commit Blocked: Architectural health verification failed%s\\n" "\$C_BOLD" "\$C_RED" "\$C_RESET"
+    printf "%s\\n\\n" "\$AUDIT_OUT"
     printf "%s💡 Tip: Want crystalline drop-in templates? Run 'npm create chemx' or sponsor at https://github.com/sponsors/Chemical-X-Protocol%s\\n\\n" "\$C_CYAN" "\$C_RESET"
     exit 1
   fi
 fi
 
-printf "%s✔ [Chemical X] Pre-commit architectural guardrails passed.%s\\n" "\$C_GREEN" "\$C_RESET"
+if [ "\$CHEMX_VERBOSE" = "1" ]; then
+  printf "%s✔ [Chemical X] Pre-commit architectural guardrails passed.%s\\n" "\$C_GREEN" "\$C_RESET"
+fi
 exit 0
 `;
 

package/cli/mcp/manifests.js

@@ -34,16 +34,20 @@ export const MASTER_MCP_TOOL = {
           'patterns',
           'issue',
           'project',
-          'tesseract'
+          'tesseract',
+          'trace',
+          'backtrace'
         ],
         description: 'The Chemical X subsystem action to execute.'
       },
       params: {
         type: 'object',
-        description: 'Parameter payload for the specific action (e.g., { path, symbol, outline, connections } for read; { query, blastRadius, semantic, hybrid } for q; { path, search, replace } for patch; { dir, command } for test/build).',
+        description: 'Parameter payload for the specific action (e.g., { path, symbol, outline, logic, template, connections } for read; { query, blastRadius, trace, backtrace, semantic, hybrid } for q; { path, search, replace } for patch; { dir, command } for test/build).',
         properties: {
           query: { type: 'string', description: 'Search term, symbol name, or conceptual query (for q/search)' },
           blastRadius: { type: 'boolean', description: 'Map direct consumers, transitive dependents & impacted tiers (for q)' },
+          trace: { type: 'boolean', description: 'Compute forward call trace of downstream invocations (for q/search)' },
+          backtrace: { type: 'boolean', description: 'Compute reverse backtrace causal caller path (for q/search)' },
           semantic: { type: 'boolean', description: 'Search conceptually related components via vector cosine similarity (for q)' },
           hybrid: { type: 'boolean', description: 'Blend BM25 keyword matching + Vector RRF ranking (for q)' },
           connections: { type: 'boolean', description: 'Include caller graph and dependent references (for q, read)' },
@@ -54,7 +58,12 @@ export const MASTER_MCP_TOOL = {
           reindex: { type: 'boolean', description: 'Force re-index before running query (for q)' },
           path: { type: 'string', description: 'Target file path (for read, patch, write, check, lock)' },
           symbol: { type: 'string', description: 'Target symbol declaration to extract (for read)' },
-          outline: { type: 'boolean', description: 'Extract AST signatures only (80%+ token reduction) (for read)' },
+          outline: { type: 'boolean', description: 'Extract AST signatures only (80%+ token reduction). Compose with enrich:true for free-lunch outline + logic in one call. (for read)' },
+          logic: { type: 'boolean', description: 'Extract AST logic skeleton preserving control flow, guards, and mutations (for read)' },
+          template: { type: 'boolean', description: 'Extract declarative template markup only (Vue/Svelte/JSX) (for read)' },
+          enrich: { type: 'boolean', description: 'Append compacted logic skeleton after outline block. Composable overlay: use with outline:true or symbol. Returns outline + logic in one token-compact response without boilerplate penalty. (for read)' },
+          traceSymbol: { type: 'string', description: 'Symbol name: appends forward call trace card inline when enrich:true (for read)' },
+          backtraceSymbol: { type: 'string', description: 'Symbol name: appends reverse caller chain card inline when enrich:true (for read)' },
           startLine: { type: 'number', description: 'Starting line number (1-indexed) (for read)' },
           endLine: { type: 'number', description: 'Ending line number (1-indexed) (for read)' },
           stripComments: { type: 'boolean', description: 'Remove comments to minimize tokens (for read)' },
@@ -69,6 +78,8 @@ export const MASTER_MCP_TOOL = {
           overwrite: { type: 'boolean', description: 'Allow overwriting existing file (for write)' },
           dir: { type: 'string', description: 'Target directory (for audit, test, build, patterns)' },
           command: { type: 'string', description: 'Explicit execution command (for build, test)' },
+          target: { type: 'string', description: 'Target test file or spec path (for test)' },
+          filter: { type: 'string', description: 'Filter test names by regex or string pattern (for test)' },
           subAction: { type: 'string', description: 'Sub-action for team operations (e.g. list, claim, done, triage, acquire, release)' },
           taskId: { type: 'number', description: 'Target task ID (for team task claim/done)' },
           agentId: { type: 'string', description: 'Agent handle (e.g. @antigravity, @coder)' },
@@ -78,6 +89,13 @@ export const MASTER_MCP_TOOL = {
           force: { type: 'boolean', description: 'Force complete task even if hazards remain (for team task done)' },
           tokens: { type: 'number', description: 'Prompt tokens consumed by task' },
           cost: { type: 'number', description: 'Estimated dollar cost for task' },
+          jig: { type: 'boolean', description: 'Enable universal programmatic jig generation (for generate)' },
+          kind: { type: 'string', enum: ['service', 'route', 'store', 'repo', 'util', 'spec'], description: 'Programmatic file kind for jig (for generate)' },
+          methods: { description: 'Methods definitions array or comma-separated string (for generate)' },
+          state: { description: 'State properties array or string (for generate)' },
+          routes: { description: 'Routes array or string (for generate)' },
+          schema: { description: 'JSON schema definition (for generate)' },
+          preset: { type: 'string', enum: ['src', 'app', 'root', 'lib'], description: 'Architecture directory preset (for generate)' },
           name: { type: 'string', description: 'Capsule name (for generate)' },
           desc: { type: 'string', description: 'Functional description to tailor archetype (for generate)' },
           framework: { type: 'string', enum: ['vue', 'react', 'svelte'], description: 'Framework flavor (for generate)' },
@@ -90,7 +108,7 @@ export const MASTER_MCP_TOOL = {
       },
       command: {
         type: 'string',
-        description: 'Optional CLI command string format (e.g., "test", "build", "verify", "typecheck", "audit src", "q a-button --blast-radius --json", "q \\"button state\\" --semantic --json", "read src/foo.vue --outline", "check src/bar.ts", "team task list").'
+        description: 'Optional CLI command string format (e.g., "test", "build", "verify", "typecheck", "audit src", "q a-button --blast-radius --json", "q \\"button state\\" --semantic --json", "read src/foo.vue --outline", "read src/foo.vue --outline --enrich", "check src/bar.ts", "team task list").'
       }
     }
   }

package/cli/mcp/tools-generate.js

@@ -1,4 +1,4 @@
-import { createCapsuleFiles } from '../generator.js';
+import { createCapsuleFiles, createJigFiles, JIG_KINDS } from '../generator.js';
 import { openIndexDb } from '../search-schema.js';
 import { fetchScoreTrends, formatTrendReport, renderSparkline } from '../trend.js';
 import { resolveTargetCwd } from './tools-search.js';
@@ -6,12 +6,32 @@ import { resolveTargetCwd } from './tools-search.js';
 export const handleGenerateCapsule = (args = {}, cwd = process.cwd()) => {
   const { name, framework, tier = 'm', targetDir = null, lean = false, desc = '', description = '', dryRun = false } = args;
 
+  const isJig = Boolean(args.jig || args.kind || (args.tier && JIG_KINDS.has(args.tier.toLowerCase())));
+  if (isJig) {
+    const kind = args.kind || (typeof args.jig === 'string' ? args.jig : null) || (args.tier && JIG_KINDS.has(args.tier.toLowerCase()) ? args.tier : 'service');
+    const jigResult = createJigFiles({
+      kind,
+      name: (name || `sample-${kind}`).trim(),
+      targetParent: targetDir,
+      dir: args.dir,
+      preset: args.preset,
+      methods: args.methods,
+      state: args.state,
+      routes: args.routes,
+      schema: args.schema,
+      desc: desc || description,
+      dryRun: Boolean(dryRun),
+      cwd
+    });
+    return jigResult;
+  }
+
   const hasName = Boolean(name && name.trim());
   const hasValidFramework = Boolean(framework && ['react', 'vue', 'svelte'].includes(framework.toLowerCase()));
   const canGenerate = hasName && hasValidFramework;
 
   if (!canGenerate) {
-    throw new Error('chemx_generate_capsule requires "name" and "framework" (react, vue, svelte).');
+    throw new Error('chemx_generate_capsule requires "name" and "framework" (react, vue, svelte), or pass "jig: true" / "kind".');
   }
 
   const result = createCapsuleFiles({

package/cli/mcp/tools-read.js

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import { openIndexDb } from '../search-db.js';
 import {
-  findSymbolReferences, findFileDependencies, findFileDependents, calculateBlastRadius
+  findSymbolReferences, findFileDependencies, findFileDependents, calculateBlastRadius,
+  calculateCallTrace, calculateBacktrace,
 } from '../search-queries.js';
 import { findSimilarSymbols } from '../search-queries-similar.js';
 import { readTokenOptimized } from '../reader.js';
@@ -35,6 +36,28 @@ const buildContextEnvelope = (db, targetPath) => {
   return '';
 };
 
+const buildTraceCard = (db, symbol) => {
+  try {
+    const result = calculateCallTrace(db, symbol, { maxDepth: 3 });
+    if (!result || !result.callees || result.callees.length === 0) return '';
+    const lines = result.callees.slice(0, 6).map((c) => `//   -> ${c.symbol || c} (${c.file ? path.basename(c.file) : '?'})`);
+    return `\n// --- Forward Trace: ${symbol} ---\n${lines.join('\n')}`;
+  } catch {
+    return '';
+  }
+};
+
+const buildBacktraceCard = (db, symbol) => {
+  try {
+    const result = calculateBacktrace(db, symbol, { maxDepth: 5 });
+    if (!result || !result.rootCallers || result.rootCallers.length === 0) return '';
+    const lines = result.rootCallers.slice(0, 5).map((c) => `//   <- ${path.basename(c)}`);
+    return `\n// --- Backtrace: ${symbol} ---\n${lines.join('\n')}`;
+  } catch {
+    return '';
+  }
+};
+
 export const handleChemxRead = (args = {}, cwd = process.cwd()) => {
   if (!args.path) throw new Error('chemx_read requires "path" argument.');
   const targetCwd = resolveTargetCwd(args.cwd || cwd);
@@ -51,19 +74,38 @@ export const handleChemxRead = (args = {}, cwd = process.cwd()) => {
 
   const targetPath = path.isAbsolute(rawPath) ? rawPath : path.resolve(targetCwd, rawPath);
   const res = readTokenOptimized(targetPath, {
-    outline: args.outline, symbol: args.symbol,
-    stripComments: args.stripComments !== false, compact: args.compact !== false,
-    startLine, endLine
+    outline: args.outline,
+    logic: args.logic,
+    template: args.template,
+    enrich: args.enrich,
+    traceSymbol: args.traceSymbol,
+    backtraceSymbol: args.backtraceSymbol,
+    symbol: args.symbol,
+    stripComments: args.stripComments !== false,
+    compact: args.compact !== false,
+    startLine,
+    endLine
   });
 
-  const db = (args.connections || args.symbol) ? openIndexDb(targetCwd) : null;
+  const needsDb = args.connections || args.symbol || (args.enrich && (args.traceSymbol || args.backtraceSymbol));
+  const db = needsDb ? openIndexDb(targetCwd) : null;
   const connectionCard = (args.connections && db) ? buildConnectionCard(db, args.symbol, targetPath) : '';
   const contextEnvelope = (args.symbol && db) ? buildContextEnvelope(db, targetPath) : '';
 
+  const traceCard = (args.enrich && args.traceSymbol && db)
+    ? buildTraceCard(db, args.traceSymbol)
+    : '';
+  const backtraceCard = (args.enrich && args.backtraceSymbol && db)
+    ? buildBacktraceCard(db, args.backtraceSymbol)
+    : '';
+
   const ext = path.extname(targetPath).toLowerCase();
   const lang = EXT_LANG_MAP[ext] || '';
-  const fence = res.content.includes('```') ? '~~~' : '```';
-  const fenced = `${fence}${lang}\n${res.content}\n${fence}`;
-  const header = `// ${res.file} (${res.lineCount || res.totalLines} lines, ~${res.tokensEst} tokens)${connectionCard}\n`;
+  const bodyParts = [res.content, res.enriched, traceCard, backtraceCard].filter(Boolean);
+  const body = bodyParts.join('\n');
+  const fence = body.includes('```') ? '~~~' : '```';
+  const fenced = `${fence}${lang}\n${body}\n${fence}`;
+  const enrichNote = res.tokensEnriched > 0 ? ` +${res.tokensEnriched} enriched` : '';
+  const header = `// ${res.file} (${res.lineCount || res.totalLines} lines, ~${res.tokensEst} tokens${enrichNote})${connectionCard}\n`;
   return header + contextEnvelope + fenced;
 };

package/cli/mcp/tools-verify.js

@@ -30,6 +30,8 @@ export const handleChemxTest = async (args = {}, cwd = process.cwd()) => {
   return runTestAudit([], false, {
     json: true,
     command: args.command,
+    target: args.target,
+    filter: args.filter,
     print: false,
     cwd: targetCwd
   });

package/cli/mcp/tools.js

@@ -16,16 +16,65 @@ const parseCommand = (command, params) => {
   const parts = command.trim().split(/\s+/);
   const subCmd = parts[0];
   if (subCmd === 'audit' || subCmd === 'check') return { action: subCmd, params: { path: parts[1] || 'src', ...params } };
-  if (subCmd === 'build') return { action: 'build', params: { dir: parts[1] || '.', ...params } };
-  if (['verify', 'typecheck', 'test'].includes(subCmd)) return { action: subCmd, params };
+  if (subCmd === 'test') {
+    const targetMatch = command.match(/--target=([^\s]+)/);
+    const filterMatch = command.match(/(?:--filter=|-t=|-t\s+)([^\s]+)/);
+    const positional = parts.slice(1).find((p) => !p.startsWith('-'));
+    return {
+      action: 'test',
+      params: {
+        target: targetMatch ? targetMatch[1] : (positional || params?.target),
+        filter: filterMatch ? filterMatch[1] : params?.filter,
+        ...params
+      }
+    };
+  }
+  if (subCmd === 'jig') {
+    const kind = parts[1];
+    const name = parts[2];
+    const methodsMatch = command.match(/--methods=([^\s]+)/);
+    const routesMatch = command.match(/--routes=([^\s]+)/);
+    return {
+      action: 'generate',
+      params: {
+        jig: true,
+        kind,
+        name,
+        methods: methodsMatch ? methodsMatch[1] : undefined,
+        routes: routesMatch ? routesMatch[1] : undefined,
+        ...params
+      }
+    };
+  }
+  if (['verify', 'typecheck'].includes(subCmd)) return { action: subCmd, params };
   if (subCmd === 'read' || subCmd === 'r') {
     const hasOutline = command.includes('--outline') || command.includes(' -o');
+    const hasLogic = command.includes('--logic') || command.includes(' -l');
+    const hasTemplate = command.includes('--template') || command.includes(' -t');
+    const hasEnrich = command.includes('--enrich');
     const symbolMatch = command.match(/(?:--symbol=|-s\s+|-s=)([^\s]+)/);
+    const traceMatch = command.match(/--trace=([^\s]+)/);
+    const backtraceMatch = command.match(/--backtrace=([^\s]+)/);
     const lineMatch = parts[1]?.match(/^([^:]+):(\d+)(?:[-:](\d+))?$/);
     const targetPath = lineMatch ? lineMatch[1] : parts[1];
     const startLine = lineMatch ? parseInt(lineMatch[2], 10) : undefined;
     const endLine = lineMatch && lineMatch[3] ? parseInt(lineMatch[3], 10) : undefined;
-    return { action: 'read', params: { path: targetPath, outline: hasOutline, symbol: symbolMatch ? symbolMatch[1] : undefined, startLine, endLine, ...params } };
+    return {
+      action: 'read',
+      params: {
+        path: targetPath,
+        outline: hasOutline || undefined,
+        logic: hasLogic || undefined,
+        template: hasTemplate || undefined,
+        enrich: hasEnrich || undefined,
+        symbol: symbolMatch ? symbolMatch[1] : undefined,
+        traceSymbol: traceMatch ? traceMatch[1] : undefined,
+        backtraceSymbol: backtraceMatch ? backtraceMatch[1] : undefined,
+        startLine,
+        endLine,
+        ...params
+      }
+    };
   }
   if (subCmd === 'q' || subCmd === 'search') return { action: 'q', params: { query: parts.slice(1).join(' '), ...params } };
   if (subCmd === 'team') {

package/cli/project-detector.js

@@ -170,8 +170,73 @@ const TIER_DIRECTORY_MAPS = {
   ]
 };
 
-export const detectTierBaseDir = (tier, cwd = process.cwd()) => {
+export const PRESET_DIRECTORY_MAPS = {
+  src: {
+    molecule: 'src/components/molecules',
+    atom: 'src/components/atoms',
+    organism: 'src/components/organisms',
+    template: 'src/components/templates',
+    hook: 'src/hooks',
+    view: 'src/views',
+    service: 'src/services',
+    route: 'src/routes',
+    store: 'src/stores',
+    repo: 'src/repos',
+    util: 'src/utils',
+    spec: 'test/unit'
+  },
+  app: {
+    molecule: 'app/components/molecules',
+    atom: 'app/components/atoms',
+    organism: 'app/components/organisms',
+    template: 'app/components/templates',
+    hook: 'app/composables',
+    view: 'app/pages',
+    service: 'app/services',
+    route: 'server/api',
+    store: 'app/stores',
+    repo: 'server/repos',
+    util: 'app/utils',
+    spec: 'test/unit'
+  },
+  root: {
+    molecule: 'components/molecules',
+    atom: 'components/atoms',
+    organism: 'components/organisms',
+    template: 'components/templates',
+    hook: 'hooks',
+    view: 'pages',
+    service: 'services',
+    route: 'routes',
+    store: 'stores',
+    repo: 'repos',
+    util: 'utils',
+    spec: 'test'
+  },
+  lib: {
+    molecule: 'src/lib/components/molecules',
+    atom: 'src/lib/components/atoms',
+    organism: 'src/lib/components/organisms',
+    template: 'src/lib/components/templates',
+    hook: 'src/lib/hooks',
+    view: 'src/routes',
+    service: 'src/lib/services',
+    route: 'src/routes/api',
+    store: 'src/lib/stores',
+    repo: 'src/lib/repos',
+    util: 'src/lib/utils',
+    spec: 'test'
+  }
+};
+
+export const detectTierBaseDir = (tier, cwd = process.cwd(), presetOverride = null) => {
   const config = loadProjectConfig(cwd);
+  const activePreset = presetOverride || config.preset;
+
+  if (activePreset && PRESET_DIRECTORY_MAPS[activePreset]?.[tier]) {
+    return PRESET_DIRECTORY_MAPS[activePreset][tier];
+  }
+
   if (config.dirs && config.dirs[tier]) {
     const configuredPath = path.resolve(cwd, config.dirs[tier]);
     if (fs.existsSync(configuredPath)) return config.dirs[tier];
@@ -182,7 +247,45 @@ export const detectTierBaseDir = (tier, cwd = process.cwd()) => {
     if (fs.existsSync(path.resolve(cwd, c))) return c;
   }
 
-  return '.';
+  if (fs.existsSync(path.resolve(cwd, 'app/components'))) {
+    return PRESET_DIRECTORY_MAPS.app[tier] || 'app/components';
+  }
+
+  return PRESET_DIRECTORY_MAPS.src[tier] || '.';
+};
+
+export const detectJigBaseDir = (kind, { cwd = process.cwd(), preset = null } = {}) => {
+  const config = loadProjectConfig(cwd);
+  const activePreset = preset || config.preset;
+
+  if (activePreset && PRESET_DIRECTORY_MAPS[activePreset]?.[kind]) {
+    return PRESET_DIRECTORY_MAPS[activePreset][kind];
+  }
+
+  if (config.dirs && config.dirs[kind]) {
+    const configuredPath = path.resolve(cwd, config.dirs[kind]);
+    if (fs.existsSync(configuredPath)) return config.dirs[kind];
+  }
+
+  const defaultDirMap = {
+    service: ['src/services', 'app/services', 'services', 'src/lib/services'],
+    route: ['src/routes', 'server/api', 'routes', 'src/routes/api'],
+    store: ['src/stores', 'app/stores', 'stores', 'src/lib/stores'],
+    repo: ['src/repos', 'server/repos', 'repos', 'src/lib/repos'],
+    util: ['src/utils', 'app/utils', 'utils', 'src/lib/utils'],
+    spec: ['test/unit', 'tests/unit', 'test', 'tests']
+  };
+
+  const candidates = defaultDirMap[kind] || [`src/${kind}s`];
+  for (const c of candidates) {
+    if (fs.existsSync(path.resolve(cwd, c))) return c;
+  }
+
+  if (fs.existsSync(path.resolve(cwd, 'app'))) {
+    return PRESET_DIRECTORY_MAPS.app[kind] || `app/${kind}s`;
+  }
+
+  return PRESET_DIRECTORY_MAPS.src[kind] || `src/${kind}s`;
 };
 
 const TAILWIND_PACKAGES = [

package/cli/reader-cli.js

@@ -0,0 +1,146 @@
+import { ANSI } from './theme.js';
+import { readTokenOptimized } from './reader.js';
+
+/**
+ * CLI command runner for chemx read / chemx view.
+ *
+ * @param {string[]} args CLI arguments.
+ * @param {boolean} isCli Whether invoked directly from CLI.
+ */
+export const runReaderCli = (args, isCli = false) => {
+  if (args.includes('--help') || args.includes('-h') || args.includes('help')) {
+    const isJson = args.includes('--json');
+    if (isJson) {
+      process.stdout.write(JSON.stringify({ help: true, success: true }) + '\n');
+    } else {
+      process.stdout.write([
+        `${ANSI.BOLD}USAGE${ANSI.RESET}`,
+        `  chemx read <file> [options]`,
+        '',
+        `${ANSI.BOLD}OPTIONS${ANSI.RESET}`,
+        `  --outline                AST structure outline only (80%+ token savings)`,
+        `  --logic, -l              AST logic skeleton (control flow, state, mutations)`,
+        `  --template, -t           Extract template markup only (Vue/Svelte/JSX)`,
+        `  --enrich                 Append compacted logic skeleton after outline (free-lunch overlay)`,
+        `  --trace=<name>           Forward call trace card appended inline (requires --enrich)`,
+        `  --backtrace=<name>       Reverse caller chain card appended inline (requires --enrich)`,
+        `  --symbol=<name>          Extract specific function/hook/interface declaration`,
+        `  --start=<N>              Start line number (1-indexed)`,
+        `  --end=<N>                End line number (1-indexed)`,
+        `  --strip-comments         Remove comments to minimize tokens`,
+        `  --compact                Collapse empty whitespace lines`,
+        `  --json                   Output result as minified JSON`,
+        `  -h, --help               Show this help message`,
+        '',
+        `${ANSI.BOLD}EXAMPLES${ANSI.RESET}`,
+        `  chemx read src/store.ts --outline`,
+        `  chemx read src/controller.ts --outline --enrich`,
+        `  chemx read src/card.vue --outline --enrich --trace=handleSubmit`,
+        `  chemx read src/controller.ts --logic`,
+        `  chemx read api.ts --symbol=login --connections`,
+        ''
+      ].join('\n'));
+    }
+    if (isCli) process.exit(0);
+    return { help: true, success: true };
+  }
+
+  const nonFlagArgs = args.filter((a) => !a.startsWith('-'));
+  let filePath = nonFlagArgs[0];
+
+  if (!filePath) {
+    process.stderr.write(`${ANSI.RED}✕ Missing file path. Usage: chemx r <file[:start-end]> [-o] [-l] [-s name]${ANSI.RESET}\n`);
+    if (isCli) process.exit(1);
+    return null;
+  }
+
+  let startLine;
+  let endLine;
+
+  const colonMatch = filePath.match(/^([^:]+):(\d+)(?:[-:](\d+))?$/);
+  if (colonMatch) {
+    filePath = colonMatch[1];
+    startLine = parseInt(colonMatch[2], 10);
+    if (colonMatch[3]) endLine = parseInt(colonMatch[3], 10);
+  }
+
+  const isJson = args.includes('--json') || args.includes('-j');
+  const isOutline = args.includes('--outline') || args.includes('-o');
+  const isLogic = args.includes('--logic') || args.includes('-l');
+  const isTemplate = args.includes('--template') || args.includes('-t');
+  const isCompact = args.includes('--compact') || args.includes('-c');
+  const isStripComments = args.includes('--strip-comments') || args.includes('--no-comments') || args.includes('-sc');
+  const isEnrich = args.includes('--enrich');
+
+  const traceFlag = args.find((a) => a.startsWith('--trace='));
+  const traceSymbol = traceFlag ? traceFlag.split('=')[1] : null;
+
+  const backtraceFlag = args.find((a) => a.startsWith('--backtrace='));
+  const backtraceSymbol = backtraceFlag ? backtraceFlag.split('=')[1] : null;
+
+  let symbol = null;
+  const symEqFlag = args.find((a) => a.startsWith('--symbol=') || a.startsWith('-sym='));
+  if (symEqFlag) {
+    symbol = symEqFlag.split('=')[1];
+  } else {
+    const sIndex = args.findIndex((a) => a === '-s' || a === '--symbol');
+    if (sIndex !== -1 && args[sIndex + 1] && !args[sIndex + 1].startsWith('-')) {
+      symbol = args[sIndex + 1];
+    } else {
+      const sFlag = args.find((a) => a.startsWith('-s='));
+      if (sFlag) {
+        const val = sFlag.split('=')[1];
+        if (/^\d+$/.test(val)) {
+          if (startLine === undefined) startLine = parseInt(val, 10);
+        } else {
+          symbol = val;
+        }
+      }
+    }
+  }
+
+  if (startLine === undefined) {
+    const startFlag = args.find((a) => a.startsWith('--start='));
+    if (startFlag) startLine = parseInt(startFlag.split('=')[1], 10);
+  }
+
+  if (endLine === undefined) {
+    const endFlag = args.find((a) => a.startsWith('--end=') || a.startsWith('-e='));
+    if (endFlag) endLine = parseInt(endFlag.split('=')[1], 10);
+  }
+
+  try {
+    const res = readTokenOptimized(filePath, {
+      outline: isOutline,
+      logic: isLogic,
+      template: isTemplate,
+      compact: isCompact,
+      stripComments: isStripComments,
+      enrich: isEnrich,
+      traceSymbol,
+      backtraceSymbol,
+      symbol,
+      startLine,
+      endLine,
+    });
+
+    if (isJson) {
+      process.stdout.write(JSON.stringify(res, null, 2) + '\n');
+    } else {
+      const enrichSuffix = res.tokensEnriched > 0 ? ` +${res.tokensEnriched} enriched` : '';
+      process.stdout.write(`${ANSI.BOLD}${ANSI.CYAN}--- ${res.file} (${res.lineCount || res.totalLines} lines, ~${res.tokensEst} tokens${enrichSuffix}) ---${ANSI.RESET}\n`);
+      process.stdout.write(res.content + '\n');
+      if (res.enriched) {
+        process.stdout.write(res.enriched + '\n');
+      }
+    }
+
+    if (isCli) process.exit(0);
+    return res;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${ANSI.RED}✕ ${msg}${ANSI.RESET}\n`);
+    if (isCli) process.exit(1);
+    return null;
+  }
+};