@sun-asterisk/sungen 3.2.5 → 3.2.6

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`.

package/src/orchestrator/templates/ai-src/skills/sungen-gherkin-syntax/SKILL.md

@@ -118,6 +118,27 @@ Scenario: ...
 
 Path access on a bound result: `{{q.count}}`/`{{q.length}}`, `{{q.first.col}}`, `{{q.last.col}}`, `{{q[2].col}}`, `{{q.col}}` (= first row's col). `expect A is B` also supports `is at least` / `is at most` / `is not`. Tier-2 declarative (trivial inline, no catalog): `User see [<table>] row where [<col>] is {{v}} [has [<col2>] = "x"]`, `… no row where …`, `… count is {{n}}`. Full grammar + catalog/datasource/secret rules → **Advanced → Database** doc. Only emit DB steps when the project has a `database/` catalog / `datasources.yaml`.
 
+### API response assertions (optional API Driver)
+
+An `@api:<name>` call binds the response to `{{name}}` = `{ status, ok, body, headers }` (+ `ok_count`/`status_counts` under `@concurrent`). Assert with the same `expect A is B` grammar + path access:
+
+```gherkin
+@api:create_user(email={{email}}) @query:user_by_email(email={{email}})
+Scenario: ...
+  Then expect {{create_user.status}} is 201                    # status
+  And  expect {{create_user.body.id}} is at least {{one}}      # server-derived body field
+  And  expect {{user_by_email.count}} is {{one}}               # proof of effect (DB oracle)
+```
+
+Path access: `{{name.status}}`, `{{name.body.<path>}}` (dot/`[i]` nav), `{{name.headers.x-request-id}}` (dot form — hyphens are fine, no quotes/brackets), `{{name.ok_count}}`.
+
+Full-shape contract check: `expect {{name.body}} matches schema [Ref]` validates the response body against the named JSON Schema in `qa/api/schemas.yaml` (populated by `sungen api import`). Use alongside a couple of concrete field asserts, not instead of them.
+
+**Depth rule** (see `sungen-tc-review` API rubric):
+- **Success (2xx)** → assert status **and** ≥1 body field; a **mutating** success must also prove the effect (`@query` read-back, follow-up GET, or `@concurrent` `ok_count`). Never status-only.
+- **Error (4xx/5xx)** → assert the status (via `@cases` `expect_status` or an explicit `is 4xx`); assert the error message field when the contract defines one.
+- **Anti-pattern** — re-asserting the value you just sent (`{{x.body.email}} is {{email}}` on the thing you created) proves little; assert a **server-derived** field (id, timestamp, computed status) or read it back.
+
 ### States
 
 `hidden` `visible` `disabled` `enabled` `checked` `unchecked` `focused` `empty` `loading` `selected` `sorted ascending` `sorted descending`

package/src/orchestrator/templates/ai-src/skills/sungen-selector-fix/SKILL.md

@@ -84,6 +84,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
    - **Typical mismatch cases**: Gherkin uses English label (`[Submit]`) but app displays Vietnamese (`"Gửi"`); placeholder is descriptive (`"Nhập email của bạn"`) not a bare field name (`"Email"`); button text includes an icon glyph before/after the word.
 7. **Substring ambiguity check**: for each `role` + `name` selector, check if any other element in the snapshot has a name that **contains** this name as a substring (e.g., `"Đăng ký"` vs `"Đăng ký bằng Google"`). If yes → add `exact: true` to prevent strict mode violation at runtime.
 8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
+   - **Type-collision check** (see `sungen-selector-keys` § Collision rule): before writing a base key, check whether it already exists with a *different* `type`. If so, give **both** entries a `--type` suffix instead of clobbering or sharing the base key — a base-key entry of the wrong type gets picked up by any step referencing that label. Watch `page` especially: a `[X] page` step reads `value` as a URL, so if `X` already holds a button (`value: 'button'`) the assertion compiles to `toHaveURL(/button/)`. Write `X--page` (URL from the live page / feature `Path:`) alongside `X--button`.
 9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
 10. **Compile**: **Screen**: `sungen generate --screen <screen>`. **Flow**: `sungen generate --flow <flow>`. Then proceed to Phase 1.
 
@@ -97,6 +98,7 @@ When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen
 - Writing XPath or class-based CSS selectors → breaks on DOM/style refactoring. Use role/testid/text/label/placeholder from the accessibility tree.
 - Falling back to `locator: 'div.some-class > span'` when the element IS visible in the accessibility snapshot with a role + name → the snapshot gives you `getByRole` for free; use it.
 - Overwriting user-authored selectors → always merge.
+- Reusing a base key for two element types (e.g. a `[X] button` and a `[X] page`) → the wrong-type entry wins on lookup; disambiguate with `--type` suffixes (see step 8 type-collision check).
 
 ---
 

package/src/orchestrator/templates/ai-src/skills/sungen-selector-keys/SKILL.md

@@ -88,6 +88,39 @@ add campaign--text:
   value: 'Add Campaign'
 ```
 
