@sun-asterisk/sungen 3.1.2-beta.118 → 3.1.2-beta.120

package/dist/orchestrator/templates/ai-instructions/claude-skill-api-design.md

@@ -0,0 +1,49 @@
+---
+name: sungen-api-design
+description: The API-first design loop for an api unit (qa/api/<area> or qa/api/flows/<flow>) — discover the catalog, lay out the API viewpoints, generate @api/@cases/flow/@concurrent scenarios, then drive the sungen audit --api gate + reviewer + repair to a high businessDepth (≥0.7). Use when create-test/run-test detects an api unit (no selectors, no visual capture).
+---
+
+# API design loop (driver-api · Orchestration + Harness)
+
+Use this when the unit is **api-first** — `qa/api/<area>/` or `qa/api/flows/<flow>/`. There are **no selectors and no visual capture**: the contract is the **named-endpoint catalog** (`api/apis.yaml`), referenced by `@api:<name>`. QA writes **no HTTP code**. Full annotation reference: the **API Steps** guide (`@api` / `@cases` / flows / `@concurrent` / `@hybrid`).
+
+## The loop (mirror of /sungen:design, API-native)
+
+### 1. Discover (no capture)
+Run `sungen context --api <name>` — it reads the catalog and prints the **endpoints** + the **generation units** (one `matrix` unit per endpoint, an `async` unit per mutating endpoint, a `flow` unit for an api flow). Read `qa/api/<name>/requirements/spec.md` if present. No `apis.yaml` yet? → `sungen api import <openapi|csv>` or `sungen api add --area <name>` first.
+
+### 2. API viewpoint overview (by method-profile)
+For each endpoint, cover its viewpoints — severity-weighted by method:
+
+| Profile | Endpoints | Must cover | Then |
+|---|---|---|---|
+| read | GET, HEAD | `contract` (status + body shape) | `pagination`/`filter` (list), `not-found` (by-id) |
+| mutating | POST/PUT/PATCH/DELETE | `contract`, `error` (validation/4xx/auth) | `idempotency` (`@concurrent`), `side-effect` (`@query`) |
+
+Bands: **~70%** success+failure matrix · **~20%** flows (auth/CRUD chains) · **~10%** async/idempotency.
+
+### 3. Generate (incremental — never the whole suite in one Write)
+- **Contract**: `@api:<name>` + `expect {{name.status}} is …` **and a body assertion** (`{{name.body.<path>}}`).
+- **Error matrix**: `@api:<name>(p={{p}}) @cases:<dataset>` — one scenario, a dataset of `input → expected status`.
+- **Flow**: ordered `@api` tags threading a prior response (`token={{login.body.token}}` → the catalog `Bearer :token` header; `id={{create.body.id}}` → a path param). Self-clean (delete what you create).
+- **Idempotency**: `@api:<name> @concurrent:N` + `expect {{name.ok_count}} is 1`, cross-checked with `@query` (the DB is the oracle).
+
+### 4. Gate + repair (always — businessDepth ≥ 0.7 is the bar)
+Run `sungen audit --api <name>`; read `gateStatus` + `findings`. Then the **semantic reviewer** (sungen-reviewer sub-agent, API criteria). Repair **both** (budget 3 rounds), re-audit until PASS:
+
+| Finding | Repair |
+|---|---|
+| `VIEWPOINT-API-CONTRACT` | the endpoint is invoked but its response is never asserted → add `expect {{name.status}}` + a `{{name.body.…}}` check |
+| `VIEWPOINT-API-ERROR` | a mutating endpoint has no failure scenario → add a `@cases` error matrix (or an explicit 4xx) |
+| `VIEWPOINT-API-IDEMPOTENCY` | a mutating endpoint has no race check → add `@concurrent:N` + a `@query` DB cross-check |
+| **`DEPTH-FAIL`** (businessDepth < 0.7) | a **mutating success** scenario asserts only `status` → make it **prove the effect**: assert a response **body** field, a **`@query`** side-effect, or a **`@concurrent` `ok_count`** invariant. (An error/`@cases` scenario proving the status is correct — it is *not* depth-required.) |
+
+Stop when the gate PASSes + businessDepth ≥ 0.7, or the budget is exhausted → report residual gaps honestly (mark genuinely-unautomatable cases `@manual` with an oracle). Never fake a pass.
+
+### 5. Record + converge
+`sungen manifest --api <name>` (reuse) and ledger each phase; show the trace + the HUMAN-LOOP FOCUS. (Integrity `script-check`/`trace` for api: see run-test.)
+
+## Rules
+- **No HTTP, no selectors** — only `.feature` + the reviewed `apis.yaml` + `test-data`.
+- **Non-prod default** — a `production` datasource is refused unless `SUNGEN_ALLOW_PROD=1`.
+- **The DB is the oracle** for idempotency/side-effects — HTTP status alone can lie; pair `@api` with `@query`.

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-create-test.md

