@sun-asterisk/sungen 3.1.2 → 3.2.0-beta.141

package/src/cli/commands/context.ts

@@ -0,0 +1,52 @@
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { discoverUnitContext } from '../../orchestrator/context-discovery';
+
+/**
+ * `sungen context` — run the Discover → Contextualize phase (AO-3) for a unit and emit the
+ * normalized Context + generation-unit work-list. The `/sungen:design` loop calls this first so it
+ * knows WHAT to generate (the endpoints/screens + their modes) before authoring scenarios. Pure +
+ * deterministic; writes `.sungen/reports/<unit>-context.json`.
+ */
+export function registerContextCommand(program: Command): void {
+  program
+    .command('context')
+    .description('Discover + contextualize a unit (screen/flow/api area) → Context + generation units')
+    .option('-s, --screen <name>', 'Screen name')
+    .option('--flow <name>', 'Flow name (resolved as flows/<name>)')
+    .option('--api <name>', 'API-first area or api flow (resolved as api/<name>)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
+    .option('--json', 'Print the raw JSON')
+    .action(async (o: { screen?: string; flow?: string; api?: string; area?: string; json?: boolean }) => {
+      try {
+        const unitId = (o.api || o.area) ? `api/${o.api || o.area}` : o.flow ? `flows/${o.flow}` : o.screen;
+        if (!unitId) throw new Error('Provide --screen <name>, --flow <name>, or --api <area>.');
+        const cwd = process.cwd();
+        const result = await discoverUnitContext(unitId, cwd);
+
+        const outDir = path.join(cwd, '.sungen', 'reports');
+        fs.mkdirSync(outDir, { recursive: true });
+        const slug = unitId.replace(/\//g, '-');
+        const outPath = path.join(outDir, `${slug}-context.json`);
+        fs.writeFileSync(outPath, JSON.stringify(result, null, 2), 'utf-8');
+        if (o.json) { console.log(JSON.stringify(result, null, 2)); return; }
+
+        const L = console.log;
+        const facts = result.context.facts as { endpoints?: Array<{ name: string; method: string; path: string }> };
+        L(`\n━━━ Context: ${unitId} (capability: ${result.capability}) ━━━`);
+        const srcKeys = Object.keys(result.context.sources);
+        L(`  Sources: ${srcKeys.length ? srcKeys.join(', ') : '(none)'}`);
+        if (facts.endpoints?.length) {
+          L(`  Endpoints (${facts.endpoints.length}):`);
+          for (const e of facts.endpoints) L(`     • ${e.method} ${e.path}  (@api:${e.name})`);
+        }
+        const byMode = result.units.reduce<Record<string, number>>((m, u) => { m[u.mode] = (m[u.mode] || 0) + 1; return m; }, {});
+        L(`  Generation units: ${result.units.length} — ${Object.entries(byMode).map(([m, n]) => `${m}×${n}`).join(' · ') || '(none)'}`);
+        L(`\n  Report: ${path.relative(cwd, outPath)}\n`);
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/delivery.ts

@@ -52,45 +52,54 @@ function log(msg: string): void {
  * `name` is kept as an alias of `featureBaseName` so existing callers/labels
  * (preflight table, summary) read naturally — every visible row is per-feature.
  */
+type UnitKind = 'screen' | 'flow' | 'api';
+/** qa/ subfolder for a unit kind. */
+const qaParent = (kind: UnitKind): string => (kind === 'flow' ? 'flows' : kind === 'api' ? 'api' : 'screens');
+
 interface DeliveryTarget {
   screen: string;
   featureBaseName: string;
   /** Alias of `featureBaseName` — preserves the old `target.name` call sites. */
   name: string;
+  kind: UnitKind;
+  /** Back-compat: flows kept distinct labels/paths before api was added. */
   isFlow: boolean;
 }
 
-function makeTarget(screen: string, featureBaseName: string, isFlow: boolean): DeliveryTarget {
-  return { screen, featureBaseName, name: featureBaseName, isFlow };
+function makeTarget(screen: string, featureBaseName: string, kind: UnitKind): DeliveryTarget {
+  return { screen, featureBaseName, name: featureBaseName, kind, isFlow: kind === 'flow' };
 }
 
 /**
- * List all `.feature` files inside a screen/flow as separate targets.
+ * List all `.feature` files inside a screen/flow/api unit as separate targets.
  * Returns empty array when the directory has no features yet.
  */
-function listFeatureTargets(cwd: string, screen: string, isFlow: boolean): DeliveryTarget[] {
-  const featuresDir = path.join(cwd, 'qa', isFlow ? 'flows' : 'screens', screen, 'features');
+function listFeatureTargets(cwd: string, screen: string, kind: UnitKind): DeliveryTarget[] {
+  const featuresDir = path.join(cwd, 'qa', qaParent(kind), screen, 'features');
   if (!fs.existsSync(featuresDir)) return [];
   return fs.readdirSync(featuresDir)
     .filter((f) => f.endsWith('.feature'))
-    .map((f) => makeTarget(screen, f.slice(0, -'.feature'.length), isFlow))
+    .map((f) => makeTarget(screen, f.slice(0, -'.feature'.length), kind))
     .sort((a, b) => a.featureBaseName.localeCompare(b.featureBaseName));
 }
 
 function listAllTargets(cwd: string): DeliveryTarget[] {
   const targets: DeliveryTarget[] = [];
-
-  const screensDir = path.join(cwd, 'qa', 'screens');
-  if (fs.existsSync(screensDir)) {
-    for (const d of fs.readdirSync(screensDir, { withFileTypes: true })) {
-      if (d.isDirectory()) targets.push(...listFeatureTargets(cwd, d.name, false));
+  const scan = (kind: UnitKind, skip: (n: string) => boolean = () => false) => {
+    const root = path.join(cwd, 'qa', qaParent(kind));
+    if (!fs.existsSync(root)) return;
+    for (const d of fs.readdirSync(root, { withFileTypes: true })) {
+      if (d.isDirectory() && !skip(d.name)) targets.push(...listFeatureTargets(cwd, d.name, kind));
     }
-  }
-
-  const flowsDir = path.join(cwd, 'qa', 'flows');
-  if (fs.existsSync(flowsDir)) {
-    for (const d of fs.readdirSync(flowsDir, { withFileTypes: true })) {
-      if (d.isDirectory()) targets.push(...listFeatureTargets(cwd, d.name, true));
+  };
+  scan('screen');
+  scan('flow');
+  scan('api', (n) => n === 'flows');               // api areas: qa/api/<area>
+  // api flows: qa/api/flows/<flow> → screen `flows/<flow>`, kind 'api' (paths compose to qa/api/flows/… + specs/generated/api/flows/…)
+  const apiFlowsRoot = path.join(cwd, 'qa', 'api', 'flows');
+  if (fs.existsSync(apiFlowsRoot)) {
+    for (const d of fs.readdirSync(apiFlowsRoot, { withFileTypes: true })) {
+      if (d.isDirectory()) targets.push(...listFeatureTargets(cwd, path.posix.join('flows', d.name), 'api'));
     }
   }
 
@@ -108,28 +117,27 @@ function listAllTargets(cwd: string): DeliveryTarget[] {
  * feature file with the basename across all screens & flows.
  */
 function resolveTargetsFromArg(cwd: string, name: string): DeliveryTarget[] {
-  if (fs.existsSync(path.join(cwd, 'qa', 'flows', name))) {
-    return listFeatureTargets(cwd, name, true);
-  }
-  if (fs.existsSync(path.join(cwd, 'qa', 'screens', name))) {
-    return listFeatureTargets(cwd, name, false);
-  }
-  // Treat as feature basename — find the parent screen/flow that hosts it.
+  if (fs.existsSync(path.join(cwd, 'qa', 'flows', name))) return listFeatureTargets(cwd, name, 'flow');
+  if (fs.existsSync(path.join(cwd, 'qa', 'screens', name))) return listFeatureTargets(cwd, name, 'screen');
+  if (fs.existsSync(path.join(cwd, 'qa', 'api', name))) return listFeatureTargets(cwd, name, 'api');
+  // `flows/<flow>` or a bare api-flow name → qa/api/flows/<flow>
+  const apiFlow = name.startsWith('flows/') ? name : path.posix.join('flows', name);
+  if (fs.existsSync(path.join(cwd, 'qa', 'api', apiFlow))) return listFeatureTargets(cwd, apiFlow, 'api');
+  // Treat as feature basename — find the parent unit that hosts it.
   const candidates = listAllTargets(cwd).filter((t) => t.featureBaseName === name);
   if (candidates.length > 0) return candidates;
   // Fallback: treat as screen name even if directory missing (lets preflight
   // surface the "feature file missing" error with the right path).
-  return [makeTarget(name, name, false)];
+  return [makeTarget(name, name, 'screen')];
 }
 
 function qaDir(cwd: string, target: DeliveryTarget): string {
-  return path.join(cwd, 'qa', target.isFlow ? 'flows' : 'screens', target.screen);
+  return path.join(cwd, 'qa', qaParent(target.kind), target.screen);
 }
 
 function generatedDir(cwd: string, target: DeliveryTarget): string {
-  return target.isFlow
-    ? path.join(cwd, 'specs', 'generated', 'flows', target.screen)
-    : path.join(cwd, 'specs', 'generated', target.screen);
+  const sub = target.kind === 'flow' ? path.join('flows', target.screen) : target.kind === 'api' ? path.join('api', target.screen) : target.screen;
+  return path.join(cwd, 'specs', 'generated', sub);
 }
 
 // ----------------------------------------------------------------------------
@@ -262,7 +270,8 @@ function runPreflight(cwd: string, target: DeliveryTarget): PreflightCheck {
 
   const featureOk = checkFeatureReal(featureFile);
   const testDataOk = checkTestDataHasVars(testDataFile);
-  const selectorsOk = checkSelectorsHasEntries(selectorsFile, target.featureBaseName);
+  // API units have no DOM → no selectors; the catalog (apis.yaml) is the contract. N/A, not missing.
+  const selectorsOk = target.kind === 'api' ? true : checkSelectorsHasEntries(selectorsFile, target.featureBaseName);
   const specOk = fs.existsSync(specFile);
   const resultsOk = resultsFile !== null;
 
@@ -284,7 +293,7 @@ function runPreflight(cwd: string, target: DeliveryTarget): PreflightCheck {
   }
   if (!specOk) {
     missing.push(`compiled .spec.ts missing: ${path.relative(cwd, specFile)}`);
-    suggestions.push(target.isFlow ? `sungen generate --flow ${target.screen}` : `sungen generate --screen ${target.screen}`);
+    suggestions.push(`sungen generate --${target.kind === 'flow' ? 'flow' : target.kind === 'api' ? 'api' : 'screen'} ${target.screen}`);
   }
   if (!resultsOk) {
     const env = process.env.SUNGEN_ENV;

package/src/cli/commands/generate.ts

@@ -4,7 +4,8 @@ import * as fs from 'fs';
 import { CodeGenerator } from '../../generators/test-generator/code-generator';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 import { scanTestDataSecrets } from '../../harness/secret-scan';
-import { lintDataDriven } from '../../harness/data-driven-lint';
+import { capabilityRegistry } from '../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 import { readCapabilities, writeCapabilities, driverMeta, loadDriverCatalog } from '../../harness/capability';
 
 /**
@@ -43,12 +44,21 @@ function findFeatureFilesForFlow(flowName: string): string[] {
 }
 
 /**
- * Find all feature files across all screens and flows
+ * Find feature files for a specific API-first unit — an area (`orders`) or an api flow
+ * (`flows/<flow>`). Catalog/test-data live alongside under qa/api/<name>/.
+ */
+function findFeatureFilesForApi(name: string): string[] {
+  return findFeatureFiles(path.join(process.cwd(), 'qa', 'api', name, 'features'));
+}
+
+/**
+ * Find all feature files across all screens, flows, and API-first areas/flows.
  */
 function findAllFeatureFiles(): string[] {
   const allFiles: string[] = [];
   const screensDir = path.join(process.cwd(), 'qa', 'screens');
   const flowsDir = path.join(process.cwd(), 'qa', 'flows');
+  const apiDir = path.join(process.cwd(), 'qa', 'api');
 
   if (fs.existsSync(screensDir)) {
     const screenDirs = fs.readdirSync(screensDir, { withFileTypes: true })
@@ -72,6 +82,9 @@ function findAllFeatureFiles(): string[] {
     }
   }
 
+  // API-first: every .feature under qa/api/** (areas qa/api/<area>/features + flows qa/api/flows/<flow>/features).
+  if (fs.existsSync(apiDir)) allFiles.push(...findFeatureFiles(apiDir));
+
   return allFiles;
 }
 
@@ -81,19 +94,32 @@ export function registerGenerateCommand(program: Command): void {
     .description('Generate Playwright test code from Gherkin features')
     .option('-s, --screen <name>', 'Generate tests for a specific screen')
     .option('--flow <name>', 'Generate tests for a specific flow')
-    .option('--all', 'Generate tests for all screens and flows')
+    .option('--api <name>', 'Generate tests for an API-first area or api flow (e.g. orders, flows/signup)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
+    .option('--all', 'Generate tests for all screens, flows, and API areas')
     .option('--framework <name>', 'Override the platform driver (else read from qa/capabilities.yaml)')
     .option('--inline-data', 'Hardcode test data at compile time instead of runtime loading')
     .action(async (options) => {
       try {
         const screenName = options.screen;
         const flowName = options.flow;
+        const apiName = options.api || options.area;
 
         // Find feature files
         let featureFiles: string[];
         let qaSourceDir: string;
 
-        if (screenName) {
+        if (apiName) {
+          featureFiles = findFeatureFilesForApi(apiName);
+          if (featureFiles.length === 0) {
+            throw new Error(
+              `No feature files found for API unit: ${apiName}\n` +
+              `Looked in: qa/api/${apiName}/features/  (scaffold with \`sungen api add --area ${apiName}\` or \`--flow\`)`
+            );
+          }
+          qaSourceDir = path.join(process.cwd(), 'qa', 'api');
+          console.log(`\nGenerating tests: api/${apiName}\n`);
+        } else if (screenName) {
           featureFiles = findFeatureFilesForScreen(screenName);
           if (featureFiles.length === 0) {
             throw new Error(
@@ -116,10 +142,10 @@ export function registerGenerateCommand(program: Command): void {
         } else {
           featureFiles = findAllFeatureFiles();
           if (featureFiles.length === 0) {
-            throw new Error('No feature files found in qa/screens/ or qa/flows/');
+            throw new Error('No feature files found in qa/screens/, qa/flows/, or qa/api/');
           }
           qaSourceDir = path.join(process.cwd(), 'qa');
-          console.log(`\nGenerating tests for all screens and flows\n`);
+          console.log(`\nGenerating tests for all screens, flows, and API areas\n`);
         }
 
         // Output directory
@@ -183,8 +209,11 @@ export function registerGenerateCommand(program: Command): void {
           console.log(`   Move real secrets to an env overlay / CI secret; keep test-data placeholders only.`);
         }
 
-        // Data-driven lint (@cases / @query) — advisory, never blocks generation.
-        const ddWarnings = scanDirs.flatMap((d) => lintDataDriven(d, cwd));
+        // Advisory harness sensors (e.g. @cases/@query lint) — run via the Capability SPI,
+        // never block generation. Each capability registers its own; the kernel just runs them.
+        discoverAndRegisterCapabilities();
+        const advisorySensors = capabilityRegistry.sensors('advisory');
+        const ddWarnings = scanDirs.flatMap((d) => advisorySensors.flatMap((s) => s.run({ dir: d, cwd })));
         if (ddWarnings.length) {
           console.log(`\n⚠️  Data-driven lint (@cases / @query) — review:`);
           for (const w of ddWarnings.slice(0, 20)) console.log(`   ${w.scenario ? w.scenario + ': ' : ''}${w.message}`);

package/src/cli/commands/ledger.ts

@@ -9,7 +9,9 @@ export function registerLedgerCommand(program: Command): void {
   ledger
     .command('record')
     .description('Append a step event to the ledger')
-    .requiredOption('-s, --screen <name>', 'Screen or flow name')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .requiredOption('--step <name>', 'Step name (discovery | viewpoint | gherkin | audit | repair:1 ...)')
     .option('--run <id>', 'Run id — groups all phases of one create-test invocation (else auto-segmented by time gap)')
     .option('--model <id>', 'Model id')
@@ -19,10 +21,12 @@ export function registerLedgerCommand(program: Command): void {
     .option('--note <text>', 'Free note')
     .action((o) => {
       try {
-        recordEvent(o.screen, {
+        const name = o.screen || o.api || o.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        recordEvent(name, {
           step: o.step, runId: o.run, model: o.model, tokensIn: o.tokensIn, tokensOut: o.tokensOut, ms: o.ms, note: o.note,
         });
-        console.log(`✓ ledger: ${o.screen} · ${o.step}`);
+        console.log(`✓ ledger: ${name} · ${o.step}`);
       } catch (e) {
         console.error('Error:', e instanceof Error ? e.message : e);
         process.exit(1);
@@ -32,12 +36,16 @@ export function registerLedgerCommand(program: Command): void {
   ledger
     .command('report')
     .description('Summarise ledger + efficiency verdicts (pulls audit score if present)')
-    .requiredOption('-s, --screen <name>', 'Screen or flow name')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--all-runs', 'Aggregate ALL runs (default: latest run only)')
     .option('--json', 'Output raw JSON')
     .action((o) => {
       try {
-        const r = buildReport(o.screen, { allRuns: o.allRuns });
+        const name = o.screen || o.api || o.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const r = buildReport(name, { allRuns: o.allRuns });
         if (o.json) { console.log(JSON.stringify(r, null, 2)); return; }
         const scope = r.runScope === 'all' ? `all ${r.runs} runs` : `latest run${r.runs > 1 ? ` of ${r.runs}` : ''}`;
         console.log(`\n━━━ Usage Ledger: ${r.screen} (${r.events} events · ${scope}) ━━━`);

package/src/cli/commands/manifest.ts

@@ -4,10 +4,10 @@ import * as fs from 'fs';
 import { buildManifest, diffManifest, loadManifest, saveManifest } from '../../harness/manifest';
 
 function findScreenDir(name: string): string | null {
-  const screen = path.join(process.cwd(), 'qa', 'screens', name);
-  if (fs.existsSync(screen)) return screen;
-  const flow = path.join(process.cwd(), 'qa', 'flows', name);
-  if (fs.existsSync(flow)) return flow;
+  for (const p of ['screens', 'flows', 'api']) {
+    const d = path.join(process.cwd(), 'qa', p, name);
+    if (fs.existsSync(d)) return d;
+  }
   return null;
 }
 
@@ -16,14 +16,16 @@ export function registerManifestCommand(program: Command): void {
     .command('manifest')
     .description('Spec-fingerprint manifest: build a scenario↔spec-section map, or diff to plan keep/regenerate/retire')
     .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--diff', 'Compare current spec vs stored manifest → change plan')
     .option('--json', 'Output raw JSON')
     .action((options) => {
       try {
-        const name = options.screen;
-        if (!name) throw new Error('Provide --screen <name>');
+        const name = options.screen || options.api || options.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
         const dir = findScreenDir(name);
-        if (!dir) throw new Error(`Screen/flow not found: ${name}`);
+        if (!dir) throw new Error(`Not found: qa/screens|flows|api/${name}`);
 
         if (options.diff) {
           const manifest = loadManifest(name);

package/src/cli/commands/repair.ts

@@ -0,0 +1,57 @@
+import { Command } from 'commander';
+import * as fs from 'fs';
+import * as path from 'path';
+import { planRepair } from '../../harness/repair';
+
+/**
+ * `sungen repair` (#343) — turn a unit's audit findings + Playwright failures into a concrete fix
+ * plan, using the unit-capability's fix catalog (the `repair` SPI). Deterministic; the `/sungen:design`
+ * + `/sungen:run-test` repair loops apply the same proposals. Run `sungen audit`/the tests first.
+ */
+export function registerRepairCommand(program: Command): void {
+  program
+    .command('repair')
+    .description('Propose concrete fixes for a unit from its audit findings + test failures (capability fix catalog)')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
+    .option('--json', 'Output raw JSON')
+    .action((o: { screen?: string; api?: string; area?: string; json?: boolean }) => {
+      try {
+        const name = o.screen || o.api || o.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const cwd = process.cwd();
+        // Capability-resolution id + the generated dir, per kind.
+        const kind = fs.existsSync(path.join(cwd, 'qa', 'api', name)) || o.api ? 'api'
+          : fs.existsSync(path.join(cwd, 'qa', 'flows', name)) ? 'flow' : 'screen';
+        const unitId = kind === 'api' ? `api/${name}` : kind === 'flow' ? `flows/${name}` : name;
+        const generatedDir = path.join(cwd, 'specs', 'generated', kind === 'api' ? path.join('api', name) : kind === 'flow' ? path.join('flows', name) : name);
+
+        const plan = planRepair(unitId, name, cwd, generatedDir);
+        if (o.json) { console.log(JSON.stringify(plan, null, 2)); return; }
+
+        const L = console.log;
+        L(`\n━━━ Repair plan: ${name} (capability: ${plan.capability ?? 'none'}) ━━━`);
+        if (!plan.rulesAvailable) L(`  (this capability ships no repair rules)`);
+        if (!plan.proposals.length && !plan.unmatched.length) {
+          L(`  ✓ Nothing to repair — run \`sungen audit --${kind === 'api' ? 'api' : 'screen'} ${name}\` + the tests first, or the unit is clean.\n`);
+          return;
+        }
+        if (plan.proposals.length) {
+          L(`\n  Proposed fixes (${plan.proposals.length}):`);
+          for (const p of plan.proposals) {
+            L(`    • [${p.ruleId}] ${p.source === 'runtime' ? '(test) ' : ''}${p.signal}`);
+            L(`        → ${p.fix}`);
+          }
+        }
+        if (plan.unmatched.length) {
+          L(`\n  No known rule (review manually):`);
+          for (const u of plan.unmatched.slice(0, 10)) L(`    - ${u}`);
+        }
+        L('');
+      } catch (e) {
+        console.error('Error:', e instanceof Error ? e.message : e);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/script-check.ts

@@ -2,28 +2,32 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { runScriptCheck } from '../../harness/script-check';
+import { reportSlug } from '../../harness/unit-paths';
 
 export function registerScriptCheckCommand(program: Command): void {
   program
     .command('script-check')
     .description('Verify the generated Playwright spec is a faithful 1:1 of the Gherkin feature (no hand-edit / stale drift)')
     .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--json', 'Output raw JSON')
     .action(async (options) => {
       try {
-        const name = options.screen;
-        if (!name) throw new Error('Provide --screen <name>');
+        const name = options.screen || options.api || options.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
         const screen = path.join(process.cwd(), 'qa', 'screens', name);
         const flow = path.join(process.cwd(), 'qa', 'flows', name);
-        const flowMode = !fs.existsSync(screen) && fs.existsSync(flow);
-        const dir = fs.existsSync(screen) ? screen : (fs.existsSync(flow) ? flow : null);
-        if (!dir) throw new Error(`Screen/flow not found: ${name}`);
+        const api = path.join(process.cwd(), 'qa', 'api', name);
+        const kind = fs.existsSync(screen) ? 'screen' : fs.existsSync(flow) ? 'flow' : fs.existsSync(api) ? 'api' : null;
+        const dir = kind === 'screen' ? screen : kind === 'flow' ? flow : kind === 'api' ? api : null;
+        if (!dir || !kind) throw new Error(`Not found: qa/screens|flows|api/${name}`);
 
-        const r = await runScriptCheck(dir, name, flowMode);
+        const r = await runScriptCheck(dir, name, kind);
 
         const outDir = path.join(process.cwd(), '.sungen', 'reports');
         fs.mkdirSync(outDir, { recursive: true });
-        fs.writeFileSync(path.join(outDir, `${name}-script-check.json`), JSON.stringify(r, null, 2), 'utf-8');
+        fs.writeFileSync(path.join(outDir, `${reportSlug(name)}-script-check.json`), JSON.stringify(r, null, 2), 'utf-8');
 
         if (options.json) { console.log(JSON.stringify(r, null, 2)); process.exit(r.status === 'OK' ? 0 : 2); }
 
@@ -39,7 +43,7 @@ export function registerScriptCheckCommand(program: Command): void {
         if (r.findings.length) { L('  findings:'); for (const f of r.findings) L(`    • ${f}`); }
         else L('  ✓ The test code faithfully reflects the Gherkin (1:1).');
         L('');
-        if (r.drift === 'drift') L('  → Fix: re-run `sungen generate --screen ' + name + '` (or /sungen:run-test) so the spec matches the feature. Never hand-edit generated specs.');
+        if (r.drift === 'drift') L(`  → Fix: re-run \`sungen generate --${kind === 'api' ? 'api' : kind === 'flow' ? 'flow' : 'screen'} ${name}\` (or /sungen:run-test) so the spec matches the feature. Never hand-edit generated specs.`);
         L('');
         process.exit(r.status === 'OK' ? 0 : 2);
       } catch (error) {

package/src/cli/commands/trace.ts

@@ -8,16 +8,19 @@ export function registerTraceCommand(program: Command): void {
     .command('trace')
     .description('Visualise the executed test-design process (workflow/skill steps, repair loops), find bottlenecks, and show where to focus human review')
     .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--json', 'Output raw JSON')
     .option('--mermaid', 'Print only the Mermaid flowchart')
     .action((options) => {
       try {
-        const name = options.screen;
-        if (!name) throw new Error('Provide --screen <name>');
+        const name = options.screen || options.api || options.area;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
         const screen = path.join(process.cwd(), 'qa', 'screens', name);
         const flow = path.join(process.cwd(), 'qa', 'flows', name);
-        const dir = fs.existsSync(screen) ? screen : (fs.existsSync(flow) ? flow : null);
-        if (!dir) throw new Error(`Screen/flow not found: ${name}`);
+        const api = path.join(process.cwd(), 'qa', 'api', name);
+        const dir = fs.existsSync(screen) ? screen : fs.existsSync(flow) ? flow : fs.existsSync(api) ? api : null;
+        if (!dir) throw new Error(`Not found: qa/screens|flows|api/${name}`);
 
         const r = buildTrace(dir, name);
         if (options.json) { console.log(JSON.stringify(r, null, 2)); return; }

package/src/cli/index.ts

@@ -26,6 +26,10 @@ import { registerChallengeCommand } from './commands/challenge';
 import { registerBlindspotCommand } from './commands/blindspot';
 import { registerCapabilityCommand } from './commands/capability';
 import { registerFlowCheckCommand } from './commands/flow-check';
+import { registerContextCommand } from './commands/context';
+import { registerRepairCommand } from './commands/repair';
+import { capabilityRegistry } from '../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 
 // Read version from package.json so `--version` never drifts from the released version.
 const { version } = require('../../package.json') as { version: string };
@@ -42,7 +46,7 @@ async function main() {
   program
     .option('-v, --verbose', 'Enable verbose logging');
 
-  // Register commands (9)
+  // Register commands
   registerInitCommand(program);
   registerAddCommand(program);
   registerGenerateCommand(program);
@@ -62,9 +66,18 @@ async function main() {
   registerBlindspotCommand(program);
   registerCapabilityCommand(program);
   registerFlowCheckCommand(program);
+  registerContextCommand(program);
+  registerRepairCommand(program);
   registerIngestCommand(program);
   registerEvalCommand(program);
 
+  // Capability-contributed CLI commands (Capability SPI): drivers own their authoring commands
+  // (e.g. @sungen/driver-api → `sungen api import`). Discover, then register each.
+  discoverAndRegisterCapabilities();
+  for (const cap of capabilityRegistry.all()) {
+    for (const registerCommand of cap.cliCommands ?? []) registerCommand(program);
+  }
+
   await program.parseAsync(process.argv);
 }
 

package/src/generators/test-generator/adapters/adapter-interface.ts

@@ -64,7 +64,7 @@ export interface TestGeneratorAdapter {
   // Template rendering methods
   renderTestFile(data: TestFileData): string;
   renderScenario(data: ScenarioData): string;
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string;
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string;
   renderBeforeEach(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderBeforeAll(data: { steps: Array<{ comment?: string; code: string }> }): string;
   renderAfterEach(data: { steps: Array<{ comment?: string; code: string }> }): string;

package/src/generators/test-generator/adapters/playwright/playwright-adapter.ts

@@ -26,7 +26,7 @@ export class PlaywrightAdapter implements TestGeneratorAdapter {
     return this.templateEngine.renderScenario(data);
   }
 
-  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean }): string {
+  renderImports(options?: { runtimeData?: boolean; basePath?: string; isParallel?: boolean; needsCleanupImport?: boolean ; needsDb?: boolean; needsApi?: boolean }): string {
     return this.templateEngine.renderImports(options);
   }
 

package/src/generators/test-generator/adapters/playwright/templates/imports.hbs

@@ -6,6 +6,9 @@ import { TestDataLoader } from '{{basePath}}/test-data';
 {{#if needsDb}}
 import { db } from '{{basePath}}/db';
 {{/if}}
+{{#if needsApi}}
+import { api } from '{{basePath}}/api';
+{{/if}}
 
 // This file is auto-generated from Gherkin feature files
 // DO NOT EDIT MANUALLY - changes will be overwritten