+### Collision rule (MANDATORY)
+
+**Before writing a base key, check whether it already exists with a *different* `type`.**
+If it does, DO NOT overwrite it and DO NOT let the two share the base key — give **each** entry
+its own `--type` suffix. A key match alone does not carry type: the resolver walks
+`key--type` → `key` (see § Lookup Priority), so a base-key entry of the wrong type will be
+picked up by any step referencing that label, regardless of the type the step expects.
+
+The `page` type is the sharpest trap. A page step (`Then User see [X] page`) reads the entry's
+`value` as a **URL**. If key `X` already holds a `role`/button entry, the page step resolves that
+button and emits `toHaveURL(/button/)` — a literal button label treated as a URL path.
+
+```yaml
+# Gherkin: `When User click [読取結果一覧] button`  AND  `Then User see [読取結果一覧] page`
+# WRONG — one base key, page step inherits the button's value ('button') as a URL:
+読取結果一覧:
+  type: 'role'
+  value: 'button'
+  name: '読取結果一覧'
+
+# RIGHT — disambiguate by type; the page entry carries the real URL:
+読取結果一覧--button:
+  type: 'role'
+  value: 'button'
+  name: '読取結果一覧'
+
+読取結果一覧--page:
+  type: 'page'
+  value: '/reading-results'   # captured from the live page, or the feature Path:
+```
+
+If the label is used by only ONE type, the base key (no suffix) is fine — suffix only on collision.
+
 Type aliases (normalized automatically):
 | Gherkin type | Normalized suffix |
 |---|---|

package/src/orchestrator/templates/ai-src/skills/sungen-tc-review/SKILL.md

@@ -159,6 +159,12 @@ Build a mapping table: for each applicable group, does the feature have a matchi
 | **Syntax compliance** — steps match `sungen-gherkin-syntax` patterns, correct `[Ref] type with {{v}}`, no bare `is visible` | 4 |
 | Grouping — each case has 2–7 related assertions for the same action | 4 |
 
+**API scenarios (`@api`) — depth rubric:** a success case scores on Assertion Quality only if it proves the effect, not just the status. Apply per scenario:
+- **status-only mutating success = fail the "Specific" check** — `expect {{x.status}} is 201` alone proves nothing happened. Require a server-derived body field **and** a proof of effect (`@query` read-back / follow-up GET / `@concurrent` `ok_count`).
+- **read contract** — status + ≥1 body field (medium is acceptable for reads).
+- **error (4xx)** — the status IS the assertion; also check the error-message field when the contract defines one.
+- **anti-pattern (counts against "Avoids anti-patterns")** — re-asserting the input just sent instead of a server-derived value.
+
 ### Test Data (10)
 
 | Check | Pts |

package/src/orchestrator/templates/specs-api.ts

@@ -48,6 +48,37 @@ function loadConfig(): Record<string, ApiDataSource> {
 function substitute(text: string, params: Record<string, any>): string {
   return text.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => encodeURIComponent(String(params[p] ?? '')));
 }