@@ -18,7 +18,11 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
 
 - **name** — ${input:name:screen or flow name (e.g., login, award-submission)}
 
-**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+**Auto-detect context**: check if `qa/api/<name>/` or `qa/api/flows/<name>/` exists → **API unit mode** (below). Else if `qa/flows/<name>/` → flow mode (base path: `qa/flows/<name>/`). Else `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+
+## API unit mode (driver-api)
+
+If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the design loop differs — **no visual capture, no selectors**; the contract is the named-endpoint catalog. **Follow the `sungen-api-design` skill end-to-end** instead of the screen/flow steps: `sungen context --api <name>` (discover) → API viewpoint overview → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios → **`sungen audit --api <name>` gate + reviewer + repair loop to businessDepth ≥ 0.7** → record + trace. Then recommend `/sungen-run-test <name>`. The capture / viewpoint-group / selector steps do **not** apply.
 
 ## Steps
 

package/dist/orchestrator/templates/ai-instructions/copilot-cmd-run-test.md

@@ -30,7 +30,16 @@ Count 0 → offer the user:
 
 Skip when `--env` matches the base locale.
 
-**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+**Auto-detect context**: check if `qa/api/<name>/` or `qa/api/flows/<name>/` exists → **API unit mode** (below). Else if `qa/flows/<name>/` → flow mode (base path: `qa/flows/<name>/`). Else `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+
+## API unit mode (driver-api) — no selectors
+
+If the unit is **api-first**, skip every selector/capture phase (an API test has no DOM):
+1. **Resolve the datasource** — `base_url` + auth wired in `qa/datasources.yaml` + `.env.qa` (`${X_URL}` from `sungen api init`); a `production` datasource is refused unless `SUNGEN_ALLOW_PROD=1`.
+2. **Compile**: `npx sungen generate --api <name>` → `specs/generated/api/<name>/`.
+3. **Run**: `npx playwright test specs/generated/api/<name>/<name>.spec.ts`.
+4. **Auto-fix** (use `sungen-error-mapping`): 401/403 → `@hybrid`+`@auth` or `Bearer :token` header (`sungen makeauth`); base_url unresolved → set `${X_URL}`; missing param → trace `{{var}}` to test-data/a prior `@api` response; `expect.status` mismatch → reconcile against `apis.yaml` (re-`generate --api`, never hand-edit the spec); flaky → self-clean + `@concurrent` caps.
+5. **Integrity + trace** — `sungen script-check --api <name>` (1:1; on DRIFT re-`generate --api`, never hand-edit the spec) + `sungen trace --api <name>` (process map + HUMAN-LOOP FOCUS). Report + offer next steps.
 
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 

package/dist/orchestrator/templates/ai-instructions/github-skill-sungen-api-design.md

