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

package/src/capabilities/discover.ts

@@ -13,6 +13,8 @@
  * A driver that isn't installed is simply skipped (capabilities are opt-in). Errors thrown *inside* a
  * present driver propagate — only a genuinely absent package is swallowed (resolve-then-require).
  */
+import { createRequire } from 'module';
+import * as path from 'path';
 import { capabilityRegistry } from './registry';
 import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
 
@@ -24,14 +26,32 @@ import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
 const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api'];
 
 function loadExternalDriver(name: string): void {
-  try {
-    require.resolve(name);
-  } catch {
-    return; // not installed — capabilities are opt-in, so skip silently
+  // Resolve from the user's PROJECT first, then from core's own location. Opt-in drivers
+  // (`sungen capability add db|api`) install into the PROJECT's node_modules — a globally-installed
+  // core (`npm i -g`) wouldn't see them via a core-anchored `require`. The bundled @sungen/driver-ui
+  // is a core dependency (co-located with core), so the second anchor finds it.
+  for (const anchor of [path.join(process.cwd(), 'package.json'), __filename]) {
+    let req: NodeRequire;
+    try { req = createRequire(anchor); } catch { continue; }
+    let resolved: string;
+    try { resolved = req.resolve(name); } catch { continue; } // not installed at this anchor → try next
+    try {
+      const mod = req(resolved);
+      const register: ((r: typeof capabilityRegistry) => void) | undefined = mod?.sungenDriver?.register ?? mod?.register;
+      if (typeof register === 'function') register(capabilityRegistry);
+    } catch (e) {
+      // A present-but-BROKEN driver (e.g. a stale/incompatible leftover whose own core dep doesn't
+      // resolve) must never crash the whole CLI — `sungen --version`, `capability remove`, etc. must
+      // still work. Warn + skip so the user can recover.
+      console.warn(
+        `⚠ sungen: capability driver "${name}" is installed but failed to load — skipping.\n` +
+        `  ${(e as Error)?.message || e}\n` +
+        `  Fix: reinstall it (\`sungen capability add ${name.replace(/^@sungen\/driver-/, '')}\`) or remove it.`,
+      );
+    }
+    return; // found at this anchor (loaded or warned) — don't fall through to other anchors
   }
-  const mod = require(name); // present: let any error thrown inside the driver propagate (don't mask)
-  const register: ((r: typeof capabilityRegistry) => void) | undefined = mod?.sungenDriver?.register ?? mod?.register;
-  if (typeof register === 'function') register(capabilityRegistry);
+  // not installed at any anchor — capabilities are opt-in, so skip silently
 }
 
 export function discoverAndRegisterCapabilities(): void {

package/src/capabilities/registry.ts

@@ -13,7 +13,7 @@
  */
 import type { StepPattern } from '../generators/test-generator/patterns/types';
 import type { Sensor } from './sensor';
-import type { DiscoveryProvider, ContextMapper } from './context';
+import type { DiscoveryProvider, ContextMapper, RepairProvider } from './context';
 
 export interface CapabilityDescriptor {
   /** Stable id: 'ui' | 'db' | 'api' | 'core' | … */
@@ -29,6 +29,8 @@ export interface CapabilityDescriptor {
   /** Orchestration phase hooks — declared in R1, consumed by the pipeline from R2 onward. */
   discovery?: DiscoveryProvider;     // sources → Context slice
   contextMapper?: ContextMapper;     // Context → generation units + modes
+  /** Repair phase: the capability's deterministic fix catalog (audit/runtime finding → fix). */
+  repair?: RepairProvider;
   /** Provider for this capability's viewpoint catalog (UI: the 17-pattern universal catalog). */
   viewpoints?: () => unknown;
   /**

package/src/capabilities/sensor.ts

@@ -41,7 +41,7 @@ export interface GateInput {
   screenName: string;
   cwd: string;
   featureText: string;
-  scenarios: Array<{ name: string; queryRefs?: string[]; apiRefs?: string[] }>;
+  scenarios: Array<{ name: string; queryRefs?: string[]; apiRefs?: string[]; casesDataset?: string; stepsText?: string; manual?: boolean }>;
   /** UI: universal-viewpoint theme gaps the coverage gate found (generic string list). */
   universalGaps?: string[];
 }

package/src/cli/commands/audit.ts

@@ -2,12 +2,16 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { runAudit, AuditReport } from '../../harness/audit';
+import { reportSlug } from '../../harness/unit-paths';
 
 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;
+  // `name` may be a bare screen/flow/area, or an api unit id (`api/<area>`, `api/flows/<flow>`).
+  const candidates = [
+    path.join(process.cwd(), 'qa', 'screens', name),
+    path.join(process.cwd(), 'qa', 'flows', name),
+    path.join(process.cwd(), 'qa', 'api', name),         // qa/api/<area> or qa/api/flows/<flow>
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
   return null;
 }
 
@@ -88,20 +92,22 @@ export function registerAuditCommand(program: Command): void {
     .command('audit')
     .description('Harness: measure test-design quality (viewpoint gate, depth, balance, duplicates, traceability)')
     .option('-s, --screen <name>', 'Screen or flow name to audit')
+    .option('--api <name>', 'API-first area or api flow to audit (e.g. orders, flows/signup)')
+    .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--json', 'Output the raw JSON report')
     .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: qa/screens/${name} or qa/flows/${name}`);
+        if (!dir) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
         const report = runAudit(dir, name);
 
-        // Persist report under .sungen/reports/
+        // Persist report under .sungen/reports/ (flat slug: api flow `flows/x` → `flows-x-audit.json`).
         const outDir = path.join(process.cwd(), '.sungen', 'reports');
         fs.mkdirSync(outDir, { recursive: true });
-        const outPath = path.join(outDir, `${name}-audit.json`);
+        const outPath = path.join(outDir, `${reportSlug(name)}-audit.json`);
         fs.writeFileSync(outPath, JSON.stringify(report, null, 2), 'utf-8');
 
         if (options.json) {

package/src/cli/commands/capability.ts

@@ -1,5 +1,6 @@
 import { Command } from 'commander';
 import { spawnSync } from 'child_process';
+import { createRequire } from 'module';
 import * as fs from 'fs';
 import * as path from 'path';
 import {
@@ -8,6 +9,42 @@ import {
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
 
+/** The running CLI's (core) version — opt-in drivers install in lockstep with it (not `@latest`). */
+function coreVersion(): string {
+  try { return require('../../../package.json').version || 'latest'; } catch { return 'latest'; }
+}
+
+/**
+ * Verify a capability driver (db/api/…) installed into the PROJECT exposes the capability SPI entry
+ * (`sungenDriver.register`). Resolved from the project's node_modules so it works with a globally
+ * installed core. Capability drivers are NOT codegen adapters — don't route them through loadDriver.
+ */
+function verifyCapabilityDriver(pkg: string, cwd: string): void {
+  const req = createRequire(path.join(cwd, 'package.json'));
+  // 1) Installed? (resolve only — distinguishes "not installed" from "installed but broken")
+  try {
+    req.resolve(pkg);
+  } catch {
+    throw new Error(`${pkg} is not installed in this project — run \`npm install -D ${pkg}\` here (a package.json must exist in this directory).`);
+  }
+  // 2) Loadable? Surface the REAL error — a failure here is almost always a stale/wrong
+  //    @sun-asterisk/sungen on the module path (e.g. leftover node_modules), NOT a missing driver.
+  let mod: any;
+  try {
+    mod = req(pkg);
+  } catch (e: any) {
+    throw new Error(
+      `${pkg} is installed but failed to load:\n  ${e?.message || e}\n` +
+      '  This usually means a stale @sun-asterisk/sungen is on the module path. Run in a clean,\n' +
+      '  dedicated project directory and remove stray installs (e.g. rm -rf ~/node_modules).',
+    );
+  }
+  const register = mod?.sungenDriver?.register ?? mod?.register;
+  if (typeof register !== 'function') {
+    throw new Error(`${pkg} is installed but is not a sungen capability driver (missing sungenDriver.register).`);
+  }
+}
+
 function findScreenDir(name: string): string | null {
   const s = path.join(process.cwd(), 'qa', 'screens', name);
   if (fs.existsSync(s)) return s;
@@ -111,16 +148,27 @@ export function registerCapabilityCommand(program: Command): void {
         const bundled = adapterRegistry.hasAdapter(adapterName); // e.g. `web` is bundled in Phase 2a
 
         if (!bundled && !o.skipInstall) {
-          console.log(`📦 Installing ${meta.package} (dev dependency)...`);
-          const r = spawnSync('npm', ['install', '-D', meta.package], { stdio: 'inherit', shell: true });
-          if (r.status !== 0) throw new Error(`npm install -D ${meta.package} failed.`);
+          // Pin the driver to the RUNNING core's exact version (lockstep). Without this, plain
+          // `npm install @sungen/driver-x` resolves the package's `latest` dist-tag — which on a
+          // beta channel can lag (e.g. a prerelease first-published-as-latest), pulling a driver
+          // whose core dep resolves to the wrong @sun-asterisk/sungen and fails to load.
+          const spec = `${meta.package}@${coreVersion()}`;
+          console.log(`📦 Installing ${spec} (dev dependency)...`);
+          const r = spawnSync('npm', ['install', '-D', spec], { stdio: 'inherit', shell: true });
+          if (r.status !== 0) throw new Error(`npm install -D ${spec} failed.`);
         } else if (bundled) {
           console.log(`✓ ${driver} is built-in (no install needed).`);
         }
 
-        // Verify it can load (skip for bundled — already registered).
+        // Verify it loaded (skip for bundled — already registered). Two driver shapes:
+        //  - platform driver (web/mobile): a codegen adapter, loaded via the adapter registry (mod.activate)
+        //  - capability driver (db/api/…): a capability-SPI package (mod.sungenDriver.register) — NOT an adapter
         if (!bundled) {
-          adapterRegistry.loadDriver(adapterName, meta.package, cwd); // throws if not loadable
+          if (meta.kind === 'platform') {
+            adapterRegistry.loadDriver(adapterName, meta.package, cwd); // throws if not loadable
+          } else {
+            verifyCapabilityDriver(meta.package, cwd); // capability SPI entry, resolved from the project
+          }
         }
 
         const profile = readCapabilities(cwd);

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

@@ -44,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 })
@@ -73,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;
 }
 
@@ -82,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(
@@ -117,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

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);
+      }
+    });
+}