@sun-asterisk/sungen 3.2.5 → 3.2.7

package/src/generators/test-generator/adapters/appium/templates/scenario.hbs

@@ -1,4 +1,4 @@
-  it('{{scenarioName}}', async () => {
+  it('{{escapeQuotes scenarioName}}', async () => {
 {{#each steps}}
 {{#if comment}}
     // {{comment}}

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

@@ -1,9 +1,9 @@
 {{#if casesDataset}}
   for (const __row of testData.cases('{{casesDataset}}')) {
 {{#if tags}}
-  test(`{{scenarioName}} — ${__row.__label}`, { tag: [{{{tags}}}] }, async ({{#if isParallel}}{ page }{{/if}}) => {
+  test('{{escapeQuotes scenarioName}} — ' + __row.__label, { tag: [{{{tags}}}] }, async ({{#if isParallel}}{ page }{{/if}}) => {
 {{else}}
-  test(`{{scenarioName}} — ${__row.__label}`, async ({{#if isParallel}}{ page }{{/if}}) => {
+  test('{{escapeQuotes scenarioName}} — ' + __row.__label, async ({{#if isParallel}}{ page }{{/if}}) => {
 {{/if}}
     const rowData = testData.withRow(__row);
 {{#each steps}}
@@ -17,9 +17,9 @@
 {{else}}
 {{#if isParallel}}
 {{#if tags}}
-  test('{{scenarioName}}', { tag: [{{{tags}}}] }, async ({ page }) => {
+  test('{{escapeQuotes scenarioName}}', { tag: [{{{tags}}}] }, async ({ page }) => {
 {{else}}
-  test('{{scenarioName}}', async ({ page }) => {
+  test('{{escapeQuotes scenarioName}}', async ({ page }) => {
 {{/if}}
 {{#each steps}}
 {{#if comment}}
@@ -30,9 +30,9 @@
   });
 {{else}}
 {{#if tags}}
-  test('{{scenarioName}}', { tag: [{{{tags}}}] }, async () => {
+  test('{{escapeQuotes scenarioName}}', { tag: [{{{tags}}}] }, async () => {
 {{else}}
-  test('{{scenarioName}}', async () => {
+  test('{{escapeQuotes scenarioName}}', async () => {
 {{/if}}
 {{#each steps}}
 {{#if comment}}

package/src/generators/test-generator/adapters/playwright/templates/steps/actions/expand-action.hbs

@@ -1,11 +1,33 @@
+{ const el = {{> locator}};
+{{#if expanded.state}}
+{{!-- Toggle-only: component exposes no observable expanded state → click without asserting. --}}
+await el.click();
+{{else if expanded.class}}
+{{!-- State signalled by a class on a descendant (e.g. an accordion chevron icon). --}}
 {{#if (eq direction 'expand')}}
-if (await {{> locator}}.getAttribute('aria-expanded') !== 'true') {
-  await {{> locator}}.click();
-}
-await expect({{> locator}}).toHaveAttribute('aria-expanded', 'true');
+if (!(await el.locator('.{{expanded.class}}').count())) { await el.click(); }
+await expect(el.locator('.{{expanded.class}}')).toBeVisible();
+{{else}}
+if (await el.locator('.{{expanded.class}}').count()) { await el.click(); }
+await expect(el.locator('.{{expanded.class}}')).toHaveCount(0);
+{{/if}}
+{{else if expanded.attribute}}
+{{!-- Explicit boolean attribute ('true'/'false'), custom or aria-expanded. --}}
+{{#if (eq direction 'expand')}}
+if (await el.getAttribute('{{expanded.attribute}}') !== 'true') { await el.click(); }
+await expect(el).toHaveAttribute('{{expanded.attribute}}', 'true');
+{{else}}
+if (await el.getAttribute('{{expanded.attribute}}') !== 'false') { await el.click(); }
+await expect(el).toHaveAttribute('{{expanded.attribute}}', 'false');
+{{/if}}
+{{else}}
+{{!-- Default (zero-config): drive by aria-expanded, but assert it ONLY when the element exposes it. --}}
+{{#if (eq direction 'expand')}}
+if (await el.getAttribute('aria-expanded') !== 'true') { await el.click(); }
+if (await el.getAttribute('aria-expanded') !== null) { await expect(el).toHaveAttribute('aria-expanded', 'true'); }
 {{else}}
-if (await {{> locator}}.getAttribute('aria-expanded') !== 'false') {
-  await {{> locator}}.click();
+if (await el.getAttribute('aria-expanded') !== 'false') { await el.click(); }
+if (await el.getAttribute('aria-expanded') !== null) { await expect(el).toHaveAttribute('aria-expanded', 'false'); }
+{{/if}}
+{{/if}}
 }
-await expect({{> locator}}).toHaveAttribute('aria-expanded', 'false');
-{{/if}}

package/src/generators/test-generator/adapters/playwright/templates/steps/assertions/selected-assertion.hbs

@@ -1 +1,16 @@
-await expect({{> locator}}).toHaveAttribute('aria-selected', 'true');
+{{#if (or (eq role 'checkbox') (eq role 'radio') (eq role 'switch'))}}
+{{!-- Form control: "selected" is the checked state, never aria-selected. A native checkbox/radio
+     exposes no aria-selected attribute — its state lives in the `checked` property. --}}
+await expect({{> locator}}).toBeChecked();
+{{else}}
+{{!-- Other/unknown role (tab, option, or a text/testid/css selector): probe at runtime. An ARIA
+     single-select widget exposes aria-selected → assert it; anything without it falls back to the
+     checked state. Never hardcode aria-selected — it breaks on native form controls. --}}
+{ const el = {{> locator}};
+if ((await el.getAttribute('aria-selected')) !== null) {
+await expect(el).toHaveAttribute('aria-selected', 'true');
+} else {
+await expect(el).toBeChecked();
+}
+}
+{{/if}}

package/src/generators/test-generator/patterns/expect-patterns.ts

@@ -17,6 +17,14 @@ import { MappedStep } from '../step-mapper';
 const VALUE = String.raw`\{\{[^}]+\}\}|"[^"]*"|'[^']*'|-?\d+(?:\.\d+)?`;
 const reExpect = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(${VALUE})\\s+is\\s+(not\\s+|at\\s+least\\s+|at\\s+most\\s+)?(${VALUE})\\s*$`, 'i');
 
+/** `expect {{name.body}} matches schema [Ref]` — validate a bound API response body against a named
+ *  JSON Schema (from qa/api/schemas.yaml, populated by `sungen api import`). Requires the API Driver
+ *  (the scenario carries `@api:<name>`, so the `api` runtime helper is imported).
+ *  Two regexes: the MATCHER sees ref contents masked (`{{~}}`, `[~]` — see maskRefsForMatching); the
+ *  GENERATOR gets the ORIGINAL step text, so it extracts the real `[Ref]`. */
+const reMatchesSchemaMasked = /^\s*(?:User\s+)?expect\s+\{\{~\}\}\s+matches\s+schema\s+\[~\]\s*$/i;
+const reMatchesSchema = new RegExp(`^\\s*(?:User\\s+)?expect\\s+(\\{\\{[^}]+\\}\\})\\s+matches\\s+schema\\s+\\[([A-Za-z0-9_.-]+)\\]\\s*$`, 'i');
+
 /** Render a value token (`{{var}}` | "literal" | 'literal' | number) as a JS expression. */
 function valueExpr(token: string): string {
   const t = token.trim();
@@ -29,6 +37,21 @@ function valueExpr(token: string): string {
 }
 
 export const expectPatterns: StepPattern[] = [
+  {
+    name: 'expect-matches-schema',
+    priority: 63, // above expect-data; its regex needs `matches schema`, so no overlap
+    matcher: (step: ParsedStep) => reMatchesSchemaMasked.test(step.text),
+    generator: (step: ParsedStep, _ctx: PatternContext): MappedStep => {
+      // The masked matcher is looser than this extraction regex, so a malformed step (empty var/ref,
+      // odd chars) can claim the pattern yet not re-match here — emit a clear TODO instead of crashing.
+      const m = step.text.match(reMatchesSchema);
+      if (!m) return { code: `// TODO: malformed 'matches schema' step (expected: expect {{name.body}} matches schema [Ref]): ${step.text}`, comment: 'Unrecognized matches-schema step' };
+      const value = valueExpr(m[1]);
+      const ref = m[2];
+      const code = `{ const __schema = api.assertSchema(${value}, ${JSON.stringify(ref)}); expect(__schema.ok, \`matches schema [${ref}]: \${__schema.errors}\`).toBe(true); }`;
+      return { code, comment: `Expect ${m[1]} matches schema [${ref}]` };
+    },
+  },
   {
     name: 'expect-data',
     priority: 62, // above generic see-assertions; sibling of the DB assertions

package/src/generators/test-generator/utils/selector-resolver.ts

@@ -39,6 +39,17 @@ interface SelectorEntry {
   // === v2: Assertion Helpers ===
   attribute?: string;     // Attribute to check (for "has" assertions)
   pattern?: string;       // Regex for attribute value
+
+  // === Expand/collapse state signal ===
+  // How the open/closed state of an expandable element is observed. Many accordions expose no
+  // `aria-expanded` (state shows only via an icon class swap), so hardcoding it makes the assertion
+  // time out. When omitted, codegen drives by aria-expanded but asserts it ONLY if present — a safe
+  // zero-config fallback. Provide one of these to verify a non-aria component explicitly.
+  expanded?: {
+    class?: string;       // class present on a descendant when open (e.g. 'mdi-chevron-up')
+    attribute?: string;   // boolean attribute ('true'/'false') on the toggle element
+    state?: 'none';       // no observable state → toggle-click only, skip the assertion
+  };
 }
 
 // New selector file structure: flat key-value pairs
@@ -64,6 +75,12 @@ export interface ResolvedSelector {
   strategy: 'testid' | 'id' | 'placeholder' | 'label' | 'text' | 'css' | 'role' | 'locator'
     | 'accessibility-id' | 'xpath' | 'android-uiautomator' | 'ios-predicate';
   value: string;
+  // Original YAML `type:` of the matched entry (before it collapses into a `strategy`). Callers
+  // that assign meaning to the entry kind — e.g. page assertions, whose `value` is a URL ONLY when
+  // the entry is a `page` selector — must verify this instead of trusting a key match. A key can
+  // collide across types (one `読取結果一覧` entry, type `role`, reused for a page assertion), so a
+  // key-only lookup can hand back an entry whose `value` ('button') is meaningless as a URL.
+  selectorType?: SelectorType;
   // Mobile per-platform variant (`android:`/`ios:` in selectors.yaml). When set, the appium codegen
   // emits a runtime `driver.isIOS ? '<ios>' : '<android>'` so one @platform:mobile spec resolves the
   // right native selector per OS. Each side carries its own strategy+value (issue #392).
@@ -87,6 +104,7 @@ export interface ResolvedSelector {
   pagination?: Record<string, string>;
   attribute?: string;   // Attribute to check
   pattern?: string;     // Regex for attribute value
+  expanded?: { class?: string; attribute?: string; state?: 'none' };  // Expand/collapse state signal
 }
 
 /**
@@ -460,8 +478,14 @@ export class SelectorResolver {
     const type = entry.type || 'placeholder';
     // Check if value exists in entry (even if empty string), use it; otherwise use originalLabel
     const rawValue = entry.value !== undefined && entry.value !== null ? entry.value : originalLabel;
-    // Check if name exists in entry (even if empty string), use it; otherwise use originalLabel
-    const rawName = entry.name !== undefined && entry.name !== null ? entry.name : originalLabel;
+    // Name resolution has three cases:
+    //   - key absent (undefined)      → fall back to originalLabel (the [Reference] text)
+    //   - explicit null / empty string → disable the name filter entirely (rawName = '')
+    //   - a real string               → use it verbatim
+    // Explicit `name: null` in YAML is a deliberate opt-out (e.g. a role selector that must NOT
+    // filter by accessible name); it must not be conflated with "unset". The role template omits
+    // `{ name }` when this resolves to a falsy value.
+    const rawName = entry.name === undefined ? originalLabel : (entry.name ?? '');
     const value = SelectorResolver.resolveTemplateVars(rawValue);
     const name = SelectorResolver.resolveTemplateVars(rawName);
     const nth = entry.nth !== undefined && entry.nth !== null ? entry.nth : undefined;
@@ -480,10 +504,14 @@ export class SelectorResolver {
     if (entry.pagination) v2Fields.pagination = entry.pagination;
     if (entry.attribute) v2Fields.attribute = entry.attribute;
     if (entry.pattern) v2Fields.pattern = entry.pattern;
+    if (entry.expanded) v2Fields.expanded = entry.expanded;
 
     // Helper to attach v2 fields and inputMethod
     const withExtras = (resolved: ResolvedSelector): ResolvedSelector => {
       if (inputMethod) resolved.inputMethod = inputMethod;
+      // Preserve the entry's original YAML type so callers can verify the entry kind (a key match
+      // alone does not guarantee the entry means what the step expects — see ResolvedSelector.selectorType).
+      resolved.selectorType = type;
       return { ...resolved, ...v2Fields };
     };
 

package/src/orchestrator/project-initializer.ts

@@ -4,6 +4,7 @@
  */
 
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { execSync } from 'child_process';
 import { buildOutputs } from './ai-skills/build';
@@ -47,18 +48,53 @@ export function mergeCodexMcpToml(existing: string, mobileOnly: boolean): string
   const serverKey = mobileOnly ? 'appium-mcp' : 'playwright';
   // Already configured (by the user or a previous run) → preserve, do nothing.
   if (new RegExp(String.raw`^\s*\[mcp_servers\.(?:"?${serverKey}"?)\]`, 'm').test(existing)) return null;
+  // startup_timeout_sec: Codex's default is 10s, which `npx <pkg>@latest` blows past on a cold
+  // cache (it downloads the package first) — the server then "fails to start" and Codex drops it.
+  // default_tools_approval_mode: Codex gates every MCP tool call behind an approval elicitation;
+  // non-interactive runs (`codex exec`, full-auto) auto-CANCEL it — "user cancelled MCP tool call"
+  // — so run-test could never drive the browser headlessly. Auto-approve is scoped to this server
+  // only and the whole file already requires project trust.
+  const serverOpts = 'startup_timeout_sec = 120\ndefault_tools_approval_mode = "approve"\n';
   const block = mobileOnly
-    ? '[mcp_servers.appium-mcp]\ncommand = "npx"\nargs = ["-y", "appium-mcp"]\n'
-    : '[mcp_servers.playwright]\ncommand = "npx"\nargs = ["@playwright/mcp@latest"]\n';
+    ? `[mcp_servers.appium-mcp]\ncommand = "npx"\nargs = ["-y", "appium-mcp"]\n${serverOpts}`
+    : `[mcp_servers.playwright]\ncommand = "npx"\nargs = ["@playwright/mcp@latest"]\n${serverOpts}`;
   if (existing.trim() === '') return CODEX_MCP_HEADER + block;
   return existing + (existing.endsWith('\n') ? '\n' : '\n\n') + block;
 }
 
+/**
+ * Whether the user's global Codex config (`~/.codex/config.toml`) marks `projectDir` trusted.
+ * Codex loads a project `.codex/config.toml` ONLY for trusted projects and skips it SILENTLY
+ * otherwise — the #1 "Codex doesn't see the Playwright MCP server" failure — so init checks and
+ * warns instead of leaving the user with a config that never loads. Pure string scan (no toml dep).
+ */
+export function codexTrustsProject(configText: string, projectDir: string): boolean {
+  let currentProject: string | null = null;
+  const trusted: string[] = [];
+  for (const line of configText.split('\n')) {
+    const header = line.match(/^\s*\[(.+)\]\s*$/);
+    if (header) {
+      const m = header[1].trim().match(/^projects\.(?:"(.+)"|'(.+)'|(.+))$/);
+      currentProject = m ? (m[1] ?? m[2] ?? m[3]) : null;
+      continue;
+    }
+    if (currentProject && /^\s*trust_level\s*=\s*"trusted"\s*$/.test(line)) trusted.push(currentProject);
+  }
+  // Codex resolves the project by walking UP from cwd (git root / trusted ancestor), so a dir
+  // nested inside a trusted project is itself trusted — verified live: `codex mcp list` inside
+  // examples/<new>/ loads its .codex/config.toml with only the repo root in the trust list.
+  return trusted.some(
+    (dir) => projectDir === dir || projectDir.startsWith(dir.endsWith(path.sep) ? dir : dir + path.sep),
+  );
+}
+
 export class ProjectInitializer {
   private baseCwd: string;
   private cwd: string;
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
+  /** set by createCodexMCPConfig when the project isn't Codex-trusted (config would never load) */
+  private codexTrustWarning = false;
   private agents: AdapterKey[];
   private force: boolean;
   private mobile: MobileInitOptions;
@@ -360,12 +396,23 @@ export class ProjectInitializer {
     const existed = fs.existsSync(filePath);
     const existing = existed ? fs.readFileSync(filePath, 'utf-8') : '';
     const merged = mergeCodexMcpToml(existing, this.mobileOnly);
-    if (merged === null) {
+    if (merged !== null) {
+      fs.writeFileSync(filePath, merged, 'utf-8');
+      this.createdItems.push(existed ? '.codex/config.toml (updated)' : '.codex/config.toml');
+    } else {
       this.skippedItems.push('.codex/config.toml');
-      return;
     }
-    fs.writeFileSync(filePath, merged, 'utf-8');
-    this.createdItems.push(existed ? '.codex/config.toml (updated)' : '.codex/config.toml');
+
+    // Trust gate: without a trusted entry in the GLOBAL Codex config, the project config above
+    // is silently ignored and run-test never gets the MCP browser. Warn in the summary.
+    const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+    let trusted = false;
+    try {
+      trusted = codexTrustsProject(fs.readFileSync(path.join(codexHome, 'config.toml'), 'utf-8'), this.cwd);
+    } catch {
+      // no global config yet → definitely untrusted
+    }
+    this.codexTrustWarning = !trusted;
   }
 
   /**
@@ -436,6 +483,16 @@ export class ProjectInitializer {
       });
     }
 
+    if (this.codexTrustWarning) {
+      console.log('\n⚠ Codex: this project is not trusted yet, so .codex/config.toml (the MCP browser');
+      console.log('  config for run-test) will be SILENTLY IGNORED by Codex. To fix, either:');
+      console.log('    • open the project with `codex` once and approve the trust prompt, or');
+      console.log('    • add to ~/.codex/config.toml:');
+      console.log(`        [projects."${this.cwd}"]`);
+      console.log('        trust_level = "trusted"');
+      console.log('  Then verify with `codex mcp list` — it should show the sungen MCP server.');
+    }
+
     console.log('\nNext steps:');
     let stepIndex = 1;
     if (projectName) {
@@ -597,10 +654,11 @@ export class ProjectInitializer {
     // Ensure standard scripts exist in package.json
     this.ensurePackageScripts(packageJsonPath);
 
-    // Mobile-only drops @playwright/test (no web runner needed).
+    // Mobile-only drops @playwright/test (no web runner needed). `ajv`/`ajv-formats` back the API
+    // Driver's `expect {{name.body}} matches schema [Ref]` (loaded lazily; harmless if unused).
     const requiredDeps = this.mobileOnly
-      ? ['@types/node', 'yaml']
-      : ['@playwright/test', '@types/node', 'yaml'];
+      ? ['@types/node', 'yaml', 'ajv', 'ajv-formats']
+      : ['@playwright/test', '@types/node', 'yaml', 'ajv', 'ajv-formats'];
 
     let missingDeps: string[] = requiredDeps;
     try {

package/src/orchestrator/templates/ai-src/commands/add-api.md

@@ -0,0 +1,76 @@
+---
+name: add-api
+description: "Add a new Sungen API area or flow — scaffolds the datasource + qa/api/<area>/ directories and can import an OpenAPI/Swagger or CSV spec so the endpoint catalog (+ field metadata, auth, schemas) is populated for you"
+argument-hint: "[area-name] [--base-url <url>] [--flow <name>] [--import <openapi|csv|sheet-url>] [--datasource <name>]"
+order: 10
+claude-tools: "Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion"
+copilot-tools: "[vscode, execute, read, agent, edit, search, todo]"
+codex-trigger: "Run when the user asks to add or scaffold a NEW API area/resource or an API flow to test (REST/HTTP endpoints, not a UI screen). Step 1 of the API workflow. Do NOT use for UI screens, flows across screens, creating test cases, or running tests."
+---
+{{^cap parallel-subagents}}
+**Input**: an API area name (a resource/tag, e.g. `orders`, `users`) and the base URL:
+`/sungen-add-api orders --base-url https://api.example.com`.
+Import a spec so the catalog is filled in: `/sungen-add-api orders --base-url https://api.example.com --import ./openapi.yaml`.
+Add an API flow (ordered CRUD/auth journey) instead of a single area: `/sungen-add-api user-lifecycle --flow`.
+{{/cap}}
+You are scaffolding an **API-first** unit for test generation — an area (one resource) or a flow (a cross-endpoint journey). There is **no visual capture and no selectors**: the contract is the named-endpoint catalog (`api/apis.yaml`), referenced by `@api:<name>`. Follow the `sungen-api-design` skill after scaffolding.
+
+## Parameters
+
+{{#cap parallel-subagents}}
+Parse from `$ARGUMENTS`:
+- **name** — area or flow name (e.g. `orders`, `users`, `user-lifecycle`)
+- **`--base-url <url>`** — the API base URL (stored in `.env.qa`, referenced as `${<DS>_URL}`). Needed the first time (project not yet API-initialized); skippable if `qa/datasources.yaml` already has a `kind: api` datasource.
+- **`--flow <name>`** — scaffold an ordered `@api` chain (auth → CRUD) under `qa/api/flows/<name>/` instead of a single area.
+- **`--import <source>`** — an OpenAPI/Swagger file/URL or a CSV / published Google-Sheet URL. When given, the catalog + `fields:` metadata + inferred auth headers + response `schemas.yaml` are generated from it.
+- **`--datasource <name>`** — datasource name (default `app_api`).
+{{/cap}}
+{{^cap parallel-subagents}}
+- **name** — ${input:name:API area or flow name (e.g. orders, users)}
+- **`--base-url <url>`** — API base URL (first-time init; skip if already API-initialized)
+- **`--flow <name>`** — scaffold an ordered @api chain instead of a single area
+- **`--import <source>`** — OpenAPI/Swagger or CSV/Sheet URL → auto-populate the catalog
+- **`--datasource <name>`** — datasource name (default app_api)
+{{/cap}}
+
+If **name** is missing, ask: "What is the API area (resource) name? (e.g., `orders`, `users`)".
+If **`--base-url`** is missing AND `qa/datasources.yaml` has no `kind: api` datasource, ask for it (it's needed to run the tests later; you can proceed with scaffolding and add it after).
+
+## Steps
+
+### 1. Initialize the API project (first area only)
+
+Check `qa/datasources.yaml` for a `kind: api` datasource. If none, run:
+```bash
+sungen api init --base-url <base-url> --datasource <datasource>
+```
+This creates the `kind: api` datasource, `qa/api/`, and the `.env.qa` URL key. Skip if already initialized (never clobbers).
+
+### 2. Scaffold the area (or flow)
+
+```bash
+sungen api add --area <name>        # a single resource → qa/api/<name>/
+# or
+sungen api add --flow <name>        # an ordered CRUD/auth journey → qa/api/flows/<name>/
+```
+This creates `features/`, `api/apis.yaml`, `test-data/`, and `requirements/spec.md`.
+
+### 3. Populate the catalog (recommended)
+
+If `--import <source>` was given, run it — importing a spec is the single biggest quality lever (the catalog gets accurate paths, query/body params, `fields:` constraints, inferred auth headers, and response `schemas.yaml`, so `/sungen:create-test` can enumerate a complete case set instead of guessing):
+```bash
+sungen api import <source> --datasource <datasource>
+```
+No spec? Hand-author `qa/api/<name>/api/apis.yaml` (or fill `requirements/spec.md` and let `/sungen:create-test` draft it). Review the generated catalog + wire the datasource `base_url`/auth in `datasources.yaml` + `.env.qa`.
+
+### 4. Converge (next actions)
+
+Use `AskUserQuestion` to offer the next step — do NOT just print text:
+- **`/sungen:create-test <name>`** (Recommended) — generate `.feature` + `test-data` (auto-detects the API unit; enumerates the coverage model from `fields:`).
+- **`/sungen:add-api <another> --base-url …`** — scaffold another area.
+- Review `qa/api/<name>/api/apis.yaml` + wire the datasource, then create tests.
+
+## Rules
+- **No visual capture, no selectors** — API units are catalog-driven; don't run Playwright/Figma capture.
+- **Never clobber** — `init` merges datasources; `add` refuses an existing area; `import` needs `--merge` to combine.
+- **Non-prod default** — a `production` datasource is refused at runtime unless `SUNGEN_ALLOW_PROD=1`.

package/src/orchestrator/templates/ai-src/commands/create-test.md

@@ -62,10 +62,10 @@ Parse **name** from `$ARGUMENTS`. If missing, ask the user.
 ## API unit mode (driver-api)
 
 {{#cap parallel-subagents}}
-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 --area <name>` (discover) → API viewpoint overview → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios → **`sungen audit --area <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.
+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` + `sungen-api-coverage-model` skills end-to-end** instead of the screen/flow steps below: `sungen context --area <name>` (discover endpoints + `fields:`) → **enumerate the Tier-1 case list per endpoint from the coverage model** (contract + not-found/required-matrix + auth + idempotency, expanded mechanically from `fields:`) → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios with **strict assertions** (prove the effect, never status-only) → **`sungen audit --area <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.
 {{/cap}}
 {{^cap parallel-subagents}}
-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 --area <name>` (discover) → API viewpoint overview → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios → **`sungen audit --area <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.
+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` + `sungen-api-coverage-model` skills end-to-end** instead of the screen/flow steps: `sungen context --area <name>` (discover endpoints + `fields:`) → **enumerate the Tier-1 case list per endpoint from the coverage model** (contract + not-found/required-matrix + auth + idempotency, expanded mechanically from `fields:`) → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios with **strict assertions** (prove the effect, never status-only) → **`sungen audit --area <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.
 {{/cap}}
 
 ## Steps

package/src/orchestrator/templates/ai-src/config/codex.md

@@ -2,7 +2,8 @@
 
 This project uses **sungen** (Gherkin → Playwright test compiler). Its workflow and
 reference skills are installed under `.agents/skills/sungen-*`. Codex auto-discovers them;
-pick a workflow step with `/skills` or `$sungen-create-test`, or just describe the task
-(e.g. "create a test for the login screen") and the matching skill triggers by description.
+invoke a workflow step with `$sungen-create-test <args>` (typing `$` opens the skill
+autocomplete), or just describe the task (e.g. "create a test for the login screen") and
+the matching skill triggers by description. `/skills` lists the installed skills.
 
 Workflow order: add-screen → create-test → review → run-test → delivery.

package/src/orchestrator/templates/ai-src/skills/sungen-api-coverage-model/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: sungen-api-coverage-model
+description: The per-endpoint API coverage model — the systematic case set to enumerate for each endpoint (read / mutating / flow), keyed to the catalog's fields: metadata, tiered so a first pass is complete (not "happy path + 1 error"). Load this in API unit mode alongside sungen-api-design; it turns endpoints × field constraints into a concrete case list, mechanically, instead of guessing.
+---
+
+# API coverage model (what to test per endpoint)
+
+The gap this closes: a bare `@api` generation defaults to **one happy path + maybe one error** per endpoint — 3 of 8 needed cases. This skill is the **enumeration rule**: for each endpoint, walk the checklist below and emit **every applicable case**. Cases are derived **mechanically** from the catalog `fields:` block (`required` / `type` / `format` / `min`/`max` / `minLength`/`maxLength` / `pattern` / enum `values`) surfaced by `sungen context --area <name>` — do NOT guess the matrix from prose when `fields:` exists.
+
+**Tiers** — always emit **Tier 1** (the complete-first-pass minimum). Emit **Tier 2** when the user asks for full coverage or the spec flags the concern as business-critical. Don't stop at Tier 1's *count* if an endpoint has more required/constrained fields — the matrix scales with the fields.
+
+## Read endpoint (GET / HEAD)
+
+| # | Case | Tier | Route | From |
+|---|------|------|-------|------|
+| R1 | **Contract** — 2xx + response body asserted (≥1 server-derived field value; when a `schemaRef` exists, add `expect {{name.body}} matches schema [Ref]` for the full shape) | 1 | `@api` | always |
+| R2 | **Not found** — by-id read with a missing id → 404 (or the spec's code) | 1 | `@api` | path has an id param |
+| R3 | **Unauthorized** — no / invalid token → 401 | 1 | `@api` + `@cases` | endpoint requires auth |
+| R4 | **Empty state** — query that returns 0 rows → 2xx + empty array / count 0 | 2 | `@api` | list endpoint |
+| R5 | **Forbidden** — valid token, wrong role → 403 | 2 | `@api` | role-scoped |
+| R6 | **Per query param validation** — for each `fields:` query param: required→omit→400; type mismatch→400; enum→invalid value→400; `min/max`→BVA rows | 2 | `@cases` | each constrained query field |
+| R7 | **Pagination / filter / sort** — offset/limit boundaries, sort direction, filter match | 2 | `@api`/`@cases` | paginated list |
+
+## Mutating endpoint (POST / PUT / PATCH / DELETE)
+
+| # | Case | Tier | Route | From |
+|---|------|------|-------|------|
+| M1 | **Happy path** — 2xx + response body asserted (id/echoed fields) **and prove the effect** (`@query` DB read-back, or a follow-up GET) | 1 | `@api` (+`@query`) | always |
+| M2 | **Required-field matrix** — one row per `required` field omitted → 400 + error message | 1 | `@cases` | each `required` field |
+| M3 | **Unauthorized** — no / invalid token → 401 | 1 | `@api`/`@cases` | endpoint requires auth |
+| M4 | **Idempotency / duplicate** — `@concurrent:N` + `@query` oracle → exactly one effect (or 409 on the 2nd) | 1 | `@concurrent`+`@query` | create / non-idempotent |
+| M5 | **Type + boundary matrix** — per constrained field: wrong type; `min-1/min/max/max+1`; `minLength/maxLength` edges | 2 | `@cases` | each constrained field |
+| M6 | **Format / enum matrix** — per `format`/`pattern`/enum field: an invalid value → 400 | 2 | `@cases` | each format/enum field |
+| M7 | **Forbidden** — valid token, wrong role → 403 | 2 | `@api`/`@cases` | role-scoped |
+| M8 | **Semantic (422)** — fields individually valid but violate a business rule (e.g. end < start) | 2 | `@cases` | cross-field rule |
+| M9 | **Payload size / content-type** — oversized body → 413/400; missing/wrong `Content-Type` → 400 | 2 | `@cases` | as spec dictates |
+
+## Flow (multi-endpoint journey — qa/api/flows/<flow>)
+
+| # | Case | Tier |
+|---|------|------|
+| F1 | **CRUD chain** — create → read-back → update → read-back → delete → 404 (each step asserts + self-cleans) | 1 |
+| F2 | **Auth flow** — login → authed call 2xx → logout → same call 401 | 1 |
+| F3 | **Cross-endpoint invariant** — create in A, verify in B (data consistency) | 2 |
+
+## Deriving the matrix from `fields:`
+
+For an endpoint with `fields:` metadata, expand mechanically:
+
+- `required: true` → **one M2/R6 missing-field row** (omit it, expect 400 + message).
+- `type` (integer/number/boolean) → a **wrong-type row** (send a string).
+- `min`/`max` (or `minLength`/`maxLength`) → **BVA rows**: `min-1` (invalid), `min` (valid edge), `max` (valid edge), `max+1` (invalid).
+- `values` (enum) → a **not-in-enum row**.
+- `format`/`pattern` → an **ill-formed row** (bad email, wrong pattern).
+
+Collapse these into compact `@cases` datasets — one dataset per endpoint, one row per (field, technique), each row carrying its `expect_status`. Don't write one scenario per row.
+
+## Assertion depth (tie every case to a proof)
+
+Never emit a status-only assertion for a success case. Three tiers — see also `sungen-tc-review` (API assertion rubric):
+
+- **Shallow ❌** — `expect {{x.status}} is 201` alone. Proves the server didn't 500; not that anything happened.
+- **Medium ⚠️** — status + a response body field (`{{x.body.id}}`). OK for a read contract.
+- **Strict ✅ (required for mutating success + Tier-1 reads)** — status + body field **value that isn't just the input echoed back** + a **proof of effect**: a `@query` DB read-back, a follow-up GET, `matches schema [Ref]` (full-shape contract, when a `schemaRef` exists), or a `@concurrent` `ok_count` invariant.
+
+> `expect {{name.body}} matches schema [Ref]` validates the whole response body against the named JSON Schema in `qa/api/schemas.yaml` (populated by `sungen api import`). Use it in addition to — not instead of — a couple of concrete field-value asserts on the critical fields.
+
+Anti-pattern to avoid: re-asserting the value you just sent (`expect {{x.body.username}} is {{username}}` on the thing you created proves little) — assert a **server-derived** field (generated id, timestamp, computed status) or read it back independently.
+
+## Output discipline
+- Enumerate the **full Tier-1 list per endpoint first**, then write incrementally (≈10–15 scenarios per Write call) — never the whole suite in one response (output-token cap).
+- Name scenarios `VP-API-NNN <what it proves>`; keep the endpoint + technique legible.
+- Enumerate the matrix **mechanically from `fields:`** — that is the coverage guarantee this phase; don't rely on a gate to backfill it. (A future audit gate will additionally flag a `required`/constrained field with no matching negative case — `VIEWPOINT-API-REQUIRED-MATRIX` / `-BOUNDARY` / `-FORMAT` — but until it ships, completeness comes from the enumeration above, not from repair.)

package/src/orchestrator/templates/ai-src/skills/sungen-api-design/SKILL.md

@@ -10,20 +10,30 @@ Use this when the unit is **api-first** — `qa/api/<area>/` or `qa/api/flows/<f
 ## The loop (mirror of /sungen:design, API-native)
 
 ### 1. Discover (no capture)
-Run `sungen context --area <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.
+Run `sungen context --area <name>` — it reads the catalog and prints the **endpoints**, their **`fields:` metadata** (required/type/format/range/enum), any **`schemaRef`**, and 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:
+### 2. Enumerate the coverage model (don't guess the matrix)
+**Load the `sungen-api-coverage-model` skill** and, for each endpoint, walk its checklist to produce the **concrete Tier-1 case list** (a read endpoint → contract + not-found + unauthorized; a mutating endpoint → happy+side-effect + required-field matrix + unauthorized + idempotency). Expand the validation matrix **mechanically from `fields:`** — one `@cases` row per (required/constrained field × technique), each with its `expect_status`. This is the difference between 3-of-8 and a complete first pass.
 
-| 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`) |
+**Mapping Contract** — endpoint profile → cases → route:
+
+| Profile | Viewpoint | Cases (Tier 1) | Technique | Route |
+|---|---|---|---|---|
+| GET/HEAD | contract | 1 | happy + body-field assert (+`matches schema [Ref]` if `schemaRef`) | `@api` |
+| GET/HEAD | not-found | 1 (by-id) | missing id → 404 | `@api` |
+| GET/HEAD | auth | 1 | no/invalid token → 401 | `@api`/`@cases` |
+| GET/HEAD | param validation | N (Tier 2) | EP/BVA per query field | `@cases` |
+| POST/PUT/PATCH/DELETE | contract + side-effect | 1 | happy + `@query` read-back | `@api`+`@query` |
+| POST/PUT/PATCH/DELETE | required matrix | N = #required fields | one row per omitted field → 400 | `@cases` |
+| POST/PUT/PATCH/DELETE | auth | 1 | no/invalid token → 401 | `@api`/`@cases` |
+| POST/PUT/PATCH/DELETE | idempotency | 1 | `@concurrent:N` + `@query` | `@concurrent`+`@query` |
+| POST/PUT/PATCH/DELETE | type/boundary/format | N (Tier 2) | per constrained field | `@cases` |
 
 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>}}`).
+Follow the coverage model's **assertion depth tiers** — a mutating success case must **prove the effect** (body value + `@query`/read-back), never status-only, and must not merely re-assert the input it just sent.
+- **Contract**: `@api:<name>` + `expect {{name.status}} is …` **and a body assertion** on a server-derived field (`{{name.body.<path>}}`); when the entry has a `schemaRef`, add `expect {{name.body}} matches schema [<Ref>]` for the full-shape contract (validates against `qa/api/schemas.yaml`).
 - **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).
@@ -37,8 +47,13 @@ Run `sungen audit --area <name>`; read `gateStatus` + `findings`. Then the **sem
 | `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 |
 | `VIEWPOINT-API-MANUAL-AUTOMATABLE` | a `@manual` scenario whose endpoint resolves is automatable → drop `@manual`, use `@api` (+ `@cases`); reserve `@manual` for genuine judgment cases |
+| `VIEWPOINT-API-REQUIRED-MATRIX` | a `required` field (from `fields:`) has no missing-field case → add a `@cases` row omitting it, asserting 4xx |
+| `VIEWPOINT-API-BOUNDARY` | a field with a `min/max/minLength/maxLength` constraint has no boundary case → add BVA `@cases` rows (`min-1/min/max/max+1`) |
+| `VIEWPOINT-API-FORMAT` | a `format`/`pattern`/enum field has no invalid-value case → add a `@cases` row with an ill-formed value → 4xx |
 | **`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.) |
 
+The `VIEWPOINT-API-REQUIRED-MATRIX`/`-BOUNDARY`/`-FORMAT` rows are the repair actions for those findings **once the field-driven gate sensors ship** (they will fire only when the endpoint has `fields:`, so a bare catalog raises none — no false demands). Until then, completeness comes from enumerating the matrix mechanically from `fields:` at generation time (see `sungen-api-coverage-model`), not from these gate findings.
+
 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
@@ -54,6 +69,25 @@ Stop when the gate PASSes + businessDepth ≥ 0.7, or the budget is exhausted
 
 A flow (`create → login → delete`) is a **Functional integration** test, **not** non-functional — don't file it under "Non-Functional". Reserve non-functional for perf/security/concurrency.
 
+## File upload (real files)
+`body:` carries only scalar fields — to send a **real file**, declare it in the catalog entry; the runtime reads the fixture from disk. Two forms, by how the server accepts the file:
+- **`files:`** → `multipart/form-data`, the file is a form part: `files: { file: { path: ":avatar", mimeType: image/png } }` (+ optional text `body:` fields alongside). Shorthand `files: { file: ":avatar" }`.
+- **`bodyFile:`** → raw binary body (the whole body IS the file's bytes, e.g. `application/octet-stream`): `bodyFile: { path: ":image", mimeType: application/octet-stream }`.
+
+Fixture path resolves cwd-relative/absolute first, else `qa/fixtures/<path>` (drop sample files there, reference by name from `test-data`). An empty resolved file param omits the part → use for missing-file `@cases` error rows. `files:`/`bodyFile:` are mutually exclusive. **Automate the upload success case with `@api`** — don't defer it to `@manual`.
+
+## Per-endpoint knobs & auth patterns
+- **Timeout** — a slow endpoint can override the datasource default (15s) with `timeout_ms: 30000` on its catalog entry (else the datasource `timeout_ms` applies).
+- **OAuth2 (pure API, no browser)** — no new grammar; it's `@api` chaining. Call the token endpoint, bind the token, thread it into later calls' `Bearer :token` header:
+  ```gherkin
+  @api:get_token(client_id={{client_id}},client_secret={{client_secret}}) @api:list_orders(token={{get_token.body.access_token}})
+  Scenario: VP-API-FLOW client-credentials token authorizes the call
+    Then expect {{get_token.status}} is 200
+    And expect {{list_orders.status}} is 200
+  ```
+  The token endpoint is a normal catalog entry (`POST /oauth/token`, form/JSON body); `list_orders` carries `headers: { authorization: "Bearer :token" }`. For a browser-authorized session instead, use `@hybrid` + `@auth:<role>`.
+- **Pagination** — use query params (`?page=:page&limit=:limit`, imported into `params`) + assert the page shape with plain field access (`{{list.body.next_page_token}}`, `{{list.body.items.length}}`); no special primitive needed.
+
 ## 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`.