@@ -0,0 +1,49 @@
+---
+name: sungen-api-design
+description: The API-first design loop for an api unit (qa/api/<area> or qa/api/flows/<flow>) — discover the catalog, lay out the API viewpoints, generate @api/@cases/flow/@concurrent scenarios, then drive the sungen audit --api gate + reviewer + repair to a high businessDepth (≥0.7). Use when create-test/run-test detects an api unit (no selectors, no visual capture).
+---
+
+# API design loop (driver-api · Orchestration + Harness)
+
+Use this when the unit is **api-first** — `qa/api/<area>/` or `qa/api/flows/<flow>/`. There are **no selectors and no visual capture**: the contract is the **named-endpoint catalog** (`api/apis.yaml`), referenced by `@api:<name>`. QA writes **no HTTP code**. Full annotation reference: the **API Steps** guide (`@api` / `@cases` / flows / `@concurrent` / `@hybrid`).
+
+## The loop (mirror of /sungen:design, API-native)
+
+### 1. Discover (no capture)
+Run `sungen context --api <name>` — it reads the catalog and prints the **endpoints** + the **generation units** (one `matrix` unit per endpoint, an `async` unit per mutating endpoint, a `flow` unit for an api flow). Read `qa/api/<name>/requirements/spec.md` if present. No `apis.yaml` yet? → `sungen api import <openapi|csv>` or `sungen api add --area <name>` first.
+
+### 2. API viewpoint overview (by method-profile)
+For each endpoint, cover its viewpoints — severity-weighted by method:
+
+| Profile | Endpoints | Must cover | Then |
+|---|---|---|---|
+| read | GET, HEAD | `contract` (status + body shape) | `pagination`/`filter` (list), `not-found` (by-id) |
+| mutating | POST/PUT/PATCH/DELETE | `contract`, `error` (validation/4xx/auth) | `idempotency` (`@concurrent`), `side-effect` (`@query`) |
+
+Bands: **~70%** success+failure matrix · **~20%** flows (auth/CRUD chains) · **~10%** async/idempotency.
+
+### 3. Generate (incremental — never the whole suite in one Write)
+- **Contract**: `@api:<name>` + `expect {{name.status}} is …` **and a body assertion** (`{{name.body.<path>}}`).
+- **Error matrix**: `@api:<name>(p={{p}}) @cases:<dataset>` — one scenario, a dataset of `input → expected status`.
+- **Flow**: ordered `@api` tags threading a prior response (`token={{login.body.token}}` → the catalog `Bearer :token` header; `id={{create.body.id}}` → a path param). Self-clean (delete what you create).
+- **Idempotency**: `@api:<name> @concurrent:N` + `expect {{name.ok_count}} is 1`, cross-checked with `@query` (the DB is the oracle).
+
+### 4. Gate + repair (always — businessDepth ≥ 0.7 is the bar)
+Run `sungen audit --api <name>`; read `gateStatus` + `findings`. Then the **semantic reviewer** (sungen-reviewer sub-agent, API criteria). Repair **both** (budget 3 rounds), re-audit until PASS:
+
+| Finding | Repair |
+|---|---|
+| `VIEWPOINT-API-CONTRACT` | the endpoint is invoked but its response is never asserted → add `expect {{name.status}}` + a `{{name.body.…}}` check |
+| `VIEWPOINT-API-ERROR` | a mutating endpoint has no failure scenario → add a `@cases` error matrix (or an explicit 4xx) |
+| `VIEWPOINT-API-IDEMPOTENCY` | a mutating endpoint has no race check → add `@concurrent:N` + a `@query` DB cross-check |
+| **`DEPTH-FAIL`** (businessDepth < 0.7) | a **mutating success** scenario asserts only `status` → make it **prove the effect**: assert a response **body** field, a **`@query`** side-effect, or a **`@concurrent` `ok_count`** invariant. (An error/`@cases` scenario proving the status is correct — it is *not* depth-required.) |
+
+Stop when the gate PASSes + businessDepth ≥ 0.7, or the budget is exhausted → report residual gaps honestly (mark genuinely-unautomatable cases `@manual` with an oracle). Never fake a pass.
+
+### 5. Record + converge
+`sungen manifest --api <name>` (reuse) and ledger each phase; show the trace + the HUMAN-LOOP FOCUS. (Integrity `script-check`/`trace` for api: see run-test.)
+
+## Rules
+- **No HTTP, no selectors** — only `.feature` + the reviewed `apis.yaml` + `test-data`.
+- **Non-prod default** — a `production` datasource is refused unless `SUNGEN_ALLOW_PROD=1`.
+- **The DB is the oracle** for idempotency/side-effects — HTTP status alone can lie; pair `@api` with `@query`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sun-asterisk/sungen",
-  "version": "3.1.2-beta.118",
+  "version": "3.1.2-beta.120",
   "description": "Deterministic E2E Test Compiler - Gherkin + Selectors → Playwright tests",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -33,7 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@sungen/driver-ui": "3.1.2-beta.118",