+/** Bind `:param` tokens WITHOUT URL-encoding — for headers, body-file paths, and multipart file paths. */
+function substituteRaw(text: string, params: Record<string, any>): string {
+  return text.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => String(params[p] ?? ''));
+}
+/** Delete any case-insensitive variant of a header (HTTP header names are case-insensitive, but a
+ *  plain object keys on exact case — so a datasource `Content-Type` and our `content-type` would
+ *  both be sent). Call before setting, or to let Playwright own the header (multipart boundary). */
+function deleteHeader(headers: Record<string, string>, name: string): void {
+  const lower = name.toLowerCase();
+  for (const k of Object.keys(headers)) if (k.toLowerCase() === lower) delete headers[k];
+}
+
+/** A multipart file field embedded by the compiler (string = shorthand for { path }). */
+type FileSpec = string | { path: string; mimeType?: string; filename?: string; name?: string };
+
+const MIME: Record<string, string> = {
+  png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp',
+  svg: 'image/svg+xml', pdf: 'application/pdf', csv: 'text/csv', txt: 'text/plain',
+  json: 'application/json', xml: 'application/xml', zip: 'application/zip', mp4: 'video/mp4',
+};
+export function inferMime(name: string): string {
+  return MIME[(name.split('.').pop() || '').toLowerCase()] || 'application/octet-stream';
+}
+/** Resolve a fixture path: cwd-relative/absolute first, else qa/fixtures/<path>. */
+export function resolveFixture(p: string, label: string): string {
+  const direct = path.isAbsolute(p) ? p : path.join(process.cwd(), p);
+  if (fs.existsSync(direct)) return direct;
+  const inFixtures = path.join(process.cwd(), 'qa', 'fixtures', p);
+  if (fs.existsSync(inFixtures)) return inFixtures;
+  throw new Error(`API Driver: ${label} — fixture "${p}" not found (looked in ${direct} and qa/fixtures/${p}).`);
+}
 
 /**
  * Join a datasource base URL with a catalog path. Concatenate rather than rely on Playwright's
@@ -82,7 +113,7 @@ class ApiClient {
    */
   async call(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; headers?: Record<string, string>; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
     params: Record<string, any> = {},
     opts: { storageState?: string } = {},
   ): Promise<{ status: number; ok: boolean; body: any; headers: Record<string, string> }> {
@@ -94,7 +125,7 @@ class ApiClient {
     const headers: Record<string, string> = { ...(conf.headers || {}) };
     // catalog headers; :param tokens bind at runtime — raw (no URL-encoding, unlike the path)
     for (const [k, v] of Object.entries(req.headers || {}))
-      headers[k] = String(v).replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, (_m, p) => String(params[p] ?? ''));
+      headers[k] = substituteRaw(String(v), params);
     // Body: substitute `:param` into the body template (object values), then encode per `encoding`.
     let body: any;
     if (req.body !== undefined && req.body !== null) {
@@ -102,8 +133,39 @@ class ApiClient {
     }
     // Map the wire format to the right Playwright option (#345): json → data (application/json,
     // default), form → form (application/x-www-form-urlencoded), multipart → multipart (form-data).
+    // A `files` block is a real upload: read each fixture into a { name, mimeType, buffer } part and
+    // send multipart, with any `body` values riding along as text fields.
     const bodyOpt: Record<string, unknown> = {};
-    if (body !== undefined) {
+    if (req.bodyFile) {
+      // Raw-binary body: the whole request body is the fixture's bytes. Content-Type comes from the
+      // spec's mimeType (default application/octet-stream) — this is what octet-stream upload
+      // endpoints expect (a multipart body would be rejected 415).
+      const spec = typeof req.bodyFile === 'string' ? { path: req.bodyFile } : req.bodyFile;
+      const fpath = substituteRaw(String(spec.path), params);
+      if (fpath) {
+        const resolved = resolveFixture(fpath, label);
+        bodyOpt.data = fs.readFileSync(resolved);
+        // Own the Content-Type: drop any datasource default (case-insensitive) so we don't send both.
+        deleteHeader(headers, 'content-type');
+        headers['content-type'] = spec.mimeType ?? 'application/octet-stream';
+      }
+    } else if (req.files && Object.keys(req.files).length) {
+      const mp: Record<string, any> = {};
+      if (body && typeof body === 'object')
+        for (const [k, v] of Object.entries(body as Record<string, unknown>)) mp[k] = typeof v === 'string' ? v : JSON.stringify(v);
+      for (const [field, raw] of Object.entries(req.files)) {
+        const spec = typeof raw === 'string' ? { path: raw } : raw;
+        const fpath = substituteRaw(String(spec.path), params);
+        if (!fpath) continue; // empty param → omit the part (a missing-file / wrong-type error row)
+        const resolved = resolveFixture(fpath, label);
+        const filename = spec.filename ?? path.basename(resolved);
+        mp[spec.name ?? field] = { name: filename, mimeType: spec.mimeType ?? inferMime(filename), buffer: fs.readFileSync(resolved) };
+      }
+      // Playwright generates the multipart/form-data Content-Type (with boundary); drop any datasource
+      // default Content-Type so it doesn't conflict with / duplicate the generated one.
+      deleteHeader(headers, 'content-type');
+      bodyOpt.multipart = mp;
+    } else if (body !== undefined) {
       const enc = req.encoding ?? 'json';
       if (enc === 'form') bodyOpt.form = body;
       else if (enc === 'multipart') bodyOpt.multipart = body;
@@ -115,7 +177,7 @@ class ApiClient {
     // authenticated cookies. Disposed per call so no request context lingers and hangs the process.
     const ctx: APIRequestContext = await request.newContext({
       extraHTTPHeaders: headers,
-      timeout: conf.timeout_ms ?? 15000,
+      timeout: req.timeout ?? conf.timeout_ms ?? 15000, // per-endpoint override → datasource → 15s
       ...(opts.storageState ? { storageState: opts.storageState } : {}),
     });
     try {
@@ -139,7 +201,7 @@ class ApiClient {
    */
   async callN(
     label: string,
-    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; headers?: Record<string, string>; datasource?: string },
+    req: { method: string; path: string; body?: unknown; encoding?: 'json' | 'form' | 'multipart'; files?: Record<string, FileSpec>; bodyFile?: FileSpec; headers?: Record<string, string>; timeout?: number; datasource?: string },
     params: Record<string, any> = {},
     n = 1,
     opts: { storageState?: string } = {},
@@ -160,6 +222,57 @@ class ApiClient {
       statuses: responses.map((r) => r.status),
     };
   }
+
+  /**
+   * Validate a response body against a named JSON Schema from `qa/api/schemas.yaml` (populated by
+   * `sungen api import` from the OpenAPI `components.schemas`). Backs `expect {{name.body}} matches
+   * schema [Ref]` — a full-contract check beyond individual field asserts. Returns `{ ok, errors }`;
+   * the generated assertion feeds `errors` into the failure message. Uses Ajv (a QA-project dep).
+   */
+  assertSchema(value: unknown, schemaName: string): { ok: boolean; errors: string } {
+    return assertSchemaImpl(value, schemaName);
+  }
+}
+
+// ── Response-schema validation (Ajv) ─────────────────────────────────────────────────────────────
+// Schemas live in qa/api/schemas.yaml (name → JSON Schema, incl. #/components/schemas/* $refs).
+// Loaded + compiled lazily so a project that never asserts a schema needs no Ajv resolution.
+let _apiSchemas: Record<string, any> | null | undefined;
+function loadApiSchemas(): Record<string, any> {
+  if (_apiSchemas !== undefined) return _apiSchemas || {};
+  const file = [path.join(process.cwd(), 'qa', 'api', 'schemas.yaml'), path.join(process.cwd(), 'schemas.yaml')].find((f) => fs.existsSync(f));
+  if (!file) { _apiSchemas = null; return {}; }
+  const { parse } = require('yaml');
+  _apiSchemas = (parse(fs.readFileSync(file, 'utf8')) as Record<string, any>) || {};
+  return _apiSchemas || {};
+}
+
+let _ajv: any;
+function getAjv(): any {
+  if (_ajv) return _ajv;
+  const Ajv = require('ajv');
+  _ajv = new Ajv({ allErrors: true, strict: false });
+  try { require('ajv-formats')(_ajv); } catch { /* formats optional */ }
+  // Register every named schema under its component ref so inter-schema $refs resolve.
+  for (const [name, schema] of Object.entries(loadApiSchemas())) {
+    try { _ajv.addSchema(schema, `#/components/schemas/${name}`); } catch { /* dup/invalid → skip */ }
+  }
+  return _ajv;
+}
+
+function assertSchemaImpl(value: unknown, schemaName: string): { ok: boolean; errors: string } {
+  const schema = loadApiSchemas()[schemaName];
+  if (!schema) return { ok: false, errors: `schema "${schemaName}" not found in qa/api/schemas.yaml` };
+  let validate: any;
+  try {
+    const ajv = getAjv();
+    validate = ajv.getSchema(`#/components/schemas/${schemaName}`) || ajv.compile(schema);
+  } catch (e: any) {
+    return { ok: false, errors: `schema "${schemaName}" failed to compile: ${e?.message || e}` };
+  }
+  const ok = validate(value) === true;
+  const errors = ok ? '' : (validate.errors || []).map((e: any) => `${e.instancePath || '(root)'} ${e.message}`).join('; ') || 'did not match schema';
+  return { ok, errors };
 }
 
 export const api = new ApiClient();

package/src/orchestrator/templates/specs-test-data.ts

@@ -48,7 +48,26 @@ export class TestDataLoader {
     if (value === undefined || value === null) {
       throw new Error(`Test data key not found: ${key}`);
     }
-    return String(value);
+    return this.interpolate(String(value));
+  }
+
+  /**
+   * Substitute embedded `{{ref}}` cross-references inside a resolved string value.
+   * Each ref is looked up via resolve() (flat key, @cases row column, or dotted path),
+   * so `expected_operator_id_label: 'ID : {{operator.id}}'` yields the real value at
+   * runtime — matching the delivery report's substituteTestDataVars. `$`-prefixed
+   * dynamic vars ({{$timestamp}} …) are already substituted at load time and never
+   * match `[\w.]+`, so they are left untouched. Resolution recurses (a referenced value
+   * may itself hold refs) up to a depth cap that guards against reference cycles; an
+   * unknown or empty ref is left as the literal `{{ref}}` — never blanked.
+   */
+  private interpolate(value: string, depth: number = 0): string {
+    if (depth > 10 || value.indexOf('{{') === -1) return value;
+    return value.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (match, ref: string) => {
+      const resolved = this.resolve(ref);
+      if (resolved === undefined || resolved === null || resolved === '') return match;
+      return this.interpolate(String(resolved), depth + 1);
+    });
   }
 
   /**