+    "@sungen/driver-ui": "3.1.2-beta.120",
     "@anthropic-ai/sdk": "^0.71.0",
     "@babel/parser": "^7.28.5",
     "@babel/traverse": "^7.28.5",

package/src/cli/commands/delivery.ts

@@ -52,47 +52,49 @@ 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 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));
+  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));
     }
-  }
+  };
+  scan('screen');
+  scan('flow');
+  scan('api', (n) => n === 'flows'); // qa/api/<area> (api flows live under qa/api/flows — a follow-up)
 
   return targets.sort((a, b) => a.featureBaseName.localeCompare(b.featureBaseName));
 }
@@ -108,28 +110,24 @@ 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');
+  // 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 +260,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 +283,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/script-check.ts

@@ -8,18 +8,20 @@ export function registerScriptCheckCommand(program: Command): void {
     .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('--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;
+        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 });
@@ -39,7 +41,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,18 @@ 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('--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;
+        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/harness/script-check.ts

@@ -106,9 +106,18 @@ function normalize(src: string): string {
     .trim();
 }
 
-function findSpec(dir: string, name: string, flowMode: boolean): string | null {
+/** The unit kind — drives the generated-spec subdir + the qa source dir. */
+export type UnitKind = 'screen' | 'flow' | 'api';
+
+/** Generated-spec subdir for a unit: screen → <name>, flow → flows/<name>, api → api/<name>. */
+function specSubdir(dir: string, name: string, kind: UnitKind): string {
+  return kind === 'flow' ? path.join(dir, 'flows', name) : kind === 'api' ? path.join(dir, 'api', name) : path.join(dir, name);
+}
+
+function findSpec(dir: string, name: string, kind: UnitKind): string | null {
   // Screens compile to  <dir>/<name>/<feature>.spec.ts
   // Flows   compile to  <dir>/flows/<name>/<feature>.spec.ts
+  // Api     compile to  <dir>/api/<name>/<feature>.spec.ts
   // Scope the search to THIS target's own subdir — otherwise the first spec of
   // ANY other screen/flow is returned, which (for an uncompiled flow) falsely
   // reports the wrong screen's tests as drift.
@@ -121,19 +130,19 @@ function findSpec(dir: string, name: string, flowMode: boolean): string | null {
       else if (e.name.endsWith('.spec.ts')) hits.push(p);
     }
   };
-  const scoped = flowMode ? path.join(dir, 'flows', name) : path.join(dir, name);
+  const scoped = specSubdir(dir, name, kind);
   if (!fs.existsSync(scoped)) return null; // no spec for this target (e.g. not compiled yet)
   walk(scoped);
   return hits[0] ?? null;
 }
 
-export async function runScriptCheck(screenDir: string, screenName: string, flowMode: boolean): Promise<ScriptCheckResult> {
+export async function runScriptCheck(screenDir: string, screenName: string, kind: UnitKind): Promise<ScriptCheckResult> {
   const featurePath = path.join(screenDir, 'features', `${screenName}.feature`);
   const scenarios = loadScenarios(featurePath);
   const automated = scenarios.filter((s) => !s.manual);
   const manual = scenarios.filter((s) => s.manual);
 
-  const committedSpec = findSpec(path.join(process.cwd(), 'specs', 'generated'), screenName, flowMode);
+  const committedSpec = findSpec(path.join(process.cwd(), 'specs', 'generated'), screenName, kind);
 
   const findings: string[] = [];
   let specTitles: string[] = [];
@@ -167,10 +176,14 @@ export async function runScriptCheck(screenDir: string, screenName: string, flow
     try {
       const { CodeGenerator } = require('../generators/test-generator/code-generator');
       const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'sungen-scriptcheck-'));
-      const qaSourceDir = path.join(process.cwd(), 'qa', flowMode ? 'flows' : 'screens');
-      const gen = new CodeGenerator({ framework: 'playwright', screenName, runtimeData: true, flowMode });
+      const qaSourceDir = path.join(process.cwd(), 'qa', kind === 'flow' ? 'flows' : kind === 'api' ? 'api' : 'screens');
+      // api units derive their unit id (api/<area>) from the feature path — like `generate --api`;
+      // screen/flow pass screenName + flowMode explicitly (unchanged → byte-identical regenerate).
+      const gen = kind === 'api'
+        ? new CodeGenerator({ framework: 'playwright', runtimeData: true })
+        : new CodeGenerator({ framework: 'playwright', screenName, runtimeData: true, flowMode: kind === 'flow' });
       await gen.generateAllTests(qaSourceDir, tmp, [featurePath]);
-      const fresh = findSpec(tmp, screenName, flowMode);
+      const fresh = findSpec(tmp, screenName, kind);
       if (fresh) {
         const a = normalize(specSrc);
         const b = normalize(fs.readFileSync(fresh, 'utf-8'));

package/src/orchestrator/ai-rules-updater.ts

@@ -47,6 +47,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['claude-skill-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
   ['claude-skill-tc-review.md', '.claude/skills/sungen-tc-review/SKILL.md'],
   ['claude-skill-harness-audit.md', '.claude/skills/sungen-harness-audit/SKILL.md'],
+  ['claude-skill-api-design.md', '.claude/skills/sungen-api-design/SKILL.md'],
   ['claude-skill-ingest-legacy.md', '.claude/skills/sungen-ingest-legacy/SKILL.md'],
   ['claude-skill-viewpoint.md', '.claude/skills/sungen-viewpoint/SKILL.md'],
   ['claude-skill-viewpoint-group-a-data-entry.md', '.claude/skills/sungen-viewpoint/group-a-data-entry.md'],
@@ -79,6 +80,7 @@ export const AI_RULES_FILE_MAPPING: [string, string][] = [
   ['github-skill-sungen-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
   ['github-skill-sungen-tc-review.md', '.github/skills/sungen-tc-review/SKILL.md'],
   ['github-skill-sungen-harness-audit.md', '.github/skills/sungen-harness-audit/SKILL.md'],
+  ['github-skill-sungen-api-design.md', '.github/skills/sungen-api-design/SKILL.md'],
   ['github-skill-sungen-ingest-legacy.md', '.github/skills/sungen-ingest-legacy/SKILL.md'],
   ['github-skill-sungen-viewpoint.md', '.github/skills/sungen-viewpoint/SKILL.md'],
   ['github-skill-sungen-viewpoint-group-a-data-entry.md', '.github/skills/sungen-viewpoint/group-a-data-entry.md'],

package/src/orchestrator/templates/ai-instructions/claude-agent-reviewer.md

@@ -19,6 +19,12 @@ You are an **independent Senior QA Reviewer**. You did **not** write these tests
 3. **Business-critical depth.** For cart / product-detail / filter / list viewpoints, do steps assert **DATA** (name, price, quantity, all-items-belong) — not just page/modal visibility? Recommend the concrete deep step: `User remember [X] text as {{v}}` + `... with {{v}}`, or `User see all [X] contain {{v}}`.
 4. **@manual justification.** Is each `@manual` genuinely unautomatable (cross-screen/external/visual) — or a cop-out to dodge the gate? Cross-screen → should be a flow.
 5. **Meaning-level duplicates & missing criticals** the keyword gate can't see.
+6. **API units** (`qa/api/<area>/` — `@api` scenarios, no UI). Judge what the api gate can't:
+   - **Prove the effect, not the status.** A mutating endpoint's success path asserting only `{{r.status}} is 201` proves nothing about WHAT changed — demand a **body** assertion (`{{r.body.id}}` / `{{r.body.<field>}}`), a **`@query`** DB side-effect, or (idempotency) a `{{r.ok_count}}` invariant. This is the API businessDepth bar.
+   - **Error matrix coherent.** `@cases` rows are a real failure family (validation/auth/conflict) with realistic inputs → declared statuses, not padding.
+   - **Flows self-clean.** A CRUD/auth chain deletes what it created (final `@api:delete_*`) or is `@cleanup`-tagged.
+   - **Idempotency uses the DB oracle.** A "no double-charge / exactly once" claim is proven by `@concurrent` + a `@query` count, not HTTP status alone (status can lie under a race).
+   - **Auth negatives** exist for protected mutations (401/403), not just the happy path.
 
 ## Output (do NOT edit any file)
 Return a concise verdict:

package/src/orchestrator/templates/ai-instructions/claude-cmd-create-test.md

@@ -23,7 +23,11 @@ You are a **Senior QA Engineer** specialized in test case design. You structure
 
 Parse **name** from `$ARGUMENTS`. If missing, ask the user.
 
-**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode. Else check `qa/screens/<name>/` → screen mode. This determines paths, generation strategy, and CLI commands.
+**Auto-detect context**: check if `qa/api/<name>/` or `qa/api/flows/<name>/` exists → **API unit mode** (below). Else if `qa/flows/<name>/` → flow mode. Else `qa/screens/<name>/` → screen mode. This determines paths, generation strategy, and CLI commands.
+
+## API unit mode (driver-api)
+
+If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the design loop differs — **no visual capture, no selectors**; the contract is the named-endpoint catalog. **Follow the `sungen-api-design` skill end-to-end** instead of the screen/flow steps below: `sungen context --api <name>` (discover) → API viewpoint overview → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios → **`sungen audit --api <name>` gate + the `sungen-reviewer` sub-agent + repair loop to businessDepth ≥ 0.7** → record + trace. Then jump to the "Converge" next-step options (recommend `/sungen:run-test <name>`). The capture / viewpoint-group / selector steps do **not** apply.
 
 ## Steps
 

package/src/orchestrator/templates/ai-instructions/claude-cmd-run-test.md

@@ -30,7 +30,22 @@ If the count is 0 → use `AskUserQuestion` to offer:
 
 Skip this pre-flight when `--env` matches the base locale (no overlay needed in that case).
 
-**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+**Auto-detect context**: check if `qa/api/<name>/` or `qa/api/flows/<name>/` exists → **API unit mode** (below). Else if `qa/flows/<name>/` → flow mode (base path: `qa/flows/<name>/`). Else `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+
+## API unit mode (driver-api) — no selectors
+
+If the unit is **api-first**, skip every selector/capture phase (an API test has no DOM). Instead:
+
+1. **Resolve the datasource** — ensure the `kind: api` datasource's `base_url` + auth are wired in `qa/datasources.yaml` + `.env.qa` (the `${X_URL}` key from `sungen api init`). A `production` datasource is refused unless `SUNGEN_ALLOW_PROD=1`.
+2. **Compile**: `[ -x ./bin/sungen.js ] && ./bin/sungen.js generate --api <name> || npx sungen generate --api <name>` → `specs/generated/api/<name>/`.
+3. **Run**: `npx playwright test specs/generated/api/<name>/<name>.spec.ts` (per-spec JSON results, as below).
+4. **Auto-fix** (no selectors — the failure classes differ): use `sungen-error-mapping`.
+   - **401/403** → wire `@hybrid` + `@auth:<role>` (reuse the UI session) or the catalog `Bearer :token` header; suggest `sungen makeauth <role>`.
+   - **datasource/base_url unresolved** → set the `${X_URL}` key in `.env.qa`.
+   - **missing/empty bound param** → trace `{{var}}` to test-data or a prior `@api` response; fill it.
+   - **`expect.status` mismatch** → reconcile against `apis.yaml`/spec (the catalog is the oracle); **never hand-edit the generated spec** (re-`generate --api` instead).
+   - **flaky** → enforce self-cleaning flows, per-row isolation (`@cases`), `@concurrent` caps.
+5. **Integrity + trace** — `sungen script-check --api <name>` (verify the spec is a 1:1 of the Gherkin; on DRIFT re-`generate --api`, never hand-edit) and `sungen trace --api <name>` (process map + HUMAN-LOOP FOCUS). Then report + offer next steps.
 
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 

package/src/orchestrator/templates/ai-instructions/claude-skill-api-design.md

@@ -0,0 +1,49 @@
+---
+name: sungen-api-design
+description: The API-first design loop for an api unit (qa/api/<area> or qa/api/flows/<flow>) — discover the catalog, lay out the API viewpoints, generate @api/@cases/flow/@concurrent scenarios, then drive the sungen audit --api gate + reviewer + repair to a high businessDepth (≥0.7). Use when create-test/run-test detects an api unit (no selectors, no visual capture).
+---
+
+# API design loop (driver-api · Orchestration + Harness)
+
+Use this when the unit is **api-first** — `qa/api/<area>/` or `qa/api/flows/<flow>/`. There are **no selectors and no visual capture**: the contract is the **named-endpoint catalog** (`api/apis.yaml`), referenced by `@api:<name>`. QA writes **no HTTP code**. Full annotation reference: the **API Steps** guide (`@api` / `@cases` / flows / `@concurrent` / `@hybrid`).
+
+## The loop (mirror of /sungen:design, API-native)
+
+### 1. Discover (no capture)
+Run `sungen context --api <name>` — it reads the catalog and prints the **endpoints** + the **generation units** (one `matrix` unit per endpoint, an `async` unit per mutating endpoint, a `flow` unit for an api flow). Read `qa/api/<name>/requirements/spec.md` if present. No `apis.yaml` yet? → `sungen api import <openapi|csv>` or `sungen api add --area <name>` first.
+
+### 2. API viewpoint overview (by method-profile)
+For each endpoint, cover its viewpoints — severity-weighted by method:
+
+| Profile | Endpoints | Must cover | Then |
+|---|---|---|---|
+| read | GET, HEAD | `contract` (status + body shape) | `pagination`/`filter` (list), `not-found` (by-id) |
+| mutating | POST/PUT/PATCH/DELETE | `contract`, `error` (validation/4xx/auth) | `idempotency` (`@concurrent`), `side-effect` (`@query`) |
+
+Bands: **~70%** success+failure matrix · **~20%** flows (auth/CRUD chains) · **~10%** async/idempotency.
+
+### 3. Generate (incremental — never the whole suite in one Write)
+- **Contract**: `@api:<name>` + `expect {{name.status}} is …` **and a body assertion** (`{{name.body.<path>}}`).
+- **Error matrix**: `@api:<name>(p={{p}}) @cases:<dataset>` — one scenario, a dataset of `input → expected status`.
+- **Flow**: ordered `@api` tags threading a prior response (`token={{login.body.token}}` → the catalog `Bearer :token` header; `id={{create.body.id}}` → a path param). Self-clean (delete what you create).
+- **Idempotency**: `@api:<name> @concurrent:N` + `expect {{name.ok_count}} is 1`, cross-checked with `@query` (the DB is the oracle).
+
+### 4. Gate + repair (always — businessDepth ≥ 0.7 is the bar)
+Run `sungen audit --api <name>`; read `gateStatus` + `findings`. Then the **semantic reviewer** (sungen-reviewer sub-agent, API criteria). Repair **both** (budget 3 rounds), re-audit until PASS:
+
+| Finding | Repair |
+|---|---|
+| `VIEWPOINT-API-CONTRACT` | the endpoint is invoked but its response is never asserted → add `expect {{name.status}}` + a `{{name.body.…}}` check |
+| `VIEWPOINT-API-ERROR` | a mutating endpoint has no failure scenario → add a `@cases` error matrix (or an explicit 4xx) |
+| `VIEWPOINT-API-IDEMPOTENCY` | a mutating endpoint has no race check → add `@concurrent:N` + a `@query` DB cross-check |
+| **`DEPTH-FAIL`** (businessDepth < 0.7) | a **mutating success** scenario asserts only `status` → make it **prove the effect**: assert a response **body** field, a **`@query`** side-effect, or a **`@concurrent` `ok_count`** invariant. (An error/`@cases` scenario proving the status is correct — it is *not* depth-required.) |
+
+Stop when the gate PASSes + businessDepth ≥ 0.7, or the budget is exhausted → report residual gaps honestly (mark genuinely-unautomatable cases `@manual` with an oracle). Never fake a pass.
+
+### 5. Record + converge
+`sungen manifest --api <name>` (reuse) and ledger each phase; show the trace + the HUMAN-LOOP FOCUS. (Integrity `script-check`/`trace` for api: see run-test.)
+
+## Rules
+- **No HTTP, no selectors** — only `.feature` + the reviewed `apis.yaml` + `test-data`.
+- **Non-prod default** — a `production` datasource is refused unless `SUNGEN_ALLOW_PROD=1`.
+- **The DB is the oracle** for idempotency/side-effects — HTTP status alone can lie; pair `@api` with `@query`.

package/src/orchestrator/templates/ai-instructions/copilot-cmd-create-test.md

@@ -18,7 +18,11 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
 
 - **name** — ${input:name:screen or flow name (e.g., login, award-submission)}
 
-**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+**Auto-detect context**: check if `qa/api/<name>/` or `qa/api/flows/<name>/` exists → **API unit mode** (below). Else if `qa/flows/<name>/` → flow mode (base path: `qa/flows/<name>/`). Else `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+
+## API unit mode (driver-api)
+
+If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the design loop differs — **no visual capture, no selectors**; the contract is the named-endpoint catalog. **Follow the `sungen-api-design` skill end-to-end** instead of the screen/flow steps: `sungen context --api <name>` (discover) → API viewpoint overview → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios → **`sungen audit --api <name>` gate + reviewer + repair loop to businessDepth ≥ 0.7** → record + trace. Then recommend `/sungen-run-test <name>`. The capture / viewpoint-group / selector steps do **not** apply.
 
 ## Steps
 

package/src/orchestrator/templates/ai-instructions/copilot-cmd-run-test.md

@@ -30,7 +30,16 @@ Count 0 → offer the user:
 
 Skip when `--env` matches the base locale.
 
-**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+**Auto-detect context**: check if `qa/api/<name>/` or `qa/api/flows/<name>/` exists → **API unit mode** (below). Else if `qa/flows/<name>/` → flow mode (base path: `qa/flows/<name>/`). Else `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+
+## API unit mode (driver-api) — no selectors
+
+If the unit is **api-first**, skip every selector/capture phase (an API test has no DOM):
+1. **Resolve the datasource** — `base_url` + auth wired in `qa/datasources.yaml` + `.env.qa` (`${X_URL}` from `sungen api init`); a `production` datasource is refused unless `SUNGEN_ALLOW_PROD=1`.
+2. **Compile**: `npx sungen generate --api <name>` → `specs/generated/api/<name>/`.
+3. **Run**: `npx playwright test specs/generated/api/<name>/<name>.spec.ts`.
+4. **Auto-fix** (use `sungen-error-mapping`): 401/403 → `@hybrid`+`@auth` or `Bearer :token` header (`sungen makeauth`); base_url unresolved → set `${X_URL}`; missing param → trace `{{var}}` to test-data/a prior `@api` response; `expect.status` mismatch → reconcile against `apis.yaml` (re-`generate --api`, never hand-edit the spec); flaky → self-clean + `@concurrent` caps.
+5. **Integrity + trace** — `sungen script-check --api <name>` (1:1; on DRIFT re-`generate --api`, never hand-edit the spec) + `sungen trace --api <name>` (process map + HUMAN-LOOP FOCUS). Report + offer next steps.
 
 ## Pre-run (phased — per `sungen-selector-fix` skill)