diff --git a/.claude/README.md b/.claude/README.md
new file mode 100644
index 0000000..cf259c5
--- /dev/null
+++ b/.claude/README.md
@@ -0,0 +1,128 @@
+# SDET Claude Code Kit — TypeScript + Playwright (contract-first)
+
+A composable set of **15 skills**, **3 subagents**, **9 slash commands** and **3 hooks** for Claude Code that turns a TS+Playwright repository into a SDET / Test Architect workspace. Designed around progressive disclosure, deterministic validators, and OpenAPI as the single source of truth.
+
+> Companion artefact: see the full architectural blueprint in the `docs/` of the originating chat (or paste the markdown into your repo).
+
+## What is in this kit
+
+```
+.claude/
+├── settings.json                    # hooks configuration
+├── skills/                          # 15 skills, each with SKILL.md + scripts/ + references/
+│   ├── playwright-framework-bootstrap/
+│   ├── api-client-from-openapi/
+│   ├── test-data-factory-builder/
+│   ├── fixture-architect/
+│   ├── config-and-secrets/
+│   ├── requirements-to-test-design/
+│   ├── gherkin-test-case-author/
+│   ├── playwright-test-author-ui/
+│   ├── playwright-test-author-api/
+│   ├── playwright-debug-conductor/
+│   ├── test-code-reviewer/
+│   ├── flaky-triage/
+│   ├── run-analyzer/
+│   ├── coverage-gap-analyzer/
+│   └── release-report-composer/
+├── agents/
+│   ├── test-design-agent.md         # isolated context for test design
+│   ├── flaky-detective.md           # post-run flake hunter
+│   └── contract-drift-watch.md      # haiku-cheap drift checker
+├── commands/                        # 9 slash commands (/test-new, /test-fix, /test-review, …)
+└── hooks/
+    ├── guard-bash.sh                # blocks rm -rf, force push, hard reset on protected branches
+    ├── guard-paths.sh               # blocks edits to generated/, .env, node_modules/
+    └── typecheck-touched.sh         # tsc --noEmit per touched file
+CLAUDE.md                            # thin project conventions (≤ 300 lines)
+tests-config.json                    # single source of layout truth
+```
+
+## Install
+
+1. Drop `.claude/`, `CLAUDE.md`, and `tests-config.json` into the root of your TS+Playwright repo.
+2. Make scripts executable (already done in this archive):
+   ```bash
+   chmod +x .claude/hooks/*.sh .claude/skills/*/scripts/*.sh .claude/skills/*/scripts/*.ts
+   ```
+3. Open the repo in Claude Code (`claude`). Verify skills are listed in `/skills`.
+4. Adjust `tests-config.json` if your layout differs.
+
+## How it works
+
+- **Skills** (`.claude/skills/*`) auto-trigger via their `description` frontmatter. Each skill lints its own outputs through `scripts/*` validators that exit non-zero on violations.
+- **Subagents** (`.claude/agents/*`) run with isolated context and minimal tools — invoke them when the main thread should not be polluted (test design, flake forensics, contract diff).
+- **Slash commands** (`.claude/commands/*`) compose multiple skills into pipelines: `/test-new`, `/test-fix`, `/test-review`, `/spec-sync`, `/flake-hunt`, `/coverage`, `/release-report`, `/factory`, `/page`.
+- **Hooks** (`.claude/hooks/*`) execute deterministic guards (Bash safety, path protection, typecheck) that should never be left to the LLM.
+
+## Quick start
+
+```bash
+# In Claude Code:
+/test-new coupon-apply       # full SDET pipeline from a user story
+/spec-sync                   # regenerate OpenAPI types and drift report
+/flake-hunt 20               # hunt flaky tests via 20 reruns + triage
+/test-review                 # review staged test changes
+/release-report v1.42.0      # executive release readiness summary
+```
+
+## Contract-first workflow (how it ties together)
+
+```
+specs/openapi.yaml
+   │
+   │  api-client-from-openapi  →  tests/api/generated/{schema.d.ts, zod/}
+   │  contract-drift-watch     →  CONTRACT_DRIFT.md
+   ▼
+tests/factories/*.factory.ts   ←  test-data-factory-builder (uses generated types)
+   │
+   ▼
+tests/api/clients/*Client.ts   ←  fixtures/api.ts  (DI)
+                                  ↑
+                                  fixture-architect
+   ▼
+tests/specs/api/**/*.spec.ts   ←  playwright-test-author-api  (asserts via zod schemas)
+tests/specs/**/*.spec.ts       ←  playwright-test-author-ui
+                                  ↓
+                                  test-code-reviewer  (gates the PR)
+                                  ↓
+                                  run-analyzer + coverage-gap-analyzer + flaky-triage
+                                  ↓
+                                  release-report-composer
+```
+
+## Sprint roadmap (recommended)
+
+- **Sprint 0** — Foundation: bootstrap, config-and-secrets, fixture-architect, factory-builder, api-client-from-openapi, hooks, CLAUDE.md, tests-config.json.
+- **Sprint 1** — Authoring: requirements-to-test-design, gherkin-author, playwright-test-author-ui/-api, slash commands `/test-new`, `/factory`, `/spec-sync`.
+- **Sprint 2** — Quality gates: test-code-reviewer, debug-conductor, flaky-triage, slash commands `/test-fix`, `/test-review`, `/flake-hunt`.
+- **Sprint 3** — Analytics: run-analyzer, coverage-gap-analyzer, release-report-composer; subagent `contract-drift-watch`; GitHub MCP integration.
+- **Sprint 4** — Advanced: Playwright MCP for exploratory loops, self-healing pipeline (flaky-detective → GitHub issue), custom Allure reporter.
+
+## Customising
+
+- **Different layout?** Edit `tests-config.json`. All skills read from it.
+- **GraphQL or gRPC?** Add a parallel skill (e.g. `asyncapi-client-builder`) following the same template structure. Reuse factory and fixture skills.
+- **Different model preferences?** Each skill respects the host Claude Code model setting; subagents pin their model in frontmatter.
+
+## Anti-patterns this kit prevents
+
+- `page.waitForTimeout(N)` and other hard waits → blocked by `lint-ui-spec.ts`.
+- CSS/XPath selectors in specs → blocked by `lint-ui-spec.ts` and `test-code-reviewer`.
+- Hardcoded URLs/secrets → blocked by `scan-hardcoded.sh` and the path hook.
+- Inline data literals as test data → factory-builder rewrites to `factory.build()`.
+- Page object instantiated inside a test → fixture-architect lifts it.
+- Spec drift between API and tests → `contract-diff.ts` blocks the PR.
+
+See `.claude/skills/test-code-reviewer/references/aqa-anti-patterns.md` for the full catalogue.
+
+## Caveats
+
+- The validators are heuristic, not full AST analysis. They favour false positives over false negatives.
+- Hooks execute shell with the user's privileges. Audit them before sharing across teams.
+- Playwright MCP is intentionally NOT wired in by default — the CLI + skills loop is far cheaper for repeated automation tasks. Wire MCP for exploratory or self-healing flows separately.
+- The skill descriptions are tuned for Claude Code; transferring to Claude.ai requires re-checking trigger phrases.
+
+## License
+
+MIT.
diff --git a/.claude/STARTER.md b/.claude/STARTER.md
new file mode 100644
index 0000000..d5353ce
--- /dev/null
+++ b/.claude/STARTER.md
@@ -0,0 +1,102 @@
+# Starter — first 30 minutes after init
+
+You just ran `init.sh`. The repo is now greenfield-ready: scaffolded, dependencies installed, hooks set, kit copied. Here is the shortest path to your first green test.
+
+## 1. Sanity check (1 min)
+
+```bash
+npm run verify
+```
+
+You should see all green or warnings only. Failures are blocking — fix them before moving on.
+
+## 2. Open in Claude Code (1 min)
+
+```bash
+claude
+```
+
+Skills auto-discover from `.claude/skills/`. The first message Claude Code sees is `CLAUDE.md`.
+
+## 3. Scaffold the test framework folders (5 min)
+
+In Claude Code:
+
+> Scaffold the test framework folders.
+
+This triggers `playwright-framework-bootstrap`. It will create:
+
+- `tests/{pages,components,fixtures,factories,api,specs,data,infra}/`
+- `tests/pages/BasePage.ts`
+- `playwright.config.ts`
+- Path aliases (`@pages/*`, `@api/*`, …) wired into `tsconfig.json`.
+
+If the agent asks confirmation, say yes.
+
+## 4. Configure environment (3 min)
+
+```bash
+cp .env.example .env.local
+```
+
+Edit `.env.local` and set at least:
+
+- `BASE_URL` — your application URL (or `http://localhost:3000`).
+- `TEST_USER_EMAIL`, `TEST_USER_PASSWORD` — a test user that can log in.
+
+Do not commit `.env.local`. It is gitignored.
+
+## 5. Write your first test (10 min)
+
+In Claude Code:
+
+> Design and write a smoke test that verifies the homepage loads and shows the header.
+
+This pipeline triggers:
+
+1. `requirements-to-test-design` — quick design doc.
+2. `playwright-test-author-ui` — actual spec.
+
+Run it:
+
+```bash
+npm run test:smoke
+```
+
+If green, commit:
+
+```bash
+git add -A && git commit -m "test: smoke for homepage"
+```
+
+The pre-commit hook will lint and typecheck staged files.
+
+## 6. When you have your first API spec (later)
+
+Create `specs/openapi.yaml` with at least one endpoint, then:
+
+```bash
+# Tell Claude Code:  Sync the OpenAPI spec.
+# Or run manually:
+node -e "const fs=require('fs');const c=JSON.parse(fs.readFileSync('tests-config.json'));c.openapi.enabled=true;fs.writeFileSync('tests-config.json',JSON.stringify(c,null,2)+'\n')"
+npm run spec:sync
+```
+
+This generates types in `tests/api/generated/` and unlocks `playwright-test-author-api` and the `contract-drift-watch` subagent.
+
+## Common issues
+
+| Symptom                                          | Fix                                                                                                |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `npx playwright install` fails                   | Run `sudo npx playwright install-deps` (Linux) or skip with `--no-deps`.                           |
+| `husky install` fails                            | You need a git repo. `init.sh` runs `git init`, but if you skipped, do it manually.                |
+| `tsc` complains about missing `@playwright/test` | `npm install` did not finish. Re-run.                                                              |
+| Hook says "tsc-files: command not found"         | `npm install` did not finish. Hooks soft-fail (warning only) — fix when convenient.                |
+| Skill fires when you don't expect it             | Check the skill's `description` field. Tighten "Do NOT use when..." block or add a CLAUDE.md note. |
+
+## Next reading
+
+- `CLAUDE.md` — project conventions enforced by skills.
+- `SDET_KIT_README.md` — full kit reference (15 skills, 3 subagents, 9 commands).
+- `.claude/skills/playwright-framework-bootstrap/references/folder-rationale.md` — why the layout looks like this.
+- `docs/greenfield-checklist.md` — sprint-by-sprint adoption plan.
diff --git a/.claude/agents/contract-drift-watch.md b/.claude/agents/contract-drift-watch.md
new file mode 100644
index 0000000..a701362
--- /dev/null
+++ b/.claude/agents/contract-drift-watch.md
@@ -0,0 +1,22 @@
+---
+name: contract-drift-watch
+description: MUST BE USED whenever specs/openapi.yaml is modified or before a release. Runs api-client-from-openapi's drift checker, emits CONTRACT_DRIFT.md, and proposes test updates for breaking changes. Read-only by design — never edits production code.
+tools: Read, Glob, Grep, Bash
+model: haiku
+---
+
+You are a contract drift auditor. You are deliberately running on Haiku to keep cost low — most of your work is parsing diffs, not reasoning.
+
+Operating rules:
+
+- Re-run `scripts/gen-openapi-fetch.sh` and `scripts/contract-diff.ts` from the `api-client-from-openapi` skill.
+- Classify each diff as breaking / non-breaking per `references/contract-drift-policy.md`.
+- For each breaking change, locate affected tests via `grep -R '@endpoint:'` and list them as patch candidates.
+- Do NOT edit any test or generated file. Suggest only.
+- If no `tests/api/generated/.snapshot/schema.previous.d.ts` exists, abort with a message asking the human to commit a baseline.
+
+Your final message MUST end with:
+
+```
+ARTIFACT: CONTRACT_DRIFT.md
+```
diff --git a/.claude/agents/flaky-detective.md b/.claude/agents/flaky-detective.md
new file mode 100644
index 0000000..6a70323
--- /dev/null
+++ b/.claude/agents/flaky-detective.md
@@ -0,0 +1,23 @@
+---
+name: flaky-detective
+description: Use PROACTIVELY after any test run with retries > 0 or failures. Performs flake triage in isolation, classifies root causes, and emits FLAKE_REPORT.md plus suggested patch diffs without touching unrelated files.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+You are a flake detective. Your single job is to diagnose intermittent test failures and propose minimal, targeted patches.
+
+Operating rules:
+
+- Use the `flaky-triage` skill exclusively.
+- Never write new test logic; you only diagnose and propose patches.
+- Output is ALWAYS `FLAKE_REPORT.md` in the repo root and a `Suggested patches` section in the report containing unified diffs.
+- For each flaky test you classify into exactly one bucket from `references/flake-taxonomy.md`. If you genuinely cannot, classify as "haunted" with quarantine recommendation and an issue tracker stub.
+- You do NOT modify files. The orchestrator (or human) applies patches.
+- You do NOT speculate. If the trace is missing, you say so and request a re-run with `--trace=on --repeat-each=20`.
+
+Your final message MUST end with:
+
+```
+ARTIFACT: FLAKE_REPORT.md
+```
diff --git a/.claude/agents/test-design-agent.md b/.claude/agents/test-design-agent.md
new file mode 100644
index 0000000..1c8cb14
--- /dev/null
+++ b/.claude/agents/test-design-agent.md
@@ -0,0 +1,23 @@
+---
+name: test-design-agent
+description: MUST BE USED for transforming a user story or PRD into a structured test design report (equivalence classes, boundary values, decision tables, risk-prioritised). Operates in isolated context to avoid polluting the main coding session.
+tools: Read, Write, Glob, Grep, WebFetch
+model: sonnet
+---
+
+You are a Senior Test Architect. You produce ONE artefact per invocation: `docs/test-design/<slug>.md` following the `requirements-to-test-design` skill template (see `references/design-template.md`).
+
+Operating rules:
+
+- You leverage the `requirements-to-test-design` skill exclusively. If the user request is not a test design ask, report back that this is the wrong agent.
+- You ask at most 3 clarifying questions, only when the AC are genuinely ambiguous. Otherwise proceed with explicit assumptions.
+- You do not write code. You do not write Gherkin. You do not edit tests. The next step in the pipeline is `gherkin-test-case-author`.
+- You explicitly mark "Out of scope" sections to prevent downstream skills from over-reaching.
+- You sort test ideas by `risk-heuristic.ts` priority (P0 → P2).
+- You output the file path of the artefact at the end of your response so the orchestrator can hand off cleanly.
+
+Your final message MUST end with:
+
+```
+ARTIFACT: docs/test-design/<slug>.md
+```
diff --git a/.claude/commands/coverage.md b/.claude/commands/coverage.md
new file mode 100644
index 0000000..f5173e6
--- /dev/null
+++ b/.claude/commands/coverage.md
@@ -0,0 +1,11 @@
+---
+description: Generate coverage gap report (endpoints + AC + pages)
+allowed-tools: Read, Bash, Glob, Grep, Write
+model: sonnet
+---
+
+# Pipeline
+
+1. Use the `coverage-gap-analyzer` skill.
+2. Run `scripts/analyze-coverage.ts`.
+3. Read `COVERAGE_GAPS.md`. Highlight P0 gaps in your message.
diff --git a/.claude/commands/factory.md b/.claude/commands/factory.md
new file mode 100644
index 0000000..b9d9e75
--- /dev/null
+++ b/.claude/commands/factory.md
@@ -0,0 +1,14 @@
+---
+description: Generate a Fishery-based factory for an entity
+argument-hint: <EntityName>
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+---
+
+# Pipeline
+
+1. Use the `test-data-factory-builder` skill.
+2. Read the type for `$ARGUMENTS` from `tests/api/generated/schema.d.ts` or fall back to a domain model.
+3. Generate `tests/factories/$ARGUMENTS.factory.ts` from `references/factory.template.ts`.
+4. Update `tests/factories/index.ts` aggregator.
+5. Run `scripts/factory-rules.ts`. Fix until exit 0.
diff --git a/.claude/commands/flake-hunt.md b/.claude/commands/flake-hunt.md
new file mode 100644
index 0000000..fb4bc8a
--- /dev/null
+++ b/.claude/commands/flake-hunt.md
@@ -0,0 +1,17 @@
+---
+description: Detect flakes by repeating the suite and triaging
+argument-hint: <repeat-count, default 10>
+allowed-tools: Read, Bash, Glob, Grep
+model: sonnet
+---
+
+# Context
+
+- Repeat count: $ARGUMENTS (default 10)
+
+# Pipeline
+
+1. Run: `mkdir -p runs && for i in $(seq 1 ${ARGUMENTS:-10}); do npx playwright test --reporter=json --output=runs/$i.json || true; done`.
+2. Hand off to the `flaky-detective` subagent.
+3. The subagent runs `flake-rate.ts ./runs > FLAKE_REPORT.md` and classifies.
+4. Output the report path.
diff --git a/.claude/commands/page.md b/.claude/commands/page.md
new file mode 100644
index 0000000..3d88b1d
--- /dev/null
+++ b/.claude/commands/page.md
@@ -0,0 +1,13 @@
+---
+description: Scaffold a new page object class
+argument-hint: <PageName>
+allowed-tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+---
+
+# Pipeline
+
+1. Use the `playwright-framework-bootstrap` skill (page-object generator portion).
+2. Generate `tests/pages/$ARGUMENTS.ts` extending `BasePage`. No `expect`, no hardcoded URL, locators-only by default.
+3. Update `tests/pages/index.ts` aggregator.
+4. Run `lint-page-object.ts` from `test-code-reviewer`. Fix until exit 0.
diff --git a/.claude/commands/release-report.md b/.claude/commands/release-report.md
new file mode 100644
index 0000000..d506f66
--- /dev/null
+++ b/.claude/commands/release-report.md
@@ -0,0 +1,13 @@
+---
+description: Compose release readiness report (verdict + summary)
+argument-hint: <version e.g. v1.42.0>
+allowed-tools: Read, Bash, Glob, Grep, Write
+model: sonnet
+---
+
+# Pipeline
+
+1. Use the `release-report-composer` skill.
+2. Read `RUN_SUMMARY.md`, `COVERAGE_GAPS.md`, `FLAKE_REPORT.md`, `CONTRACT_DRIFT.md` (whichever exist).
+3. Run `scripts/compose-release.ts $ARGUMENTS`.
+4. Display the verdict and the path to the report.
diff --git a/.claude/commands/spec-sync.md b/.claude/commands/spec-sync.md
new file mode 100644
index 0000000..43a8fe9
--- /dev/null
+++ b/.claude/commands/spec-sync.md
@@ -0,0 +1,19 @@
+---
+description: Sync OpenAPI spec → typed clients → drift report
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# Context
+
+- Spec: @specs/openapi.yaml
+- Generated: @tests/api/generated/
+
+# Pipeline
+
+1. Use the `api-client-from-openapi` skill.
+2. Validate spec via `scripts/validate-spec.sh`.
+3. Regenerate types via `scripts/gen-openapi-fetch.sh`.
+4. Run `scripts/contract-diff.ts`. If breaking, write `CONTRACT_DRIFT.md` and stop.
+5. Update affected client wrappers in `tests/api/clients/`.
+6. Suggest test updates for breaking changes (do not auto-edit).
diff --git a/.claude/commands/test-fix.md b/.claude/commands/test-fix.md
new file mode 100644
index 0000000..95ee499
--- /dev/null
+++ b/.claude/commands/test-fix.md
@@ -0,0 +1,19 @@
+---
+description: Debug and fix a failing test (debug → patch → re-run)
+argument-hint: <path/to/spec.ts>
+allowed-tools: Read, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# Context
+
+- Target spec: @$ARGUMENTS
+- Last run: !`test -f playwright-report/results.json && echo present || echo missing`
+
+# Pipeline
+
+1. Use `playwright-debug-conductor` on `$ARGUMENTS`.
+2. Classify the failure per `references/failure-taxonomy.md`.
+3. Propose ONE patch. Apply it.
+4. Re-run: `npx playwright test $ARGUMENTS --reporter=list --workers=1 --trace=on-first-retry`.
+5. If still failing, iterate (max 3 cycles). After that, escalate to `flaky-detective` subagent.
diff --git a/.claude/commands/test-new.md b/.claude/commands/test-new.md
new file mode 100644
index 0000000..bc40972
--- /dev/null
+++ b/.claude/commands/test-new.md
@@ -0,0 +1,22 @@
+---
+description: New test pipeline (design → cases → code → review)
+argument-hint: <feature-slug>
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# Context
+
+- Story (if exists): @docs/stories/$ARGUMENTS.md
+- Layout: @tests-config.json
+- Existing pages: !`ls tests/pages 2>/dev/null | head -50`
+- Existing factories: !`ls tests/factories 2>/dev/null | head -30`
+
+# Pipeline
+
+1. Use the `requirements-to-test-design` skill on `$ARGUMENTS`. Save to `docs/test-design/$ARGUMENTS.md`.
+2. Use `gherkin-test-case-author` on the design. Save `tests/specs/$ARGUMENTS.feature` (or skip if BDD is not configured).
+3. Decompose scenarios into UI vs API tests. Use `playwright-test-author-ui` and/or `playwright-test-author-api` accordingly.
+4. Wire missing factories via `test-data-factory-builder` and missing fixtures via `fixture-architect`.
+5. Use `test-code-reviewer`. Do NOT finish until exit 0.
+6. Run target tests; if any retry hits the limit, hand off to `playwright-debug-conductor`.
diff --git a/.claude/commands/test-review.md b/.claude/commands/test-review.md
new file mode 100644
index 0000000..41dda50
--- /dev/null
+++ b/.claude/commands/test-review.md
@@ -0,0 +1,17 @@
+---
+description: Review staged test changes for anti-patterns
+allowed-tools: Read, Bash, Grep, Glob
+model: sonnet
+---
+
+# Context
+
+- Staged files: !`git diff --staged --name-only -- 'tests/**' 2>/dev/null`
+- All changed files: !`git diff --name-only -- 'tests/**' 2>/dev/null`
+
+# Pipeline
+
+1. Use the `test-code-reviewer` skill.
+2. Run all relevant validators (`lint-ui-spec.ts`, `lint-api-spec.ts`, `lint-page-object.ts`, `fixture-rules.ts`, `factory-rules.ts`, `tsc --noEmit`).
+3. Aggregate findings per `references/review-template.md`.
+4. Output report and exit code summary.
diff --git a/.claude/docs/greenfield-checklist.md b/.claude/docs/greenfield-checklist.md
new file mode 100644
index 0000000..68206ab
--- /dev/null
+++ b/.claude/docs/greenfield-checklist.md
@@ -0,0 +1,98 @@
+# Greenfield adoption checklist
+
+A pragmatic week-by-week plan for a brand-new TS+Playwright project that uses the SDET Claude Code kit.
+
+## Pre-flight (before opening Claude Code)
+
+- [ ] Node 20+, npm 10+ installed (`node -v`, `npm -v`).
+- [ ] Git installed and configured (`git config user.email`).
+- [ ] Claude Code CLI installed and authenticated (`claude --version`).
+- [ ] Target repository created or empty directory cloned.
+
+## Sprint 0 (Day 1 — ~2 hours)
+
+The kit drops in, the framework is scaffolded, the first smoke test passes.
+
+- [ ] Run `bash sdet-greenfield-addon/scripts/init.sh` from repo root.
+- [ ] Confirm `npm run verify` returns no failures.
+- [ ] Open Claude Code: `claude`.
+- [ ] Ask: **"Scaffold the test framework folders."** Confirm `playwright-framework-bootstrap` runs.
+- [ ] Edit `tests-config.json` if your folder names differ from the default.
+- [ ] Copy `.env.example` → `.env.local`. Fill `BASE_URL` at minimum.
+- [ ] Ask Claude Code: **"Write a smoke test for the homepage that asserts the page title is correct."**
+- [ ] Run `npm run test:smoke`. Iterate until green.
+- [ ] First commit: `git add -A && git commit -m "chore: scaffold SDET kit"`.
+
+**Exit criteria:** one green test, hooks active, kit operational.
+
+## Sprint 1 (Week 1)
+
+Build the foundation. Add fixtures, factories, first page objects, real auth.
+
+- [ ] Pick the first user story you actually need to test.
+- [ ] Ask: **"Design tests for [story]."** → triggers `test-design-agent`.
+- [ ] Review the produced `docs/test-design/<slug>.md`.
+- [ ] If using BDD: ask **"Write Gherkin scenarios from the design."** Otherwise skip.
+- [ ] Add the first real page object: ask **"Create a page object for the [X] page with these elements: …"**.
+- [ ] Add an authenticated `storageState` setup project. Use `references/auth.setup.template.ts` from `fixture-architect`.
+- [ ] Add the first factory: **"Create a factory for User with admin transient param."**
+- [ ] Write the actual UI test using all the above.
+- [ ] Make sure `pre-commit` hook fires and lints staged files.
+
+**Exit criteria:** 3–5 real tests, real fixtures, real factories, pre-commit hook battle-tested.
+
+## Sprint 2 (Week 2)
+
+Light up contract testing once the API exists.
+
+- [ ] Backend team produces `specs/openapi.yaml` (or you document the actual API yourself).
+- [ ] Re-enable the OpenAPI skill: edit `tests-config.json` → `openapi.enabled = true`.
+- [ ] Ask: **"Sync the OpenAPI spec."** → triggers `api-client-from-openapi`.
+- [ ] Verify `tests/api/generated/schema.d.ts` is created.
+- [ ] Ask: **"Write API tests for /orders endpoint covering 201, 400, 404."**
+- [ ] Add `playwright.config.ts` `api` project pointed at `API_BASE_URL`.
+- [ ] First baseline contract snapshot: `cp tests/api/generated/schema.d.ts tests/api/generated/.snapshot/schema.previous.d.ts`.
+
+**Exit criteria:** API tests run via `npm run test:api`. Drift detection works on next spec change.
+
+## Sprint 3 (Week 3)
+
+Quality gates and CI.
+
+- [ ] Add the GitHub Actions workflow: `cp sdet-greenfield-addon/templates/github-workflows/tests.yml .github/workflows/`.
+- [ ] Configure repo secrets: `TEST_USER_EMAIL`, `TEST_USER_PASSWORD`.
+- [ ] Configure repo vars: `BASE_URL`, `API_BASE_URL`.
+- [ ] First CI run on a PR. Address failures.
+- [ ] Run `flaky-detective` after the first multi-run to baseline flakiness.
+- [ ] Add `@smoke` and `@regression` tags to your tests.
+
+**Exit criteria:** PRs blocked on lint/typecheck/test failures. Reports archived as artifacts.
+
+## Sprint 4 (Week 4)
+
+Analytics + release readiness.
+
+- [ ] After ~2 weeks of CI runs, ask: **"Analyze the run history and surface trends."** → `run-analyzer`.
+- [ ] Ask: **"Generate a coverage gap report."** → `coverage-gap-analyzer`.
+- [ ] Pre-release: ask: **"Compose a release report for v0.1."** → `release-report-composer`.
+- [ ] Optional: integrate Allure / Sentry / TestOps via MCP.
+
+**Exit criteria:** weekly trend reports, gap reports inform sprint planning, release sign-off doc generated automatically.
+
+## Anti-patterns to avoid in greenfield
+
+- ❌ **Don't** write 50 page objects upfront. Let real tests drive the locator inventory.
+- ❌ **Don't** mock everything in early E2E. Real backend (staging) gives the most signal.
+- ❌ **Don't** chase coverage % before stability. A flaky 90% suite is worse than a stable 40%.
+- ❌ **Don't** disable hooks because they fire too often. Tighten the rule, don't silence the alarm.
+- ❌ **Don't** commit `.env.local`. The `pre-commit` scanner catches it; do not bypass with `--no-verify`.
+
+## When you outgrow the kit
+
+After ~2 months of real usage, you will accumulate project-specific knowledge that should live as **new** skills:
+
+- Common test patterns specific to your domain → `<your-domain>-test-patterns` skill.
+- Custom reporters or data sources → workflow skills.
+- Onboarding playbooks → document creation skill.
+
+Use `skill-creator` to scaffold them.
diff --git a/.claude/hooks/guard-bash.sh b/.claude/hooks/guard-bash.sh
new file mode 100755
index 0000000..8859741
--- /dev/null
+++ b/.claude/hooks/guard-bash.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# guard-bash.sh — PreToolUse hook for Bash. Reads JSON from stdin (Claude Code passes
+# tool input there) and exits non-zero to block destructive or risky commands.
+#
+# Risk patterns:
+#   - rm -rf  (anywhere)
+#   - git push --force / -f
+#   - git reset --hard on main/master
+#   - npx playwright codegen in CI
+#   - direct edits to tests/api/generated/** (must go via skill scripts)
+#
+set -euo pipefail
+
+INPUT=$(cat)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || echo "")
+[[ -z "$CMD" ]] && exit 0
+
+deny() {
+  echo "BLOCKED: $1" >&2
+  exit 2  # exit 2 tells Claude Code: blocked, do not run
+}
+
+# Catastrophic
+echo "$CMD" | grep -qE '\brm\s+(-[a-z]*r[a-z]*f|-rf|-fr)\b' && deny "rm -rf is forbidden via Bash hook."
+echo "$CMD" | grep -qE 'git\s+push\s+(--force|-f)' && deny "git push --force is forbidden."
+echo "$CMD" | grep -qE 'git\s+reset\s+--hard\s+(origin/)?(main|master|release)' && deny "Hard reset on protected branch."
+echo "$CMD" | grep -qE 'sudo\s+' && deny "sudo is not allowed in agent commands."
+
+# Restricted in CI
+if [[ -n "${CI:-}" ]]; then
+  echo "$CMD" | grep -qE 'playwright\s+codegen' && deny "playwright codegen is interactive; not allowed in CI."
+fi
+
+exit 0
diff --git a/.claude/hooks/guard-paths.sh b/.claude/hooks/guard-paths.sh
new file mode 100755
index 0000000..86047c8
--- /dev/null
+++ b/.claude/hooks/guard-paths.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+#
+# guard-paths.sh — PreToolUse hook for Edit/Write. Blocks edits to paths
+# that must be touched only via dedicated skill scripts.
+#
+set -euo pipefail
+
+INPUT=$(cat)
+PATH_TO_TOUCH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+[[ -z "$PATH_TO_TOUCH" ]] && exit 0
+
+deny() {
+  echo "BLOCKED: $1" >&2
+  exit 2
+}
+
+# Generated artefacts — only the api-client-from-openapi skill should regenerate
+case "$PATH_TO_TOUCH" in
+  *tests/api/generated/*)
+    deny "tests/api/generated/** is regenerated only via gen-openapi-fetch.sh." ;;
+  *.snapshot/*)
+    deny "Snapshots are baselines; update via /spec-sync --commit-baseline." ;;
+  */node_modules/*)
+    deny "Do not edit node_modules." ;;
+  *.env|*.env.*)
+    case "$PATH_TO_TOUCH" in
+      *.env.example|*.env.*.template) ;;  # allowed
+      *) deny "Editing .env files via the agent is forbidden. Use secret store." ;;
+    esac ;;
+esac
+
+exit 0
diff --git a/.claude/hooks/typecheck-touched.sh b/.claude/hooks/typecheck-touched.sh
new file mode 100755
index 0000000..58c1db7
--- /dev/null
+++ b/.claude/hooks/typecheck-touched.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+#
+# typecheck-touched.sh — PostToolUse hook for Edit/Write.
+# Runs tsc --noEmit on the touched file via tsc-files (incremental).
+# Soft-fails: prints errors, never blocks (exit 0) so the agent can iterate.
+#
+set -euo pipefail
+
+INPUT=$(cat)
+PATH_TO_CHECK=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null || echo "")
+[[ -z "$PATH_TO_CHECK" ]] && exit 0
+[[ "$PATH_TO_CHECK" != *.ts ]] && exit 0
+
+if ! command -v npx >/dev/null 2>&1; then exit 0; fi
+
+# tsc-files runs the project's tsconfig but only for the listed files.
+npx --no-install tsc-files --noEmit "$PATH_TO_CHECK" 2>&1 || true
+
+exit 0
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..b81696e
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "_comment": "Hooks gate destructive actions and run formatters/typecheck after edits. See https://docs.claude.com for the latest schema; tweak matchers as Claude Code evolves.",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-bash.sh" }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard-paths.sh" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/typecheck-touched.sh" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '[hook] consider running: npx playwright test --grep @smoke --reporter=list'"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.claude/skills/api-client-from-openapi/SKILL.md b/.claude/skills/api-client-from-openapi/SKILL.md
new file mode 100644
index 0000000..9a96953
--- /dev/null
+++ b/.claude/skills/api-client-from-openapi/SKILL.md
@@ -0,0 +1,47 @@
+---
+name: api-client-from-openapi
+description: Generates a typed REST API client layer for tests from an OpenAPI/Swagger specification using openapi-typescript + openapi-fetch (default) or orval. Wires zod runtime validators for contract assertions. Use when user mentions OpenAPI, Swagger, API client, generated types, "sync the spec", contract testing, or when paths in tests/api/generated/ are missing or stale. Do NOT use to write business test logic; defer to playwright-test-author-api.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# API Client From OpenAPI
+
+## Trigger
+
+- New endpoints in `specs/openapi.yaml`.
+- `tests-config.json.openapi.source` exists but generated dir is empty/stale.
+- User says: "regenerate types", "spec changed", "contract drift", "typed API client".
+
+## Decision tree
+
+1. Read `tests-config.json.stack.openapi`.
+2. If `openapi-typescript+openapi-fetch` → run `scripts/gen-openapi-fetch.sh`.
+3. If `orval` → run `scripts/gen-orval.sh` with `references/orval.config.template.ts`.
+
+## Workflow
+
+1. **Validate spec** via `scripts/validate-spec.sh` (uses `redocly lint`). Halt on errors.
+2. **Generate types** to `tests-config.json.openapi.generated` (e.g. `tests/api/generated/schema.d.ts`).
+3. **Wrap fetch client** in `tests/api/clients/<resource>Client.ts` with retry/log/baseURL injected from config-and-secrets.
+4. **Generate zod schemas** from JSON-Schema (`scripts/openapi-to-zod.ts`).
+5. **Add `expectMatchesSchema(response, schema)`** helper in `tests/api/contract.ts`.
+6. **Run contract drift check** (`scripts/contract-diff.ts`): compares last committed types snapshot vs new — emits a Markdown report and a non-zero exit if breaking changes are unannotated.
+
+## Anti-patterns this prevents
+
+- `axios` ad-hoc calls in spec files.
+- `any` returns from API helpers.
+- Tests asserting on snake_case while DTO is camelCase (caught by generated types).
+- Spec drift ignored — drift report is required artefact in PR.
+
+## Outputs
+
+- Updated `tests/api/generated/`.
+- `CONTRACT_DRIFT.md` if there are diffs.
+- Re-export aggregator `tests/api/index.ts`.
+
+## References
+
+- `references/tooling-decision.md` (openapi-typescript vs orval vs swagger-typescript-api)
+- `references/zod-from-openapi.md`
+- `references/contract-drift-policy.md`
diff --git a/.claude/skills/api-client-from-openapi/assets/README.md b/.claude/skills/api-client-from-openapi/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/api-client-from-openapi/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/api-client-from-openapi/references/contract-drift-policy.md b/.claude/skills/api-client-from-openapi/references/contract-drift-policy.md
new file mode 100644
index 0000000..77be9e9
--- /dev/null
+++ b/.claude/skills/api-client-from-openapi/references/contract-drift-policy.md
@@ -0,0 +1,46 @@
+# Contract drift policy
+
+## What counts as drift
+
+| Change                                          | Severity               | Action                             |
+| ----------------------------------------------- | ---------------------- | ---------------------------------- |
+| New optional field added                        | non-breaking           | log only                           |
+| New required field added                        | breaking               | block PR; update factories + tests |
+| Field renamed                                   | breaking               | block PR; coordinate with backend  |
+| Field removed                                   | breaking               | block PR                           |
+| Type widened (e.g. `string` → `string \| null`) | non-breaking but risky | warn                               |
+| Type narrowed                                   | breaking               | block PR                           |
+| Endpoint removed                                | breaking               | block PR                           |
+| New endpoint                                    | non-breaking           | log; consider new tests            |
+| Status code changed                             | breaking               | block PR                           |
+| Auth scheme changed                             | breaking               | block PR                           |
+
+## Process
+
+1. On every spec change, `scripts/contract-diff.ts` runs.
+2. Diff is rendered as `CONTRACT_DRIFT.md` and committed alongside the PR.
+3. `contract-drift-watch` subagent classifies each diff and proposes test patches for breaking changes.
+4. PR cannot be merged with an unresolved breaking-change marker.
+
+## Snapshot baseline
+
+The "previous" baseline is `tests/api/generated/.snapshot/schema.d.ts`. It is updated by an explicit human-confirmed step (`/spec-sync --commit-baseline`).
+
+## Reporting layout
+
+```markdown
+# Contract drift report (vs baseline @ <git-sha>)
+
+## Breaking changes (must address)
+
+- POST /orders: response schema renamed `customer_id` → `customerId`.
+- DELETE /orders/{id}: status `204` → `200` with body.
+
+## Non-breaking
+
+- GET /users: new optional field `nickname`.
+
+## Test impact
+
+- tests/specs/api/orders/\*.spec.ts (3 files): need camelCase update.
+```
diff --git a/.claude/skills/api-client-from-openapi/references/tooling-decision.md b/.claude/skills/api-client-from-openapi/references/tooling-decision.md
new file mode 100644
index 0000000..ff3f737
--- /dev/null
+++ b/.claude/skills/api-client-from-openapi/references/tooling-decision.md
@@ -0,0 +1,39 @@
+# OpenAPI tooling decision
+
+## TL;DR
+
+For TypeScript+Playwright **test** clients we default to `openapi-typescript` + `openapi-fetch` + `zod`. The combo is the lightest, type-only at compile time, and lets us bolt on runtime validation per-endpoint.
+
+## Comparison
+
+| Tool                                   | Output                                        | Bundle size    | Strengths                                               | Weaknesses                                          |
+| -------------------------------------- | --------------------------------------------- | -------------- | ------------------------------------------------------- | --------------------------------------------------- |
+| `openapi-typescript` + `openapi-fetch` | `.d.ts` types + tiny fetch wrapper            | ≈ 6 KB runtime | Treeshakable, idiomatic, no boilerplate, fastest builds | No runtime validation built-in; we add `zod`        |
+| `orval`                                | Full TS clients (axios/fetch), Zod, MSW mocks | Larger         | One-stop: types + clients + mocks + validators          | Heavier config, slower codegen, harder tree-shaking |
+| `swagger-typescript-api`               | Class-style clients                           | Medium         | Good for legacy Swagger 2.x                             | Less active, opinionated class-style API            |
+
+## When to choose orval over the default
+
+- You need MSW mocks generated alongside types (UI dev mode).
+- You want runtime Zod validators auto-generated (no manual step).
+- The team is already on orval in the production codebase and unification matters.
+
+## When to choose `openapi-typescript`
+
+- Test-only consumer; minimal blast radius.
+- You want explicit control over which endpoints produce zod validators (avoid mass schema generation).
+- Build performance is a constraint (large mono-spec).
+
+## Folder layout
+
+```
+tests/api/
+├── generated/
+│   ├── schema.d.ts          # openapi-typescript output
+│   └── zod/                 # openapi-to-zod generated (per resource)
+├── clients/
+│   ├── ordersClient.ts      # typed wrapper using openapi-fetch
+│   └── usersClient.ts
+├── contract.ts              # expectMatchesSchema() helper
+└── index.ts                 # re-exports
+```
diff --git a/.claude/skills/api-client-from-openapi/references/zod-from-openapi.md b/.claude/skills/api-client-from-openapi/references/zod-from-openapi.md
new file mode 100644
index 0000000..6789dfb
--- /dev/null
+++ b/.claude/skills/api-client-from-openapi/references/zod-from-openapi.md
@@ -0,0 +1,48 @@
+# Zod schemas from OpenAPI
+
+## Rationale
+
+`openapi-typescript` gives us **compile-time** types. For real contract testing we also need **runtime** validators that fail loudly when the live API drifts from the spec. Zod is the de-facto choice in TS test code: composable, narrowable, and integrates with `expect`.
+
+## Generation strategy
+
+1. Walk JSON-Schema components in `specs/openapi.yaml` (`components.schemas.*`).
+2. For each schema, emit a Zod definition into `tests/api/generated/zod/<schema>.ts`.
+3. Re-export from `tests/api/generated/zod/index.ts`.
+
+We do not generate validators for every operation — only for response shapes referenced by `components.schemas`. Inline schemas inside `responses` are flagged as a spec smell.
+
+## Helper
+
+```ts
+// tests/api/contract.ts
+import { expect } from '@playwright/test';
+import type { ZodSchema } from 'zod';
+
+export function expectMatchesSchema<T>(value: unknown, schema: ZodSchema<T>): asserts value is T {
+  const result = schema.safeParse(value);
+  if (!result.success) {
+    expect.soft(result.success, `Schema mismatch:\n${result.error.format()}`).toBe(true);
+    throw result.error;
+  }
+}
+```
+
+## Usage in API spec
+
+```ts
+import { OrderSchema } from '@api/generated/zod';
+import { expectMatchesSchema } from '@api/contract';
+
+test('GET /orders/:id matches schema', async ({ ordersClient }) => {
+  const { data, response } = await ordersClient.getById('order-1');
+  expect(response.status).toBe(200);
+  expectMatchesSchema(data, OrderSchema);
+});
+```
+
+## Tools
+
+- `openapi-zod-client` — most popular community generator.
+- `ts-to-zod` — for cases where types are already TS first.
+- Hand-written for hot paths — sometimes faster and more readable.
diff --git a/.claude/skills/api-client-from-openapi/scripts/contract-diff.ts b/.claude/skills/api-client-from-openapi/scripts/contract-diff.ts
new file mode 100755
index 0000000..4e1c6ab
--- /dev/null
+++ b/.claude/skills/api-client-from-openapi/scripts/contract-diff.ts
@@ -0,0 +1,56 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * contract-diff.ts — diffs the current OpenAPI-generated schema.d.ts against
+ * the committed baseline and writes CONTRACT_DRIFT.md.
+ * Exits 1 when breaking changes are detected and not annotated.
+ *
+ * Usage: tsx contract-diff.ts
+ */
+import { execSync } from 'node:child_process';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.cwd();
+const cfg = JSON.parse(readFileSync(join(root, 'tests-config.json'), 'utf8'));
+const generated = join(root, cfg.openapi.generated, 'schema.d.ts');
+const snapshot = join(root, cfg.openapi.generated, '.snapshot', 'schema.previous.d.ts');
+
+if (!existsSync(generated)) {
+  console.error(`FAIL: ${generated} missing. Run gen-openapi-fetch.sh first.`);
+  process.exit(2);
+}
+if (!existsSync(snapshot)) {
+  console.log('NOTE: no baseline snapshot yet. Treating current as baseline.');
+  writeFileSync(join(root, 'CONTRACT_DRIFT.md'), '# Contract drift report\n\nNo baseline yet.\n');
+  process.exit(0);
+}
+
+const diff = execSync(`diff -u "${snapshot}" "${generated}" || true`).toString();
+
+const breakingMarkers = [/-.*[A-Za-z_]+\??:/g, /^-\s*[A-Za-z]+:/gm];
+let breaking = 0;
+for (const re of breakingMarkers) {
+  const m = diff.match(re);
+  if (m) breaking += m.length;
+}
+
+const md = [
+  '# Contract drift report',
+  '',
+  `Generated: ${new Date().toISOString()}`,
+  '',
+  '## Raw diff',
+  '```diff',
+  diff || '(no changes)',
+  '```',
+  '',
+  `Heuristic breaking signals: **${breaking}**`,
+].join('\n');
+
+writeFileSync(join(root, 'CONTRACT_DRIFT.md'), md);
+
+if (breaking > 0) {
+  console.error(`Detected ${breaking} potential breaking change(s). See CONTRACT_DRIFT.md`);
+  process.exit(1);
+}
+console.log('OK: no breaking signals.');
diff --git a/.claude/skills/api-client-from-openapi/scripts/gen-openapi-fetch.sh b/.claude/skills/api-client-from-openapi/scripts/gen-openapi-fetch.sh
new file mode 100755
index 0000000..0c20360
--- /dev/null
+++ b/.claude/skills/api-client-from-openapi/scripts/gen-openapi-fetch.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+#
+# gen-openapi-fetch.sh — regenerate types via openapi-typescript.
+# Reads tests-config.json for source/target paths.
+#
+set -euo pipefail
+
+ROOT="${1:-$(pwd)}"
+CFG="$ROOT/tests-config.json"
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "FAIL: jq is required."
+  exit 2
+fi
+
+SRC=$(jq -r '.openapi.source' "$CFG")
+DST_DIR=$(jq -r '.openapi.generated' "$CFG")
+mkdir -p "$ROOT/$DST_DIR"
+
+OUT="$ROOT/$DST_DIR/schema.d.ts"
+
+# Snapshot before regeneration for diffing
+if [[ -f "$OUT" ]]; then
+  mkdir -p "$ROOT/$DST_DIR/.snapshot"
+  cp "$OUT" "$ROOT/$DST_DIR/.snapshot/schema.previous.d.ts"
+fi
+
+npx openapi-typescript "$ROOT/$SRC" -o "$OUT"
+echo "OK: types written to $OUT"
diff --git a/.claude/skills/api-client-from-openapi/scripts/validate-spec.sh b/.claude/skills/api-client-from-openapi/scripts/validate-spec.sh
new file mode 100755
index 0000000..edcfe2f
--- /dev/null
+++ b/.claude/skills/api-client-from-openapi/scripts/validate-spec.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+#
+# validate-spec.sh — lint OpenAPI spec via redocly.
+#
+set -euo pipefail
+ROOT="${1:-$(pwd)}"
+CFG="$ROOT/tests-config.json"
+SRC=$(jq -r '.openapi.source' "$CFG")
+
+if ! command -v npx >/dev/null 2>&1; then
+  echo "FAIL: npx required."
+  exit 2
+fi
+
+npx --yes @redocly/cli@latest lint "$ROOT/$SRC"
diff --git a/.claude/skills/config-and-secrets/SKILL.md b/.claude/skills/config-and-secrets/SKILL.md
new file mode 100644
index 0000000..fffdccd
--- /dev/null
+++ b/.claude/skills/config-and-secrets/SKILL.md
@@ -0,0 +1,31 @@
+---
+name: config-and-secrets
+description: Manages environment-specific Playwright configuration, secrets, and test data isolation. Wires dotenv-flow / @playwright/test projects per env, enforces no-secrets-in-repo, and validates baseURL injection. Use when user mentions "env config", "staging vs prod", "secrets", "process.env", or when a baseURL/secret is hardcoded in a test or page object. Do NOT use to scaffold the whole framework; that is playwright-framework-bootstrap.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Config & Secrets
+
+## Trigger
+
+- Hardcoded URL/credentials detected by `scripts/scan-hardcoded.sh`.
+- User mentions: env, dotenv, secrets, staging, prod, .env.
+
+## Workflow
+
+1. Establish `.env.example` with documented keys, NEVER `.env` itself in repo (verify in `.gitignore`).
+2. Use `dotenv-flow` or `dotenv` + `process.env` strict accessor (`tests/infra/env.ts` with `zod` schema).
+3. Per environment: define a Playwright `project` with overridden `use.baseURL`.
+4. Secrets: integrate with the host secret store (1Password/AWS SM/GH Actions secrets) via `scripts/load-secrets.sh`.
+5. Forbid `console.log(process.env...)` via ESLint custom rule.
+
+## Validators
+
+- `scripts/scan-hardcoded.sh`: greps for `https?://`, `password|token|secret|apiKey` literals in `tests/`.
+- Returns non-zero with file:line list.
+
+## References
+
+- `references/env.template.ts` (zod-validated env loader)
+- `references/multi-env-projects.md`
+- `references/secret-stores.md`
diff --git a/.claude/skills/config-and-secrets/assets/README.md b/.claude/skills/config-and-secrets/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/config-and-secrets/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/config-and-secrets/references/env.template.ts b/.claude/skills/config-and-secrets/references/env.template.ts
new file mode 100644
index 0000000..d7c108b
--- /dev/null
+++ b/.claude/skills/config-and-secrets/references/env.template.ts
@@ -0,0 +1,27 @@
+/**
+ * tests/infra/env.ts — strict, validated env access.
+ * Import as `import { env } from '@infra/env';` everywhere instead of `process.env.X`.
+ */
+import 'dotenv/config';
+import { z } from 'zod';
+
+const schema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'staging', 'production']).default('test'),
+  BASE_URL: z.string().url(),
+  API_BASE_URL: z.string().url(),
+  TEST_USER_EMAIL: z.string().email(),
+  TEST_USER_PASSWORD: z.string().min(1),
+  TEST_ADMIN_EMAIL: z.string().email().optional(),
+  TEST_ADMIN_PASSWORD: z.string().min(1).optional(),
+  SEED: z.coerce.number().int().nonnegative().optional(),
+  CI: z.string().optional(),
+});
+
+const parsed = schema.safeParse(process.env);
+if (!parsed.success) {
+  // Hard fail at import — better than running 1000 broken tests
+  console.error('Invalid environment:', parsed.error.format());
+  process.exit(2);
+}
+
+export const env = parsed.data;
diff --git a/.claude/skills/config-and-secrets/references/multi-env-projects.md b/.claude/skills/config-and-secrets/references/multi-env-projects.md
new file mode 100644
index 0000000..d6d2d27
--- /dev/null
+++ b/.claude/skills/config-and-secrets/references/multi-env-projects.md
@@ -0,0 +1,53 @@
+# Multi-environment via Playwright projects
+
+## Pattern
+
+A single `playwright.config.ts` declares all environments. Run a specific one with `--project=staging-chromium`.
+
+```ts
+const baseUseFor = (env: 'local' | 'staging' | 'prod') => ({
+  baseURL: {
+    local: 'http://localhost:3000',
+    staging: 'https://staging.example.com',
+    prod: 'https://example.com',
+  }[env],
+});
+
+export default defineConfig({
+  projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    {
+      name: 'local-chromium',
+      use: { ...devices['Desktop Chrome'], ...baseUseFor('local') },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'staging-chromium',
+      use: { ...devices['Desktop Chrome'], ...baseUseFor('staging') },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'prod-smoke',
+      use: { ...devices['Desktop Chrome'], ...baseUseFor('prod') },
+      grep: /@smoke/,
+    },
+  ],
+});
+```
+
+## Secrets per env
+
+`.env` files layered by `dotenv-flow`:
+
+- `.env` — committed defaults (no secrets)
+- `.env.local` — local-only (gitignored)
+- `.env.staging` — pulled via `load-secrets.sh`
+- `.env.production` — pulled via `load-secrets.sh`, never written to disk in CI; injected directly
+
+## Tagging strategy
+
+- `@smoke` — runs against every env, including prod
+- `@regression`— runs against staging
+- `@dangerous` — never runs against prod (a CI gate enforces this)
+
+Prefer `grep:`/`grepInvert:` in projects over `test.skip()` to avoid 1000 skipped lines in reports.
diff --git a/.claude/skills/config-and-secrets/references/secret-stores.md b/.claude/skills/config-and-secrets/references/secret-stores.md
new file mode 100644
index 0000000..4f5b0b1
--- /dev/null
+++ b/.claude/skills/config-and-secrets/references/secret-stores.md
@@ -0,0 +1,47 @@
+# Secret stores
+
+Never commit secrets. Pull them at runtime from a real secret store.
+
+## GitHub Actions
+
+```yaml
+- name: Run tests
+  env:
+    BASE_URL: ${{ vars.BASE_URL }}
+    TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
+    TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
+  run: npx playwright test
+```
+
+## 1Password CLI (local)
+
+```bash
+# scripts/load-secrets.sh
+op signin
+op run --env-file=.env.staging.template -- npx playwright test --project=staging-chromium
+```
+
+`.env.staging.template`:
+
+```
+BASE_URL=https://staging.example.com
+TEST_USER_EMAIL=op://Engineering/test-user/email
+TEST_USER_PASSWORD=op://Engineering/test-user/password
+```
+
+## AWS Secrets Manager / Vault
+
+```ts
+// tests/infra/load-secrets.ts (worker setup project)
+import { SecretsManagerClient, GetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
+const client = new SecretsManagerClient({});
+const { SecretString } = await client.send(new GetSecretValueCommand({ SecretId: 'qa/test-user' }));
+process.env.TEST_USER_PASSWORD = JSON.parse(SecretString!).password;
+```
+
+## Hard rules
+
+- `.env*` (except `.env.example` and `.env.*.template`) → `.gitignore`.
+- A pre-commit hook scans staged files for `password|secret|token|apiKey|AKIA[0-9A-Z]{16}`.
+- CI logs are scrubbed (`echo "::add-mask::$SECRET"` in GitHub Actions).
+- No secret enters Claude Code context. Reference by env var name only.
diff --git a/.claude/skills/config-and-secrets/scripts/scan-hardcoded.sh b/.claude/skills/config-and-secrets/scripts/scan-hardcoded.sh
new file mode 100755
index 0000000..f4f3646
--- /dev/null
+++ b/.claude/skills/config-and-secrets/scripts/scan-hardcoded.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# scan-hardcoded.sh — fail when hardcoded URLs / credentials slip into tests/.
+#
+set -euo pipefail
+ROOT="${1:-$(pwd)}"
+TARGET_DIRS=("tests")
+
+violations=0
+
+for dir in "${TARGET_DIRS[@]}"; do
+  [[ -d "$ROOT/$dir" ]] || continue
+
+  # Hardcoded https/http literals (allow localhost & .env.example references)
+  if grep -RInE "https?://[^'\"\` ]+" "$ROOT/$dir" \
+     --include='*.ts' --include='*.js' \
+     --exclude-dir=generated --exclude-dir=node_modules \
+     | grep -vE "(localhost|127\.0\.0\.1|baseURL|@example\.com|process\.env|env\.[A-Z_]+|//\s*example|tests/infra/env\.ts)"; then
+    echo "FAIL: hardcoded URL(s) above. Move to env config."
+    violations=$((violations + 1))
+  fi
+
+  # Hardcoded credentials
+  if grep -RInE "(password|token|secret|apiKey|api_key)\s*[:=]\s*['\"][^'\"]{6,}" "$ROOT/$dir" \
+     --include='*.ts' --include='*.js' \
+     --exclude-dir=generated --exclude-dir=node_modules; then
+    echo "FAIL: hardcoded credential(s) above."
+    violations=$((violations + 1))
+  fi
+done
+
+if [[ $violations -gt 0 ]]; then
+  exit 1
+fi
+echo "OK: no hardcoded secrets/URLs."
diff --git a/.claude/skills/coverage-gap-analyzer/SKILL.md b/.claude/skills/coverage-gap-analyzer/SKILL.md
new file mode 100644
index 0000000..8a80a24
--- /dev/null
+++ b/.claude/skills/coverage-gap-analyzer/SKILL.md
@@ -0,0 +1,30 @@
+---
+name: coverage-gap-analyzer
+description: Cross-references OpenAPI endpoints + UI pages + Gherkin scenarios with executed tests to surface untested paths and uncovered acceptance criteria. Use when user asks "coverage gaps", "what's not tested", "which endpoints have no tests", before a release sign-off. Do NOT use for line/branch coverage of production code (that's a different tool).
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Coverage Gap Analyzer
+
+## Workflow
+
+1. Build inventory:
+   - Endpoints: parse `specs/openapi.yaml` for `paths × methods`.
+   - Pages: glob `tests-config.json.layout.pages/**/*Page.ts`.
+   - AC: parse `docs/test-design/*.md` for "AC-x" tags.
+2. Build executed map: parse last `playwright-report/results.json` + spec annotations (`test('... @endpoint:GET /orders @ac:AC-3')`).
+3. Diff inventory vs executed.
+4. Output `COVERAGE_GAPS.md` with prioritised list (risk × frequency).
+
+## Tagging convention (must follow)
+
+```ts
+test('cancel pending order @ac:AC-12 @endpoint:DELETE /orders/{id}', async ({ ... }) => { ... });
+```
+
+The skill grep-extracts `@ac:`, `@endpoint:`, `@page:` tags and matches them to the inventory. Untagged tests do not contribute coverage.
+
+## References
+
+- `references/test-tagging-convention.md`
+- `references/coverage-template.md`
diff --git a/.claude/skills/coverage-gap-analyzer/assets/README.md b/.claude/skills/coverage-gap-analyzer/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/coverage-gap-analyzer/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/coverage-gap-analyzer/references/coverage-template.md b/.claude/skills/coverage-gap-analyzer/references/coverage-template.md
new file mode 100644
index 0000000..b3a2d5c
--- /dev/null
+++ b/.claude/skills/coverage-gap-analyzer/references/coverage-template.md
@@ -0,0 +1,33 @@
+# Coverage gaps — <date>
+
+> Generated by `coverage-gap-analyzer`.
+
+## Summary
+
+| Inventory           | Total | Covered | Missing |   % |
+| ------------------- | ----: | ------: | ------: | --: |
+| OpenAPI endpoints   |     0 |       0 |       0 |   — |
+| Acceptance criteria |     0 |       0 |       0 |   — |
+| Page objects        |     0 |       0 |       0 |   — |
+
+## Critical gaps (P0)
+
+| Endpoint / AC / Page | Risk note |
+| -------------------- | --------- |
+
+## Major gaps (P1)
+
+| ... |
+
+## Tag hygiene issues
+
+| File:Line                  | Issue                                         |
+| -------------------------- | --------------------------------------------- |
+| tests/specs/foo.spec.ts:12 | Test missing @feature tag                     |
+| tests/specs/bar.spec.ts:30 | @endpoint:DELETE /unknown does not match spec |
+
+## Recommendation
+
+1. Address P0 gaps before release sign-off.
+2. Schedule P1 gaps in next sprint.
+3. Fix tag hygiene before coverage numbers can be trusted.
diff --git a/.claude/skills/coverage-gap-analyzer/references/test-tagging-convention.md b/.claude/skills/coverage-gap-analyzer/references/test-tagging-convention.md
new file mode 100644
index 0000000..9a565cc
--- /dev/null
+++ b/.claude/skills/coverage-gap-analyzer/references/test-tagging-convention.md
@@ -0,0 +1,51 @@
+# Test tagging convention
+
+Tags are how the coverage analyser knows what each test covers. Without tags, a test contributes nothing to coverage metrics.
+
+## Required tags
+
+| Tag                         | Format                          | Required when                             |
+| --------------------------- | ------------------------------- | ----------------------------------------- |
+| `@ac:<ID>`                  | `@ac:AC-12`                     | The test verifies an acceptance criterion |
+| `@endpoint:<METHOD> <PATH>` | `@endpoint:DELETE /orders/{id}` | API spec                                  |
+| `@page:<PageName>`          | `@page:CheckoutPage`            | UI spec                                   |
+| `@feature:<feature>`        | `@feature:auth`                 | All specs (used for grouping)             |
+| `@owner:<team>`             | `@owner:qa-platform`            | All specs                                 |
+
+## Optional tags
+
+- `@smoke` — runs against every env including prod.
+- `@regression` — runs in nightly suite.
+- `@external` — depends on an external service; CI may skip when unreachable.
+- `@quarantine` — unstable; allowed for ≤ 2 sprints.
+- `@dangerous` — never runs against prod.
+- `@fuzz` — uses randomized input.
+
+## How to tag
+
+In Playwright, embed in the test title (matched by the `grep` and parsers):
+
+```ts
+test('cancel pending order @ac:AC-12 @endpoint:DELETE /orders/{id} @feature:orders @owner:qa-platform', async ({ ... }) => {
+  /* ... */
+});
+```
+
+For `describe` blocks, place tags at the describe level — they apply to all child tests:
+
+```ts
+test.describe('Order cancellation @feature:orders @owner:qa-platform', () => {
+  /* ... */
+});
+```
+
+## Validation
+
+`scripts/validate-tags.ts` (in this skill) ensures:
+
+- Every test has at least `@feature` and `@owner`.
+- `@endpoint:` tags reference real endpoints from the OpenAPI spec.
+- `@ac:` tags reference IDs that exist in `docs/test-design/*.md`.
+- `@page:` tags reference real page-object class names.
+
+Mismatches show up in the gap report.
diff --git a/.claude/skills/coverage-gap-analyzer/scripts/analyze-coverage.ts b/.claude/skills/coverage-gap-analyzer/scripts/analyze-coverage.ts
new file mode 100755
index 0000000..f1cdd86
--- /dev/null
+++ b/.claude/skills/coverage-gap-analyzer/scripts/analyze-coverage.ts
@@ -0,0 +1,104 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * analyze-coverage.ts — produce COVERAGE_GAPS.md.
+ *
+ * Strategy: parse OpenAPI for endpoints, parse test files for tags,
+ * intersect, emit gaps. AC tag matching is best-effort string match.
+ */
+import { readFileSync, readdirSync, statSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.cwd();
+const cfg = JSON.parse(readFileSync(join(root, 'tests-config.json'), 'utf8'));
+const specsDir = join(root, cfg.layout.specs);
+const pagesDir = join(root, cfg.layout.pages);
+const openapiPath = join(root, cfg.openapi.source);
+
+// --- Inventories ---
+
+function collect(dir: string, suffix = '.ts', acc: string[] = []): string[] {
+  if (!existsSync(dir)) return acc;
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) collect(p, suffix, acc);
+    else if (p.endsWith(suffix)) acc.push(p);
+  }
+  return acc;
+}
+
+// Endpoints from OpenAPI (very simple YAML scan, sufficient for a coverage gap heuristic)
+function readEndpoints(): string[] {
+  if (!existsSync(openapiPath)) return [];
+  const raw = readFileSync(openapiPath, 'utf8');
+  const endpoints: string[] = [];
+  const lines = raw.split('\n');
+  let currentPath = '';
+  for (const line of lines) {
+    const pm = /^\s{2}(\/[^:]+):\s*$/.exec(line);
+    if (pm) currentPath = pm[1].trim();
+    const mm = /^\s{4}(get|post|put|patch|delete|head|options):\s*$/i.exec(line);
+    if (mm && currentPath) endpoints.push(`${mm[1].toUpperCase()} ${currentPath}`);
+  }
+  return endpoints;
+}
+
+// Page objects
+function readPages(): string[] {
+  return collect(pagesDir).map((p) => p.split('/').pop()!.replace(/\.ts$/, ''));
+}
+
+// Tags in tests
+const testTagRe = /@(\w+):([^\s'"]+)/g;
+function readCoveredTags(): { endpoints: Set<string>; acs: Set<string>; pages: Set<string> } {
+  const endpoints = new Set<string>();
+  const acs = new Set<string>();
+  const pages = new Set<string>();
+  for (const file of collect(specsDir, '.spec.ts')) {
+    const src = readFileSync(file, 'utf8');
+    for (const m of src.matchAll(testTagRe)) {
+      const [, k, v] = m;
+      if (k === 'endpoint') endpoints.add(v);
+      else if (k === 'ac') acs.add(v);
+      else if (k === 'page') pages.add(v);
+    }
+    // catch endpoint tags formatted as "@endpoint:METHOD /path"
+    for (const m of src.matchAll(/@endpoint:([A-Z]+)\s+([^\s'"]+)/g)) {
+      endpoints.add(`${m[1]} ${m[2]}`);
+    }
+  }
+  return { endpoints, acs, pages };
+}
+
+const inventoryEndpoints = readEndpoints();
+const inventoryPages = readPages();
+const covered = readCoveredTags();
+
+const missingEndpoints = inventoryEndpoints.filter((e) => !covered.endpoints.has(e));
+const missingPages = inventoryPages.filter((p) => !covered.pages.has(p));
+
+const md: string[] = [];
+md.push(`# Coverage gaps — ${new Date().toISOString().slice(0, 10)}`);
+md.push('');
+md.push('## Endpoints');
+md.push(
+  `Inventory: ${inventoryEndpoints.length} | Covered: ${covered.endpoints.size} | Missing: ${missingEndpoints.length}`,
+);
+md.push('');
+if (missingEndpoints.length) {
+  md.push('### Missing endpoints');
+  for (const e of missingEndpoints) md.push(`- [ ] ${e}`);
+  md.push('');
+}
+
+md.push('## Pages');
+md.push(
+  `Inventory: ${inventoryPages.length} | Covered: ${covered.pages.size} | Missing: ${missingPages.length}`,
+);
+md.push('');
+if (missingPages.length) {
+  md.push('### Page objects without any test reference');
+  for (const p of missingPages) md.push(`- [ ] ${p}`);
+}
+
+writeFileSync(join(root, 'COVERAGE_GAPS.md'), md.join('\n'));
+console.log('OK: COVERAGE_GAPS.md written.');
diff --git a/.claude/skills/fixture-architect/SKILL.md b/.claude/skills/fixture-architect/SKILL.md
new file mode 100644
index 0000000..03bf264
--- /dev/null
+++ b/.claude/skills/fixture-architect/SKILL.md
@@ -0,0 +1,46 @@
+---
+name: fixture-architect
+description: Designs Playwright fixtures with proper scoping (test vs worker), composition, and dependency injection. Wires page objects, API clients, factories, authenticated storage state, and per-test cleanup. Use when user adds a new fixture, mentions "test.extend", "worker scope", "auth state", "shared context", "DI for tests", or when a spec instantiates page objects manually inside the test body. Do NOT use to write business steps; defer to playwright-test-author-ui.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Fixture Architect
+
+## Trigger
+
+- Spec contains `new SomePage(page)` inline.
+- User: "add fixture", "worker fixture", "shared login", "extend test".
+
+## Decision tree
+
+| Need                                           | Scope    | Pattern                                               |
+| ---------------------------------------------- | -------- | ----------------------------------------------------- |
+| Page object (per test)                         | `test`   | `({ page }, use) => use(new XPage(page))`             |
+| API client                                     | `test`   | uses request-context fixture                          |
+| Logged-in user (reused across tests in worker) | `worker` | `storageState` cached file                            |
+| Test data lifecycle (create+delete)            | `test`   | factory + afterEach cleanup in fixture                |
+| Network mocks (route handlers)                 | `test`   | `await use()` between `page.route` and `page.unroute` |
+
+## Workflow
+
+1. Read `tests-config.json.layout.fixtures`.
+2. Compose into `tests/fixtures/index.ts` via `base.extend`. NEVER overwrite `page` without justification.
+3. For worker-scope auth: use `references/auth.setup.template.ts` pattern (`storageState` saved by setup project, consumed by other projects).
+4. Validate with `scripts/fixture-rules.ts`:
+   - No fixture without `await use(...)`.
+   - No fixture mutating global state outside its lifecycle.
+   - Fixture name does not collide with built-ins (`page`, `request`, `browser`, `context`).
+   - `worker`-scope fixtures must not depend on `test`-scope ones.
+
+## Anti-patterns prevented
+
+- Leaky fixtures (cleanup missing → next test inherits state).
+- Implicit ordering between fixtures (rely on dependency graph, not file order).
+- Mega-fixture file > 300 lines (skill splits per concern).
+
+## References
+
+- `references/scope-decision.md`
+- `references/auth.setup.template.ts`
+- `references/composing-fixtures.md`
+- `references/anti-leaks-checklist.md`
diff --git a/.claude/skills/fixture-architect/assets/README.md b/.claude/skills/fixture-architect/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/fixture-architect/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/fixture-architect/references/anti-leaks-checklist.md b/.claude/skills/fixture-architect/references/anti-leaks-checklist.md
new file mode 100644
index 0000000..2c0c928
--- /dev/null
+++ b/.claude/skills/fixture-architect/references/anti-leaks-checklist.md
@@ -0,0 +1,36 @@
+# Fixture leak checklist
+
+A "leak" = state created in one test surfaces in the next. Symptoms: order-dependent failures, ghost data, "passes alone, fails in suite".
+
+## Hard checks
+
+1. Every fixture body has exactly one `await use(...)` call.
+2. Resources created before `use` are torn down after `use` (try/finally if necessary).
+3. No fixture writes to a file path shared across tests without a per-test suffix.
+4. No fixture mutates `process.env` without restoring.
+5. No fixture mutates the imported factory (e.g. assigns `userFactory.someProp = ...`).
+6. Worker-scope fixtures avoid mutable maps/sets that grow across tests.
+7. `page.route` handlers are removed via `page.unroute` or live in a `test`-scope fixture that auto-cleans on teardown.
+
+## Soft checks (warn)
+
+- Fixture name shadows a built-in (`page`, `request`, `browser`, `context`, `browserName`).
+- Two fixtures depend on each other in a cycle.
+- A `test`-scope fixture is consumed by more than 5 other fixtures (refactor candidate).
+
+## Diagnosis when a leak is suspected
+
+```bash
+npx playwright test --workers=1 --shuffle  # randomise order
+npx playwright test --repeat-each=3        # detect order-dependent failures
+```
+
+If the suite passes with `--workers=1` but fails parallel — concurrent state mutation.
+If it fails with `--shuffle` only — order-dependent leak.
+
+## Common offenders
+
+- Login that writes a single `auth.json` shared across users.
+- Test data factories that return the same `id` because the sequence resets.
+- `beforeAll` in spec files that mutates a module-level singleton.
+- Mock servers started in `worker` scope, configured in `test` scope, never reset.
diff --git a/.claude/skills/fixture-architect/references/auth.setup.template.ts b/.claude/skills/fixture-architect/references/auth.setup.template.ts
new file mode 100644
index 0000000..f2bc021
--- /dev/null
+++ b/.claude/skills/fixture-architect/references/auth.setup.template.ts
@@ -0,0 +1,32 @@
+/**
+ * tests/fixtures/auth.setup.ts — runs once per project (referenced by `dependencies: ['setup']`)
+ * to populate tests/.auth/<role>.json. Other tests load this file via storageState in playwright.config.ts.
+ *
+ * Why this pattern:
+ *  - One UI/API login per worker, not per test. ~10x perf for E2E suites.
+ *  - storageState is a pure JSON snapshot — safe to share read-only across workers.
+ *  - Failures in setup mark the whole project as broken instead of producing 1000 cryptic test fails.
+ */
+import { test as setup, expect } from '@playwright/test';
+import path from 'node:path';
+
+const userAuthFile = path.join(__dirname, '../.auth/user.json');
+const adminAuthFile = path.join(__dirname, '../.auth/admin.json');
+
+setup('authenticate as user', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill(process.env.TEST_USER_EMAIL!);
+  await page.getByLabel('Password').fill(process.env.TEST_USER_PASSWORD!);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible();
+  await page.context().storageState({ path: userAuthFile });
+});
+
+setup('authenticate as admin', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill(process.env.TEST_ADMIN_EMAIL!);
+  await page.getByLabel('Password').fill(process.env.TEST_ADMIN_PASSWORD!);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page.getByRole('navigation', { name: /admin/i })).toBeVisible();
+  await page.context().storageState({ path: adminAuthFile });
+});
diff --git a/.claude/skills/fixture-architect/references/composing-fixtures.md b/.claude/skills/fixture-architect/references/composing-fixtures.md
new file mode 100644
index 0000000..30b44a0
--- /dev/null
+++ b/.claude/skills/fixture-architect/references/composing-fixtures.md
@@ -0,0 +1,80 @@
+# Composing fixtures
+
+Compose using `base.extend<TestFixtures, WorkerFixtures>()` and split per concern. Aggregate in `tests/fixtures/index.ts`.
+
+## Pattern
+
+```ts
+// tests/fixtures/pages.ts
+import { test as base } from '@playwright/test';
+import { LoginPage, DashboardPage } from '@pages';
+
+type PageFixtures = {
+  loginPage: LoginPage;
+  dashboardPage: DashboardPage;
+};
+
+export const pagesTest = base.extend<PageFixtures>({
+  loginPage: async ({ page }, use) => {
+    await use(new LoginPage(page));
+  },
+  dashboardPage: async ({ page }, use) => {
+    await use(new DashboardPage(page));
+  },
+});
+```
+
+```ts
+// tests/fixtures/api.ts
+import { test as base } from '@playwright/test';
+import { OrdersClient } from '@api/clients/ordersClient';
+
+type ApiFixtures = {
+  ordersClient: OrdersClient;
+};
+
+export const apiTest = base.extend<ApiFixtures>({
+  ordersClient: async ({ request }, use) => {
+    await use(new OrdersClient(request));
+  },
+});
+```
+
+```ts
+// tests/fixtures/data.ts — manages lifecycle: create + cleanup
+import { test as base } from '@playwright/test';
+import { userFactory } from '@factories/user.factory';
+
+type DataFixtures = {
+  seededUser: { id: string; email: string };
+};
+
+export const dataTest = base.extend<DataFixtures>({
+  seededUser: async ({ ordersClient: _ }, use, testInfo) => {
+    const draft = userFactory.build();
+    // const user = await usersClient.create(draft);
+    const user = { id: draft.id, email: draft.email };
+    await use(user);
+    // teardown — guaranteed even on failure
+    // await usersClient.delete(user.id);
+  },
+});
+```
+
+```ts
+// tests/fixtures/index.ts
+import { mergeTests } from '@playwright/test';
+import { pagesTest } from './pages';
+import { apiTest } from './api';
+import { dataTest } from './data';
+
+export const test = mergeTests(pagesTest, apiTest, dataTest);
+export { expect } from '@playwright/test';
+```
+
+## Rules
+
+- Files in `fixtures/` ≤ 250 LOC.
+- One concern per file (pages / api / data / mocks / auth).
+- Aggregate via `mergeTests`, never manually re-extend.
+- A fixture body always uses `await use(value)` — even when teardown is empty.
diff --git a/.claude/skills/fixture-architect/references/scope-decision.md b/.claude/skills/fixture-architect/references/scope-decision.md
new file mode 100644
index 0000000..e2f103b
--- /dev/null
+++ b/.claude/skills/fixture-architect/references/scope-decision.md
@@ -0,0 +1,34 @@
+# Fixture scope decision
+
+Playwright supports two scopes:
+
+- `test` — default; fixture is created per test, cleaned up after.
+- `worker` — fixture is created once per worker process and reused across tests.
+
+## When to use worker scope
+
+Use it when **all** of the following hold:
+
+1. The fixture is read-only across tests (no mutation that could leak).
+2. Construction is expensive (auth flow, browser launch, large dataset preload).
+3. Tests using it do not rely on a fresh state (otherwise pin to `test`).
+
+## Common cases
+
+| Resource                                        | Scope                               | Why                                    |
+| ----------------------------------------------- | ----------------------------------- | -------------------------------------- |
+| Logged-in `storageState` for a stable test user | `worker`                            | Avoid logging in 1000 times; immutable |
+| API client with baseURL & auth token            | `worker`                            | Stateless wrapper                      |
+| Page object                                     | `test`                              | Bound to a `page` (which is per-test)  |
+| User created via factory then deleted           | `test`                              | Side effects must be cleaned up        |
+| Mock server                                     | `worker` (start), `test` (handlers) | Server up once; handlers per test      |
+
+## Do NOT mix scopes incorrectly
+
+A `worker`-scope fixture cannot consume `test`-scope fixtures. Playwright will throw at runtime. The fixture-rules.ts validator catches this statically by checking the dependency graph.
+
+## Caveats
+
+- worker-scope state is reset between projects, not between tests within a project.
+- If a worker-scope fixture mutates state during a test, parallel tests in the same worker will interfere.
+- Prefer multiple small worker-scope fixtures over one fat one — Playwright reuses across the dependency graph anyway.
diff --git a/scripts/fixture-rules.ts b/.claude/skills/fixture-architect/scripts/fixture-rules.ts
similarity index 100%
rename from scripts/fixture-rules.ts
rename to .claude/skills/fixture-architect/scripts/fixture-rules.ts
diff --git a/.claude/skills/flaky-triage/SKILL.md b/.claude/skills/flaky-triage/SKILL.md
new file mode 100644
index 0000000..5d7c353
--- /dev/null
+++ b/.claude/skills/flaky-triage/SKILL.md
@@ -0,0 +1,35 @@
+---
+name: flaky-triage
+description: Detects, classifies, and proposes fixes for flaky Playwright tests by analysing test results JSON and traces across multiple runs. Distinguishes timing flakes, data flakes, environment flakes, and real bugs. Use when user reports "flaky", "intermittent failure", "this test passes locally", or after a CI report shows reruns. Do NOT use to write new tests.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Flaky Triage
+
+## Inputs
+
+- `playwright-report/` (HTML + JSON).
+- N×raw runs in `test-results/`.
+- Optional: CI history exported via `scripts/export-ci-runs.sh`.
+
+## Workflow
+
+1. Aggregate pass/fail per test across runs (`scripts/flake-rate.ts`).
+2. For each test with rate ∈ (0, 1): pull traces, diff failing vs passing step.
+3. Classify:
+   - **Timing**: assertion fired before stable state → fix with `expect.poll` / web-first.
+   - **Data**: shared seed, sequence collision → fix with `factory.sequence` + per-test namespace.
+   - **Env**: external dep down/slow → quarantine + reproduce in isolation.
+   - **Locator**: dynamic ID/class → switch to role/test-id.
+   - **Real bug**: app race condition → file ticket, do NOT mark flaky.
+4. Output `FLAKE_REPORT.md` + suggested patch.
+
+## Quarantine policy
+
+A flaky test may be tagged `@quarantine` for ≤ 2 sprints with an open issue link. After that, delete or fix.
+
+## References
+
+- `references/flake-taxonomy.md`
+- `references/quarantine-policy.md`
+- `references/repro-strategy.md`
diff --git a/.claude/skills/flaky-triage/assets/README.md b/.claude/skills/flaky-triage/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/flaky-triage/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/flaky-triage/references/flake-taxonomy.md b/.claude/skills/flaky-triage/references/flake-taxonomy.md
new file mode 100644
index 0000000..fd28b83
--- /dev/null
+++ b/.claude/skills/flaky-triage/references/flake-taxonomy.md
@@ -0,0 +1,28 @@
+# Flake taxonomy
+
+Each flake belongs to exactly one class. Class drives the fix.
+
+| Class                  | Hallmarks                                                               | Fix                                                                                                                |
+| ---------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **Timing**             | Same step fails fast on retry; trace shows assertion before DOM stable. | Web-first; `expect.poll` for value-based polling; remove arbitrary `actionTimeout`.                                |
+| **Animation**          | Headed passes, headless fails; element fades in/out.                    | Disable animations via CSS (`animation: none !important`) in test fixture; or assert with `toHaveClass(/active/)`. |
+| **Network**            | 429/5xx in trace; passes in isolation.                                  | Mark `@external`; mock or run only against staging.                                                                |
+| **Data leak**          | Fails in suite, passes alone; depends on prior test.                    | Per-test cleanup; per-test factory namespace; `--shuffle --workers=1` repro.                                       |
+| **Sequence collision** | Two parallel workers create the same id.                                | Factory uses `sequence` + worker-index suffix.                                                                     |
+| **Time-dependent**     | Fails near midnight, daylight-saving, end-of-month.                     | `page.clock.install()` and pin a timestamp.                                                                        |
+| **Locator drift**      | Trace shows multiple elements match; element re-rendered.               | Switch to `getByRole`; scope inside ancestor; never `nth(N)`.                                                      |
+| **Env**                | Specific worker / browser / OS only.                                    | Reproduce on the matching env; if irreproducible, classify "haunted" and quarantine.                               |
+| **Real bug**           | Reproduces via API client without UI; consistent under load.            | File `BUG.md`; do not modify the test.                                                                             |
+
+## Heuristic: probability x reproducibility
+
+| Reproducibility      | Action                                                     |
+| -------------------- | ---------------------------------------------------------- |
+| 100% (deterministic) | Not flake; debug as failure.                               |
+| 30–95%               | Triage; classify.                                          |
+| < 30%                | Repeat with `--repeat-each=20`; if still rare, quarantine. |
+| 0%                   | Already fixed or environment artifact; close.              |
+
+## Why care about classification
+
+Untyped flakes accumulate. After 6 months of "rerun" culture you have 200 tests with hidden bugs and no signal worth trusting. The skill enforces a class per case so the team can plot the distribution and target the worst class first.
diff --git a/.claude/skills/flaky-triage/references/quarantine-policy.md b/.claude/skills/flaky-triage/references/quarantine-policy.md
new file mode 100644
index 0000000..e0a1596
--- /dev/null
+++ b/.claude/skills/flaky-triage/references/quarantine-policy.md
@@ -0,0 +1,34 @@
+# Quarantine policy
+
+Quarantine is a last resort, not a coping mechanism.
+
+## Tag
+
+```ts
+test('quarantine candidate @quarantine #PROJ-1234', async ({}) => {
+  /* ... */
+});
+```
+
+## Rules
+
+1. Every `@quarantine` MUST have an open issue link in the title or annotation.
+2. CI runs quarantined tests but does NOT fail the build on them. Failures are reported separately.
+3. Maximum age: **2 sprints**. After that, the test is either fixed or deleted.
+4. Quarantine cap per repo: **2%** of total tests. If exceeded, all engineering work pauses on new features until under cap.
+
+## Enforcement
+
+`scripts/check-quarantine-age.sh` runs in CI:
+
+- Greps for `@quarantine` tags.
+- Cross-references with the issue tracker via `GH_TOKEN` and the issue id parsed from the title.
+- Fails the build if any quarantined test is older than 2 sprints (configurable in days).
+
+## Ownership
+
+A quarantined test has an owner (the SDET who tagged it). The owner gets a weekly reminder until the test is removed from quarantine or the team explicitly accepts the cost.
+
+## Anti-pattern
+
+`test.describe.skip(...)` mass-disabling — the worst version of quarantine because it disappears from reports. Prefer the tag.
diff --git a/.claude/skills/flaky-triage/references/repro-strategy.md b/.claude/skills/flaky-triage/references/repro-strategy.md
new file mode 100644
index 0000000..a029d7a
--- /dev/null
+++ b/.claude/skills/flaky-triage/references/repro-strategy.md
@@ -0,0 +1,30 @@
+# Reproducing flakes
+
+The single most useful trick is to make the flake reliably reproducible.
+
+## Step ladder
+
+1. **Repeat-each**: `npx playwright test path/spec --repeat-each=20`. Catches simple races.
+2. **Shuffle**: `npx playwright test --shuffle`. Catches order-dependent leaks.
+3. **Workers=1 + repeat-each=20**: isolates from parallelism.
+4. **Workers=4 + repeat-each=20**: surfaces parallelism issues.
+5. **Slow CI sim**: `--use-args slowMo=200` and `CPU=2` (`taskset -c 0,1`) to mimic constrained CI agents.
+6. **Different timezone**: `TZ=America/Los_Angeles npx playwright test`.
+7. **Different locale**: `LANG=de_DE.UTF-8 LANGUAGE=de`.
+8. **Throttled network**: per-context `await context.route('**', route => /* delay */)` or use Chrome DevTools throttling profile.
+9. **Different browser engine**: rerun on firefox + webkit.
+
+## Capture maximum data on first reliable repro
+
+```bash
+npx playwright test path/spec \
+  --workers=1 \
+  --repeat-each=20 \
+  --trace=on \
+  --video=on \
+  --reporter=list,html,json
+```
+
+## When you cannot reproduce
+
+Don't fight it. Quarantine, file an issue with the failing trace, and move on. Reproducible flakes get fixed; irreproducible "haunted" tests get deleted after 2 sprints — the cost of looking flaky outweighs the small probability of catching a real bug.
diff --git a/.claude/skills/flaky-triage/scripts/flake-rate.ts b/.claude/skills/flaky-triage/scripts/flake-rate.ts
new file mode 100755
index 0000000..a1eaa51
--- /dev/null
+++ b/.claude/skills/flaky-triage/scripts/flake-rate.ts
@@ -0,0 +1,60 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * flake-rate.ts — given a directory of Playwright JSON reports, computes
+ * pass/fail rate per test and emits a Markdown table sorted by flakiness.
+ *
+ * Usage:
+ *   tsx flake-rate.ts ./runs > FLAKE_REPORT.md
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const dir = process.argv[2] ?? './runs';
+
+interface Stat {
+  passed: number;
+  failed: number;
+  flaky: number;
+  total: number;
+}
+const stats = new Map<string, Stat>();
+
+function bump(key: string, status: string) {
+  const s = stats.get(key) ?? { passed: 0, failed: 0, flaky: 0, total: 0 };
+  s.total++;
+  if (status === 'passed' || status === 'expected') s.passed++;
+  else if (status === 'failed' || status === 'unexpected' || status === 'timedOut') s.failed++;
+  else if (status === 'flaky') s.flaky++;
+  stats.set(key, s);
+}
+
+function walk(node: any) {
+  for (const spec of node.specs ?? []) {
+    for (const t of spec.tests ?? []) {
+      const key = `${spec.file ?? '?'} > ${spec.title}`;
+      for (const r of t.results ?? []) bump(key, r.status);
+    }
+  }
+  for (const child of node.suites ?? []) walk(child);
+}
+
+const files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+for (const f of files) {
+  const json = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+  walk(json);
+}
+
+const rows = [...stats.entries()]
+  .map(([title, s]) => ({ title, ...s, rate: s.failed / Math.max(s.total, 1) }))
+  .filter((r) => r.rate > 0 && r.rate < 1)
+  .sort((a, b) => b.rate - a.rate);
+
+console.log('# Flake report\n');
+console.log(`Runs analysed: ${files.length}\n`);
+console.log('| Test | Total | Pass | Fail | Flake | Failure rate |');
+console.log('|---|---:|---:|---:|---:|---:|');
+for (const r of rows) {
+  console.log(
+    `| ${r.title} | ${r.total} | ${r.passed} | ${r.failed} | ${r.flaky} | ${(r.rate * 100).toFixed(0)}% |`,
+  );
+}
diff --git a/.claude/skills/gherkin-test-case-author/SKILL.md b/.claude/skills/gherkin-test-case-author/SKILL.md
new file mode 100644
index 0000000..69686a8
--- /dev/null
+++ b/.claude/skills/gherkin-test-case-author/SKILL.md
@@ -0,0 +1,27 @@
+---
+name: gherkin-test-case-author
+description: Authors Gherkin (Given-When-Then) or structured test cases from an existing test design document. Enforces declarative style, single-purpose scenarios, ubiquitous domain language, and correct level of abstraction. Use when a docs/test-design/*.md exists and user says "write test cases", "gherkin", "feature file", "BDD", "scenarios". Do NOT use to author Playwright TypeScript code; defer to playwright-test-author-*.
+allowed-tools: Read, Write, Glob, Grep
+---
+
+# Gherkin Test Case Author
+
+## Hard rules
+
+- One scenario = one behaviour. If you write `And ... And ... And` more than 3 times, split.
+- Use **declarative** language ("user submits the form"), not **imperative** ("user clicks #submit").
+- No UI selectors in `.feature`. Selectors live in step definitions / page objects.
+- Use `Background` only for setup shared by ALL scenarios in the file. Otherwise factor to fixtures.
+- Scenario Outline only when the test logic is identical and only data changes.
+
+## Workflow
+
+1. Read `docs/test-design/<feature>.md`.
+2. Generate `tests/specs/<feature>.feature` (or structured TC json if BDD is not used).
+3. Run `scripts/gherkin-lint.sh` (gherkin-lint with strict ruleset).
+
+## References
+
+- `references/declarative-vs-imperative.md`
+- `references/gherkin-smells.md` (UI leak, "And" abuse, conjunctions, abstract verbs)
+- `references/feature.template.feature`
diff --git a/.claude/skills/gherkin-test-case-author/assets/README.md b/.claude/skills/gherkin-test-case-author/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/gherkin-test-case-author/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/gherkin-test-case-author/references/declarative-vs-imperative.md b/.claude/skills/gherkin-test-case-author/references/declarative-vs-imperative.md
new file mode 100644
index 0000000..41e49fe
--- /dev/null
+++ b/.claude/skills/gherkin-test-case-author/references/declarative-vs-imperative.md
@@ -0,0 +1,46 @@
+# Declarative vs imperative Gherkin
+
+## Imperative (avoid)
+
+Reads like a UI script. Brittle, ages poorly, hides intent.
+
+```gherkin
+Scenario: Login
+  Given I open "https://app.example.com/login"
+  When I type "user@example.com" into the field with id "email"
+  And I type "Pa$$w0rd" into the field with id "password"
+  And I click the button with class "btn-primary"
+  Then I see the text "Welcome" on the page
+```
+
+## Declarative (prefer)
+
+Describes user intent in domain language; details live in step definitions.
+
+```gherkin
+Scenario: Authenticated user reaches the dashboard
+  Given a registered user
+  When the user signs in with valid credentials
+  Then the dashboard is displayed
+```
+
+## How to choose verbs
+
+- Domain verbs ("submits", "approves", "cancels") rather than UI verbs ("clicks", "types").
+- Reference roles ("the user", "an admin"), not selectors.
+- Talk about outcomes ("the order is rejected"), not implementation ("the API returns 422").
+
+## Where the detail goes
+
+- Step definitions translate intent to API/UI actions.
+- Page objects encapsulate selectors.
+- Factories provide data ("a registered user" → `userFactory.build()` + API seed).
+
+## Smell triggers
+
+| Smell                                  | Fix                                   |
+| -------------------------------------- | ------------------------------------- |
+| `id "..."` / `class "..."` in scenario | Move to step definition / page object |
+| `wait 2 seconds`                       | Use web-first assertions inside step  |
+| Multi-paragraph `Then`                 | Split scenario                        |
+| Same `Given` in 5+ scenarios           | Promote to `Background` or fixture    |
diff --git a/.claude/skills/gherkin-test-case-author/references/feature.template.feature b/.claude/skills/gherkin-test-case-author/references/feature.template.feature
new file mode 100644
index 0000000..ce079cd
--- /dev/null
+++ b/.claude/skills/gherkin-test-case-author/references/feature.template.feature
@@ -0,0 +1,34 @@
+@feature:auth @owner:qa-platform
+Feature: User authentication
+
+  As a registered user
+  I want to sign in with my credentials
+  So that I can access my private dashboard
+
+  Background:
+    Given the application is reachable
+
+  @smoke @ac:AC-1
+  Scenario: Authenticated user reaches the dashboard
+    Given a registered user
+    When the user signs in with valid credentials
+    Then the dashboard is displayed
+
+  @ac:AC-2
+  Scenario: Invalid password is rejected with a clear message
+    Given a registered user
+    When the user signs in with the wrong password
+    Then a generic invalid-credentials message is displayed
+    And the user remains on the sign-in page
+
+  @ac:AC-3
+  Scenario Outline: Locked accounts cannot sign in
+    Given a registered user whose account is "<status>"
+    When the user signs in with valid credentials
+    Then the sign-in is denied with reason "<reason>"
+
+    Examples:
+      | status     | reason             |
+      | suspended  | account-suspended  |
+      | deleted    | account-not-found  |
+      | unverified | email-not-verified |
diff --git a/.claude/skills/gherkin-test-case-author/references/gherkin-smells.md b/.claude/skills/gherkin-test-case-author/references/gherkin-smells.md
new file mode 100644
index 0000000..b8ac2d5
--- /dev/null
+++ b/.claude/skills/gherkin-test-case-author/references/gherkin-smells.md
@@ -0,0 +1,30 @@
+# Gherkin smells
+
+A non-exhaustive list flagged by the reviewer.
+
+## Structure smells
+
+- **And-abuse**: `When ... And ... And ... And ...` — collapse to one declarative step or split scenarios.
+- **Conjunction step**: `Given the user is logged in and has 3 items in cart` — split with `And`.
+- **Outline-as-data-dump**: `Examples:` table with 50 rows — move to a unit/contract test.
+- **Background bloat**: `Background` containing setup specific to one scenario.
+- **Tag soup**: 7+ tags on a single scenario — usually a sign two scenarios are conflated.
+
+## Language smells
+
+- **Imperative verbs**: clicks, types, scrolls — replace with domain verbs.
+- **UI selectors leaking**: `#submit`, `.btn-primary` — never in a feature file.
+- **Implementation leaking**: "the database row is updated" — talk about outcomes the user observes.
+- **Vague verbs**: "checks", "verifies", "ensures" — say what is observed.
+- **Plural assertions**: "Then the user sees the dashboard and the welcome banner and the menu" — split.
+
+## Scope smells
+
+- A single scenario covering happy path + edge case + error.
+- Two scenarios that differ only by environment (lift to projects/tags instead).
+- Scenario outline whose logic actually differs across rows.
+
+## Maintainability smells
+
+- Step definitions duplicated across feature files — promote to a shared step library.
+- A step that takes 6+ parameters — wrap parameters in a builder/factory call.
diff --git a/.claude/skills/gherkin-test-case-author/scripts/gherkin-lint.sh b/.claude/skills/gherkin-test-case-author/scripts/gherkin-lint.sh
new file mode 100755
index 0000000..fcfe4e0
--- /dev/null
+++ b/.claude/skills/gherkin-test-case-author/scripts/gherkin-lint.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+#
+# gherkin-lint.sh — runs gherkin-lint over feature files (best-effort soft check).
+#
+set -euo pipefail
+ROOT="${1:-$(pwd)}"
+
+if ! find "$ROOT/tests" -name '*.feature' -print -quit 2>/dev/null | grep -q .; then
+  echo "OK: no .feature files."
+  exit 0
+fi
+
+# Use npx with --yes to avoid interactive prompts; tolerate missing config
+npx --yes gherkin-lint "tests/**/*.feature" || {
+  echo "Gherkin lint reported issues. Address smells in references/gherkin-smells.md."
+  exit 1
+}
diff --git a/.claude/skills/playwright-debug-conductor/SKILL.md b/.claude/skills/playwright-debug-conductor/SKILL.md
new file mode 100644
index 0000000..7ad640d
--- /dev/null
+++ b/.claude/skills/playwright-debug-conductor/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: playwright-debug-conductor
+description: Conducts an interactive debugging session for a failing Playwright test using Trace Viewer, headed mode, --debug, slow-mo, and UI mode. Produces a root-cause hypothesis with evidence (screenshot, trace event, network log). Use when a test fails repeatedly, user asks "why is this flaky", "debug this test", "trace viewer says...", or after playwright-test-author-* hits 2+ retries. Do NOT use to write new tests.
+allowed-tools: Read, Edit, Bash, Glob, Grep
+---
+
+# Playwright Debug Conductor
+
+## Workflow
+
+1. Re-run the failing spec with `--trace on --reporter=list --workers=1 --headed=$HEADED`.
+2. Open `test-results/.../trace.zip` programmatically and `scripts/extract-failing-step.ts` summarises:
+   - failing locator + last DOM snapshot
+   - last 5 network calls + status
+   - last 20 console messages
+   - duration of each step
+3. Classify failure: `selector`, `timing`, `data`, `env`, `app-bug`, `flake`.
+4. Propose ONE fix at a time. Validate by re-running.
+5. If app bug: stop, file `BUG.md` with reproducer.
+
+## Failure classifier
+
+| Signal                                           | Class          | First action                                         |
+| ------------------------------------------------ | -------------- | ---------------------------------------------------- |
+| `Locator expected to be visible` after long wait | timing         | switch to web-first; widen actionTimeout per-action  |
+| `strict mode violation: resolved to N elements`  | selector       | scope locator inside an ancestor; use `getByRole`    |
+| 401/403 in last network call                     | env / auth     | verify storageState; rotate test creds               |
+| 5xx in last network call                         | env / app-bug  | reproduce via API client; if reproducible → BUG.md   |
+| Order-dependent failure                          | data leak      | run with `--shuffle --workers=1`; suspect a fixture  |
+| Passes headed, fails headless                    | timing / focus | check animation, autofocus, `prefers-reduced-motion` |
+
+## References
+
+- `references/failure-taxonomy.md`
+- `references/trace-cheatsheet.md`
+- `references/ui-mode-vs-debug.md`
diff --git a/.claude/skills/playwright-debug-conductor/assets/README.md b/.claude/skills/playwright-debug-conductor/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/playwright-debug-conductor/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/playwright-debug-conductor/references/failure-taxonomy.md b/.claude/skills/playwright-debug-conductor/references/failure-taxonomy.md
new file mode 100644
index 0000000..e319f03
--- /dev/null
+++ b/.claude/skills/playwright-debug-conductor/references/failure-taxonomy.md
@@ -0,0 +1,32 @@
+# Failure taxonomy
+
+Every failed test must end up in exactly one bucket. The bucket determines the fix path.
+
+| Class        | Description                                                     | Fix owner                   |
+| ------------ | --------------------------------------------------------------- | --------------------------- |
+| **selector** | Locator misses, matches multiple, or matches the wrong element. | SDET                        |
+| **timing**   | Assertion fired before stable state.                            | SDET                        |
+| **data**     | Test data wrong/missing/leaked.                                 | SDET (factory or fixture)   |
+| **env**      | Wrong baseURL, expired secret, broken setup.                    | SDET / DevOps               |
+| **app-bug**  | The product genuinely misbehaves.                               | Dev                         |
+| **flake**    | Intermittent, root cause unknown.                               | Hand off to flaky-detective |
+| **harness**  | Playwright/Node/runner misconfig.                               | SDET / Platform             |
+
+## Decision flow
+
+```
+Failure
+ ├─ Reproducible alone? ── no ──> flake → flaky-detective
+ ├─ yes
+ │   ├─ Same on multiple browsers?
+ │   │    yes ── reproducible via API client only? ── yes ──> app-bug → BUG.md
+ │   │                                              no  ──> timing/selector
+ │   │    no  ──> harness / browser-specific
+ │   ├─ Wrong data? ──> data
+ │   ├─ Wrong baseURL/secret? ──> env
+ │   └─ otherwise ──> selector / timing per signals
+```
+
+## Anti-pattern: "fix" by retry
+
+Retrying does NOT close any failure class. If the only "fix" you can propose is "increase retries / timeout", reclassify as flake and triage properly.
diff --git a/.claude/skills/playwright-debug-conductor/references/trace-cheatsheet.md b/.claude/skills/playwright-debug-conductor/references/trace-cheatsheet.md
new file mode 100644
index 0000000..a87694a
--- /dev/null
+++ b/.claude/skills/playwright-debug-conductor/references/trace-cheatsheet.md
@@ -0,0 +1,39 @@
+# Trace Viewer cheatsheet
+
+## Open a trace
+
+```bash
+npx playwright show-trace test-results/<dir>/trace.zip
+# or open the HTML report and click any failed test → "Trace"
+```
+
+## What to look at, in order
+
+1. **Last action before failure** — pick the red step. Its DOM snapshot is on the right. Compare expected locator vs actual DOM.
+2. **Action timing** — was the action queued long before resolution? Likely actionability gate (visible/enabled/stable).
+3. **Network tab** — last few requests. 4xx/5xx, slow responses, missing CORS.
+4. **Console tab** — uncaught errors, deprecation warnings.
+5. **Source tab** — the line that called the failing API.
+6. **Snapshots side-by-side** — toggle "Before" and "After" of the failing step.
+
+## Generate a richer trace
+
+```bash
+npx playwright test path/to/spec --trace on --video on --headed --workers=1
+```
+
+## Targeted trace for an investigation
+
+```ts
+test('investigate intermittent submit', async ({ page }, testInfo) => {
+  await testInfo.attach('initial-html', { body: await page.content(), contentType: 'text/html' });
+  // ... actions ...
+});
+```
+
+## Common findings
+
+- Element exists but is covered by a sticky header → `scrollIntoViewIfNeeded` or assert on `toBeInViewport`.
+- Element re-renders mid-action → use `getByRole` (re-resolves) instead of `locator(...).nth(0)`.
+- Animation hides the element briefly → `prefers-reduced-motion` env or wait for `transition-end`.
+- Element resolves to 2 because a dialog and the main page share the same role/text → scope inside `getByRole('dialog')`.
diff --git a/.claude/skills/playwright-debug-conductor/references/ui-mode-vs-debug.md b/.claude/skills/playwright-debug-conductor/references/ui-mode-vs-debug.md
new file mode 100644
index 0000000..97ee570
--- /dev/null
+++ b/.claude/skills/playwright-debug-conductor/references/ui-mode-vs-debug.md
@@ -0,0 +1,48 @@
+# UI mode vs --debug vs codegen
+
+A quick map of when to reach for which tool.
+
+## UI mode (`npx playwright test --ui`)
+
+Best default for interactive debugging.
+
+- Time-travel through actions with DOM snapshots.
+- Live watch: edits to spec/page-object re-run automatically.
+- Filter by test name / project / tags / status.
+- Pick locator interactively against the live page.
+
+Use when: iterating on a single test, choosing locators, exploring why a step misbehaves.
+
+## `--debug` (`npx playwright test --debug`)
+
+Drops you into the Playwright Inspector with `pause()` semantics.
+
+- Step over each action.
+- Edit locators on the fly via the Inspector.
+- Useful when UI mode is too "watchy" and you need full control.
+
+Use when: pinpoint debugging deep inside a long test.
+
+## `codegen` (`npx playwright codegen <url>`)
+
+Records actions and emits suggestion-quality scaffolding.
+
+- Fastest way to get a candidate locator.
+- Output is NOT production-ready — it goes through `playwright-test-author-ui` to be reformulated.
+
+Use when: bootstrapping a new page object, exploring a new flow.
+
+## Headed + slow-mo
+
+```bash
+PWDEBUG=1 npx playwright test path/spec --headed --workers=1
+# or
+npx playwright test --headed --workers=1 --use-args slowMo=300
+```
+
+Use when: visually verifying a flow, or when a test passes headless and fails headed (or vice versa).
+
+## When NOT to use these
+
+- In CI. CI runs headless with `--reporter=list,html`. Trace Viewer post-mortem is the right tool there.
+- For flake triage on a wide scale — that's `flaky-triage` running over JSON results, not interactive.
diff --git a/.claude/skills/playwright-debug-conductor/scripts/extract-failing-step.ts b/.claude/skills/playwright-debug-conductor/scripts/extract-failing-step.ts
new file mode 100755
index 0000000..89b6244
--- /dev/null
+++ b/.claude/skills/playwright-debug-conductor/scripts/extract-failing-step.ts
@@ -0,0 +1,57 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * extract-failing-step.ts — produce a compact JSON summary of the failure.
+ * Reads test-results/results.json (Playwright JSON reporter) and emits per-failed-test:
+ *   { file, title, errorMessage, durationMs, projectName, attachments }
+ *
+ * Usage:
+ *   tsx extract-failing-step.ts > FAILURES.json
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.cwd();
+const resultsPath = join(root, 'playwright-report', 'results.json');
+
+if (!existsSync(resultsPath)) {
+  console.error(`FAIL: ${resultsPath} not found. Run with --reporter=json,list,html.`);
+  process.exit(2);
+}
+
+const results = JSON.parse(readFileSync(resultsPath, 'utf8'));
+
+interface Out {
+  file: string;
+  title: string;
+  projectName: string;
+  durationMs: number;
+  errorMessage: string;
+  attachments: { name: string; path?: string }[];
+}
+
+const failures: Out[] = [];
+
+function walk(suite: any, file: string) {
+  if (suite.specs) {
+    for (const spec of suite.specs) {
+      for (const t of spec.tests ?? []) {
+        for (const r of t.results ?? []) {
+          if (r.status === 'failed' || r.status === 'timedOut' || r.status === 'unexpected') {
+            failures.push({
+              file: spec.file ?? file,
+              title: spec.title,
+              projectName: t.projectName,
+              durationMs: r.duration,
+              errorMessage: (r.errors?.[0]?.message ?? r.error?.message ?? '').slice(0, 2000),
+              attachments: (r.attachments ?? []).map((a: any) => ({ name: a.name, path: a.path })),
+            });
+          }
+        }
+      }
+    }
+  }
+  for (const child of suite.suites ?? []) walk(child, file || child.file || '');
+}
+
+walk(results, '');
+process.stdout.write(JSON.stringify(failures, null, 2));
diff --git a/.claude/skills/playwright-framework-bootstrap/SKILL.md b/.claude/skills/playwright-framework-bootstrap/SKILL.md
new file mode 100644
index 0000000..36ffb54
--- /dev/null
+++ b/.claude/skills/playwright-framework-bootstrap/SKILL.md
@@ -0,0 +1,52 @@
+---
+name: playwright-framework-bootstrap
+description: Bootstraps or refactors a TypeScript+Playwright repository into a canonical layered architecture (UI/API/Data/Infra/Test). Creates page-objects/, components/, api/, fixtures/, factories/, data/, specs/ with strict boundaries and writes tests-config.json. Use when user starts a new automation project, asks to "set up a framework", "scaffold tests", "refactor folder structure", or when tests-config.json is missing. Do NOT use when only writing a single test or feature; use playwright-test-author-* instead.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Playwright Framework Bootstrap
+
+## When to trigger
+
+- New empty repo or one without `tests-config.json`.
+- User says "scaffold", "bootstrap", "set up framework", "structure tests folder".
+- Migration from a flat `tests/*.spec.ts` layout.
+
+## When NOT to trigger
+
+- A single test/page-object change → defer to `playwright-test-author-*`.
+- Config-only edits → defer to `config-and-secrets`.
+
+## Workflow
+
+1. **Detect state.** Read `package.json`, `playwright.config.ts`, `tsconfig.json`, existing `tests/`. If `tests-config.json` exists, only verify and gap-fill.
+2. **Pin layout.** Generate `tests-config.json` from `references/layout.template.json`.
+3. **Create directories** matching the config (idempotent).
+4. **Install minimal deps** (only if user opts in): `@playwright/test`, `fishery`, `openapi-typescript`, `openapi-fetch`, `zod`, `dotenv`. Confirm versions against `references/deps.lock.md`.
+5. **Write `playwright.config.ts`** from `references/playwright.config.template.ts` with: projects per browser, `fullyParallel: true`, `retries: process.env.CI ? 2 : 0`, `reporter: [['list'], ['html', { open: 'never' }]]`, traces `on-first-retry`, screenshots `only-on-failure`.
+6. **Write `BasePage.ts`** (locators-only abstract class, NO assertions, NO navigation logic in base).
+7. **Validate** with `scripts/validate-layout.sh` (exit 0 required).
+
+## Required outputs
+
+- `tests-config.json` committed.
+- `playwright.config.ts`, `tsconfig.json` paths aligned (`@pages/*`, `@api/*`, `@fixtures/*`).
+- README diff snippet appended explaining layout.
+
+## Hard rules (enforced by `scripts/validate-layout.sh`)
+
+- No file in `specs/` may import from `pages/*/locators` directly — only via the page class.
+- `BasePage` must not import `expect`.
+- No two classes named `*Page` outside `pages/`.
+
+## References
+
+- `references/layout.template.json`
+- `references/playwright.config.template.ts`
+- `references/base-page.template.ts`
+- `references/folder-rationale.md` (why each layer exists)
+
+## Composability
+
+- Pairs with `config-and-secrets`, `fixture-architect`, `api-client-from-openapi`.
+- Always run BEFORE any `playwright-test-author-*` skill.
diff --git a/.claude/skills/playwright-framework-bootstrap/assets/README.md b/.claude/skills/playwright-framework-bootstrap/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/playwright-framework-bootstrap/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/playwright-framework-bootstrap/references/base-page.template.ts b/.claude/skills/playwright-framework-bootstrap/references/base-page.template.ts
new file mode 100644
index 0000000..df75492
--- /dev/null
+++ b/.claude/skills/playwright-framework-bootstrap/references/base-page.template.ts
@@ -0,0 +1,25 @@
+import type { Page } from '@playwright/test';
+
+/**
+ * BasePage — abstract anchor for all page objects.
+ * Hard rules (enforced by lint-page-object.ts):
+ *  - NO `expect` imports here. Assertions belong to specs.
+ *  - NO navigation logic. Each subclass declares its own `path` and a public `goto()`.
+ *  - NO shared mutable state.
+ *  - Only locator builders and stateless helpers.
+ */
+export abstract class BasePage {
+  protected constructor(protected readonly page: Page) {}
+
+  /** Sub-classes declare a relative path; goto() composes with the configured baseURL. */
+  protected abstract readonly path: string;
+
+  async goto(): Promise<void> {
+    await this.page.goto(this.path);
+  }
+
+  /** Returns the human-readable URL for diagnostics; never used for assertions. */
+  url(): string {
+    return this.page.url();
+  }
+}
diff --git a/.claude/skills/playwright-framework-bootstrap/references/deps.lock.md b/.claude/skills/playwright-framework-bootstrap/references/deps.lock.md
new file mode 100644
index 0000000..d1ad423
--- /dev/null
+++ b/.claude/skills/playwright-framework-bootstrap/references/deps.lock.md
@@ -0,0 +1,16 @@
+# Recommended dependency versions
+
+Update with care; pin in `package.json` to `^` minor.
+
+| Package                  | Min version          | Reason                                     |
+| ------------------------ | -------------------- | ------------------------------------------ |
+| `@playwright/test`       | `^1.50.0`            | web-first assertions, UI mode, traces      |
+| `typescript`             | `^5.4.0`             | satisfies operator, const type params      |
+| `fishery`                | `^2.2.2`             | sequence + transient params + associations |
+| `@faker-js/faker`        | `^9.0.0`             | deterministic seeding                      |
+| `openapi-typescript`     | `^7.0.0`             | spec → types                               |
+| `openapi-fetch`          | `^0.13.0`            | tiny typed client                          |
+| `zod`                    | `^3.23.0`            | runtime contract validation                |
+| `dotenv` / `dotenv-flow` | `^16.0.0` / `^4.0.0` | env layering                               |
+| `eslint`                 | `^9.0.0`             | flat config                                |
+| `husky` + `lint-staged`  | `^9.0.0` / `^15.0.0` | pre-commit gates                           |
diff --git a/.claude/skills/playwright-framework-bootstrap/references/folder-rationale.md b/.claude/skills/playwright-framework-bootstrap/references/folder-rationale.md
new file mode 100644
index 0000000..47753ef
--- /dev/null
+++ b/.claude/skills/playwright-framework-bootstrap/references/folder-rationale.md
@@ -0,0 +1,36 @@
+# Folder rationale
+
+The layered layout exists to enforce SRP and DIP at the file-system level. Skills validate that imports cross layers in one direction only.
+
+| Folder              | Responsibility                                                                       | Forbidden inside                                      |
+| ------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------- |
+| `tests/pages/`      | Page objects: locators + behaviours per page. One class per page.                    | `expect`, hardcoded URLs, business assertions         |
+| `tests/components/` | Component objects shared across multiple pages (header, footer, modal).              | Cross-page navigation logic                           |
+| `tests/api/`        | API client layer. `generated/` for OpenAPI artefacts, `clients/` for typed wrappers. | `axios`, raw `fetch` outside generated/clients        |
+| `tests/fixtures/`   | Playwright `test.extend` composition. DI for tests.                                  | Domain logic, factories                               |
+| `tests/factories/`  | Test data factories (Fishery + Faker). One file per entity.                          | Network calls, side effects                           |
+| `tests/specs/`      | The actual tests. AAA / Given-When-Then.                                             | Locators (must come from pages), inline data literals |
+| `tests/data/`       | Static JSON fixtures (golden files, schema samples).                                 | Generated code                                        |
+| `tests/infra/`      | env loader, logger, base helpers.                                                    | Domain entities                                       |
+
+## Import direction (allowed)
+
+```
+specs/  ──>  fixtures/  ──>  pages/, components/, factories/, api/clients/
+                       \─>  infra/
+factories/  ──>  api/generated (types only)
+api/clients/  ──>  api/generated, infra/
+```
+
+Reverse imports are forbidden. The `validate-layout.sh` script greps imports and exits non-zero on violations.
+
+## Why so many layers?
+
+- Page objects encode "where" — locators and primitive interactions.
+- Components encode reuse across pages.
+- Fixtures encode "what is available in a test" — DI container.
+- Factories encode "what data the test needs" — independent of how it's persisted.
+- API clients encode "how to talk to the system" — typed and contract-aware.
+- Specs encode "what behaviour we verify" — declarative, AAA, no mechanics.
+
+Mixing these is the #1 source of brittleness in real-world Playwright suites.
diff --git a/.claude/skills/playwright-framework-bootstrap/references/layout.template.json b/.claude/skills/playwright-framework-bootstrap/references/layout.template.json
new file mode 100644
index 0000000..e16f3ab
--- /dev/null
+++ b/.claude/skills/playwright-framework-bootstrap/references/layout.template.json
@@ -0,0 +1,32 @@
+{
+  "layout": {
+    "pages": "tests/pages",
+    "components": "tests/components",
+    "apiClients": "tests/api",
+    "fixtures": "tests/fixtures",
+    "factories": "tests/factories",
+    "specs": "tests/specs",
+    "data": "tests/data",
+    "infra": "tests/infra"
+  },
+  "openapi": {
+    "source": "specs/openapi.yaml",
+    "generated": "tests/api/generated"
+  },
+  "naming": {
+    "pageClass": "PascalCase",
+    "specFile": "kebab-case.spec.ts",
+    "factoryFile": "kebab-case.factory.ts"
+  },
+  "selectors": {
+    "preferred": ["getByRole", "getByLabel", "getByTestId"],
+    "testIdAttr": "data-testid"
+  },
+  "stack": {
+    "factories": "fishery",
+    "openapi": "openapi-typescript+openapi-fetch",
+    "schemaValidation": "zod"
+  },
+  "envs": ["local", "staging", "prod"],
+  "version": 1
+}
diff --git a/.claude/skills/playwright-framework-bootstrap/references/playwright.config.template.ts b/.claude/skills/playwright-framework-bootstrap/references/playwright.config.template.ts
new file mode 100644
index 0000000..902c8e4
--- /dev/null
+++ b/.claude/skills/playwright-framework-bootstrap/references/playwright.config.template.ts
@@ -0,0 +1,45 @@
+import { defineConfig, devices } from '@playwright/test';
+import 'dotenv/config';
+
+const isCI = !!process.env.CI;
+
+export default defineConfig({
+  testDir: 'tests/specs',
+  fullyParallel: true,
+  forbidOnly: isCI,
+  retries: isCI ? 2 : 0,
+  workers: isCI ? '50%' : undefined,
+  reporter: [
+    ['list'],
+    ['html', { open: 'never', outputFolder: 'playwright-report' }],
+    ['json', { outputFile: 'playwright-report/results.json' }],
+    ['junit', { outputFile: 'playwright-report/junit.xml' }],
+  ],
+  use: {
+    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    actionTimeout: 10_000,
+    navigationTimeout: 30_000,
+    testIdAttribute: 'data-testid',
+  },
+  projects: [
+    { name: 'setup', testMatch: /.*\.setup\.ts/ },
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'], storageState: 'tests/.auth/user.json' },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'], storageState: 'tests/.auth/user.json' },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'api',
+      testDir: 'tests/specs/api',
+      use: { baseURL: process.env.API_BASE_URL ?? 'http://localhost:8080' },
+    },
+  ],
+});
diff --git a/scripts/validate-layout.sh b/.claude/skills/playwright-framework-bootstrap/scripts/validate-layout.sh
similarity index 100%
rename from scripts/validate-layout.sh
rename to .claude/skills/playwright-framework-bootstrap/scripts/validate-layout.sh
diff --git a/.claude/skills/playwright-test-author-api/SKILL.md b/.claude/skills/playwright-test-author-api/SKILL.md
new file mode 100644
index 0000000..859a09f
--- /dev/null
+++ b/.claude/skills/playwright-test-author-api/SKILL.md
@@ -0,0 +1,39 @@
+---
+name: playwright-test-author-api
+description: Writes Playwright API/contract tests using the typed OpenAPI client and zod schemas. Enforces request/response schema validation, idempotent setup, status-code + body assertions, and contract-driven negative tests. Use when user asks for an API test, "test the endpoint", "verify response schema", "contract test", "negative test for API". Do NOT use for UI flows; defer to playwright-test-author-ui.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Playwright Test Author — API
+
+## Hard rules
+
+- Use generated client (`tests/api/clients/*`) — no `fetch()`/`axios` directly in spec.
+- ALWAYS validate response body via the corresponding `zod` schema (auto-generated from OpenAPI).
+- Cover: happy path, schema integrity, auth boundary, validation errors per AC, idempotency where applicable.
+- Each test must clean up its data (or use a per-test factory tag).
+- 5xx → flaky → mark `test.fail()` with TODO ticket, do NOT silently retry.
+
+## Workflow
+
+1. Read endpoint definition in `specs/openapi.yaml` (path, methods, params, responses).
+2. Read corresponding test design — pick scenarios tagged for `api` layer.
+3. Author test in `tests/specs/api/<resource>/<endpoint>.spec.ts` using `references/api-spec.template.ts`.
+4. Run `scripts/lint-api-spec.ts` until exit 0.
+5. Run target spec: `npx playwright test tests/specs/api/<resource> --project=api`.
+
+## Test matrix per endpoint (minimum)
+
+- Happy path: valid request → success status + schema.
+- Auth boundary: missing/invalid token → 401/403.
+- Validation: each required field individually omitted → 4xx.
+- Boundary values: numeric/length min/max ± 1.
+- Idempotency: repeating the same request (where applicable) yields the same result.
+- Negative: forbidden role, deleted resource, version conflict.
+
+## References
+
+- `references/contract-test-patterns.md`
+- `references/idempotency-strategies.md`
+- `references/error-taxonomy.md`
+- `references/api-spec.template.ts`
diff --git a/.claude/skills/playwright-test-author-api/assets/README.md b/.claude/skills/playwright-test-author-api/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/playwright-test-author-api/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/playwright-test-author-api/references/api-spec.template.ts b/.claude/skills/playwright-test-author-api/references/api-spec.template.ts
new file mode 100644
index 0000000..b89cd5f
--- /dev/null
+++ b/.claude/skills/playwright-test-author-api/references/api-spec.template.ts
@@ -0,0 +1,66 @@
+/**
+ * Template for an API/contract spec.
+ * Demonstrates the canonical structure: client + factory + schema validator.
+ */
+import { test, expect } from '@fixtures';
+import { OrderSchema, OrderListSchema } from '@api/generated/zod';
+import { expectMatchesSchema } from '@api/contract';
+import { orderFactory } from '@factories/order.factory';
+
+test.describe('POST /orders', () => {
+  test('@smoke creates an order and returns it matching the schema', async ({
+    ordersClient,
+    seededUser,
+  }) => {
+    const draft = orderFactory.build({ userId: seededUser.id });
+
+    const { data, response } = await ordersClient.create(draft);
+
+    expect(response.status).toBe(201);
+    expectMatchesSchema(data, OrderSchema);
+    expect(data.userId).toBe(seededUser.id);
+  });
+
+  test('rejects request without required field with a 422 and structured error', async ({
+    ordersClient,
+    seededUser,
+  }) => {
+    const invalid = orderFactory.build({ userId: seededUser.id, items: [] });
+
+    const { data, response } = await ordersClient.create(invalid);
+
+    expect(response.status).toBe(422);
+    expect(data).toMatchObject({
+      code: 'validation_error',
+      fields: expect.arrayContaining(['items']),
+    });
+  });
+
+  test('returns 401 when called anonymously', async ({ anonClient }) => {
+    const draft = orderFactory.build();
+    const { response } = await anonClient.orders.create(draft);
+    expect(response.status).toBe(401);
+  });
+});
+
+test.describe('GET /orders', () => {
+  test('paginates correctly with limit and cursor', async ({ ordersClient, seededUser }) => {
+    // Arrange — seed 5 orders deterministically
+    for (const draft of orderFactory.buildList(5, { userId: seededUser.id })) {
+      await ordersClient.create(draft);
+    }
+
+    const page1 = await ordersClient.list({ userId: seededUser.id, limit: 2 });
+    expect(page1.response.status).toBe(200);
+    expectMatchesSchema(page1.data, OrderListSchema);
+    expect(page1.data.items).toHaveLength(2);
+
+    const page2 = await ordersClient.list({
+      userId: seededUser.id,
+      limit: 2,
+      cursor: page1.data.nextCursor,
+    });
+    expect(page2.data.items).toHaveLength(2);
+    expect(page2.data.items[0].id).not.toBe(page1.data.items[0].id);
+  });
+});
diff --git a/.claude/skills/playwright-test-author-api/references/contract-test-patterns.md b/.claude/skills/playwright-test-author-api/references/contract-test-patterns.md
new file mode 100644
index 0000000..5f2e995
--- /dev/null
+++ b/.claude/skills/playwright-test-author-api/references/contract-test-patterns.md
@@ -0,0 +1,56 @@
+# Contract test patterns
+
+## 1. Schema integrity (every successful response)
+
+```ts
+expect(response.status).toBe(200);
+expectMatchesSchema(data, OrderSchema);
+```
+
+Catches: drift, accidental field renames, type widening, removed fields. If the spec is the source of truth and the live API drifts, this assertion fires before any business logic test.
+
+## 2. Required-field validation (per AC)
+
+For each required field declared in the OpenAPI schema, assert that omitting it yields a 4xx with a structured error. Generate these tests programmatically when feasible:
+
+```ts
+for (const required of ['userId', 'items']) {
+  test(`returns 422 when ${required} is missing`, async ({ ordersClient }) => {
+    const { [required]: _, ...partial } = orderFactory.build();
+    const { data, response } = await ordersClient.create(partial as never);
+    expect(response.status).toBe(422);
+    expect(data.fields).toContain(required);
+  });
+}
+```
+
+## 3. Auth boundary
+
+Always include 401 (anonymous) and 403 (wrong role) tests. Do NOT collapse them into a single parameterised case — they exercise different code paths in the backend.
+
+## 4. Idempotency
+
+For POST endpoints declaring `Idempotency-Key`:
+
+```ts
+const key = crypto.randomUUID();
+const r1 = await ordersClient.create(draft, { idempotencyKey: key });
+const r2 = await ordersClient.create(draft, { idempotencyKey: key });
+expect(r1.data.id).toBe(r2.data.id);
+expect(r2.response.status).toBe(200); // not 201 on the second call
+```
+
+## 5. Pagination boundaries
+
+- limit = 0 (if allowed) or limit = 1.
+- limit = max-1, max, max+1 (spec must say what max is).
+- cursor pointing past the end → empty list, valid schema.
+- cursor that has been deleted → graceful behaviour per AC.
+
+## 6. Long polling / async
+
+If an endpoint kicks off async work, the test polls a status endpoint with `expect.poll`, never `setInterval`.
+
+## 7. Pact-style consumer tests
+
+For services consumed by other services, contract tests are bi-directional. We integrate via Pact files in CI; this is out of scope for skill-driven authoring but the spec format we produce is compatible.
diff --git a/.claude/skills/playwright-test-author-api/references/error-taxonomy.md b/.claude/skills/playwright-test-author-api/references/error-taxonomy.md
new file mode 100644
index 0000000..523c75c
--- /dev/null
+++ b/.claude/skills/playwright-test-author-api/references/error-taxonomy.md
@@ -0,0 +1,32 @@
+# Error response taxonomy
+
+A consistent error envelope makes contract tests trivial. The skill assumes the following shape (RFC 7807-flavoured):
+
+```jsonc
+{
+  "code": "validation_error", // machine-readable, snake_case
+  "message": "Items must not be empty.",
+  "fields": ["items"], // optional, present for 4xx field errors
+  "traceId": "...", // for cross-system debugging
+}
+```
+
+## Canonical buckets
+
+| Status | code namespace     | When                                    |
+| ------ | ------------------ | --------------------------------------- |
+| 400    | `bad_request`      | Malformed JSON, missing required header |
+| 401    | `unauthenticated`  | No / invalid token                      |
+| 403    | `forbidden`        | Token valid but role insufficient       |
+| 404    | `not_found`        | Resource missing                        |
+| 409    | `conflict`         | Duplicate, idempotency mismatch         |
+| 422    | `validation_error` | Field-level violations                  |
+| 429    | `rate_limited`     | Throttling hit                          |
+| 500    | `internal_error`   | Server fault — should be rare           |
+
+## Test rules
+
+- Never assert on `message` string verbatim — copy changes constantly. Assert on `code`.
+- Always assert on `fields` array for 422.
+- Always check that `traceId` is non-empty (helps support).
+- Reject 5xx outright in the test — if a 5xx is expected, the AC is broken.
diff --git a/.claude/skills/playwright-test-author-api/references/idempotency-strategies.md b/.claude/skills/playwright-test-author-api/references/idempotency-strategies.md
new file mode 100644
index 0000000..58d3ac7
--- /dev/null
+++ b/.claude/skills/playwright-test-author-api/references/idempotency-strategies.md
@@ -0,0 +1,50 @@
+# Idempotency strategies
+
+## Why we test it
+
+POST endpoints that mutate state must be idempotent under retries. Otherwise a network blip duplicates orders, charges, or messages.
+
+## Strategies
+
+| Strategy                 | Where applicable                              | Test approach                                                                 |
+| ------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------- |
+| `Idempotency-Key` header | Stripe-style APIs, payment / order creation   | Send same key twice; assert same id, second response 200 not 201.             |
+| Natural unique key       | Resource has a unique constraint (email, sku) | Send same payload twice; second returns 409 Conflict OR 200 with existing id. |
+| Server-side dedup window | Messaging / events                            | Send same payload twice within window; assert one record.                     |
+| At-most-once via locking | Cron-triggered jobs                           | Out of scope for API tests.                                                   |
+
+## Test template
+
+```ts
+test('retrying with the same Idempotency-Key returns the same resource', async ({
+  ordersClient,
+  seededUser,
+}) => {
+  const draft = orderFactory.build({ userId: seededUser.id });
+  const key = crypto.randomUUID();
+
+  const first = await ordersClient.create(draft, { idempotencyKey: key });
+  expect(first.response.status).toBe(201);
+
+  const retry = await ordersClient.create(draft, { idempotencyKey: key });
+  expect(retry.response.status).toBe(200); // not a new resource
+  expect(retry.data.id).toBe(first.data.id);
+});
+```
+
+## Negative case
+
+Different payload + same key → must NOT silently overwrite.
+
+```ts
+test('different payload with same key fails', async ({ ordersClient, seededUser }) => {
+  const key = crypto.randomUUID();
+  const a = orderFactory.build({ userId: seededUser.id });
+  const b = orderFactory.build({ userId: seededUser.id });
+
+  await ordersClient.create(a, { idempotencyKey: key });
+  const conflict = await ordersClient.create(b, { idempotencyKey: key });
+
+  expect(conflict.response.status).toBeGreaterThanOrEqual(400);
+});
+```
diff --git a/.claude/skills/playwright-test-author-api/scripts/lint-api-spec.ts b/.claude/skills/playwright-test-author-api/scripts/lint-api-spec.ts
new file mode 100755
index 0000000..999c53b
--- /dev/null
+++ b/.claude/skills/playwright-test-author-api/scripts/lint-api-spec.ts
@@ -0,0 +1,88 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * lint-api-spec.ts — checks API spec files for forbidden patterns.
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.cwd();
+const cfg = JSON.parse(readFileSync(join(root, 'tests-config.json'), 'utf8'));
+const apiSpecsDir = join(root, cfg.layout.specs, 'api');
+
+if (!existsSync(apiSpecsDir)) {
+  console.log('OK: no API spec directory yet.');
+  process.exit(0);
+}
+
+const rules: {
+  id: string;
+  severity: 'blocker' | 'major' | 'minor';
+  re: RegExp;
+  message: string;
+}[] = [
+  {
+    id: 'no-axios',
+    severity: 'major',
+    re: /from\s+['"]axios['"]/,
+    message: 'Direct axios import. Use generated client.',
+  },
+  {
+    id: 'no-fetch-url',
+    severity: 'major',
+    re: /\bfetch\s*\(\s*['"]https?:\/\//,
+    message: 'Inline fetch with URL. Use API client.',
+  },
+  {
+    id: 'no-schema-bypass',
+    severity: 'major',
+    re: /(?:\/\/.*disable.*schema|\.skipSchema\b)/,
+    message: 'Schema validation disabled.',
+  },
+  {
+    id: 'no-status-only',
+    severity: 'minor',
+    re: /^\s*expect\(response\.status\)\.toBe\(2\d\d\);\s*$/m,
+    message: 'Only status asserted; add schema or body assertion.',
+  },
+  {
+    id: 'no-message-assert',
+    severity: 'minor',
+    re: /\.message['"]\s*\)\.toBe\(['"]/,
+    message: 'Asserting on error message string. Assert on code instead.',
+  },
+];
+
+function collect(dir: string, acc: string[] = []): string[] {
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) collect(p, acc);
+    else if (p.endsWith('.spec.ts')) acc.push(p);
+  }
+  return acc;
+}
+
+const files = collect(apiSpecsDir);
+let blockers = 0,
+  majors = 0,
+  minors = 0;
+
+for (const file of files) {
+  const lines = readFileSync(file, 'utf8').split('\n');
+  lines.forEach((line, idx) => {
+    for (const r of rules) {
+      if (r.re.test(line)) {
+        console.error(`${file}:${idx + 1}  [${r.severity.toUpperCase()}][${r.id}] ${r.message}`);
+        if (r.severity === 'blocker') blockers++;
+        else if (r.severity === 'major') majors++;
+        else minors++;
+      }
+    }
+  });
+}
+
+console.error(
+  `\n${files.length} API spec(s). blockers=${blockers} majors=${majors} minors=${minors}`,
+);
+if (blockers) process.exit(2);
+if (majors) process.exit(1);
+process.exit(0);
diff --git a/.claude/skills/playwright-test-author-ui/SKILL.md b/.claude/skills/playwright-test-author-ui/SKILL.md
new file mode 100644
index 0000000..5afced4
--- /dev/null
+++ b/.claude/skills/playwright-test-author-ui/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: playwright-test-author-ui
+description: Writes Playwright UI tests in TypeScript using project page objects, fixtures, and factories — never inline locators. Enforces web-first assertions, getByRole/getByTestId, no hard waits, AAA structure, and explicit data setup via factories+API. Use when user asks for a new UI test, "automate this scenario in UI", "Playwright test for the login page", or after gherkin-test-case-author finishes. Do NOT use for pure API tests (playwright-test-author-api) or for fixture/page-object scaffolding (fixture-architect / playwright-framework-bootstrap).
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Playwright Test Author — UI
+
+## Hard rules (validated by `scripts/lint-ui-spec.ts`)
+
+1. **No `page.waitForTimeout`**. Use `expect.poll`, web-first assertions, `toBeVisible({ timeout })`.
+2. **No raw CSS/XPath selectors in spec**. Selectors live in page objects only.
+3. **Selector preference**: `getByRole` > `getByLabel` > `getByPlaceholder` > `getByTestId` > others. CSS only as last resort and reviewed.
+4. **One assertion per behaviour, AAA structure**. `expect.soft` for grouped assertions on the same state.
+5. **Data setup via API + factory**, not by clicking through UI to seed.
+6. **Authentication via storageState fixture**, not by performing UI login per test.
+7. **No `test.use()` global mutations** unless the entire file requires it.
+
+## Workflow
+
+1. Read corresponding test design + Gherkin (if any) + page objects.
+2. Map scenario steps → page-object methods. If a method is missing, add it to the page object (NOT to spec).
+3. Wrap data setup in `test.beforeEach` via fixture; cleanup in `afterEach`.
+4. Run `scripts/lint-ui-spec.ts`. Fix until exit 0.
+5. Run target spec: `npx playwright test <file> --reporter=list`. Iterate.
+
+## Auto-debug loop
+
+On failure: emit Trace Viewer link via `--trace on-first-retry`. If three retries fail, hand off to `playwright-debug-conductor`.
+
+## References
+
+- `references/web-first-assertions.md`
+- `references/locator-priority.md`
+- `references/aaa-template.ts`
+- `references/anti-flake-checklist.md`
diff --git a/.claude/skills/playwright-test-author-ui/assets/README.md b/.claude/skills/playwright-test-author-ui/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/playwright-test-author-ui/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/playwright-test-author-ui/references/aaa-template.ts b/.claude/skills/playwright-test-author-ui/references/aaa-template.ts
new file mode 100644
index 0000000..2eb7818
--- /dev/null
+++ b/.claude/skills/playwright-test-author-ui/references/aaa-template.ts
@@ -0,0 +1,29 @@
+/**
+ * AAA / Given-When-Then template for a Playwright UI spec.
+ *
+ *  - Arrange: data + auth + navigation, all via fixtures.
+ *  - Act:     a single user-meaningful action.
+ *  - Assert:  outcome the user observes; web-first matchers.
+ */
+import { test, expect } from '@fixtures';
+import { orderFactory } from '@factories/order.factory';
+
+test.describe('Order cancellation', () => {
+  test('user can cancel their own pending order', async ({
+    seededUser,
+    ordersClient,
+    dashboardPage,
+  }) => {
+    // Arrange
+    const order = await ordersClient.create(orderFactory.build({ userId: seededUser.id }));
+    await dashboardPage.goto();
+
+    // Act
+    await dashboardPage.orders.cancelByReference(order.reference);
+
+    // Assert
+    await expect(dashboardPage.orders.statusOf(order.reference)).toHaveText(/cancelled/i);
+    const refreshed = await ordersClient.getById(order.id);
+    expect(refreshed.data?.status).toBe('cancelled');
+  });
+});
diff --git a/.claude/skills/playwright-test-author-ui/references/anti-flake-checklist.md b/.claude/skills/playwright-test-author-ui/references/anti-flake-checklist.md
new file mode 100644
index 0000000..6e120a0
--- /dev/null
+++ b/.claude/skills/playwright-test-author-ui/references/anti-flake-checklist.md
@@ -0,0 +1,42 @@
+# Anti-flake checklist (UI)
+
+Run mentally before merging any UI test. If any answer is "no", fix it.
+
+## Determinism
+
+- [ ] No `waitForTimeout`. Use web-first or `expect.poll`.
+- [ ] No `setTimeout`/`setInterval` inside specs.
+- [ ] All faker-generated data is seeded.
+- [ ] Test does not depend on system time. Use `await page.clock.install()` if it must.
+- [ ] Test does not depend on order — runs alone and in suite.
+
+## Isolation
+
+- [ ] Data setup via API + factory, not by clicking.
+- [ ] Each test cleans up its own data (or fixture does).
+- [ ] No global storage of `auth.json` mutated mid-suite.
+- [ ] No shared mutable module state used across tests.
+
+## Locators
+
+- [ ] Selectors live in page objects, not specs.
+- [ ] `getByRole` / `getByLabel` first. CSS/XPath only with justification.
+- [ ] No `nth-child`, no `*:nth-of-type`.
+
+## Assertions
+
+- [ ] All assertions are web-first auto-retrying matchers.
+- [ ] Soft assertions used to group related checks on the same state.
+- [ ] No screenshot snapshots over dynamic content unless masked.
+
+## Network
+
+- [ ] External-service-dependent tests are mocked or marked `@external`.
+- [ ] `page.route` handlers are unrouted before the test ends.
+- [ ] No retry-on-5xx logic — let the test fail and surface the dependency issue.
+
+## CI parity
+
+- [ ] Test passes locally with `--workers=1` AND `--workers=4 --shuffle`.
+- [ ] Test passes both headed and headless.
+- [ ] Test passes on at least two browsers (chromium + firefox).
diff --git a/.claude/skills/playwright-test-author-ui/references/locator-priority.md b/.claude/skills/playwright-test-author-ui/references/locator-priority.md
new file mode 100644
index 0000000..dadf105
--- /dev/null
+++ b/.claude/skills/playwright-test-author-ui/references/locator-priority.md
@@ -0,0 +1,42 @@
+# Locator priority
+
+A strict ordering. Use the first one that fits. Drop only with peer-review.
+
+| Priority | Locator                                    | When                                              |
+| -------- | ------------------------------------------ | ------------------------------------------------- |
+| 1        | `getByRole('button', { name: 'Submit' })`  | Almost everything users interact with has a role. |
+| 2        | `getByLabel('Email')`                      | Form fields with associated `<label>`.            |
+| 3        | `getByPlaceholder('email@example.com')`    | Inputs without a label (legacy UI).               |
+| 4        | `getByText('Welcome')`                     | Pure text targets (links, headings).              |
+| 5        | `getByTestId('submit-cta')`                | Custom widgets where roles/text are insufficient. |
+| 6        | `getByAltText('Avatar')`                   | Images.                                           |
+| 7        | `getByTitle('Settings')`                   | Tooltips.                                         |
+| 8        | `locator('[data-anything]')` / CSS / XPath | LAST RESORT. Justify in code review.              |
+
+## Why role-first
+
+- Reflects the user's mental model — clicks the same things screen readers do.
+- Survives most refactors — class names change, ARIA roles rarely.
+- Doubles as a basic accessibility check — if no role exists, the UI may have a real a11y issue worth surfacing.
+
+## test-id contract
+
+- Add `data-testid` only where role/text cannot disambiguate.
+- Naming: `kebab-case`, scoped (`checkout-submit-cta`, not `submit`).
+- Adding test-ids is a product change — propose in the PR description, not a unilateral commit.
+
+## Locator composition
+
+```ts
+const row = page.getByRole('row', { name: 'Order #42' });
+await row.getByRole('button', { name: 'Cancel' }).click();
+```
+
+Compose **inside** page-object methods, never in specs.
+
+## Forbidden patterns
+
+- `page.locator('div > .foo:nth-child(3)')` — brittle.
+- `page.locator('text=...')` outside of `getByText` builder — legacy syntax.
+- XPath that traverses ancestors — coupling to layout structure.
+- Querying inside `waitFor` polling without `getBy*` semantics.
diff --git a/.claude/skills/playwright-test-author-ui/references/web-first-assertions.md b/.claude/skills/playwright-test-author-ui/references/web-first-assertions.md
new file mode 100644
index 0000000..48c5ce0
--- /dev/null
+++ b/.claude/skills/playwright-test-author-ui/references/web-first-assertions.md
@@ -0,0 +1,57 @@
+# Web-first assertions
+
+Web-first means: the assertion retries automatically until it passes or times out. No `waitFor`, no `sleep`.
+
+## Use these (auto-retrying)
+
+```ts
+await expect(locator).toBeVisible();
+await expect(locator).toHaveText('Hello');
+await expect(locator).toHaveValue('user@example.com');
+await expect(locator).toHaveCount(3);
+await expect(locator).toBeEnabled();
+await expect(locator).toBeChecked();
+await expect(page).toHaveURL(/\/dashboard$/);
+await expect(page).toHaveTitle('Dashboard');
+```
+
+## Avoid these (single-shot)
+
+```ts
+expect(await locator.textContent()).toBe('Hello'); // ❌ no retry
+expect(await locator.isVisible()).toBe(true); // ❌ no retry
+await page.waitForTimeout(2000); // ❌ blind sleep
+await page.waitForSelector('.foo'); // ❌ legacy, prefer locator-based
+```
+
+## When you really need a poll
+
+```ts
+await expect
+  .poll(
+    async () => {
+      const r = await ordersClient.getById(id);
+      return r.data?.status;
+    },
+    { timeout: 10_000, intervals: [200, 500, 1000] },
+  )
+  .toBe('paid');
+```
+
+## Soft assertions
+
+Group several checks on the same screen so one failure does not hide others:
+
+```ts
+await expect.soft(header.title).toHaveText('Dashboard');
+await expect.soft(header.userMenu).toBeVisible();
+await expect.soft(header.notifications).toHaveCount(2);
+```
+
+`expect.soft` failures are reported but do not abort the test until a regular `expect` fails.
+
+## Tuning timeouts
+
+- Per-action: `await locator.click({ timeout: 5000 })` — last resort.
+- Per-test: `test.setTimeout(60_000)` for genuinely long flows.
+- Globally tune `actionTimeout` and `navigationTimeout` in `playwright.config.ts`, never per-spec.
diff --git a/scripts/lint-ui-spec.ts b/.claude/skills/playwright-test-author-ui/scripts/lint-ui-spec.ts
similarity index 100%
rename from scripts/lint-ui-spec.ts
rename to .claude/skills/playwright-test-author-ui/scripts/lint-ui-spec.ts
diff --git a/.claude/skills/release-report-composer/SKILL.md b/.claude/skills/release-report-composer/SKILL.md
new file mode 100644
index 0000000..0391275
--- /dev/null
+++ b/.claude/skills/release-report-composer/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: release-report-composer
+description: Composes an executive release-readiness report from run-analyzer, coverage-gap-analyzer, flaky-triage outputs and contract-drift report. Targets product/QA leads. Use when user asks "release report", "QA sign-off", "go/no-go summary", before a release branch cut. Do NOT use for daily test reports.
+allowed-tools: Read, Glob, Grep, Write
+---
+
+# Release Report Composer
+
+## Required template
+
+1. **Verdict**: ✅ go / ⚠️ go-with-risks / ❌ no-go.
+2. **Test execution**: pass/fail/flaky, durations, environments.
+3. **Coverage**: % AC covered, endpoints covered, critical gaps.
+4. **Contract drift**: breaking/non-breaking changes vs prod baseline.
+5. **Top risks** with mitigations.
+6. **Recommendations** (must-do / should-do / nice-to-have).
+
+Saves to `docs/releases/<version>.md`.
+
+## Inputs (all optional but at least one required)
+
+- `RUN_SUMMARY.md`
+- `COVERAGE_GAPS.md`
+- `FLAKE_REPORT.md`
+- `CONTRACT_DRIFT.md`
+
+## Workflow
+
+1. Detect which inputs exist.
+2. Read each and extract key numbers via simple regex.
+3. Compose `docs/releases/<version>.md` from `references/release.template.md`.
+4. Suggest verdict based on rules:
+   - Pass rate < 95%, or any breaking contract change unaddressed → no-go.
+   - 95% ≤ pass rate < 99%, or P0 coverage gaps present → go-with-risks.
+   - Otherwise → go.
+
+## References
+
+- `references/release.template.md`
+- `references/verdict-rules.md`
diff --git a/.claude/skills/release-report-composer/assets/README.md b/.claude/skills/release-report-composer/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/release-report-composer/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/release-report-composer/references/release.template.md b/.claude/skills/release-report-composer/references/release.template.md
new file mode 100644
index 0000000..7baf46f
--- /dev/null
+++ b/.claude/skills/release-report-composer/references/release.template.md
@@ -0,0 +1,62 @@
+# Release readiness — <version>
+
+> Compiled by `release-report-composer` on <date>.
+
+## Verdict
+
+**✅ go / ⚠️ go-with-risks / ❌ no-go**
+
+One-paragraph rationale.
+
+## Test execution
+
+| Metric               |          Value |
+| -------------------- | -------------: |
+| Total tests          |              0 |
+| Pass rate            |             0% |
+| Flaky rate           |             0% |
+| Wallclock            |             0m |
+| Environments covered | local, staging |
+
+## Coverage
+
+| Inventory           | Covered | Missing |   % |
+| ------------------- | ------: | ------: | --: |
+| Endpoints           |       0 |       0 |   — |
+| Acceptance criteria |       0 |       0 |   — |
+
+### Critical gaps
+
+- ...
+
+## Contract drift
+
+| Change | Severity | Status |
+| ------ | -------- | ------ |
+
+## Top risks & mitigations
+
+| Risk | Likelihood | Impact | Mitigation | Owner |
+| ---- | ---------- | ------ | ---------- | ----- |
+
+## Recommendations
+
+### Must-do (block release)
+
+- ...
+
+### Should-do (next 24h)
+
+- ...
+
+### Nice-to-have
+
+- ...
+
+## Sign-off
+
+| Role                | Name | Status |
+| ------------------- | ---- | ------ |
+| QA Lead             |      | ⬜     |
+| Engineering Manager |      | ⬜     |
+| Product             |      | ⬜     |
diff --git a/.claude/skills/release-report-composer/references/verdict-rules.md b/.claude/skills/release-report-composer/references/verdict-rules.md
new file mode 100644
index 0000000..e603a0f
--- /dev/null
+++ b/.claude/skills/release-report-composer/references/verdict-rules.md
@@ -0,0 +1,21 @@
+# Verdict rules
+
+The release-report-composer infers a recommendation. The human sign-off is still required.
+
+## Decision matrix
+
+| Condition                                                                          | Verdict          |
+| ---------------------------------------------------------------------------------- | ---------------- |
+| Pass rate ≥ 99% AND no P0 coverage gap AND no breaking contract drift              | ✅ go            |
+| 95% ≤ pass rate < 99% OR P0 coverage gap present OR non-breaking drift unannotated | ⚠️ go-with-risks |
+| Pass rate < 95% OR breaking contract drift unaddressed OR security AC not covered  | ❌ no-go         |
+
+## Caveats
+
+- Smoke pass on prod ≠ full sign-off. The verdict refers to staging coverage; prod smoke is a separate gate.
+- Quarantined tests do not contribute to pass rate; they are reported separately.
+- A green run with stale baselines (no recent CI history) downgrades to ⚠️.
+
+## Override
+
+A human can overrule the verdict. The override is logged in the report's "Sign-off" section with a justification. Auditors can later see when humans bypassed automation and why.
diff --git a/.claude/skills/release-report-composer/scripts/compose-release.ts b/.claude/skills/release-report-composer/scripts/compose-release.ts
new file mode 100755
index 0000000..914a164
--- /dev/null
+++ b/.claude/skills/release-report-composer/scripts/compose-release.ts
@@ -0,0 +1,83 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * compose-release.ts <version>
+ * Stitches RUN_SUMMARY / COVERAGE_GAPS / FLAKE_REPORT / CONTRACT_DRIFT into docs/releases/<version>.md.
+ */
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+
+const root = process.cwd();
+const version = process.argv[2];
+if (!version) {
+  console.error('Usage: compose-release.ts <version>');
+  process.exit(2);
+}
+
+const sources = {
+  run: 'RUN_SUMMARY.md',
+  coverage: 'COVERAGE_GAPS.md',
+  flake: 'FLAKE_REPORT.md',
+  drift: 'CONTRACT_DRIFT.md',
+};
+
+const read = (p: string) =>
+  existsSync(join(root, p)) ? readFileSync(join(root, p), 'utf8') : null;
+
+const run = read(sources.run);
+const coverage = read(sources.coverage);
+const flake = read(sources.flake);
+const drift = read(sources.drift);
+
+if (!run && !coverage && !flake && !drift) {
+  console.error('FAIL: no input files found.');
+  process.exit(1);
+}
+
+// Heuristics
+const passRate = run?.match(/Pass rate \|\s*([\d.]+)%/)?.[1];
+const breakingCount = drift?.match(/breaking signals:\s*\*\*(\d+)\*\*/)?.[1];
+
+let verdict = '✅ go';
+if (passRate && Number(passRate) < 99) verdict = '⚠️ go-with-risks';
+if (passRate && Number(passRate) < 95) verdict = '❌ no-go';
+if (breakingCount && Number(breakingCount) > 0) verdict = '❌ no-go';
+
+const md: string[] = [];
+md.push(`# Release readiness — ${version}`);
+md.push('');
+md.push(`> Generated ${new Date().toISOString()} by release-report-composer.`);
+md.push('');
+md.push(`## Verdict: ${verdict}`);
+md.push('');
+if (run) {
+  md.push('## Test execution');
+  md.push(run);
+  md.push('');
+}
+if (coverage) {
+  md.push('## Coverage');
+  md.push(coverage);
+  md.push('');
+}
+if (flake) {
+  md.push('## Flake report');
+  md.push(flake);
+  md.push('');
+}
+if (drift) {
+  md.push('## Contract drift');
+  md.push(drift);
+  md.push('');
+}
+
+md.push('## Sign-off');
+md.push('| Role | Name | Status |');
+md.push('|---|---|---|');
+md.push('| QA Lead |  | ⬜ |');
+md.push('| Engineering Manager |  | ⬜ |');
+md.push('| Product |  | ⬜ |');
+
+const out = join(root, 'docs', 'releases', `${version}.md`);
+mkdirSync(dirname(out), { recursive: true });
+writeFileSync(out, md.join('\n'));
+console.log(`OK: wrote ${out} with verdict ${verdict}.`);
diff --git a/.claude/skills/requirements-to-test-design/SKILL.md b/.claude/skills/requirements-to-test-design/SKILL.md
new file mode 100644
index 0000000..12abcb4
--- /dev/null
+++ b/.claude/skills/requirements-to-test-design/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: requirements-to-test-design
+description: Converts user stories, acceptance criteria, or PRDs into a structured test design (equivalence partitioning, boundary values, decision tables, state transitions, pairwise). Outputs a Markdown test design report ready for review BEFORE writing test cases. Use when user provides a user story, requirement, or acceptance criteria, or asks "what should we test", "design tests", "coverage analysis for this story". Do NOT use to write Gherkin or code; that is gherkin-test-case-author / playwright-test-author-*.
+allowed-tools: Read, Write, Glob, Grep, WebFetch
+---
+
+# Requirements → Test Design
+
+## Trigger
+
+- User pastes a user story, AC, or PRD link.
+- User: "design tests for X", "what to test", "test ideas", "coverage gaps before code".
+
+## Output structure (ALWAYS follow this template)
+
+1. **Risks & Quality attributes** (functional, security, perf, a11y, i18n).
+2. **Equivalence classes** table.
+3. **Boundary values** table (one row per numeric/string-length boundary).
+4. **Decision table** (if multiple conditions).
+5. **State transitions** (if stateful).
+6. **Pairwise combinations** when ≥3 categorical inputs.
+7. **Negative scenarios & error paths**.
+8. **Out-of-scope** (explicit, with rationale).
+9. **Test pyramid placement** for each idea: unit / contract / API / UI / e2e.
+
+## Process
+
+1. Read the story; ask clarifying questions ONLY when AC are ambiguous (max 3 questions).
+2. Run `scripts/risk-heuristic.ts` to score each scenario `{prob, impact}`; sort by risk-weighted priority.
+3. Save to `docs/test-design/<feature-slug>.md`.
+
+## Anti-patterns prevented
+
+- Jumping straight to Gherkin without a coverage map.
+- Missing negative paths.
+- "Test everything" (everything-trophy worse than nothing).
+
+## References
+
+- `references/heuristics.md` (Heuristic test strategy + RIMGEN + CRUSSPIC STMPL)
+- `references/test-pyramid-vs-trophy.md`
+- `references/design-template.md`
diff --git a/.claude/skills/requirements-to-test-design/assets/README.md b/.claude/skills/requirements-to-test-design/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/requirements-to-test-design/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/requirements-to-test-design/references/design-template.md b/.claude/skills/requirements-to-test-design/references/design-template.md
new file mode 100644
index 0000000..c7818ff
--- /dev/null
+++ b/.claude/skills/requirements-to-test-design/references/design-template.md
@@ -0,0 +1,79 @@
+# Test design — <FEATURE_NAME>
+
+> Source: link to PRD / Jira / RFC.
+> Author: <name>, <date>.
+> Status: draft / reviewed / approved.
+
+## 1. Summary
+
+One paragraph: what is being built and why. Capture the user value in plain language.
+
+## 2. Risks & Quality attributes
+
+| Attribute   | Risk | Likelihood | Impact | Priority |
+| ----------- | ---- | ---------- | ------ | -------- |
+| Capability  | …    | M          | H      | P0       |
+| Security    | …    | L          | H      | P1       |
+| Performance | …    | M          | M      | P2       |
+
+## 3. Equivalence classes
+
+| Input | Class          | Example | Expected                       |
+| ----- | -------------- | ------- | ------------------------------ |
+| email | valid          | a@b.com | accepted                       |
+| email | invalid (no @) | abc.com | rejected with specific message |
+
+## 4. Boundary values
+
+| Field           | Boundary | Just-below | At         | Just-above   |
+| --------------- | -------- | ---------- | ---------- | ------------ |
+| password length | min 8    | 7 → reject | 8 → accept | 9 → accept   |
+| order items     | max 100  | 99 → ok    | 100 → ok   | 101 → reject |
+
+## 5. Decision table (if applicable)
+
+| Condition  | C1       | C2            | C3             | C4             |
+| ---------- | -------- | ------------- | -------------- | -------------- |
+| Logged in  | T        | T             | F              | F              |
+| Has items  | T        | F             | T              | F              |
+| **Action** | checkout | redirect-cart | redirect-login | redirect-login |
+
+## 6. State transitions (if applicable)
+
+```
+draft → submitted → approved → paid → fulfilled
+           ↓
+        rejected
+```
+
+| From → To         | Trigger  | Guard     |
+| ----------------- | -------- | --------- |
+| draft → submitted | submit() | items > 0 |
+
+## 7. Pairwise
+
+Use `references/pairwise-tool` (or AllPairs) when 3+ categorical inputs.
+
+## 8. Negative & error paths
+
+- Network 5xx mid-action.
+- Concurrent edit (optimistic locking).
+- Invalid token / expired session.
+- Wrong role.
+
+## 9. Out of scope
+
+- Performance-loadtest (handled by perf team, separate plan).
+
+## 10. Test placement
+
+| Idea                     | Layer       | Skill to author            |
+| ------------------------ | ----------- | -------------------------- |
+| email regex              | unit        | dev                        |
+| schema match for /signup | contract    | playwright-test-author-api |
+| signup happy path        | UI          | playwright-test-author-ui  |
+| concurrent edit          | integration | playwright-test-author-api |
+
+## 11. Open questions
+
+- AC silent on what happens for emails with `+` aliases — confirm with PM.
diff --git a/.claude/skills/requirements-to-test-design/references/heuristics.md b/.claude/skills/requirements-to-test-design/references/heuristics.md
new file mode 100644
index 0000000..5251086
--- /dev/null
+++ b/.claude/skills/requirements-to-test-design/references/heuristics.md
@@ -0,0 +1,47 @@
+# Test heuristics cheatsheet
+
+A mental Rolodex to find ideas you'd otherwise miss. Walk through each list when designing tests for a non-trivial feature.
+
+## Quality attributes (CRUSSPIC STMPL — Bach)
+
+- **C**apability — does it do what's claimed?
+- **R**eliability — does it keep doing it?
+- **U**sability — can a human use it without help?
+- **S**ecurity — does it protect data and access?
+- **S**calability — does it hold under load?
+- **P**erformance — fast enough?
+- **I**nstallability — can it be deployed?
+- **C**ompatibility — does it work with surrounding systems?
+- **S**upportability, **T**estability, **M**aintainability, **P**ortability, **L**ocalisability.
+
+## Risk dimensions (RIMGEA)
+
+- **R**ecognise — is the risk visible at all?
+- **I**nvestigate — what evidence reveals it?
+- **M**inimise — how can the system contain it?
+- **G**eneralise — where else could it hide?
+- **E**scalate — who must know if it's real?
+- **A**nticipate — what could trigger it next sprint?
+
+## Test design techniques
+
+| Technique                | Use when                                          |
+| ------------------------ | ------------------------------------------------- |
+| Equivalence partitioning | Inputs fall into groups treated identically       |
+| Boundary value analysis  | Numeric / length thresholds                       |
+| Decision table           | ≥2 conditions producing different outcomes        |
+| State transition         | UI/entity has explicit states + transitions       |
+| Pairwise (orthogonal)    | ≥3 categorical inputs; full matrix is impractical |
+| Cause-effect graph       | Many inputs map to many outputs with overlap      |
+| Error guessing           | Experience-driven; combine with all of the above  |
+| Exploratory charters     | Risk too poorly defined for scripts               |
+
+## Heuristic prompts (ask while reading the story)
+
+- "What if the input is empty / max / one above max / exactly at boundary?"
+- "What if the action is repeated quickly?"
+- "What if the user has slow network / no network / 401 mid-flow?"
+- "What if a different role attempts this?"
+- "What if the upstream service returns a partial / malformed response?"
+- "What if currency / locale / timezone / RTL?"
+- "What if the data was created in a previous version?"
diff --git a/.claude/skills/requirements-to-test-design/references/test-pyramid-vs-trophy.md b/.claude/skills/requirements-to-test-design/references/test-pyramid-vs-trophy.md
new file mode 100644
index 0000000..51a78a0
--- /dev/null
+++ b/.claude/skills/requirements-to-test-design/references/test-pyramid-vs-trophy.md
@@ -0,0 +1,41 @@
+# Test pyramid vs testing trophy
+
+## Pyramid (Mike Cohn, ~2009)
+
+```
+     /\        E2E      few, slow, full stack
+    /--\       Integration
+   /----\      Unit      many, fast, isolated
+  /------\
+```
+
+Bias: many cheap unit tests, few expensive E2E.
+
+## Trophy (Kent C. Dodds, ~2018)
+
+```
+        /\        E2E
+       /  \       Integration  (the bulk)
+      /----\      Unit
+     /______\     Static (TS, ESLint)
+```
+
+Bias: integration tests give the best ROI, because they reflect the way users actually use the system, while staying fast enough to run thousands.
+
+## Where each test lives in our setup
+
+| Layer             | Tooling                                                     | Owner      |
+| ----------------- | ----------------------------------------------------------- | ---------- |
+| Static            | TypeScript, ESLint, type-coverage, openapi-typescript types | dev + SDET |
+| Unit              | Vitest/Jest in product repo                                 | dev        |
+| Contract          | Playwright API tests with zod schema asserts                | SDET       |
+| Integration / API | Playwright API project                                      | SDET       |
+| Component / UI    | Playwright with mocked backend                              | SDET       |
+| E2E               | Playwright UI project, real services in staging             | SDET       |
+
+## Practical guidance
+
+- For each test idea from `requirements-to-test-design`, place it on the lowest layer that can detect the failure cheaply.
+- Duplicate **only** for safety nets that justify the maintenance: a critical login flow can have unit + integration + E2E checks.
+- Use static analysis as ruthlessly as possible — every test you don't have to write is a win.
+- Don't equate "integration" with "slow". Playwright's API project is often faster than Jest with heavy mocks.
diff --git a/.claude/skills/requirements-to-test-design/scripts/risk-heuristic.ts b/.claude/skills/requirements-to-test-design/scripts/risk-heuristic.ts
new file mode 100755
index 0000000..6242c17
--- /dev/null
+++ b/.claude/skills/requirements-to-test-design/scripts/risk-heuristic.ts
@@ -0,0 +1,34 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * risk-heuristic.ts — simple risk scorer.
+ *
+ * Input:  JSON via stdin: [{ id, scenario, probability: 1-3, impact: 1-3, areas?: string[] }]
+ * Output: same array, sorted by score desc, with `priority` field added.
+ *
+ *   probability × impact = score
+ *   score 7-9 → P0
+ *   score 4-6 → P1
+ *   score 1-3 → P2
+ */
+import { readFileSync } from 'node:fs';
+
+interface Item {
+  id: string;
+  scenario: string;
+  probability: 1 | 2 | 3;
+  impact: 1 | 2 | 3;
+  areas?: string[];
+  score?: number;
+  priority?: 'P0' | 'P1' | 'P2';
+}
+
+const stdin = readFileSync(0, 'utf8');
+const items: Item[] = JSON.parse(stdin);
+
+for (const it of items) {
+  it.score = it.probability * it.impact;
+  it.priority = it.score >= 7 ? 'P0' : it.score >= 4 ? 'P1' : 'P2';
+}
+
+items.sort((a, b) => b.score! - a.score!);
+process.stdout.write(JSON.stringify(items, null, 2));
diff --git a/.claude/skills/run-analyzer/SKILL.md b/.claude/skills/run-analyzer/SKILL.md
new file mode 100644
index 0000000..d5cec2b
--- /dev/null
+++ b/.claude/skills/run-analyzer/SKILL.md
@@ -0,0 +1,38 @@
+---
+name: run-analyzer
+description: Analyses a Playwright test run (HTML/JSON/JUnit/Allure reporters) to surface duration trends, parallel utilisation, retry counts, and top-N slowest tests. Outputs an executive summary plus drill-down. Use when user asks "how was the run", "trends", "performance of test suite", or after CI completes. Do NOT use for individual debug; defer to playwright-debug-conductor.
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Run Analyzer
+
+## Reporters supported
+
+- `playwright-json` (default), `junit`, `html`, Allure (via `allure-playwright`).
+
+## Outputs
+
+- `RUN_SUMMARY.md`: total/failed/flaky, P50/P95 duration, top-10 slowest, worker utilisation.
+- Trend graph hint (if `runs/history.jsonl` exists): regression flags ±20%.
+
+## Workflow
+
+1. Read `playwright-report/results.json`.
+2. Compute aggregates via `scripts/analyze-run.ts`.
+3. If `runs/history.jsonl` exists, append today's record and compare against the last 5 runs.
+4. Emit `RUN_SUMMARY.md`.
+
+## What good looks like
+
+| Metric                          | Target         | Action if violated                       |
+| ------------------------------- | -------------- | ---------------------------------------- |
+| Pass rate                       | ≥ 99%          | Investigate top failures                 |
+| Flaky rate (retried but passed) | ≤ 1%           | flaky-triage                             |
+| P95 single-test duration        | ≤ 60s          | Top-10 slow → factor or move to API tier |
+| Worker utilisation              | ≥ 70%          | Re-balance shards                        |
+| Total wallclock                 | ≤ 15 min on CI | Sharding strategy                        |
+
+## References
+
+- `references/parsers.md` (JUnit / Allure parsing notes)
+- `references/summary.template.md`
diff --git a/.claude/skills/run-analyzer/assets/README.md b/.claude/skills/run-analyzer/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/run-analyzer/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/run-analyzer/references/parsers.md b/.claude/skills/run-analyzer/references/parsers.md
new file mode 100644
index 0000000..c2f574c
--- /dev/null
+++ b/.claude/skills/run-analyzer/references/parsers.md
@@ -0,0 +1,40 @@
+# Reporter parser notes
+
+## Playwright JSON reporter
+
+Default. Path: `playwright-report/results.json`. Stable shape per Playwright minor; we read defensively (`results.suites`, recursive). Each test has `.results[]` with `status`, `duration`, `errors`, `attachments`.
+
+## JUnit XML
+
+Used by older CI dashboards. Path: `playwright-report/junit.xml`. Parse with `fast-xml-parser`. Less rich (no attachments), but interoperable.
+
+## Allure
+
+If `allure-playwright` is installed:
+
+```
+package.json:
+  "scripts": { "allure:open": "allure serve ./allure-results" }
+playwright.config.ts reporter:
+  reporter: [['allure-playwright', { detail: true, suiteTitle: false }]]
+```
+
+Generates `allure-results/*.json` per test.
+
+We do NOT prescribe Allure; teams should choose between Playwright HTML (zero-config, excellent traces) and Allure (richer historical trends, larger runtime). Our run-analyzer reads both.
+
+## Custom reporter pattern
+
+For metrics we cannot derive from existing reporters (e.g. memory delta, fixture timing), implement a custom reporter:
+
+```ts
+// tools/metrics-reporter.ts
+import type { Reporter, TestCase, TestResult } from '@playwright/test/reporter';
+export default class MetricsReporter implements Reporter {
+  onTestEnd(test: TestCase, result: TestResult) {
+    // append to runs/metrics.jsonl
+  }
+}
+```
+
+Wire via `reporter: [['./tools/metrics-reporter.ts']]` in config.
diff --git a/.claude/skills/run-analyzer/references/summary.template.md b/.claude/skills/run-analyzer/references/summary.template.md
new file mode 100644
index 0000000..e06dbb7
--- /dev/null
+++ b/.claude/skills/run-analyzer/references/summary.template.md
@@ -0,0 +1,44 @@
+# Run summary — <date / build>
+
+> Generated by `run-analyzer` from `playwright-report/results.json`.
+
+## Headline
+
+| Metric             |   Value | vs last 5 runs |
+| ------------------ | ------: | -------------: |
+| Pass rate          |      0% |              — |
+| Flaky rate         |      0% |              — |
+| Total tests        |       0 |              — |
+| Wallclock          |      0m |              — |
+| P50 / P95 duration | 0s / 0s |              — |
+
+Verdict: ✅ green / ⚠️ yellow / ❌ red.
+
+## Failures
+
+| File | Test | Browser | Duration | Error excerpt |
+| ---- | ---- | ------- | -------: | ------------- |
+
+## Top 10 slowest
+
+| Rank | Test | Duration |
+| ---: | ---- | -------: |
+
+## Flaky candidates (retried but passed)
+
+| Test | Browser | Retries |
+| ---- | ------- | ------: |
+
+## Worker utilisation
+
+| Worker | Tests | Wallclock | Utilisation |
+| -----: | ----: | --------: | ----------: |
+
+## Trend (last 5 runs)
+
+| Run | Pass rate | P95 dur | Wallclock |
+| --- | --------: | ------: | --------: |
+
+## Recommendations
+
+- ...
diff --git a/.claude/skills/run-analyzer/scripts/analyze-run.ts b/.claude/skills/run-analyzer/scripts/analyze-run.ts
new file mode 100755
index 0000000..81dc1e9
--- /dev/null
+++ b/.claude/skills/run-analyzer/scripts/analyze-run.ts
@@ -0,0 +1,117 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * analyze-run.ts — produces RUN_SUMMARY.md from playwright-report/results.json.
+ */
+import { readFileSync, existsSync, appendFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.cwd();
+const resultsPath = join(root, 'playwright-report', 'results.json');
+const historyPath = join(root, 'runs', 'history.jsonl');
+const out = join(root, 'RUN_SUMMARY.md');
+
+if (!existsSync(resultsPath)) {
+  console.error(`FAIL: ${resultsPath} not found.`);
+  process.exit(2);
+}
+
+interface RunRow {
+  title: string;
+  file: string;
+  project: string;
+  durationMs: number;
+  status: string;
+  retries: number;
+}
+
+const rows: RunRow[] = [];
+
+function walk(node: any, file = '') {
+  for (const spec of node.specs ?? []) {
+    for (const t of spec.tests ?? []) {
+      const lastResult = t.results?.[t.results.length - 1];
+      rows.push({
+        title: spec.title,
+        file: spec.file ?? file,
+        project: t.projectName ?? 'default',
+        durationMs: lastResult?.duration ?? 0,
+        status: lastResult?.status ?? 'unknown',
+        retries: Math.max(0, (t.results?.length ?? 1) - 1),
+      });
+    }
+  }
+  for (const child of node.suites ?? []) walk(child, file || child.file || '');
+}
+
+const json = JSON.parse(readFileSync(resultsPath, 'utf8'));
+walk(json);
+
+const total = rows.length;
+const passed = rows.filter((r) => r.status === 'passed' || r.status === 'expected').length;
+const failed = rows.filter(
+  (r) => r.status === 'failed' || r.status === 'unexpected' || r.status === 'timedOut',
+).length;
+const flaky = rows.filter(
+  (r) => r.status === 'flaky' || (r.retries > 0 && r.status === 'passed'),
+).length;
+const durations = rows.map((r) => r.durationMs).sort((a, b) => a - b);
+const p = (q: number) =>
+  durations[Math.min(durations.length - 1, Math.floor(durations.length * q))] ?? 0;
+const passRate = total ? passed / total : 0;
+const flakyRate = total ? flaky / total : 0;
+
+const slow = [...rows].sort((a, b) => b.durationMs - a.durationMs).slice(0, 10);
+const fails = rows.filter((r) => r.status !== 'passed' && r.status !== 'expected');
+
+const verdict = passRate >= 0.99 ? '✅ green' : passRate >= 0.9 ? '⚠️ yellow' : '❌ red';
+
+const md: string[] = [];
+md.push(`# Run summary — ${new Date().toISOString()}`);
+md.push('');
+md.push('| Metric | Value |');
+md.push('|---|---:|');
+md.push(`| Total tests | ${total} |`);
+md.push(`| Passed | ${passed} |`);
+md.push(`| Failed | ${failed} |`);
+md.push(`| Flaky | ${flaky} |`);
+md.push(`| Pass rate | ${(passRate * 100).toFixed(1)}% |`);
+md.push(`| Flaky rate | ${(flakyRate * 100).toFixed(1)}% |`);
+md.push(
+  `| P50 / P95 duration | ${(p(0.5) / 1000).toFixed(1)}s / ${(p(0.95) / 1000).toFixed(1)}s |`,
+);
+md.push(`| Verdict | ${verdict} |`);
+md.push('');
+
+md.push('## Top 10 slowest');
+md.push('| Test | Project | Duration |');
+md.push('|---|---|---:|');
+for (const r of slow)
+  md.push(`| ${r.title} | ${r.project} | ${(r.durationMs / 1000).toFixed(1)}s |`);
+md.push('');
+
+md.push('## Failures');
+md.push('| File | Test | Project | Duration |');
+md.push('|---|---|---|---:|');
+for (const r of fails)
+  md.push(`| ${r.file} | ${r.title} | ${r.project} | ${(r.durationMs / 1000).toFixed(1)}s |`);
+md.push('');
+
+writeFileSync(out, md.join('\n'));
+console.log(`OK: wrote ${out}`);
+
+// Append to history
+try {
+  const record = {
+    ts: Date.now(),
+    total,
+    passed,
+    failed,
+    flaky,
+    passRate,
+    p50: p(0.5),
+    p95: p(0.95),
+  };
+  appendFileSync(historyPath, JSON.stringify(record) + '\n');
+} catch {
+  /* runs/ may not exist; non-fatal */
+}
diff --git a/.claude/skills/test-code-reviewer/SKILL.md b/.claude/skills/test-code-reviewer/SKILL.md
new file mode 100644
index 0000000..cd062d6
--- /dev/null
+++ b/.claude/skills/test-code-reviewer/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: test-code-reviewer
+description: Reviews changed test code for anti-patterns (hard waits, brittle selectors, leaky fixtures, shared state, DRY abuse, missing assertions, snapshot abuse) and SOLID violations. Outputs a structured review with severity. MUST BE USED before committing or opening a PR with test changes; also use when user says "review my test", "is this test ok", "audit /tests". Do NOT use for production (non-test) code.
+allowed-tools: Read, Grep, Glob, Bash
+---
+
+# Test Code Reviewer
+
+## Process
+
+1. `git diff --staged --name-only -- 'tests/**'` (or use `$ARGUMENTS` for ad-hoc paths).
+2. For each file run the matching validator(s):
+   - `scripts/lint-ui-spec.ts` (from playwright-test-author-ui)
+   - `scripts/lint-page-object.ts` (here)
+   - `scripts/fixture-rules.ts` (from fixture-architect)
+   - `scripts/factory-rules.ts` (from test-data-factory-builder)
+   - `tsc --noEmit`
+   - `eslint --ext .ts tests/`
+3. Aggregate findings into table:
+   | File:Line | Severity (blocker/major/minor) | Anti-pattern | Fix |
+4. NEVER auto-fix; suggest. Block commit (exit 2) if any blocker.
+
+## Anti-patterns checklist (excerpt — full list in references/)
+
+- `page.waitForTimeout` → blocker
+- `page.locator('css=...')` or `xpath=` → major
+- `expect(...).toEqual(snapshot)` on dynamic content → major
+- Test depending on previous test order → blocker
+- Fixture without cleanup → major
+- `test.use({ storageState })` per-test for unrelated session → minor
+- Inline domain object literal as data → minor (factory candidate)
+- `if/else` inside `test()` body → major (split scenarios)
+- `console.log` in spec → minor
+- Hardcoded sleep ≥ 1000ms → blocker
+
+## References
+
+- `references/aqa-anti-patterns.md` (the full catalogue)
+- `references/solid-in-tests.md`
+- `references/damp-vs-dry-in-tests.md`
+- `references/review-template.md`
diff --git a/.claude/skills/test-code-reviewer/assets/README.md b/.claude/skills/test-code-reviewer/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/test-code-reviewer/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/test-code-reviewer/references/aqa-anti-patterns.md b/.claude/skills/test-code-reviewer/references/aqa-anti-patterns.md
new file mode 100644
index 0000000..9a972e4
--- /dev/null
+++ b/.claude/skills/test-code-reviewer/references/aqa-anti-patterns.md
@@ -0,0 +1,66 @@
+# AQA anti-patterns — full catalogue
+
+## Spec body
+
+| Anti-pattern                                           | Severity | Fix                                           |
+| ------------------------------------------------------ | -------- | --------------------------------------------- |
+| `page.waitForTimeout(N)`                               | blocker  | Web-first matchers / `expect.poll`.           |
+| `setTimeout(...)` inside `test()`                      | blocker  | Same as above.                                |
+| Raw CSS selector `page.locator('.foo > div')`          | major    | Move to page object; use `getByRole`.         |
+| XPath selector                                         | major    | Same as above.                                |
+| `await page.locator(...).nth(N)` outside page object   | major    | Scope with parent; never index.               |
+| Branch (`if/else`/`switch`) in test body               | major    | Split into separate scenarios.                |
+| `test.only` committed                                  | blocker  | Remove.                                       |
+| `test.skip` without ticket reference                   | minor    | Comment with issue link.                      |
+| Hardcoded URL/credential                               | blocker  | Move to env via `tests/infra/env.ts`.         |
+| `console.log` left behind                              | minor    | Remove.                                       |
+| Inline data literal for a domain entity                | minor    | Use a factory.                                |
+| Snapshot of dynamic content w/o mask                   | major    | Mask via `toHaveScreenshot({ mask: [...] })`. |
+| Asserting on error.message string                      | minor    | Assert on `code`.                             |
+| Multiple unrelated assertions interleaved with actions | minor    | Group with `expect.soft`.                     |
+
+## Page objects
+
+| Anti-pattern                                                 | Severity | Fix                               |
+| ------------------------------------------------------------ | -------- | --------------------------------- |
+| Public locator field                                         | major    | Expose method, not locator.       |
+| Method that returns boolean for assertion                    | major    | Return locator; let spec assert.  |
+| Page does its own `expect(...)`                              | major    | Move assertion to spec.           |
+| Hardcoded `path` not computed from baseURL                   | major    | Use relative path.                |
+| Multi-page navigation in one method                          | major    | Split by destination.             |
+| God-class > 400 LOC                                          | major    | Split or compose with components. |
+| Inheritance for variants (`AdminPage extends DashboardPage`) | major    | Composition over inheritance.     |
+
+## Fixtures
+
+| Anti-pattern                                | Severity | Fix                                         |
+| ------------------------------------------- | -------- | ------------------------------------------- |
+| Missing `await use(...)`                    | blocker  | Always `use`, even if value is `undefined`. |
+| Cleanup omitted                             | major    | After `use`, tear down.                     |
+| Worker-scope fixture mutates per-test state | major    | Move to `test` scope.                       |
+| Fixture name shadows built-in               | major    | Rename.                                     |
+| Cross-fixture cycles                        | major    | Untangle dependency graph.                  |
+
+## Factories
+
+| Anti-pattern                           | Severity | Fix                                     |
+| -------------------------------------- | -------- | --------------------------------------- |
+| Network call inside factory            | major    | Move to `seed()` helper.                |
+| Top-level `Date.now()` / `Math.random` | major    | `faker` with SEED.                      |
+| Inheritance among factories            | major    | Use overrides + transient params.       |
+| Hidden mutable state                   | major    | Recreate via `Factory.define` per call. |
+
+## Configuration
+
+| Anti-pattern                                  | Severity | Fix                   |
+| --------------------------------------------- | -------- | --------------------- |
+| `.env` committed                              | blocker  | `.gitignore`; rotate. |
+| Secrets logged                                | blocker  | Mask in CI; remove.   |
+| Per-spec `test.use({ baseURL })` mutating env | major    | Use a project.        |
+
+## Reporting
+
+| Anti-pattern                                                        | Severity | Fix                 |
+| ------------------------------------------------------------------- | -------- | ------------------- |
+| `--retries=5` to mask flake                                         | major    | Triage, don't bury. |
+| `expect.configure({ timeout: 60_000 })` global to dodge timing bugs | major    | Fix the timing bug. |
diff --git a/.claude/skills/test-code-reviewer/references/damp-vs-dry-in-tests.md b/.claude/skills/test-code-reviewer/references/damp-vs-dry-in-tests.md
new file mode 100644
index 0000000..2358a4a
--- /dev/null
+++ b/.claude/skills/test-code-reviewer/references/damp-vs-dry-in-tests.md
@@ -0,0 +1,39 @@
+# DAMP vs DRY in tests
+
+## TL;DR
+
+- **Production code**: DRY. Repetition is a maintenance liability.
+- **Test code**: DAMP — Descriptive And Meaningful Phrases. Some repetition is acceptable when it makes the test readable in isolation.
+
+## Why
+
+A test fails at 03:00. The on-call engineer reads it. They have ~30 seconds to grasp:
+
+- what was set up,
+- what was done,
+- what was expected.
+
+If the test is layered behind 4 helpers, 2 inheritance levels, and a magic fixture, that reading takes 15 minutes. DAMP makes the reading instant.
+
+## Rules of thumb
+
+| Situation                                    | Prefer                              |
+| -------------------------------------------- | ----------------------------------- |
+| Same setup repeated in 5 tests of one file   | Background / `beforeEach` / fixture |
+| Same setup repeated in 5 tests across files  | Fixture                             |
+| Same locators in two pages                   | Component object                    |
+| Same data shape with minor differences       | Factory + overrides                 |
+| Same one-line action repeated                | Inline — DRY does not pay           |
+| Same multi-step flow used in dozens of tests | Page-object method or step library  |
+
+## Where DRY hurts tests
+
+- `function expectLoggedIn(page)` that wraps three matchers — the abstraction hides what's actually checked.
+- `function clickEverything()` — a god-helper that conceals state changes.
+- "Test framework" growing inside `tests/utils/` until it has its own bugs.
+
+## Litmus test
+
+> "If I delete this helper, would the test become longer but more obvious?"
+
+If the answer is yes, the helper is removing valuable signal. Inline it.
diff --git a/.claude/skills/test-code-reviewer/references/review-template.md b/.claude/skills/test-code-reviewer/references/review-template.md
new file mode 100644
index 0000000..707adb2
--- /dev/null
+++ b/.claude/skills/test-code-reviewer/references/review-template.md
@@ -0,0 +1,35 @@
+# Test review report — <PR / branch>
+
+> Generated by `test-code-reviewer` on <date>. Do not edit by hand.
+
+## Summary
+
+| Severity | Count |
+| -------- | ----- |
+| Blocker  | 0     |
+| Major    | 0     |
+| Minor    | 0     |
+
+Verdict: ✅ approve / ⚠️ request-changes / ❌ block.
+
+## Findings
+
+| File:Line                    | Severity | Rule         | Anti-pattern                | Suggested fix                                |
+| ---------------------------- | -------- | ------------ | --------------------------- | -------------------------------------------- |
+| tests/specs/login.spec.ts:42 | blocker  | no-hard-wait | `page.waitForTimeout(2000)` | Replace with `expect(locator).toBeVisible()` |
+
+## Coverage observations
+
+- AC-3 (locked-account rejection) referenced in design but no test tagged `@ac:AC-3`.
+- New endpoint `POST /payments/refunds` has client method but no API spec yet.
+
+## Architectural observations
+
+- `tests/pages/CheckoutPage.ts` is 412 LOC. Consider extracting `PaymentSection` and `ShippingSection` components.
+- `tests/fixtures/index.ts` directly extends 7 fixtures inline. Consider `mergeTests`.
+
+## Recommendations
+
+1. Address blockers before merge.
+2. Open a follow-up issue for the architectural observations.
+3. Add `@ac:AC-3` tag to the relevant test or write the missing scenario.
diff --git a/.claude/skills/test-code-reviewer/references/solid-in-tests.md b/.claude/skills/test-code-reviewer/references/solid-in-tests.md
new file mode 100644
index 0000000..17b04b7
--- /dev/null
+++ b/.claude/skills/test-code-reviewer/references/solid-in-tests.md
@@ -0,0 +1,37 @@
+# SOLID applied to test code
+
+SOLID is a production-code mantra; it works for tests too if you read it pragmatically.
+
+## SRP — Single Responsibility
+
+- One class per page (`LoginPage`, not `AuthPage` doing login + signup + reset).
+- One factory file per entity.
+- One fixture per concern (pages / api / data / mocks).
+- One spec file per feature; one `describe` per behaviour group; one `test` per scenario.
+
+## OCP — Open / Closed
+
+- Page objects expose methods. Adding a new field on the page is a new method, not editing an old one.
+- Factories accept overrides + transient params. New variants don't require a new factory.
+
+## LSP — Liskov
+
+- Component objects substitutable across pages: any `HeaderComponent` instance behaves the same way regardless of which page hosts it.
+- Avoid inheritance hierarchies that violate substitutability ("AdminLoginPage extends LoginPage but skips MFA" — break.)
+
+## ISP — Interface Segregation
+
+- Fixtures expose narrow types. A spec should only need to declare the fixtures it uses; not be forced to consume a god-fixture.
+- Page-object methods take only the params they need; don't accept big "options" bags.
+
+## DIP — Dependency Inversion
+
+- Specs depend on abstractions: `OrdersClient`, `userFactory`, `LoginPage`. They never `import 'axios'` or `import 'pg'`.
+- API client wrappers depend on `openapi-fetch` interface, not on a specific URL.
+- Storage state path is injected via config, not hardcoded.
+
+## How the reviewer enforces this
+
+- SRP / SoC violations show up as oversized files (LOC threshold).
+- DIP violations are caught by `lint-ui-spec.ts` (no axios/fetch in specs).
+- ISP violations show up as fixture aggregation imports beyond what a test uses (warning, not blocker).
diff --git a/.claude/skills/test-code-reviewer/scripts/lint-page-object.ts b/.claude/skills/test-code-reviewer/scripts/lint-page-object.ts
new file mode 100755
index 0000000..abbe596
--- /dev/null
+++ b/.claude/skills/test-code-reviewer/scripts/lint-page-object.ts
@@ -0,0 +1,93 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * lint-page-object.ts — static checks for tests/pages/**.ts
+ */
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.cwd();
+const cfg = JSON.parse(readFileSync(join(root, 'tests-config.json'), 'utf8'));
+const pagesDir = join(root, cfg.layout.pages);
+
+if (!existsSync(pagesDir)) {
+  console.log('OK: pages dir does not exist yet.');
+  process.exit(0);
+}
+
+const rules: {
+  id: string;
+  severity: 'blocker' | 'major' | 'minor';
+  re: RegExp;
+  message: string;
+}[] = [
+  {
+    id: 'no-expect-in-page',
+    severity: 'major',
+    re: /from\s+['"]@playwright\/test['"][^;]*expect/,
+    message: 'Page object imports expect. Move assertions to spec.',
+  },
+  {
+    id: 'no-public-locator',
+    severity: 'major',
+    re: /^\s*(public|readonly)\s+\w+\s*:\s*Locator\s*=/m,
+    message: 'Public Locator field. Expose method instead.',
+  },
+  {
+    id: 'no-hardcoded-url',
+    severity: 'major',
+    re: /https?:\/\/[^'"\s]+/,
+    message: 'Hardcoded URL in page. Use relative path.',
+  },
+  {
+    id: 'no-process-env',
+    severity: 'minor',
+    re: /process\.env\./,
+    message: 'process.env in page object. Inject via constructor / env helper.',
+  },
+  {
+    id: 'no-wait-timeout',
+    severity: 'blocker',
+    re: /\.waitForTimeout\s*\(/,
+    message: 'waitForTimeout in page object.',
+  },
+];
+
+function collect(dir: string, acc: string[] = []): string[] {
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) collect(p, acc);
+    else if (p.endsWith('.ts')) acc.push(p);
+  }
+  return acc;
+}
+
+const files = collect(pagesDir);
+let blockers = 0,
+  majors = 0,
+  minors = 0;
+
+for (const file of files) {
+  const lines = readFileSync(file, 'utf8').split('\n');
+  // LOC threshold
+  if (lines.length > 400) {
+    console.error(`${file}:1  [MAJOR][page-loc] Page object exceeds 400 LOC. Consider splitting.`);
+    majors++;
+  }
+  lines.forEach((line, idx) => {
+    for (const r of rules) {
+      if (r.re.test(line)) {
+        console.error(`${file}:${idx + 1}  [${r.severity.toUpperCase()}][${r.id}] ${r.message}`);
+        if (r.severity === 'blocker') blockers++;
+        else if (r.severity === 'major') majors++;
+        else minors++;
+      }
+    }
+  });
+}
+
+console.error(
+  `\n${files.length} page object(s). blockers=${blockers} majors=${majors} minors=${minors}`,
+);
+if (blockers) process.exit(2);
+if (majors) process.exit(1);
+process.exit(0);
diff --git a/.claude/skills/test-data-factory-builder/SKILL.md b/.claude/skills/test-data-factory-builder/SKILL.md
new file mode 100644
index 0000000..d5f9ef5
--- /dev/null
+++ b/.claude/skills/test-data-factory-builder/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: test-data-factory-builder
+description: Designs and writes type-safe test data factories using Fishery + Faker, sourced from OpenAPI-generated types. Enforces Builder/Factory patterns, transient params, sequences, and association helpers. Use when the user creates new test data, mentions "factory", "fixture data", "seed user", "fake data", or when a spec uses object literals as test data instead of factories. Do NOT use to define Playwright fixtures (those are in fixture-architect).
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Test Data Factory Builder
+
+## Trigger
+
+- Spec contains an inline object literal that looks like a domain entity (`const user = { email: 'x@y.com', ... }`).
+- User: "create factory", "build data", "seed", "fake user".
+
+## Workflow
+
+1. Read target type from `tests/api/generated/schema.d.ts` (or local model). Reject if type is `any`.
+2. Generate `tests/factories/<entity>.factory.ts` from `references/factory.template.ts`:
+   - `Factory.define<Entity, TransientParams>(...)`.
+   - `sequence` for unique fields.
+   - `Faker.locale = 'en'` deterministic seed when `process.env.SEED` is set (idempotency).
+   - `transientParams` for boolean toggles like `{ admin: true }`.
+   - `afterBuild` for relations.
+3. Add `tests/factories/index.ts` aggregator.
+4. Validate with `scripts/factory-rules.ts` (no top-level `Date.now()`, no hidden network calls, no shared mutable state).
+
+## Hard rules
+
+- Never call API or DB inside `Factory.define`. Side effects belong to a separate `seed()` helper.
+- Never expose constructor dependencies; everything via params/transient.
+- One factory file = one entity. Composition via `associations`, not inheritance.
+
+## DAMP guidance
+
+Prefer overrides at the call site (`userFactory.build({ role: 'admin' })`) over creating `userAdminFactory`. Multiple thin factories beat one mega-factory with switch logic.
+
+## References
+
+- `references/fishery-patterns.md` (transient params, sequence rewind, afterBuild)
+- `references/faker-determinism.md`
+- `references/builder-vs-factory.md`
diff --git a/.claude/skills/test-data-factory-builder/assets/README.md b/.claude/skills/test-data-factory-builder/assets/README.md
new file mode 100644
index 0000000..433cdeb
--- /dev/null
+++ b/.claude/skills/test-data-factory-builder/assets/README.md
@@ -0,0 +1 @@
+Reserved for binary assets (templates, icons, snapshots) used by this skill.
diff --git a/.claude/skills/test-data-factory-builder/references/builder-vs-factory.md b/.claude/skills/test-data-factory-builder/references/builder-vs-factory.md
new file mode 100644
index 0000000..4de7e12
--- /dev/null
+++ b/.claude/skills/test-data-factory-builder/references/builder-vs-factory.md
@@ -0,0 +1,45 @@
+# Builder vs Factory in test data
+
+| Aspect   | Factory (Fishery)                          | Builder (manual)                                   |
+| -------- | ------------------------------------------ | -------------------------------------------------- |
+| Purpose  | Produce realistic, valid instances quickly | Step-by-step construction with explicit invariants |
+| When     | 90% of test data needs                     | Complex aggregates, multi-step lifecycles          |
+| API      | `factory.build(overrides)`                 | `new XBuilder().withY(...).build()`                |
+| Drawback | Easy to over-customise via overrides       | Verbose; requires more code                        |
+
+## Rule of thumb
+
+Use a **factory** by default. Switch to a **builder** only when:
+
+- The aggregate has more than ~7 mutable fields and many tests configure 3+ at a time.
+- There are multiple incompatible "states" (e.g. `Order` in `draft`, `submitted`, `paid`, `cancelled`) and conditional invariants.
+- You want to leverage a fluent DSL for readability in spec files.
+
+## Hybrid pattern
+
+Wrap a factory in a thin builder when call-site readability suffers:
+
+```ts
+class OrderScenario {
+  private overrides: Partial<Order> = {};
+
+  withUser(user: User) {
+    this.overrides.userId = user.id;
+    return this;
+  }
+  withItems(n: number) {
+    this.overrides.items = itemFactory.buildList(n);
+    return this;
+  }
+  paid() {
+    this.overrides.status = 'paid';
+    return this;
+  }
+
+  build() {
+    return orderFactory.build(this.overrides);
+  }
+}
+```
+
+Builders compose; factories provide defaults. Together they keep specs DAMP and readable.
diff --git a/.claude/skills/test-data-factory-builder/references/factory.template.ts b/.claude/skills/test-data-factory-builder/references/factory.template.ts
new file mode 100644
index 0000000..5e9e85d
--- /dev/null
+++ b/.claude/skills/test-data-factory-builder/references/factory.template.ts
@@ -0,0 +1,34 @@
+import { Factory } from 'fishery';
+import { faker } from '@faker-js/faker';
+// import type { components } from '@api/generated/schema';
+
+// Use OpenAPI-derived types instead of hand-written ones.
+// type User = components['schemas']['User'];
+
+interface User {
+  id: string;
+  email: string;
+  fullName: string;
+  role: 'user' | 'admin';
+  createdAt: string;
+}
+
+interface UserTransient {
+  admin?: boolean;
+}
+
+if (process.env.SEED) faker.seed(Number(process.env.SEED));
+
+export const userFactory = Factory.define<User, UserTransient>(({ sequence, transientParams }) => ({
+  id: `user-${sequence}`,
+  email: faker.internet.email().toLowerCase(),
+  fullName: faker.person.fullName(),
+  role: transientParams.admin ? 'admin' : 'user',
+  createdAt: faker.date.recent({ days: 30 }).toISOString(),
+}));
+
+// Usage:
+//   userFactory.build()                              -> deterministic user
+//   userFactory.build({ email: 'a@b.com' })          -> override fields
+//   userFactory.build({}, { transient: { admin: true } })
+//   userFactory.buildList(5)                         -> array
diff --git a/.claude/skills/test-data-factory-builder/references/faker-determinism.md b/.claude/skills/test-data-factory-builder/references/faker-determinism.md
new file mode 100644
index 0000000..8a235fb
--- /dev/null
+++ b/.claude/skills/test-data-factory-builder/references/faker-determinism.md
@@ -0,0 +1,41 @@
+# Faker determinism
+
+## Why determinism matters
+
+Tests with random data are flaky-by-design: a green run today, a red run tomorrow on the same code. We make Faker deterministic by seeding it once.
+
+## Strategy
+
+```ts
+// tests/factories/_seed.ts
+import { faker } from '@faker-js/faker';
+const seed = process.env.SEED ? Number(process.env.SEED) : 1234;
+faker.seed(seed);
+export const FAKER_SEED = seed;
+```
+
+Import this module at the top of every factory file:
+
+```ts
+import './_seed';
+```
+
+ESM ensures the seeding happens before any factory call.
+
+## CI vs local
+
+- Local: SEED unset → fixed default (1234). Same data every run.
+- CI: SEED is the build number for variance OR a fixed value committed in `.env.ci` to keep snapshots stable.
+
+## What to do when a test really needs randomness
+
+Some tests intentionally want randomized inputs (fuzz-style). Mark them:
+
+```ts
+test('@fuzz handles arbitrary names', async ({}) => {
+  faker.seed(); // reset to randomness
+  // ...
+});
+```
+
+A custom reporter aggregates `@fuzz` failures separately.
diff --git a/.claude/skills/test-data-factory-builder/references/fishery-patterns.md b/.claude/skills/test-data-factory-builder/references/fishery-patterns.md
new file mode 100644
index 0000000..9599a83
--- /dev/null
+++ b/.claude/skills/test-data-factory-builder/references/fishery-patterns.md
@@ -0,0 +1,60 @@
+# Fishery patterns we use
+
+## Sequence
+
+`sequence` increments per-factory call, providing collision-free unique values across a single test process.
+
+```ts
+Factory.define<Order>(({ sequence }) => ({ id: `order-${sequence}` }));
+```
+
+To reset between worker scopes:
+
+```ts
+import { userFactory } from './user.factory';
+userFactory.rewindSequence();
+```
+
+## Transient params
+
+Use for non-domain modifiers that change the _shape_ of the result without leaking into the type itself.
+
+```ts
+Factory.define<User, { admin?: boolean }>(({ transientParams }) => ({
+  // ...
+  role: transientParams.admin ? 'admin' : 'user',
+}));
+```
+
+## Associations
+
+For nested entities, prefer `associations`:
+
+```ts
+const orderFactory = Factory.define<Order, never, { user?: User }>(({ associations }) => ({
+  id: `order-1`,
+  user: associations.user ?? userFactory.build(),
+}));
+
+orderFactory.build({}, { associations: { user: someUser } });
+```
+
+## afterBuild
+
+Use sparingly — only for derived fields that the consumer cannot easily provide.
+
+```ts
+Factory.define<Cart>(({ afterBuild }) => {
+  afterBuild((cart) => {
+    cart.total = cart.items.reduce((s, i) => s + i.price, 0);
+  });
+  return { id: '...', items: [], total: 0 };
+});
+```
+
+## What NOT to do
+
+- ❌ Network/DB calls inside `Factory.define`. Use a separate `seed()` helper.
+- ❌ Conditional types in transient params (turn into a different factory instead).
+- ❌ Inheritance hierarchies (`AdminUserFactory extends UserFactory`). Use overrides + transient.
+- ❌ Side-effect ESM imports inside factory files (e.g. configuring globals).
diff --git a/.claude/skills/test-data-factory-builder/scripts/factory-rules.ts b/.claude/skills/test-data-factory-builder/scripts/factory-rules.ts
new file mode 100755
index 0000000..cc49378
--- /dev/null
+++ b/.claude/skills/test-data-factory-builder/scripts/factory-rules.ts
@@ -0,0 +1,60 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * factory-rules.ts — static checks for tests/factories/*.factory.ts files.
+ * Exits 1 if violations are found.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.cwd();
+const cfg = JSON.parse(readFileSync(join(root, 'tests-config.json'), 'utf8'));
+const factoriesDir = join(root, cfg.layout.factories);
+
+function* walk(dir: string): Generator<string> {
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e);
+    yield (statSync(p).isDirectory() ? [...walk(p)] : [p]) as unknown as string;
+  }
+}
+
+const files: string[] = [];
+function collect(dir: string) {
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) collect(p);
+    else if (p.endsWith('.factory.ts')) files.push(p);
+  }
+}
+collect(factoriesDir);
+
+const forbidden: { re: RegExp; reason: string }[] = [
+  { re: /\bfetch\s*\(/, reason: 'Network call inside factory file. Move to seed() helper.' },
+  { re: /\baxios\b/, reason: 'Network client in factory. Forbidden.' },
+  {
+    re: /\bDate\.now\s*\(/,
+    reason: 'Date.now() at top level breaks determinism. Use faker.date.*',
+  },
+  { re: /\bMath\.random\s*\(/, reason: 'Math.random breaks determinism. Use faker.* with SEED.' },
+  { re: /^\s*let\s+\w+\s*[:=]/m, reason: 'Top-level mutable state in factory file.' },
+  {
+    re: /class\s+\w+\s+extends\s+\w+Factory/,
+    reason: 'Factory inheritance forbidden. Use overrides + transient.',
+  },
+];
+
+let violations = 0;
+for (const file of files) {
+  const src = readFileSync(file, 'utf8');
+  for (const rule of forbidden) {
+    if (rule.re.test(src)) {
+      console.error(`FAIL: ${file}\n   ${rule.reason}`);
+      violations++;
+    }
+  }
+}
+
+if (violations > 0) {
+  console.error(`\n${violations} factory rule violation(s).`);
+  process.exit(1);
+}
+console.log(`OK: ${files.length} factory file(s) clean.`);
diff --git a/.env.example b/.env.example
index d49b1d9..bbd0d15 100644
--- a/.env.example
+++ b/.env.example
@@ -14,6 +14,8 @@ BASE_URL_PLANETCONFIG=https://planetconfig.com/
 # Determinism (Faker seed) — see docs/CONSTRAINTS.md §2.4
 SEED=1234
 
-# Reporting (optional)
-# ALLURE_RESULTS_DIR=allure-results
+# Synthetic email domain for factories (disposable, valid MX) — see CONSTRAINTS §2.4
+# SYNTHETIC_EMAIL_DOMAIN=yopmail.com
+
+# Set automatically by CI; gates worker count + forbidOnly
 # CI=true
diff --git a/.github/tests.yml b/.github/tests.yml
deleted file mode 100644
index 13c1470..0000000
--- a/.github/tests.yml
+++ /dev/null
@@ -1,81 +0,0 @@
-name: tests
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-  workflow_dispatch:
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  lint-and-typecheck:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version-file: '.nvmrc'
-          cache: npm
-      - run: npm ci
-      - run: npm run typecheck
-      - run: npm run lint
-      - run: npm run format:check
-
-  playwright:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    needs: lint-and-typecheck
-    strategy:
-      fail-fast: false
-      matrix:
-        shard: [1/2, 2/2]
-    env:
-      BASE_URL: ${{ vars.BASE_URL }}
-      API_BASE_URL: ${{ vars.API_BASE_URL }}
-      TEST_USER_EMAIL: ${{ secrets.TEST_USER_EMAIL }}
-      TEST_USER_PASSWORD: ${{ secrets.TEST_USER_PASSWORD }}
-      SEED: 1234
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version-file: '.nvmrc'
-          cache: npm
-      - run: npm ci
-      - name: Install Playwright browsers
-        run: npx playwright install --with-deps chromium
-      - name: Run tests (shard ${{ matrix.shard }})
-        run: npx playwright test --shard=${{ matrix.shard }} --reporter=blob
-      - uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: blob-report-${{ strategy.job-index }}
-          path: blob-report
-          retention-days: 7
-
-  merge-reports:
-    if: always()
-    needs: playwright
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version-file: '.nvmrc'
-          cache: npm
-      - run: npm ci
-      - uses: actions/download-artifact@v4
-        with:
-          path: all-blob-reports
-          pattern: blob-report-*
-          merge-multiple: true
-      - run: npx playwright merge-reports --reporter html ./all-blob-reports
-      - uses: actions/upload-artifact@v4
-        with:
-          name: html-report
-          path: playwright-report
-          retention-days: 14
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
deleted file mode 100644
index 36d6465..0000000
--- a/.github/workflows/build.yml
+++ /dev/null
@@ -1,19 +0,0 @@
-name: Build
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    types: [opened, synchronize, reopened, closed]
-jobs:
-  sonarqube:
-    name: SonarQube
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-        with:
-          fetch-depth: 0 # Shallow clones should be disabled for a better relevancy of analysis
-      - name: SonarQube Scan
-        uses: SonarSource/sonarqube-scan-action@fd88b7d7ccbaefd23d8f36f73b59db7a3d246602 # v6.0.0
-        env:
-          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
diff --git a/.github/workflows/playwright.yml b/.github/workflows/playwright.yml
deleted file mode 100644
index cf840d9..0000000
--- a/.github/workflows/playwright.yml
+++ /dev/null
@@ -1,27 +0,0 @@
-name: Playwright Tests
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-jobs:
-  test:
-    timeout-minutes: 60
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: lts/*
-      - name: Install dependencies
-        run: npm ci
-      - name: Install Playwright Browsers
-        run: npx playwright install --with-deps
-      - name: Run Playwright tests
-        run: npx playwright test
-      - uses: actions/upload-artifact@v4
-        if: ${{ !cancelled() }}
-        with:
-          name: playwright-report
-          path: playwright-report/
-          retention-days: 30
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 14ed159..51581e7 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -47,11 +47,13 @@ jobs:
         if: steps.playwright-cache.outputs.cache-hit == 'true'
         run: npx playwright install-deps ${{ matrix.project }}
 
-      - name: Lint and typecheck
+      - name: Lint, typecheck and validate architecture
         if: matrix.project == 'chromium'
         run: |
           npm run lint
           npm run typecheck
+          npm run validate
+          npm run format:check
 
       - name: Run Playwright (${{ matrix.project }})
         env:
diff --git a/.gitignore b/.gitignore
index bf51b7f..b868ca3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,28 +1,35 @@
-# Node
+# Dependencies
 node_modules/
 .pnpm-store/
 npm-debug.log*
 
-# Env / secrets — never commit
+# Env / secrets — never commit real values
 .env
 .env.local
 .env.*.local
 .env.development
 .env.staging
 .env.production
-# allowed:
+# allowed templates:
 !.env.example
 !.env.*.template
 
-# Playwright outputs
+# Playwright outputs / build artifacts
 playwright-report/
 test-results/
 .last-run.json
 runs/
+.tsbuildinfo
+
+# Playwright MCP debug logs/snapshots
+.playwright-mcp/
 
 # Auth state (storageState)
 tests/.auth/
 
+# Claude Code — the kit IS committed; only personal/local settings are ignored
+.claude/settings.local.json
+
 # IDE
 .vscode/
 .idea/
@@ -31,9 +38,3 @@ tests/.auth/
 # OS
 .DS_Store
 Thumbs.db
-.claude
-/CLAUDE.md
-.
-/.playwright-mcp/
-/.tsbuildinfo
-/docs/
diff --git a/.husky/pre-commit b/.husky/pre-commit
index 5edd998..c3e5de6 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1,9 +1,9 @@
 # 1. lint-staged: prettier + eslint --fix on staged files
 npx --no-install lint-staged || exit 1
 
-# 2. SDET reviewer: scan staged tests for blockers (hard waits, raw fetch, etc.)
-if [ -d ".claude/skills/playwright-test-author-ui/scripts" ] && [ -x "$(command -v npx)" ]; then
-  if [ -f "tests-config.json" ]; then
-    npx --no-install tsx .claude/skills/playwright-test-author-ui/scripts/lint-ui-spec.ts --staged || exit 1
-  fi
+# 2. SDET gates: enforce the layered architecture + scan specs for anti-patterns
+#    (hard waits, raw fetch, inline page objects, …). See tools/README.md.
+if [ -f "tests-config.json" ] && [ -x "$(command -v npx)" ]; then
+  bash tools/validate-layout.sh || exit 1
+  npx --no-install tsx tools/lint-ui-spec.ts || exit 1
 fi
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..71e6ecc
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,99 @@
+# Project conventions for Claude Code
+
+This file is the thin contract between you (Claude Code) and this repository.
+It must stay short — under 300 lines. All deeper knowledge lives in `.claude/skills/*`.
+
+## Stack
+
+- TypeScript + Playwright as the only test framework. Black-box UI E2E — no backend access.
+- This project has **no OpenAPI spec**: the three sites under test are third-party and not ours, so contract testing is N/A (see `docs/CONSTRAINTS.md` §2.1). The `.claude/` kit _supports_ OpenAPI/contract testing (`api-client-from-openapi`, `playwright-test-author-api`, `/spec-sync`) for repos that own a spec, but those capabilities are disabled here.
+- Test data uses Fishery + Faker (`SEED=1234`); runtime/env validation via `zod`.
+
+## Layered layout
+
+The repository follows the layout declared in `tests-config.json`. The validators in
+`tools/` enforce the boundaries (the `.claude/` kit carries portable copies). Reverse imports
+across layers are forbidden. Five layers only — no `components/`, `api/`, `clients/`, `generated/`, `data/`.
+
+```
+specs/  ──>  fixtures/  ──>  pages/, factories/, infra/
+pages/      ──>  infra/
+factories/  ──>  infra/
+```
+
+## Skills index (use these for any non-trivial task)
+
+Foundation:
+
+- `playwright-framework-bootstrap` — scaffold/refactor the layout
+- `api-client-from-openapi` — sync the OpenAPI spec → typed client + zod
+- `test-data-factory-builder` — Fishery factories per entity
+- `fixture-architect` — Playwright fixture composition with proper scoping
+- `config-and-secrets` — env loader, multi-env projects, secret stores
+
+Authoring:
+
+- `requirements-to-test-design` — story/PRD → structured test design
+- `gherkin-test-case-author` — declarative Gherkin from a design doc
+- `playwright-test-author-ui` — UI specs
+- `playwright-test-author-api` — API/contract specs
+
+Quality gates:
+
+- `test-code-reviewer` — anti-pattern + SOLID review (use before any commit to tests)
+- `playwright-debug-conductor` — root-cause debugging
+- `flaky-triage` — flake classification + suggested patches
+
+Analytics:
+
+- `run-analyzer` — run summaries, durations, retries
+- `coverage-gap-analyzer` — endpoint × AC × executed tests
+- `release-report-composer` — go/no-go executive report
+
+## Subagents
+
+- `test-design-agent` — isolated context for creating a test design.
+- `flaky-detective` — proactive flake hunter after retried runs.
+- `contract-drift-watch` — read-only diff against the API baseline (Haiku).
+
+## Slash commands
+
+- `/test-new <feature>` — full pipeline: design → cases → code → review.
+- `/test-fix <path>` — debug + patch + re-run.
+- `/test-review` — review staged tests.
+- `/spec-sync` — regenerate OpenAPI artefacts and emit drift report.
+- `/flake-hunt [N]` — `--repeat-each=N` then triage.
+- `/coverage` — coverage gap report.
+- `/release-report <version>` — readiness report.
+- `/factory <Entity>` — factory for a specific entity.
+- `/page <url>` — page-object scaffold.
+
+## Hooks
+
+`PreToolUse Bash` → `guard-bash.sh` blocks destructive commands (`rm -rf`, `git push --force`, `sudo`, …).
+`PreToolUse Edit|Write` → `guard-paths.sh` blocks writes to `tests/api/generated`, snapshots, and `.env`.
+`PostToolUse Edit|Write` → `typecheck-touched.sh` **typechecks** touched files only. ESLint + Prettier run separately, via `lint-staged` in `.husky/pre-commit` — not in this hook.
+`Stop` echoes a smoke-test reminder. See `.claude/settings.json`.
+
+## Hard rules (enforced by validators, not just culture)
+
+- Selectors live in page objects. Never inline in specs.
+- No `page.waitForTimeout`. Web-first assertions or `expect.poll`.
+- No `axios`/`fetch` in specs. Drive the UI through page objects.
+- No `process.env.X` inline. Use `tests/infra/env.ts`.
+- Factories never call the network. Side effects live in `seed()`.
+- Fixtures always call `await use(...)` and clean up.
+
+## What you should NOT do
+
+- Do not silently retry failing tests. Triage and either fix or quarantine with a ticket.
+- Do not auto-heal selectors. Surface the failure for review.
+- Do not mix UI and API concerns in a single test.
+- Do not duplicate factories per scenario. Use overrides + transient params.
+
+## How to run tests
+
+- Smoke: `npx playwright test --grep '@smoke'`.
+- By locale: `npx playwright test --grep '@ru'` / `--grep '@en'`.
+- With trace: `npx playwright test --trace=on`.
+- UI Mode: `npx playwright test --ui`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..a6637b3
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,143 @@
+# Contributing
+
+This guide covers how to add a test, the hard layer rules you must respect, the gates that run before your commit lands, and a troubleshooting section for the live-site flakiness you _will_ hit.
+
+Read [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) once before your first contribution, and treat [`docs/CONSTRAINTS.md`](docs/CONSTRAINTS.md) as authoritative — any workflow that conflicts with §2 must stop.
+
+---
+
+## Prerequisites
+
+```bash
+make install        # npm ci + playwright install --with-deps (3 browsers)
+```
+
+No `.env.local` is required — [`tests/infra/env.ts`](tests/infra/env.ts) ships safe defaults (the public production URLs, `SEED=1234`, and `SYNTHETIC_EMAIL_DOMAIN=yopmail.com`). Create `.env.local` only to target alternate hosts or override one of those validated vars.
+
+---
+
+## Adding a test — the AI-assisted path (recommended)
+
+This repo ships a committed SDET kit under [`.claude/`](.claude/). With Claude Code open in the repo, the fastest correct path is the `/test-new` pipeline:
+
+```
+/test-new <feature description>
+```
+
+It chains: `requirements-to-test-design` → `gherkin-test-case-author` → `playwright-test-author-ui` → `test-data-factory-builder` + `fixture-architect` → `test-code-reviewer`. The result is a reviewed spec that already respects the layer rules below. Useful follow-ups:
+
+- `/factory <Entity>` — scaffold a Fishery factory for a new entity.
+- `/page <url>` — scaffold a page object from a URL.
+- `/test-fix <path>` — debug + patch + re-run a failing spec.
+- `/test-review` — anti-pattern review of staged tests.
+- `/flake-hunt [N]` — `--repeat-each=N` then triage.
+
+> The OpenAPI-oriented commands (`/spec-sync`) and skills are **disabled** for this black-box project per [`docs/CONSTRAINTS.md`](docs/CONSTRAINTS.md) §4. Don't invoke them here.
+
+---
+
+## Adding a test — the manual path
+
+If you author by hand, place each concern in its layer (see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)):
+
+1. **Page object** — add or extend a class under `tests/pages/`. Locators and actions only; no `expect`. A `*Page` class must live here.
+2. **Factory** — if you need new synthetic data, add a `*.factory.ts` under `tests/factories/` using Fishery + Faker. Import the seed from `_seed.ts`; never call the network, `Date.now`, or `Math.random`.
+3. **Fixture** — expose the new page object / factory through `tests/fixtures/` via `mergeTests`. Always `await use(...)` and clean up. No business logic here.
+4. **Spec** — write the test under `tests/specs/` in AAA structure. Use injected fixtures, web-first assertions, and the correct locale tag (`@ru` / `@en`) and `@smoke` where appropriate. Stop at the payment boundary — never submit card/crypto data.
+
+Then run the gates locally:
+
+```bash
+npm run validate    # layout + factory + fixture + spec checks (or: make validate)
+make lint           # eslint + tsc + prettier
+make test-smoke     # quick sanity run
+```
+
+---
+
+## Hard layer rules
+
+These are enforced by [`tools/`](tools/), not by convention. A violation fails `npm run validate`, the pre-commit hook, and CI.
+
+- Selectors live in page objects — never inline in specs.
+- No `page.waitForTimeout`. Use web-first assertions or `expect.poll`.
+- No `axios` / raw `fetch` in specs.
+- No `process.env.X` inline — read env through [`tests/infra/env.ts`](tests/infra/env.ts).
+- Factories never call the network; side effects belong in `seed()`.
+- `BasePage` may not import `expect`.
+- Fixtures always call `await use(...)` and clean up.
+- No hard-coded URLs in `tests/` (except inside `tests/infra/env.ts`).
+- A single test must not mix locales — keep `@ru` and `@en` separate.
+
+See [`tools/README.md`](tools/README.md) for exactly which script guards which rule.
+
+---
+
+## Commit gates
+
+### Pre-commit (`.husky/pre-commit`)
+
+1. `lint-staged` — Prettier + `eslint --fix` on staged files.
+2. `bash tools/validate-layout.sh` — layer-boundary enforcement.
+3. `npx tsx tools/lint-ui-spec.ts` — spec anti-pattern scan.
+
+### Commit message (`.husky/commit-msg`)
+
+Conventional Commits are mandatory:
+
+```
+type(scope?): subject
+```
+
+Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci`, `build`, `revert`. Example: `test(checkout): add cancel-order scenario`. Merge/revert/fixup commits are exempt.
+
+### CI
+
+`.github/workflows/tests.yml` runs the full `chromium`/`firefox`/`webkit` matrix plus a lint + typecheck + `npm run validate` + `format:check` step on the chromium leg, then a SonarCloud job that consumes the JUnit report. **CI is the authoritative green signal** (see below).
+
+---
+
+## Troubleshooting
+
+These tests drive **live, third-party production sites**. Flakiness is expected and mitigated by `retries: 2` — it is not a sign your change is broken. Per [`docs/CONSTRAINTS.md`](docs/CONSTRAINTS.md) §3, a genuine 4xx/5xx is a **finding** (document it in [`docs/ux-findings.md`](docs/ux-findings.md)), not something to silently retry away.
+
+**A local run shows flakes; CI is green.**
+This is the documented norm (~11% first-attempt flake, often SPA-hydration timing). Trust CI as the authoritative signal. Re-run locally before assuming a regression.
+
+**Inspect a failing test interactively.**
+
+```bash
+make test-headed    # run with a visible browser
+make test-debug     # PWDEBUG=1 — Playwright Inspector, step through
+make test-ui        # interactive UI Mode (time-travel, watch)
+```
+
+**Read a trace after the fact.**
+
+```bash
+make report                                  # open the latest HTML report
+npx playwright show-trace path/to/trace.zip  # open a specific trace
+npx playwright test --trace=on               # force a trace for every test
+```
+
+Traces, screenshots, and videos are retained on failure (and uploaded as CI artefacts) per [`playwright.config.ts`](playwright.config.ts).
+
+**Browsers missing / version mismatch.**
+
+```bash
+npx playwright install --with-deps           # reinstall the 3 browsers
+```
+
+**Env / URL problems.**
+The suite runs without `.env.local`. If you overrode a `BASE_URL_*` and the run fails at boot with a zod error, fix the value — env is validated on import in [`tests/infra/env.ts`](tests/infra/env.ts) and the process exits with code `2` on an invalid URL.
+
+**A purchase test fails at the post-`/payment/` redirect assertion.**
+This is a known, documented open question — see the final section of [`docs/ux-findings.md`](docs/ux-findings.md). Reproduce with `make test-headed` and capture a trace before changing the spec; do not auto-heal selectors.
+
+**Hunt a flake systematically.**
+
+```bash
+make flake-hunt     # rerun the suite 5x to surface instability
+```
+
+or `/flake-hunt N` to run `--repeat-each=N` and triage via the kit.
diff --git a/Makefile b/Makefile
index 27607b3..1add79c 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: default all install test test-smoke test-headed test-debug test-ui test-ru test-en report lint flake-hunt clean help
+.PHONY: default all install test test-smoke test-headed test-debug test-ui test-ru test-en report lint validate verify flake-hunt clean help
 
 default: install lint test ## Install, lint, run tests (the conventional default)
 
@@ -37,6 +37,12 @@ lint: ## Run eslint + tsc + prettier checks
 	npm run typecheck
 	npm run format:check
 
+validate: ## Enforce the layered architecture (layout + factory + fixture + spec gates)
+	npm run validate
+
+verify: ## Repo health check (tooling, files, kit, no leaked secrets)
+	npm run verify
+
 flake-hunt: ## Run the suite 5x in a row to surface flaky tests
 	npx playwright test --repeat-each=5
 
diff --git a/README.md b/README.md
index a7293e6..7a475be 100644
--- a/README.md
+++ b/README.md
@@ -31,6 +31,43 @@ The deliverable is graded on **automation craft** (framework design, fixtures, f
 
 ---
 
+## AI-assisted SDET workflow
+
+The single biggest differentiator in this repo is the committed, version-controlled [`.claude/`](.claude/) **AI-assisted SDET kit**. It is not throwaway prompt history — it is a deliberate, reusable engineering asset that turns Claude Code into a disciplined automation pair. Every artefact is checked into git so a reviewer can read exactly how this suite is designed, authored, reviewed, and kept honest.
+
+The kit ships:
+
+- **15 skills** ([`.claude/skills/`](.claude/skills/)) — focused, single-responsibility playbooks: `playwright-framework-bootstrap`, `api-client-from-openapi`, `test-data-factory-builder`, `fixture-architect`, `config-and-secrets`, `requirements-to-test-design`, `gherkin-test-case-author`, `playwright-test-author-ui`, `playwright-test-author-api`, `playwright-debug-conductor`, `test-code-reviewer`, `flaky-triage`, `run-analyzer`, `coverage-gap-analyzer`, `release-report-composer`.
+- **3 subagents** ([`.claude/agents/`](.claude/agents/)) — isolated-context workers: `test-design-agent`, `flaky-detective`, `contract-drift-watch`.
+- **9 slash commands** ([`.claude/commands/`](.claude/commands/)) — one-shot pipelines: `/test-new`, `/test-fix`, `/test-review`, `/spec-sync`, `/flake-hunt`, `/coverage`, `/release-report`, `/factory`, `/page`.
+- **Hooks** ([`.claude/settings.json`](.claude/settings.json)) — guardrails that run mechanically around every agent action:
+  - `PreToolUse Bash` → `guard-bash.sh` blocks destructive commands (`rm -rf`, `git push --force`, `sudo`, …).
+  - `PreToolUse Edit|Write` → `guard-paths.sh` blocks writes to `tests/api/generated`, snapshots, and `.env` files.
+  - `PostToolUse Edit|Write` → `typecheck-touched.sh` **typechecks** touched TS files (formatting + ESLint run separately, via `lint-staged` in the pre-commit hook).
+  - `Stop` → echoes a smoke-test reminder so a run never ends silently.
+
+### The `/test-new` pipeline
+
+`/test-new <feature>` chains the skills into a review-gated authoring flow — requirement in, reviewed test out:
+
+```mermaid
+flowchart LR
+    A["/test-new feature"] --> B["requirements-to-test-design"]
+    B --> C["gherkin-test-case-author"]
+    C --> D["playwright-test-author-ui / -api"]
+    D --> E["test-data-factory-builder"]
+    D --> F["fixture-architect"]
+    E --> G["test-code-reviewer"]
+    F --> G
+    G --> H{"anti-patterns?"}
+    H -- yes --> D
+    H -- no --> I["Reviewed spec, ready to run"]
+```
+
+The same validators that gate this repo ([`tools/`](tools/)) ship inside the skills as portable templates, so the workflow is reusable in any TypeScript + Playwright project — not bespoke to these three sites. For this black-box project the OpenAPI-oriented skills (`api-client-from-openapi`, `playwright-test-author-api`) and `/spec-sync` are deliberately **disabled** by [`docs/CONSTRAINTS.md`](docs/CONSTRAINTS.md) §4; they remain in the kit to demonstrate contract-testing capability for repos that own a spec.
+
+---
+
 ## Why this stack
 
 - **Playwright** for browser automation: trace viewer + video + screenshot artefacts, web-first assertions, parallel workers, native cross-browser (Chromium / Firefox / WebKit).
@@ -41,7 +78,7 @@ The deliverable is graded on **automation craft** (framework design, fixtures, f
 
 What's intentionally **not** used:
 
-- No OpenAPI / contract testing — we test third-party sites we don't own (CONSTRAINTS §2.1).
+- No OpenAPI / contract testing — we test third-party sites we don't own (CONSTRAINTS §2.1). The `openapi-typescript` / `openapi-fetch` / `@redocly/cli` dev-deps stay installed only so the `.claude/` kit's contract-testing skills remain runnable in repos that _do_ own a spec; this project never invokes them.
 - No mocking — these are real browser sessions against real production sites.
 - No Sentry or telemetry — the SUT is not ours (CONSTRAINTS §2.2).
 
@@ -49,13 +86,29 @@ What's intentionally **not** used:
 
 ## Architecture
 
-The repo is built around a layered convention pinned in [`tests-config.json`](tests-config.json) and enforced by validators under `scripts/`. Reverse imports across layers are forbidden:
-
-```
-specs/  ──>  fixtures/  ──>  pages/, components/, factories/, api/clients/
-                       \─>  infra/
-factories/  ──>  api/generated (types only)
-api/clients/  ──>  api/generated, infra/
+The repo is built around a 5-layer convention pinned in [`tests-config.json`](tests-config.json) and mechanically enforced by validators under [`tools/`](tools/). Imports flow one direction only — reverse imports across layers are forbidden. A deeper walkthrough lives in [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+
+```mermaid
+flowchart TD
+    specs["specs/<br/>the actual tests"] --> fixtures["fixtures/<br/>mergeTests composition"]
+    fixtures --> pages["pages/<br/>page objects"]
+    fixtures --> factories["factories/<br/>Fishery test data"]
+    fixtures --> infra["infra/<br/>env loader + helpers"]
+    pages --> infra
+    factories --> infra
+
+    subgraph gates["tools/ — static-analysis gates"]
+        direction LR
+        v1["validate-layout.sh"]
+        v2["lint-ui-spec.ts"]
+        v3["factory-rules.ts"]
+        v4["fixture-rules.ts"]
+    end
+
+    gates -. enforces import direction .-> specs
+    gates -. enforces purity .-> factories
+    gates -. enforces hygiene .-> fixtures
+    gates -. enforces no-locators .-> pages
 ```
 
 ### Why layers?
@@ -67,9 +120,9 @@ api/clients/  ──>  api/generated, infra/
 | `factories/` | Fishery test-data factories                   | no network, no `Date.now`, no `Math.random`             |
 | `fixtures/`  | Playwright fixture composition (`mergeTests`) | no business logic                                       |
 | `specs/`     | the actual tests (AAA structure)              | no inline locators, no raw `fetch`, no `waitForTimeout` |
-| `scripts/`   | static-analysis validators                    | run as pre-commit checks and in CI                      |
+| `tools/`     | static-analysis validators                    | run as pre-commit checks and in CI                      |
 
-The validators (`scripts/{validate-layout.sh, factory-rules.ts, fixture-rules.ts, lint-ui-spec.ts}`) catch boundary violations at lint time so they don't slip into a PR.
+The validators (`tools/{validate-layout.sh, factory-rules.ts, fixture-rules.ts, lint-ui-spec.ts}`) catch boundary violations at lint time so they don't slip into a PR. See [`tools/README.md`](tools/README.md) for exactly what each one guards.
 
 ### Hard rules (mechanically enforced)
 
@@ -88,30 +141,40 @@ The validators (`scripts/{validate-layout.sh, factory-rules.ts, fixture-rules.ts
 
 ```
 .
+├── .claude/                      # committed AI-assisted SDET kit (the centerpiece)
+│   ├── skills/                   # 15 single-responsibility playbooks
+│   ├── agents/                   # 3 subagents
+│   ├── commands/                 # 9 slash commands
+│   ├── hooks/                    # guard-bash / guard-paths / typecheck-touched
+│   └── settings.json             # hook wiring
 ├── docs/
 │   ├── test-Assignment.pdf       # the PRD
+│   ├── CONSTRAINTS.md            # authoritative project constraints
+│   ├── ARCHITECTURE.md           # layered design + data-flow + gates
 │   └── ux-findings.md            # UX & functional defects discovered during automation
 ├── tests/
 │   ├── infra/env.ts              # zod-validated env access
-│   ├── factories/                # user, payment-draft, deterministic seed
-│   ├── pages/                    # 7 page objects + BasePage
+│   ├── factories/                # user, payment-draft, deterministic seed (_seed.ts)
+│   ├── pages/                    # 7 page objects + BasePage (8 files)
 │   ├── fixtures/                 # mergeTests of page-object fixtures
 │   └── specs/
 │       ├── signup/               # Scenario A
 │       └── purchase/             # Scenarios B and C
-├── scripts/
+├── tools/                        # this repo's wired-in quality gates
 │   ├── validate-layout.sh        # enforce layer rules
 │   ├── factory-rules.ts          # enforce factory purity
 │   ├── fixture-rules.ts          # enforce fixture hygiene
 │   ├── lint-ui-spec.ts           # spec anti-pattern linter
-│   └── ...
-├── .github/workflows/tests.yml   # CI: chromium + firefox + webkit matrix
-├── .husky/                       # pre-commit hooks (lint-staged + spec linter)
+│   ├── verify.sh                 # repo health check
+│   └── README.md                 # what each gate guards
+├── .github/workflows/tests.yml   # CI: chromium + firefox + webkit matrix + Sonar
+├── .husky/                       # pre-commit (lint-staged + validators) + commit-msg
 ├── playwright.config.ts          # 3 browser projects, retries=2, traces, video
 ├── tests-config.json             # canonical layer paths and naming
 ├── tsconfig.json                 # strict TS + path aliases (@pages, @fixtures, ...)
 ├── eslint.config.mjs             # flat config with playwright + TS rules
 ├── Makefile                      # one-command entrypoints (make help)
+├── CONTRIBUTING.md               # how to add a test + troubleshooting
 └── package.json
 ```
 
@@ -130,10 +193,12 @@ make test-ui        # interactive UI Mode
 make report         # open the last HTML report
 make flake-hunt     # rerun the suite 5x to surface flakes
 make lint           # eslint + tsc + prettier
+make validate       # enforce the layered architecture (layout + factory + fixture + spec gates)
+make verify         # repo health check (tooling, files, .claude kit, no leaked secrets)
 make help           # all targets with descriptions
 ```
 
-Without Make, the equivalent `npx playwright test ...` commands are documented in `package.json#scripts`.
+Without Make, the equivalent `npx playwright test ...` commands are documented in `package.json#scripts`. New contributors: see [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to add a test and a troubleshooting guide.
 
 ---
 
@@ -152,6 +217,8 @@ Without Make, the equivalent `npx playwright test ...` commands are documented i
 | **C** EN `1_year × stripe`                                                           | `tests/specs/purchase/personal-vpn-en.spec.ts:15` | chromium, firefox, webkit | `@en`                                                                             |
 | **C** EN `1_year × crypto` (BTC)                                                     | `tests/specs/purchase/personal-vpn-en.spec.ts:15` | chromium, firefox, webkit | `@en`                                                                             |
 
+> Rows that share a spec line (B → `:20`, C → `:15`) are parametrised — one data-driven `test()` inside a `for` loop, not copy-paste.
+
 ---
 
 ## Benchmarks (latest local run)
@@ -160,7 +227,7 @@ Without Make, the equivalent `npx playwright test ...` commands are documented i
 | --------------------------- | -------------------------------------------------------------------------------------------- |
 | Spec files                  | **3**                                                                                        |
 | Test cases                  | **30** (10 unique × 3 browsers)                                                              |
-| Lines of TypeScript / shell | **1 269** (factories + pages + specs + fixtures + scripts)                                   |
+| Lines of TypeScript / shell | **1 073** (factories + pages + specs + fixtures + tools)                                     |
 | Cross-browser run duration  | **6.8 min** (workers=1, retries=2, video on failure)                                         |
 | Pass-rate (after retries)   | **100%** of executed (24 passed + 3 flaky-but-eventually-passed)                             |
 | Fixme rate (known gaps)     | **3 / 30 = 10%** (Scenario B crypto, see `docs/ux-findings.md` B-1)                          |
@@ -169,6 +236,12 @@ Without Make, the equivalent `npx playwright test ...` commands are documented i
 
 > Benchmark methodology: `make test` against the live production sites at the inspection time (2026-04-28). Numbers reproducible via `make flake-hunt` for stability assessment.
 
+### Running & results — read this before judging a local run
+
+These tests drive **live, third-party production sites** over the public internet; they are inherently flaky (~11% first-attempt flake, documented above, mitigated by `retries: 2`). A local run on your machine may surface flakes from live-site latency or SPA-hydration timing that have nothing to do with the test code.
+
+**CI (GitHub Actions, [`tests.yml`](.github/workflows/tests.yml)) is the authoritative green signal** — it runs the full Chromium/Firefox/WebKit matrix with retries and uploads traces/videos on failure. If you see a local flake, re-run with `make test-headed` / `make test-debug` and consult the [troubleshooting guide in `CONTRIBUTING.md`](CONTRIBUTING.md#troubleshooting) before treating it as a regression. Per [`docs/CONSTRAINTS.md`](docs/CONSTRAINTS.md) §3, a genuine 4xx/5xx is a **finding**, not a flake — surface it, don't silently retry.
+
 ---
 
 ## Configuration
@@ -197,10 +270,13 @@ BASE_URL_FREEVPN          default https://freevpnplanet.com/
 BASE_URL_ACCOUNT          default https://account.freevpnplanet.com/
 BASE_URL_PERSONAL         default https://personal.freevpnplanet.com/
 BASE_URL_PLANETCONFIG     default https://planetconfig.com/
-SEED                      default 1234   (Faker determinism)
-SYNTHETIC_EMAIL_DOMAIN    default yopmail.com  (see docs/CONSTRAINTS.md §2.4)
+SEED                      default 1234         (Faker determinism)
+SYNTHETIC_EMAIL_DOMAIN    default yopmail.com  (disposable mail w/ valid MX; CONSTRAINTS §2.4)
+CI                        optional             (set by GitHub Actions; gates workers + forbidOnly)
 ```
 
+Every env var is validated by the zod schema, so a bad value fails fast at import. The factory seed module [`tests/factories/_seed.ts`](tests/factories/_seed.ts) consumes `env.SYNTHETIC_EMAIL_DOMAIN` rather than reading `process.env` directly — honouring the project's "no inline `process.env`" rule. Override it (via `.env.local` or a CI secret) when a target site requires a different disposable-mail domain.
+
 ### `tsconfig.json` path aliases
 
 ```ts
@@ -210,24 +286,25 @@ SYNTHETIC_EMAIL_DOMAIN    default yopmail.com  (see docs/CONSTRAINTS.md §2.4)
 @factories     -> tests/factories/index.ts
 @factories/*   -> tests/factories/*
 @infra/*       -> tests/infra/*
-@components/*, @api/*, @data/*  (reserved for future use)
 ```
 
 ### CI (`.github/workflows/tests.yml`)
 
 - **Triggers**: push to `main`, pull requests, manual dispatch.
 - **Matrix**: `chromium` × `firefox` × `webkit`, `fail-fast: false` so one browser failure doesn't mask the others.
-- **Cache**: Playwright browsers cached by `package-lock.json` hash.
-- **Lint + typecheck**: runs once (on the chromium leg).
-- **Artefacts**: HTML report (14 days) on every run, traces + videos (7 days) on failure.
-- **Concurrency**: `cancel-in-progress` per branch — pushing a new commit cancels the in-flight CI for that branch.
+- **Cache**: Playwright browsers cached, scoped per matrix project.
+- **Lint + typecheck + validate + format:check**: runs once (on the chromium leg) — the same `tools/` gates that run pre-commit.
+- **Artefacts**: HTML report + JUnit + traces/videos uploaded for inspection.
+- **SonarCloud**: a separate job waits for the tests, then feeds JUnit results into SonarCloud for the quality gate (badges at the top of this README).
+- **CI is the authoritative green signal** — see [Running & results](#running--results--read-this-before-judging-a-local-run).
 
 ### Pre-commit (`.husky/pre-commit`)
 
-- `lint-staged` (eslint + prettier on staged TS / JSON / MD).
-- `lint-ui-spec.ts` against staged spec files (only when the skill scripts are present).
+1. `lint-staged` — Prettier + `eslint --fix` on staged files.
+2. `bash tools/validate-layout.sh` — layer-boundary enforcement.
+3. `npx tsx tools/lint-ui-spec.ts` — spec anti-pattern scan (hard waits, raw `fetch`, inline page objects, …).
 
-Conventional commit format is enforced by `.husky/commit-msg` (regex on `^(feat|fix|docs|...)(scope)?: subject`).
+ESLint and Prettier run **only** through `lint-staged` here — they are not part of the post-edit AI hook (which typechecks only). Conventional commit format is enforced by `.husky/commit-msg` (regex on `^(feat|fix|docs|...)(scope)?: subject`). The full `npm run validate` (which adds factory + fixture gates) runs in CI.
 
 ---
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..b7c89af
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,141 @@
+# Architecture
+
+This document explains how the suite is layered, how data flows through a test, which gate enforces which boundary rule, and how the committed [`.claude/`](../.claude/) SDET kit and the [`tools/`](../tools/) validators **mechanically** keep the architecture from eroding.
+
+It is the deep companion to the short contract in [`../CLAUDE.md`](../CLAUDE.md) and the constraints in [`CONSTRAINTS.md`](CONSTRAINTS.md).
+
+---
+
+## 1. The 5 layers
+
+The repository is organised into exactly five layers, pinned in [`../tests-config.json`](../tests-config.json). Imports flow in **one direction only**; a reverse import (e.g. a page object importing a spec) is a build failure, not a code-review nit.
+
+```mermaid
+flowchart TD
+    specs["specs/<br/>AAA tests, tags, assertions"]
+    fixtures["fixtures/<br/>mergeTests composition + DI"]
+    pages["pages/<br/>page objects: locators + actions"]
+    factories["factories/<br/>Fishery + Faker, deterministic"]
+    infra["infra/<br/>zod env loader, helpers"]
+
+    specs --> fixtures
+    fixtures --> pages
+    fixtures --> factories
+    fixtures --> infra
+    pages --> infra
+    factories --> infra
+```
+
+| Layer        | Path              | Responsibility                                       | Must not                                                         |
+| ------------ | ----------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| `infra/`     | `tests/infra`     | zod-validated env access, cross-cutting helpers      | import from any layer above                                      |
+| `pages/`     | `tests/pages`     | locator builders + user actions (`BasePage` + 7 POs) | contain `expect`; import specs                                   |
+| `factories/` | `tests/factories` | type-safe synthetic data via Fishery + Faker         | touch the network, `Date.now`, `Math.random`, top-level mutables |
+| `fixtures/`  | `tests/fixtures`  | compose page objects + factories into injected deps  | hold business logic                                              |
+| `specs/`     | `tests/specs`     | the actual tests — Arrange / Act / Assert            | inline locators, raw `fetch`/`axios`, `waitForTimeout`           |
+
+There is **no** `components/`, `api/`, `clients/`, `generated/`, or `data/` layer. Those were removed during the reorganization; this project is black-box UI E2E with no API contract under our control (see [`CONSTRAINTS.md`](CONSTRAINTS.md) §2.1).
+
+---
+
+## 2. Data flow through one test
+
+A representative happy-path spec (Scenario A — Sign Up) flows like this:
+
+```mermaid
+sequenceDiagram
+    participant Spec as spec (signup-flow.spec.ts)
+    participant Fix as fixture (mergeTests)
+    participant Fac as factory (user.factory)
+    participant PO as page object (Signup/Payment)
+    participant Site as live site (account.freevpnplanet.com)
+
+    Spec->>Fix: request injected pages + data
+    Fix->>Fac: build synthetic user (SEED=1234)
+    Fac-->>Fix: { email@yopmail.com, password, … }
+    Fix->>PO: construct page objects (origin-aware)
+    Fix-->>Spec: { homePage, signupPage, paymentMethodsPage, user }
+    Spec->>PO: actions (open → login → signup → plan → method)
+    PO->>Site: goto / click / programmatic input events
+    Site-->>PO: navigation to payment provider boundary
+    Spec->>PO: assert payment URL / DOM oracle (STOP — no Pay)
+```
+
+Key invariants visible above:
+
+- **No `baseURL`.** Three origins are in play, so each page object carries an absolute URL derived from `env.BASE_URL_*`. `goto()` is always explicit.
+- **Determinism.** All synthetic data comes from Faker seeded once in [`../tests/factories/_seed.ts`](../tests/factories/_seed.ts) (`SEED=1234`), so the same email/password is produced every run.
+- **The payment boundary is a hard stop.** Specs assert the provider page is reached and never submit card/crypto data ([`CONSTRAINTS.md`](CONSTRAINTS.md) §2.3). `PaymentRedirectPage` is an oracle only — it deliberately has no card-form locators.
+
+---
+
+## 3. Boundary rules → which gate enforces them
+
+The rules are not aspirational. Each is enforced by a script under [`../tools/`](../tools/), wired into `npm run validate`, `.husky/pre-commit`, and CI. Exit code `0` = pass; non-zero fails the build.
+
+| Boundary rule                                                                                  | Enforced by                | Where it runs                      |
+| ---------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------- |
+| Specs don't import locators directly; `*Page` classes live only under `tests/pages/`           | `tools/validate-layout.sh` | `npm run validate`, pre-commit, CI |
+| `BasePage` contains no `expect`; no raw `axios`/`fetch` in specs                               | `tools/validate-layout.sh` | `npm run validate`, pre-commit, CI |
+| No `waitForTimeout`, no XPath, no inline page-object construction, no stray `console.log`      | `tools/lint-ui-spec.ts`    | `npm run validate`, pre-commit, CI |
+| Factories stay pure: no network, no `Date.now`/`Math.random`, no top-level mutable state       | `tools/factory-rules.ts`   | `npm run validate`, CI             |
+| Every fixture calls `await use(...)`; no built-in name collisions; scope sanity                | `tools/fixture-rules.ts`   | `npm run validate`, CI             |
+| Repo health: tooling present, required files exist, `.claude/` kit intact, no `.env` committed | `tools/verify.sh`          | `npm run verify`                   |
+
+All scripts read their paths from [`../tests-config.json`](../tests-config.json), so a layout change in one place propagates to every gate. See [`../tools/README.md`](../tools/README.md) for the full table.
+
+---
+
+## 4. The `.claude/` kit and how it enforces the architecture
+
+The kit is a committed, reusable engineering asset, not prompt history. It has three composable tiers plus a guardrail layer.
+
+```mermaid
+flowchart LR
+    subgraph commands["Slash commands — one-shot pipelines"]
+        c1["/test-new"]
+        c2["/test-fix"]
+        c3["/flake-hunt"]
+    end
+    subgraph agents["Subagents — isolated context"]
+        a1["test-design-agent"]
+        a2["flaky-detective"]
+    end
+    subgraph skills["Skills — single-responsibility"]
+        s1["requirements-to-test-design"]
+        s2["gherkin-test-case-author"]
+        s3["playwright-test-author-ui/api"]
+        s4["test-data-factory-builder"]
+        s5["fixture-architect"]
+        s6["test-code-reviewer"]
+    end
+
+    c1 --> s1 --> s2 --> s3
+    s3 --> s4
+    s3 --> s5
+    s4 --> s6
+    s5 --> s6
+    c1 -.delegates.-> a1
+    c3 -.delegates.-> a2
+```
+
+- **Skills** ([`.claude/skills/`](../.claude/skills/)) are the building blocks — each does one thing (design, author, review, analyze).
+- **Subagents** ([`.claude/agents/`](../.claude/agents/)) run a skill in an isolated context so a long design or flake hunt doesn't pollute the main conversation.
+- **Slash commands** ([`.claude/commands/`](../.claude/commands/)) chain skills/agents into repeatable pipelines (`/test-new`, `/test-fix`, …).
+
+### Mechanical enforcement: hooks + validators
+
+Two independent mechanisms keep the architecture honest regardless of who (human or agent) makes a change:
+
+1. **Claude Code hooks** ([`.claude/settings.json`](../.claude/settings.json)) — guard the _agent's_ actions in real time:
+   - `PreToolUse Bash` → `guard-bash.sh` blocks destructive shell commands.
+   - `PreToolUse Edit|Write` → `guard-paths.sh` blocks writes to `tests/api/generated`, snapshots, and `.env`.
+   - `PostToolUse Edit|Write` → `typecheck-touched.sh` typechecks touched files immediately (formatting/lint are handled later, by `lint-staged`).
+   - `Stop` → echoes a smoke-test reminder.
+2. **Git-level validators** ([`../tools/`](../tools/)) — guard _every_ commit, agent-authored or not, via `.husky/pre-commit` and CI.
+
+The skills carry portable copies of the same validators (e.g. `.claude/skills/playwright-test-author-ui/scripts/lint-ui-spec.ts`); the copies in `tools/` are this repository's wired-in, active gates. The kit is the template; `tools/` is the running instance.
+
+### Disabled-by-constraint
+
+For this black-box project, [`CONSTRAINTS.md`](CONSTRAINTS.md) §4 disables the OpenAPI-oriented capabilities (`api-client-from-openapi`, `playwright-test-author-api`, `/spec-sync`, `contract-drift-watch`). They remain committed to demonstrate that the workflow _supports_ contract testing when a repo owns a spec — they are simply switched off here.
diff --git a/docs/CONSTRAINTS.md b/docs/CONSTRAINTS.md
new file mode 100644
index 0000000..69201ec
--- /dev/null
+++ b/docs/CONSTRAINTS.md
@@ -0,0 +1,116 @@
+# Project Constraints
+
+> **Authoritative file for all agents, skills, and slash-commands in this repo.**
+> Any workflow that conflicts with these constraints must STOP and surface the conflict.
+> Last reviewed: 2026-04-28.
+
+## 1. Context
+
+This project automates **black-box E2E tests for three external sites** owned by a third party (freevpnplanet ecosystem):
+
+| Scenario          | Entry URL                           | Locale | Notes                                                                                                                 |
+| ----------------- | ----------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- |
+| Sign Up           | https://freevpnplanet.com/          | EN     | Log In → Sign Up → fill form + payment method → "Get your subscription" → assert payment URL/page is opened correctly |
+| Personal VPN (RU) | https://planetconfig.com/           | RU     | Pick plan → payment method page → payment page. Repeat for several methods incl. crypto                               |
+| Personal VPN (EN) | https://personal.freevpnplanet.com/ | EN     | Pick monthly/yearly plan → payment method page → payment page. Repeat for both methods                                |
+
+We do **not** own these sites, do **not** have access to their backend, and have **no** OpenAPI spec for them.
+
+## 2. Hard constraints (MUST)
+
+### 2.1 Black-box only — no contract testing
+
+- **OpenAPI / contract testing is N/A.** There is no spec we control.
+- The `api-client-from-openapi` skill is **DISABLED** for this project. Do not invoke it, do not run `/spec-sync`, do not generate `tests/api/generated/**`.
+- `tests-config.json` has `openapi.enabled = false`. Any tooling that reads this flag must skip OpenAPI work.
+- The `contract-drift-watch` subagent is **DISABLED**.
+
+### 2.2 No production telemetry on third-party sites
+
+- The **Sentry MCP is DISABLED** for this project. The sites are not ours, we have no Sentry org for them. Do not call any `mcp__plugin_sentry_sentry__*` tool. Do not invoke `sentry:*` skills.
+
+### 2.3 Tests stop at the payment page
+
+- Every payment-flow test **MUST stop** at the page where a real payment would be initiated (card form, crypto invoice, Apple Pay sheet, redirect target like `*.stripe.com`, `*.paddle.com`, `*.cryptomus.com`, etc.).
+- Tests **MUST NEVER** submit card data, crypto wallet data, OTP, 3DS, or any final "Pay" action.
+- Assertions allowed at the boundary: URL pattern, presence of payment-provider DOM markers, absence of error banners, presence of an `amount`/`currency`/`order id` element. **Disallowed**: clicking final pay buttons, filling card numbers (even Stripe test cards), uploading crypto TX hashes.
+
+### 2.4 Synthetic test data only
+
+- Test emails are synthetic, generated via **Faker with `SEED=1234`** for deterministic runs.
+- Email domain default = `@yopmail.com` (disposable-mail service with valid MX). This is a deliberate amendment from `@example.test`: the sites under test perform server-side MX-record validation and reject reserved RFC TLDs by routing to a `/payment/failed/` page (see `docs/ux-findings.md`, item B-payment-validation). yopmail accepts any local-part, has no per-user delivery, and is the industry-standard QA convention for third-party signups.
+- Local parts are clearly synthetic (`firstname.lastname.<sequence>`) so they don't collide with real human-readable addresses.
+- Override the default domain via `SYNTHETIC_EMAIL_DOMAIN` env var when a target site requires something else.
+- Passwords, names, phone numbers — also Faker, same seed.
+- Never use real personal data, never reuse a real email, never sign up with a domain we don't own.
+
+### 2.5 Localization split
+
+- RU specs live in their own `test.describe("…@ru", …)` group (or dedicated file/project).
+- EN specs (Sign Up + personal.freevpnplanet.com) live in their own `test.describe("…@en", …)` group.
+- A single test MUST NOT mix locales. The `@ru` / `@en` tags are mandatory and used by Playwright `--grep`.
+
+### 2.6 Resilience for external sites
+
+All three targets are external and outside our control. In `playwright.config.ts`:
+
+- `retries: 2`
+- `trace: 'on-first-retry'`
+- `video: 'retain-on-failure'`
+- `screenshot: 'only-on-failure'` (recommended companion)
+
+These values are non-negotiable defaults. Per-project overrides are allowed only to **strengthen** evidence (e.g. `trace: 'on'`), never to weaken it.
+
+## 3. Soft constraints (SHOULD)
+
+- Prefer `getByRole` / `getByLabel` / `getByTestId` per `tests-config.json`. Inline CSS/XPath only as last resort, with a TODO and a UX-feedback note in the accompanying Google Doc.
+- Do **not** auto-heal or silently retry broken selectors — if the third-party DOM changes, surface it as a finding in the UX/issues doc instead of patching tests opaquely.
+- Treat any 4xx/5xx during navigation as a real finding, not a flake. Quarantine with `test.fixme` + ticket reference, do not delete.
+
+## 4. What changes downstream
+
+The following project-level skills/agents are auto-disabled while this file says so:
+
+- `api-client-from-openapi` → DISABLED
+- `contract-drift-watch` (subagent) → DISABLED
+- `/spec-sync` (slash command) → DISABLED
+- `sentry:*` (all Sentry skills + MCP) → DISABLED
+- `playwright-test-author-api` → DISABLED (no API contract to test)
+- `release-report-composer` → ALLOWED but must omit contract-drift section
+
+Still active and recommended: `playwright-framework-bootstrap`, `fixture-architect`, `test-data-factory-builder`, `config-and-secrets`, `requirements-to-test-design`, `gherkin-test-case-author`, `playwright-test-author-ui`, `test-code-reviewer`, `playwright-debug-conductor`, `flaky-triage`, `run-analyzer`, `coverage-gap-analyzer`.
+
+## 5. Three E2E scenarios (canonical extraction from `docs/test-Assignment.pdf`)
+
+### Scenario A — Sign Up (EN)
+
+1. Open `https://freevpnplanet.com/`.
+2. Click **Log In**.
+3. Click **Sign Up**.
+4. Fill all required fields + payment method (synthetic data, no real card).
+5. Click **Get your subscription**.
+6. Assert payment URL is generated and the correct payment page opens. **STOP here.**
+
+### Scenario B — Personal VPN, RU
+
+1. Open `https://planetconfig.com/`.
+2. Pick purchase options, proceed to payment-method selection.
+3. Pick a payment method, proceed to payment page. **STOP.**
+4. Repeat for **several** payment methods, **including cryptocurrency**.
+
+### Scenario C — Personal VPN, EN
+
+1. Open `https://personal.freevpnplanet.com/`.
+2. Pick plan (**monthly** or **yearly**), proceed to payment-method selection.
+3. Pick a payment method, proceed to payment page. **STOP.**
+4. Repeat for **both** payment methods.
+
+## 6. Change protocol
+
+This file is the contract. To change a constraint:
+
+1. Open a PR that edits this file _only_.
+2. Get explicit user approval in the PR description.
+3. Then propagate to skills/agents/configs.
+
+Agents/skills MUST re-read this file at the start of any session and abort if asked to violate any §2 rule.
diff --git a/docs/sonarcloud-setup.md b/docs/sonarcloud-setup.md
new file mode 100644
index 0000000..8196f56
--- /dev/null
+++ b/docs/sonarcloud-setup.md
@@ -0,0 +1,149 @@
+# SonarCloud Setup Guide
+
+This guide walks you through onboarding the `free-vpn-planet-test` repository to **SonarCloud** so that quality gates, code-smell counts, and duplication metrics show up as the badges in the project README.
+
+> SonarCloud is **free for public repositories**. The setup below assumes the repo is public on GitHub. If it's private, switch to the paid plan or use a self-hosted SonarQube instance with the same `sonar-project.properties`.
+
+---
+
+## Prerequisites
+
+- A GitHub account that owns (or has admin on) `Kseolis/free-vpn-planet-test`.
+- The repo pushed to GitHub at least once (so the default branch is visible).
+- `sonar-project.properties` already committed at the repo root (✅ done in this branch).
+- `.github/workflows/tests.yml` already includes a Sonar-scan job (see step 5 below).
+
+---
+
+## Step 1 — Sign in to SonarCloud and import the organization
+
+1. Open [https://sonarcloud.io/](https://sonarcloud.io/) and click **Log in → With GitHub**.
+2. Authorize the SonarCloud GitHub App when prompted.
+3. On the SonarCloud dashboard, click **+ → Analyze new project**.
+4. Choose **Import an organization from GitHub** if `Kseolis` isn't yet on SonarCloud, otherwise select the existing `kseolis` organization.
+5. Pick the **Free** plan when offered (sufficient for public repos).
+
+The organization key on SonarCloud will be `kseolis` (lowercase) — it must match `sonar.organization` in `sonar-project.properties`.
+
+---
+
+## Step 2 — Create the project
+
+1. From the organization page, click **Add project → GitHub** → select `free-vpn-planet-test`.
+2. SonarCloud proposes a project key. **Override it to `Kseolis_free-vpn-planet-test`** so it matches the value already committed in `sonar-project.properties`.
+3. Choose **GitHub Actions** as the analysis method.
+4. SonarCloud generates a `SONAR_TOKEN`. **Copy it** — you'll need it for the GitHub secret in step 4.
+
+---
+
+## Step 3 — Configure the new-code definition
+
+1. On the project page, go to **Administration → New Code**.
+2. Set the new-code period to **Previous version** (recommended for a CI-driven project) or **30 days** (recommended for a slow-moving one).
+3. Save.
+
+This determines what the **Quality Gate** evaluates against.
+
+---
+
+## Step 4 — Add the `SONAR_TOKEN` secret to GitHub
+
+1. In GitHub, navigate to `Settings → Secrets and variables → Actions → New repository secret`.
+2. Name: `SONAR_TOKEN`.
+3. Value: the token you copied in step 2.
+4. Save.
+
+The default `GITHUB_TOKEN` is provided by GitHub Actions automatically and does not need to be added.
+
+---
+
+## Step 5 — Confirm the Sonar job in CI
+
+`.github/workflows/tests.yml` already contains a `sonar` job that runs after the test matrix. Skim it to confirm:
+
+```yaml
+sonar:
+  name: SonarCloud
+  needs: test
+  runs-on: ubuntu-latest
+  if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
+  steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 # full history; required by Sonar for blame
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 20
+        cache: npm
+    - name: Download Playwright JUnit XML
+      uses: actions/download-artifact@v4
+      with:
+        pattern: playwright-report-*
+        path: playwright-report-merged
+        merge-multiple: true
+    - name: Move junit.xml into the path Sonar expects
+      run: |
+        mkdir -p playwright-report
+        find playwright-report-merged -name 'junit.xml' -print -exec cp {} playwright-report/junit.xml \; -quit
+    - name: SonarCloud Scan
+      uses: SonarSource/sonarqube-scan-action@v3
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+```
+
+The job:
+
+1. Waits for all three browser jobs to complete (`needs: test`).
+2. Skips on **forked-PR** runs (those don't have access to `SONAR_TOKEN`, and SonarCloud rejects the scan anyway).
+3. Pulls the JUnit XML produced by Playwright and places it where `sonar-project.properties` expects.
+4. Runs the official SonarSource scanner action.
+
+---
+
+## Step 6 — Trigger the first scan
+
+1. Push any commit to `main`, or open a PR. The workflow runs automatically.
+2. Once it succeeds, go to the SonarCloud project page — the dashboard populates within ~30 seconds.
+3. From the project page, copy the badge URLs and uncomment the badge block in `README.md` (lines marked "Optional SonarCloud badges"). Replace nothing else — the project key already matches.
+
+---
+
+## Step 7 — Quality Gate hardening (recommended)
+
+By default SonarCloud uses the **Sonar way** quality gate (no new bugs, no new vulnerabilities, ≤ 3% duplications, etc.). For an E2E test repo this is overkill on coverage but still useful on:
+
+- **Bugs** (`> 0`) — fail the PR
+- **Vulnerabilities** (`> 0`) — fail the PR
+- **Code Smells** on new code (`> 5`) — warn
+
+Recommended override: **Administration → Quality Gates → Copy "Sonar way" → "Test-suite way"**, then **disable** the line-coverage and condition-coverage gates (we don't have unit-test coverage on E2E code), and apply to this project.
+
+---
+
+## Troubleshooting
+
+| Symptom                                 | Likely cause                                                          | Fix                                                                                                                                     |
+| --------------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `Project key not found`                 | `sonar.projectKey` in properties doesn't match the SonarCloud project | edit `sonar-project.properties` to match                                                                                                |
+| `You're not authorized to run analysis` | `SONAR_TOKEN` missing or expired                                      | re-issue token in SonarCloud → My Account → Security → Tokens                                                                           |
+| Coverage shown as 0%                    | Sonar expects an LCov file                                            | leave `sonar.javascript.lcov.reportPaths` empty (default in this repo) — coverage simply won't appear, which is honest for an E2E suite |
+| `junit.xml not found`                   | one of the matrix jobs failed before producing artefacts              | the `sonar` job will skip its scan; rerun after fixing the test failure                                                                 |
+| PR from a fork shows no Sonar comment   | secrets are blocked on forked PRs                                     | use the `pull_request_target` event with stricter checkout, or accept the limitation                                                    |
+
+---
+
+## Local-only scan (optional)
+
+To run SonarScanner locally before pushing:
+
+```bash
+# Install once
+brew install sonar-scanner   # macOS
+# or download from https://docs.sonarcloud.io/advanced-setup/ci-based-analysis/sonarscanner-cli/
+
+# Run
+SONAR_TOKEN=<your-token> sonar-scanner
+```
+
+The scan uses `sonar-project.properties` from the repo root.
diff --git a/docs/test-design/personal-vpn-en.md b/docs/test-design/personal-vpn-en.md
new file mode 100644
index 0000000..711c176
--- /dev/null
+++ b/docs/test-design/personal-vpn-en.md
@@ -0,0 +1,309 @@
+# Test Design — Personal VPN EN (Scenario C, @en)
+
+> Skill: `requirements-to-test-design` | Author: test-design-agent | Date: 2026-04-28
+> Next step: `gherkin-test-case-author` consumes this document.
+
+---
+
+## 1. Scope and Links
+
+| Item                      | Value                                                                                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| Source PRD                | `docs/test-Assignment.pdf` — canonical extraction: CONSTRAINTS §5 Scenario C                                                               |
+| Entry URL                 | `https://personal.freevpnplanet.com/`                                                                                                      |
+| Exit boundary             | Payment page loads (URL matches provider pattern OR payment-provider DOM marker is visible). **STOP — do not interact with payment form.** |
+| Locale tag                | `@en`                                                                                                                                      |
+| Playwright describe group | `test.describe("Personal VPN purchase — EN @en", ...)`                                                                                     |
+| Constraint source         | `docs/CONSTRAINTS.md` §2.3 (stop at payment), §2.4 (Faker SEED=1234, @example.test), §2.5 (@en tag), §2.6 (retries:2, trace, video)        |
+
+### In scope
+
+- Landing page renders and `<form id="PPG">` is present.
+- Plan selection: `offer_id` radio group — primary paths `1_month` and `1_year`; secondary `2_days` as an additional equivalence class.
+- Email field interaction (valid, invalid, empty, boundary lengths).
+- "Pay" button submit — navigates to payment-method selection page.
+- Payment-method selection page: exactly **two** methods (assumed Card + Crypto — see §9).
+- For each method: selecting it and proceeding reaches the final payment page (URL/DOM assertion). **STOP.**
+- Assignment constraint: **repeat the full flow for both payment methods** (2 primary happy-path E2E tests minimum).
+
+### Out of scope
+
+See §8 for full list. Summary: real payment submission, card data entry (including Stripe test cards), 3DS, Apple/Google Pay sheets, crypto wallet auth, crypto TX hash upload, account-exists branch, password reset, SSO with `account.freevpnplanet.com`, locale toggling mid-flow, VPN config download/delivery.
+
+### Assignment note on plan choice
+
+The assignment explicitly narrows the main path to **monthly or yearly** ("план на месяц или год"). The `2_days` trial is treated as a secondary equivalence class — its select+submit behaviour is verified in one additional lower-priority test, not repeated for both payment methods.
+
+### Selector strategy (differs from Site A and Site B)
+
+`personal.freevpnplanet.com` exposes **no `qa-*` IDs** and **no `data-testid`** attributes (contrast: Site B `planetconfig.com` has `qa-*` IDs). All selectors must use:
+
+- `page.locator('input[name="offer_id"][value="1_month"]')` — attribute selector on radio inputs.
+- `page.getByRole('button', { name: 'Pay' })` — submit button.
+- `page.getByPlaceholder('name@example.com')` — email field.
+- Role/text selectors for payment-method cards on the next page.
+
+This is the **#1 maintenance risk** for this scenario (§9).
+
+---
+
+## 2. State Diagram
+
+```
+[Landing / Home]
+    │
+    │  select offer_id ∈ {2_days*, 1_month, 1_year}
+    ▼
+[PlanSelected]
+    │
+    │  fill email (valid | invalid | empty)
+    ▼
+[EmailEntered]
+    │
+    │  click "Pay" (submit form#PPG GET /payment/)
+    ▼
+[PaymentMethodPage]  ← /payment/ or similar
+    │
+    ├── choose Card  ──────────────────────────────────►  [PaymentPage — Card]  ★ STOP
+    │
+    └── choose Crypto  ────────────────────────────────►  [PaymentPage — Crypto]  ★ STOP
+
+* 2_days is the default selected radio on page load.
+```
+
+**State guard notes:**
+
+- The `gateway` hidden field is presumed to be set by the payment-method selection page before the final redirect, not on the landing form. Direct `GET /payment/` without prior form submission is presumed inaccessible or returns an error — this is not exercised (out of scope for direct URL access tests).
+- Browser Back from [PaymentMethodPage] should return to [EmailEntered] state with form values preserved (see §7 negative paths).
+
+---
+
+## 3. Equivalence Classes
+
+### 3.1 `offer_id` — Plan
+
+| Class ID | Partition               | Values    | Priority | Notes                                     |
+| -------- | ----------------------- | --------- | -------- | ----------------------------------------- |
+| EC-P1    | Monthly plan (primary)  | `1_month` | P0       | Required by assignment                    |
+| EC-P2    | Yearly plan (primary)   | `1_year`  | P0       | Required by assignment                    |
+| EC-P3    | 2-day trial (secondary) | `2_days`  | P2       | Default on load; additional coverage only |
+
+### 3.2 Email
+
+| Class ID | Partition                     | Example                                    | Priority | Notes                                       |
+| -------- | ----------------------------- | ------------------------------------------ | -------- | ------------------------------------------- |
+| EC-E1    | Valid, standard               | `user-1234@example.test` (Faker SEED=1234) | P0       | Happy path                                  |
+| EC-E2    | Empty string                  | `""`                                       | P0       | No HTML5 `required`; behaviour TBD          |
+| EC-E3    | Missing @                     | `userexample.test`                         | P1       | Basic format violation                      |
+| EC-E4    | Missing TLD / domain          | `user@`                                    | P1       | RFC violation                               |
+| EC-E5    | Double @                      | `user@@example.test`                       | P1       | RFC violation                               |
+| EC-E6    | Leading whitespace            | `" user@example.test"`                     | P1       | Trimming check                              |
+| EC-E7    | Trailing whitespace           | `"user@example.test "`                     | P1       | Trimming check                              |
+| EC-E8    | Max local-part (64 chars)     | `${'a'.repeat(64)}@example.test`           | P2       | RFC 5321 boundary                           |
+| EC-E9    | Max total length (254 chars)  | local+domain = 254                         | P2       | RFC 5321 boundary                           |
+| EC-E10   | Exceeds max total (255 chars) | local+domain = 255                         | P2       | Over-boundary                               |
+| EC-E11   | XSS payload                   | `"><script>alert(1)</script>@x.test`       | P1       | Security — assert sanitisation on next page |
+| EC-E12   | SQL injection pattern         | `' OR 1=1--@example.test`                  | P2       | Security                                    |
+| EC-E13   | Punycode / IDN domain         | `user@xn--nxasmq6b.test`                   | P2       | i18n edge case                              |
+| EC-E14   | Subaddress (plus tag)         | `user+tag@example.test`                    | P2       | RFC-valid; should pass                      |
+
+### 3.3 Location
+
+| Class ID | Partition                  | Value | Priority | Notes                                              |
+| -------- | -------------------------- | ----- | -------- | -------------------------------------------------- |
+| EC-L1    | Netherlands (only visible) | `NL`  | P0       | Single radio, pre-checked; no UI variation to test |
+
+Flag: No multi-location selector is present on this domain (differs from potential future multi-location offering). If a second location radio appears, this becomes P0.
+
+### 3.4 Currency
+
+| Class ID | Partition          | Value | Priority | Notes                                              |
+| -------- | ------------------ | ----- | -------- | -------------------------------------------------- |
+| EC-C1    | USD (only visible) | `USD` | P0       | Single radio, pre-checked; no UI variation to test |
+
+Flag: Site B (planetconfig.com) may offer RUB; Site C is USD-only at time of inspection.
+
+### 3.5 Payment Method (on payment-method page)
+
+| Class ID | Partition | Assumed label                  | Priority | Notes                       |
+| -------- | --------- | ------------------------------ | -------- | --------------------------- |
+| EC-PM1   | Card      | "Credit Card" or equivalent    | P0       | Assignment: repeat for both |
+| EC-PM2   | Crypto    | "Cryptocurrency" or equivalent | P0       | Assignment: repeat for both |
+
+Assumption: exactly two methods visible, by parity with Site A. See §9 open questions.
+
+---
+
+## 4. Boundary Values
+
+| Parameter               | Lower bound                             | Nominal   | Upper bound          | Over-upper | Source            |
+| ----------------------- | --------------------------------------- | --------- | -------------------- | ---------- | ----------------- |
+| Email local-part length | 1 char                                  | ~10 chars | 64 chars (RFC 5321)  | 65 chars   | RFC 5321 §4.5.3.1 |
+| Email total length      | 6 chars (`a@b.cd`)                      | ~25 chars | 254 chars (RFC 5321) | 255 chars  | RFC 5321 §4.5.3.1 |
+| `offer_id` enum         | N/A — discrete values, no numeric range | —         | —                    | —          | DOM inspection    |
+
+Note: The landing page form exposes no HTML5 `minLength`, `maxLength`, `pattern`, or `min`/`max` attributes on any field. All boundaries above are inferred from RFC 5321 and common server-side practice. Any server-side length enforcement is opaque — surface mismatches as findings. This is flagged in §9.
+
+---
+
+## 5. Decision Table — Plan × Payment Method × Email Validity
+
+Inputs:
+
+- **P** = offer_id ∈ {1_month (M), 1_year (Y)}
+- **PM** = payment method ∈ {Card (C), Crypto (K)}
+- **E** = email validity ∈ {valid (V), invalid/empty (I)}
+
+Expected outputs:
+
+- `nav` = navigates from landing to payment-method page after submit.
+- `pm_page` = payment-method page renders with both method options.
+- `pay_page` = payment page for selected method loads (STOP point).
+- `err` = inline error or blocked navigation (email rejected client or server side).
+
+| Rule | P   | PM  | E             | nav | pm_page | pay_page     | err   | Priority | Test ID |
+| ---- | --- | --- | ------------- | --- | ------- | ------------ | ----- | -------- | ------- |
+| R1   | M   | C   | V             | yes | yes     | yes (Card)   | no    | P0       | TC-C-01 |
+| R2   | M   | K   | V             | yes | yes     | yes (Crypto) | no    | P0       | TC-C-02 |
+| R3   | Y   | C   | V             | yes | yes     | yes (Card)   | no    | P0       | TC-C-03 |
+| R4   | Y   | K   | V             | yes | yes     | yes (Crypto) | no    | P0       | TC-C-04 |
+| R5   | M   | —   | I (empty)     | ?   | —       | —            | maybe | P1       | TC-C-05 |
+| R6   | M   | —   | I (malformed) | ?   | —       | —            | maybe | P1       | TC-C-06 |
+| R7   | Y   | —   | I (empty)     | ?   | —       | —            | maybe | P1       | TC-C-07 |
+
+Collapse note: R1 and R3 are structurally equivalent at the plan-selection level; their difference is `offer_id` value and potentially the displayed price on the payment-method page. Both are P0 because the assignment requires testing both plans. R5–R7 collapse to "invalid email" behaviour — outcome is unknown without live observation; expected is either client-side HTML5 validation (popover) or server-side rejection. Both outcomes must be asserted explicitly.
+
+---
+
+## 6. State Transitions Table
+
+| From State            | Event                 | Guard                  | To State                             | Assertion                                                                    |
+| --------------------- | --------------------- | ---------------------- | ------------------------------------ | ---------------------------------------------------------------------------- |
+| Landing               | Page load             | —                      | PlanDefault (`2_days` selected)      | `input[name="offer_id"][value="2_days"]` is checked                          |
+| PlanDefault           | Click `1_month` radio | —                      | PlanSelected(1_month)                | `input[name="offer_id"][value="1_month"]` is checked                         |
+| PlanDefault           | Click `1_year` radio  | —                      | PlanSelected(1_year)                 | `input[name="offer_id"][value="1_year"]` is checked                          |
+| PlanSelected          | Type valid email      | —                      | EmailEntered(valid)                  | email field value equals typed string                                        |
+| PlanSelected          | Leave email empty     | —                      | EmailEntered(empty)                  | email field value is empty string                                            |
+| EmailEntered(valid)   | Click Pay             | form valid             | PaymentMethodPage                    | URL contains `/payment/` or equivalent; both method options visible          |
+| EmailEntered(empty)   | Click Pay             | no HTML5 required      | PaymentMethodPage OR ValidationError | Either navigates (server validates) or shows inline error                    |
+| EmailEntered(invalid) | Click Pay             | HTML5 pattern may fire | ValidationError OR PaymentMethodPage | Inline validation popover OR server-side error; must not silently proceed    |
+| PaymentMethodPage     | Choose Card           | —                      | PaymentPage(Card)                    | URL matches card provider pattern; card form / payment marker visible        |
+| PaymentMethodPage     | Choose Crypto         | —                      | PaymentPage(Crypto)                  | URL matches crypto provider pattern; crypto invoice / payment marker visible |
+| PaymentMethodPage     | Browser Back          | —                      | Landing (form state)                 | Form values potentially preserved (browser-native); no crash                 |
+| PaymentPage           | —                     | **STOP**               | —                                    | No further interaction                                                       |
+
+---
+
+## 7. Negative Paths
+
+Listed by priority.
+
+### P0 Negative
+
+| ID     | Scenario                                                     | Steps                                                        | Expected Result                                                                                                                                                |
+| ------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| NEG-01 | Empty email, click Pay                                       | Load page, do NOT fill email, click Pay button               | Either HTML5 validation popover blocks submit (inspect `validity.valueMissing`), OR server-side error shown on next page. Must NOT silently complete checkout. |
+| NEG-02 | No plan change (stays at `2_days` default), valid email, Pay | Leave radio at default `2_days`, fill valid email, click Pay | Form submits with `offer_id=2_days`; payment-method page renders (server accepts it). Assert plan label on payment page.                                       |
+
+### P1 Negative
+
+| ID     | Scenario                            | Steps                                                | Expected Result                                                                                                                |
+| ------ | ----------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| NEG-03 | Malformed email — missing @         | Fill `userexample.test`, click Pay                   | HTML5 type=email validation fires and blocks submission, OR server returns error.                                              |
+| NEG-04 | Malformed email — missing domain    | Fill `user@`, click Pay                              | HTML5 validation or server error. No successful navigation to payment.                                                         |
+| NEG-05 | Double @ in email                   | Fill `user@@example.test`, click Pay                 | Validation error.                                                                                                              |
+| NEG-06 | Leading whitespace in email         | Fill ` user@example.test` (space prefix)             | Either trimmed and accepted, or rejected. Assert actual behaviour; flag as finding if trimmed silently.                        |
+| NEG-07 | XSS payload in email field          | Fill `"><script>alert(1)</script>@x.test`, click Pay | If navigation proceeds to payment-method page, assert the email string is HTML-escaped / sanitised in the DOM. No alert fires. |
+| NEG-08 | Double-click Pay button quickly     | Click Pay twice within 200 ms                        | Single navigation occurs; no duplicate form submissions or double requests. Observe network tab / final URL.                   |
+| NEG-09 | Browser Back from PaymentMethodPage | Navigate forward to payment-method page, press Back  | Returns to landing; form fields may or may not be preserved (browser behaviour). No error page, no crash.                      |
+
+### P2 Negative
+
+| ID     | Scenario                                        | Steps                                                                                         | Expected Result                                                                                                                            |
+| ------ | ----------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| NEG-10 | Email at RFC max local-part boundary (64 chars) | Fill 64-char local-part + `@example.test`, click Pay                                          | Accepted and proceeds.                                                                                                                     |
+| NEG-11 | Email over RFC max local-part (65 chars)        | Fill 65-char local-part + `@example.test`, click Pay                                          | Server may reject or truncate. Assert outcome; flag as finding either way.                                                                 |
+| NEG-12 | Email total 254 chars (at max)                  | Construct 254-char valid email, click Pay                                                     | Accepted.                                                                                                                                  |
+| NEG-13 | Email total 255 chars (over max)                | Construct 255-char email, click Pay                                                           | Server may reject. Assert and flag.                                                                                                        |
+| NEG-14 | Tampered `gateway` hidden field                 | JS: set `document.querySelector('input[name="gateway"]').value = 'invalid_xyz'` before submit | Server should reject or ignore tampered value. Expect error page or default payment-method page.                                           |
+| NEG-15 | SQL injection in email                          | Fill `' OR 1=1--@example.test`, click Pay                                                     | Sanitised. No server error traceable to injection.                                                                                         |
+| NEG-16 | Network offline at click Pay                    | Intercept / throttle to offline, click Pay                                                    | Browser network error displayed. No partial submission state. No double-charge risk (payment page never reached).                          |
+| NEG-17 | 4xx/5xx from `/payment/` endpoint               | (Simulate via proxy or observe if server error occurs naturally)                              | UX surfaces error banner; does not crash silently. Treat as real finding, not flake; quarantine with `test.fixme` + ticket if encountered. |
+
+---
+
+## 8. Out of Scope
+
+| Item                                 | Rationale                                                           |
+| ------------------------------------ | ------------------------------------------------------------------- |
+| Real payment submission              | CONSTRAINTS §2.3 — hard stop at payment page                        |
+| Card number / CVV / expiry entry     | CONSTRAINTS §2.3 — even Stripe test cards forbidden                 |
+| 3DS / OTP flow                       | CONSTRAINTS §2.3                                                    |
+| Apple Pay / Google Pay sheets        | CONSTRAINTS §2.3                                                    |
+| Crypto wallet authentication         | CONSTRAINTS §2.3                                                    |
+| Crypto TX hash upload                | CONSTRAINTS §2.3                                                    |
+| Account-already-exists branch        | No authenticated state; out of black-box scope                      |
+| Password reset                       | Not part of this scenario; handled in Scenario A if applicable      |
+| SSO with `account.freevpnplanet.com` | Separate subdomain, separate concern                                |
+| VPN config download / delivery       | Post-payment; never reached                                         |
+| Locale toggle EN→RU mid-flow         | No locale switcher observed on landing; flag if one appears         |
+| Direct `GET /payment/` URL access    | No backend access; presumed auth-gated. Not part of happy-path E2E. |
+| Performance / load testing           | Not in assignment scope                                             |
+| Accessibility (a11y) audit           | Not in assignment scope                                             |
+| RU locale paths                      | Covered by Scenario B on `planetconfig.com`                         |
+| Scenario A (Sign Up flow)            | Separate design document                                            |
+
+---
+
+## 9. Open Questions and Assumptions
+
+| ID   | Item                                                                                                                                                                                                                                                         | Status                         | Impact if Wrong                                                                                                                                                  |
+| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OQ-1 | **Exact payment method labels on `/payment/` page.** Assumed: "Credit Card" (or "Card") and "Cryptocurrency" (or "Crypto") based on parity with Site A's order page.                                                                                         | **Assumption**                 | Selectors for payment-method cards will break; test will fail at NEG step. Treat as P0 blocker on first run.                                                     |
+| OQ-2 | **Selector stability — no `data-testid` / `qa-*` IDs.** This site exposes no stable test hooks. All selectors rely on `name` attributes, placeholder text, and button text. Any DOM restructuring will break tests silently or loudly.                       | **Risk — #1 maintenance risk** | High churn on selector fixes. Recommend filing a UX-feedback note requesting `data-testid` attributes on `#PPG` inputs and Pay button.                           |
+| OQ-3 | **Whether empty email is blocked client-side.** The email `<input type="email">` has no HTML5 `required` attribute. Browser may not validate emptiness, meaning the form submits and the server must validate. Actual behaviour is unknown without live run. | **Assumption**                 | NEG-01 test assertion branch depends on this. Design handles both outcomes; choose correct assertion at authoring time.                                          |
+| OQ-4 | **Whether `2_days` plan navigates to the same payment-method page.** Assumed yes (same form action `/payment/`).                                                                                                                                             | **Assumption**                 | NEG-02 scope changes if `2_days` routes differently.                                                                                                             |
+| OQ-5 | **Whether location or currency ever changes on this domain.** Currently single-value radios (`NL`, `USD`). If multi-value options are added, EC-L and EC-C tables require expansion.                                                                         | **Watch**                      | Currently low risk; flag for re-inspection each sprint.                                                                                                          |
+| OQ-6 | **CSRF nonce `ppg_nonce_1` validity window.** If the nonce expires before the form is submitted in slow tests, submission may fail with a 403.                                                                                                               | **Risk**                       | Tests may be flaky on slow CI. Mitigate with `retries: 2` (already mandated by CONSTRAINTS §2.6).                                                                |
+| OQ-7 | **Payment provider identity.** The provider behind the card and crypto payment pages is unknown until the flow is run. Possible providers by ecosystem: Stripe, Paddle, Cryptomus. URL assertion pattern must be determined on first run.                    | **Assumption**                 | Payment-page URL assertion in TC-C-01 through TC-C-04 will need provider-specific pattern. Placeholder: assert URL changed from `/payment/` to any external URL. |
+
+---
+
+## 10. Risk-Prioritised Test Condition List
+
+Priority legend: **P0** = smoke / must-pass for release; **P1** = regression; **P2** = edge-case / exploratory.
+
+Smoke suite (≤ 3 conditions, tagged `@smoke @en`): **TC-C-01, TC-C-02, TC-C-03** cover the primary assignment requirement (monthly plan + both payment methods; yearly plan + card). TC-C-04 (yearly + crypto) is P0 but can run outside the smoke gate.
+
+| Test ID | Condition                                                  | offer_id  | Email                | Payment Method           | Priority    | Tag   | Stop Point                                           |
+| ------- | ---------------------------------------------------------- | --------- | -------------------- | ------------------------ | ----------- | ----- | ---------------------------------------------------- |
+| TC-C-01 | Monthly plan → Card payment page reached                   | `1_month` | valid (Faker)        | Card                     | P0 `@smoke` | `@en` | Payment page URL / DOM marker                        |
+| TC-C-02 | Monthly plan → Crypto payment page reached                 | `1_month` | valid (Faker)        | Crypto                   | P0 `@smoke` | `@en` | Payment page URL / DOM marker                        |
+| TC-C-03 | Yearly plan → Card payment page reached                    | `1_year`  | valid (Faker)        | Card                     | P0 `@smoke` | `@en` | Payment page URL / DOM marker                        |
+| TC-C-04 | Yearly plan → Crypto payment page reached                  | `1_year`  | valid (Faker)        | Crypto                   | P0          | `@en` | Payment page URL / DOM marker                        |
+| TC-C-05 | Empty email blocks or reports error on submit              | `1_month` | empty                | —                        | P1          | `@en` | Error state asserted; no payment page                |
+| TC-C-06 | Malformed email (missing @) blocked                        | `1_month` | `userexample.test`   | —                        | P1          | `@en` | Validation error                                     |
+| TC-C-07 | Malformed email (missing domain) blocked                   | `1_year`  | `user@`              | —                        | P1          | `@en` | Validation error                                     |
+| TC-C-08 | XSS payload in email sanitised on next page                | `1_month` | XSS string           | Card                     | P1          | `@en` | No script executes; email shown escaped              |
+| TC-C-09 | Double-click Pay — single navigation only                  | `1_month` | valid                | Card                     | P1          | `@en` | Single payment-method page load                      |
+| TC-C-10 | Browser Back from PaymentMethodPage — no crash             | `1_month` | valid                | — (back before choosing) | P1          | `@en` | Returns to landing, no error                         |
+| TC-C-11 | 2-day trial plan submits and reaches payment-method page   | `2_days`  | valid (Faker)        | Card                     | P2          | `@en` | PaymentMethodPage (STOP at method selection)         |
+| TC-C-12 | Email at RFC local-part max (64 chars) accepted            | `1_month` | 64-char local        | Card                     | P2          | `@en` | Payment page reached                                 |
+| TC-C-13 | Email over RFC local-part max (65 chars) — observe outcome | `1_month` | 65-char local        | —                        | P2          | `@en` | Error or accepted — assert and flag                  |
+| TC-C-14 | Tampered `gateway` field — server handles gracefully       | `1_month` | valid                | —                        | P2          | `@en` | Error page or default method page; no silent success |
+| TC-C-15 | Leading whitespace in email — trimmed or rejected          | `1_month` | ` user@example.test` | Card                     | P2          | `@en` | Either proceeds (trimmed) or error; flag as finding  |
+
+### Risk heuristic summary
+
+| Risk Vector                                    | Severity | Mitigations in design                                                                                             |
+| ---------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
+| Selector fragility (no `qa-*` / `data-testid`) | High     | Attribute selectors on `name`/`value`; role selectors; placeholder selector. File UX-feedback ticket.             |
+| CSRF nonce expiry on slow CI                   | Medium   | `retries: 2`; keep test fast; no `waitForTimeout`.                                                                |
+| Payment method labels unknown until first run  | Medium   | TC-C-01..04 use placeholder assertion (URL changed); update after first run.                                      |
+| Empty email not blocked client-side            | Medium   | NEG-01 / TC-C-05 dual-branch assertion handles both outcomes.                                                     |
+| External site downtime / 5xx                   | Medium   | `retries: 2`, `trace: on-first-retry`, `video: retain-on-failure`; treat persistent failure as finding not flake. |
+| Over-reaching into payment submission          | Critical | Hard stop enforced by design; all test IDs terminate at payment page entry assertion.                             |
+
+---
+
+_End of test design. Hand off to `gherkin-test-case-author` for TC-C-01 through TC-C-15._
diff --git a/docs/test-design/personal-vpn-ru.md b/docs/test-design/personal-vpn-ru.md
new file mode 100644
index 0000000..9cb5658
--- /dev/null
+++ b/docs/test-design/personal-vpn-ru.md
@@ -0,0 +1,375 @@
+# Test Design — Personal VPN RU (Scenario B, @ru)
+
+> **Skill**: `requirements-to-test-design`
+> **Site**: https://planetconfig.com/
+> **Locale**: RU
+> **Tag**: `@ru`
+> **Stop boundary**: Payment page (after payment-method selection). No real payment action is ever executed.
+> **Last updated**: 2026-04-28
+
+---
+
+## 1. Scope and links
+
+| Item               | Detail                                                                                                                        |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| Source PRD         | `docs/test-Assignment.pdf` §Scenario B; canonical extraction in `docs/CONSTRAINTS.md` §5 Scenario B                           |
+| Entry URL          | `https://planetconfig.com/`                                                                                                   |
+| Form ID            | `#PPG` (method=GET, action `/payment/`)                                                                                       |
+| Exit boundary      | Payment page loads (URL matches provider pattern OR provider DOM marker is visible). **STOP — do not fill card/crypto data.** |
+| Locale             | RU (all UI labels in Russian; currency locked to RUB on landing)                                                              |
+| Config constraints | `retries: 2`, `trace: on-first-retry`, `video: retain-on-failure`, `screenshot: only-on-failure` (CONSTRAINTS §2.6)           |
+
+**In scope**
+
+- Landing page rendering (plan cards, pricing, form controls)
+- Plan selection via `offer_id` radios (`2_days`, `1_month`, `1_year`)
+- Email entry and client-side / server-side validation observable in the UI
+- Form submit ("Оплатить") → navigation to `/payment/` (method selection page)
+- Payment method selection on `/payment/` page → navigation to provider payment page
+- Assertions at the provider payment page boundary (URL pattern, amount displayed, absence of error banners)
+- Cryptocurrency payment method path (mandatory per assignment)
+- State persistence (email, plan) when navigating back
+
+**Out of scope**
+
+- Real payment execution, card number entry, 3DS/OTP, crypto TX submission
+- Telegram bot purchase channel (`t.me/Planet_Vpn_Key_Bot`)
+- VPN config delivery email / account creation post-payment
+- SBP in-banking-app confirmation flow
+- Any non-web channel
+- Backend / API contract testing (CONSTRAINTS §2.1 — black-box only)
+
+---
+
+## 2. State diagram
+
+```
+[Home]
+  │  load https://planetconfig.com/
+  ▼
+[PlanSelected]            ← default: 2_days (qa-radio-offer-2-days checked)
+  │  user clicks 1_month or 1_year card (or keeps default)
+  ▼
+[CurrencySet]             ← always RUB (single option exposed; no user action needed)
+  │
+  ▼
+[EmailEntered]
+  │  user types email into #qa-input-email
+  │
+  ├─[INVALID EMAIL]──► [ErrorVisible] ──► (back-arrow) EmailEntered
+  │
+  ▼
+[SubmitClicked]           ← #qa-btn-submit-step1 "Оплатить"
+  │
+  ├─[EMPTY EMAIL / bad format]──► [ValidationErrorVisible] ──► (back-arrow) EmailEntered
+  │
+  ├─[network 4xx/5xx]──► [ErrorPage / UX error banner]   ← STOP with finding
+  │
+  ▼
+[PaymentMethodPage]       ← GET /payment/ with offer_id + email + currency in query
+  │  user selects method (Card / Crypto / Other)
+  │
+  ├─[back button]──► [Home re-prefilled]   ← assert state preserved
+  │
+  ▼
+[PaymentPage] ◄──── STOP BOUNDARY
+  │  assertions: URL pattern, amount, currency, order id, no error banners
+  │  NO further action taken
+  ▼
+[END TEST]
+```
+
+---
+
+## 3. Equivalence classes
+
+### 3.1 `offer_id` (plan selection)
+
+| Class       | Value          | Representative | Notes                                                                         |
+| ----------- | -------------- | -------------- | ----------------------------------------------------------------------------- |
+| EC-PLAN-1   | `2_days`       | `2_days`       | Default on page load; 49.99 ₽                                                 |
+| EC-PLAN-2   | `1_month`      | `1_month`      | 499 ₽                                                                         |
+| EC-PLAN-3   | `1_year`       | `1_year`       | 2990 ₽                                                                        |
+| EC-PLAN-INV | Tampered value | `999_years`    | Submitted via URL manipulation; oracle: server error or redirect to safe plan |
+
+### 3.2 `email` field
+
+| Class                                   | Representative value                       | Expected UI outcome                                              |
+| --------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------- |
+| EC-EMAIL-1 — Valid, Latin, standard     | `user.1234@example.test` (Faker SEED=1234) | Accepted; form submits                                           |
+| EC-EMAIL-2 — Empty                      | `""`                                       | Validation error OR no navigation                                |
+| EC-EMAIL-3 — Missing `@`                | `userexample.test`                         | Validation error                                                 |
+| EC-EMAIL-4 — Missing domain             | `user@`                                    | Validation error                                                 |
+| EC-EMAIL-5 — Missing TLD                | `user@example`                             | Validation error or acceptance (browser-dependent) — flag result |
+| EC-EMAIL-6 — Space in local-part        | `foo bar@example.test`                     | Validation error                                                 |
+| EC-EMAIL-7 — Leading `@`                | `@example.test`                            | Validation error                                                 |
+| EC-EMAIL-8 — Cyrillic local-part        | `пользователь@example.test`                | IDN / punycode handling; flag acceptance or rejection            |
+| EC-EMAIL-9 — XSS probe                  | `<script>@example.test`                    | Must not execute script; next page must render sanitised value   |
+| EC-EMAIL-10 — Max local-part (64 chars) | 64-char local + `@example.test`            | Accepted (RFC 5321 conformant)                                   |
+| EC-EMAIL-11 — Local-part = 65 chars     | 65-char local + `@example.test`            | Rejected or accepted — flag                                      |
+| EC-EMAIL-12 — Total length = 254 chars  | pad domain to hit 254                      | Accepted (RFC 5321 max)                                          |
+| EC-EMAIL-13 — Total length = 255 chars  | pad domain to hit 255                      | Rejected or accepted — flag                                      |
+
+> **Note on HTML5 validation**: `required` is NOT set on `#qa-input-email`. The `type="email"` attribute triggers browser format hints but these are not reliable oracles for E2E assertions. Test by observing: (a) absence of navigation, (b) presence of a visible UI error message, (c) the URL does NOT change to `/payment/`.
+
+### 3.3 `location` (radio)
+
+| Class    | Value              | Notes                                                                                                     |
+| -------- | ------------------ | --------------------------------------------------------------------------------------------------------- |
+| EC-LOC-1 | `NL` (Netherlands) | Only option currently exposed on landing; pre-checked. Flag: if more locations appear, new EC row needed. |
+
+### 3.4 `currency_code` (radio)
+
+| Class    | Value | Notes                                        |
+| -------- | ----- | -------------------------------------------- |
+| EC-CUR-1 | `RUB` | Only option exposed on landing; pre-checked. |
+
+### 3.5 Payment method (next page — inferred)
+
+| Class    | Method                         | Mandatory coverage                                 |
+| -------- | ------------------------------ | -------------------------------------------------- |
+| EC-PAY-1 | Card (Visa/MC/Mir)             | Yes                                                |
+| EC-PAY-2 | Cryptocurrency                 | Yes — explicitly required by assignment            |
+| EC-PAY-3 | SBP / Fast Payment System      | Assumed present (common RU market); flag if absent |
+| EC-PAY-4 | Digital wallet (e.g. YooMoney) | Assumed possible; flag if absent                   |
+
+> **Assumption A**: The payment-method page exposes at least Card and Crypto options. Exact method list requires live inspection (see §9).
+
+---
+
+## 4. Boundary values
+
+### 4.1 Email length (RFC 5321)
+
+| Dimension     | Boundary    | Value     | Class       |
+| ------------- | ----------- | --------- | ----------- |
+| Local-part    | Max allowed | 64 chars  | EC-EMAIL-10 |
+| Local-part    | Max + 1     | 65 chars  | EC-EMAIL-11 |
+| Total address | Max allowed | 254 chars | EC-EMAIL-12 |
+| Total address | Max + 1     | 255 chars | EC-EMAIL-13 |
+
+### 4.2 Plan period
+
+Discrete set of 3 values — no numeric range to sweep. Boundary analysis degenerates to full coverage of all 3 classes (EC-PLAN-1 through EC-PLAN-3) plus one tampered value (EC-PLAN-INV). No additional boundary rows are meaningful.
+
+### 4.3 Pricing oracle (use to assert amount on payment page)
+
+| Plan      | Expected displayed amount |
+| --------- | ------------------------- |
+| `2_days`  | 49.99 ₽                   |
+| `1_month` | 499 ₽                     |
+| `1_year`  | 2990 ₽                    |
+
+These values must be visible on the payment page (or payment-method confirmation step). A mismatch is a P0 finding.
+
+---
+
+## 5. Decision table — plan × payment method × email validity
+
+Columns: `offer_id` | `paymentMethod` | `emailValid` | Expected outcome
+
+| #   | offer_id  | paymentMethod | emailValid             | Expected outcome                                                        |
+| --- | --------- | ------------- | ---------------------- | ----------------------------------------------------------------------- |
+| D1  | `2_days`  | Card          | true                   | Payment page loads; URL matches card-provider pattern; amount = 49.99 ₽ |
+| D2  | `1_month` | Card          | true                   | Payment page loads; amount = 499 ₽                                      |
+| D3  | `1_year`  | Card          | true                   | Payment page loads; amount = 2990 ₽                                     |
+| D4  | `2_days`  | Crypto        | true                   | Crypto payment page loads; amount = 49.99 ₽ in RUB equivalent           |
+| D5  | `1_month` | Crypto        | true                   | Crypto payment page loads; amount = 499 ₽                               |
+| D6  | `1_year`  | Crypto        | true                   | Crypto payment page loads; amount = 2990 ₽                              |
+| D7  | `1_month` | SBP/Other     | true                   | Payment page loads for that method; amount = 499 ₽ (if method exists)   |
+| D8  | any       | any           | false (empty)          | No navigation; validation error visible                                 |
+| D9  | any       | any           | false (bad format)     | No navigation; validation error visible                                 |
+| D10 | `1_year`  | Card          | true (XSS probe email) | Payment page loads; no script injection on any page in the flow         |
+
+> Rows D1–D7 are collapsible where plan and method are independent (no cross-effect expected). D4–D6 are the mandatory crypto rows. D8–D9 cover all plan combinations — one representative row per validation class is sufficient.
+
+---
+
+## 6. State transitions table
+
+| From state        | Trigger                                   | Guard                                                            | To state                        | Negative branch                  |
+| ----------------- | ----------------------------------------- | ---------------------------------------------------------------- | ------------------------------- | -------------------------------- |
+| Home              | Page loads                                | —                                                                | PlanSelected (default = 2_days) | Page fails to load → 5xx finding |
+| PlanSelected      | Click different plan card                 | Plan radio `#qa-radio-offer-1-month` or `#qa-radio-offer-1-year` | PlanUpdated                     | Radio non-functional → finding   |
+| PlanUpdated       | —                                         | —                                                                | EmailEntry ready                | —                                |
+| EmailEntry        | Type valid email                          | `type="email"` passes                                            | EmailEntered                    | —                                |
+| EmailEntered      | Click "Оплатить" (`#qa-btn-submit-step1`) | email non-empty, format valid                                    | PaymentMethodPage               | Invalid email → ValidationError  |
+| EmailEntered      | Click "Оплатить"                          | email empty                                                      | ValidationError                 | —                                |
+| ValidationError   | Fix email                                 | Valid format entered                                             | EmailEntered                    | —                                |
+| PaymentMethodPage | Select Card method                        | method radio/button present                                      | PaymentPage (card provider)     | Method absent → finding          |
+| PaymentMethodPage | Select Crypto method                      | crypto option present                                            | PaymentPage (crypto provider)   | Crypto absent → P0 finding       |
+| PaymentMethodPage | Click browser back                        | —                                                                | Home (form pre-filled)          | State lost → finding             |
+| PaymentPage       | —                                         | STOP BOUNDARY                                                    | [END TEST]                      | Error banner visible → finding   |
+
+---
+
+## 7. Negative paths
+
+Listed in risk order (P0 first):
+
+**N1 — Empty email submit** (P0)
+
+- Action: Leave `#qa-input-email` empty, click `#qa-btn-submit-step1`.
+- Oracle: URL does not change to `/payment/`; a visible error message appears OR the button is disabled OR the field is highlighted. No navigation must occur.
+- Tags: `@ru`, `@smoke`
+
+**N2 — Invalid email format: missing `@`** (P0)
+
+- Action: Enter `userexample.test`, submit.
+- Oracle: Same as N1.
+
+**N3 — Invalid email format: missing domain** (P1)
+
+- Action: Enter `user@`, submit.
+- Oracle: No navigation; UI error.
+
+**N4 — Invalid email format: leading `@`** (P1)
+
+- Action: Enter `@example.test`, submit.
+- Oracle: No navigation; UI error.
+
+**N5 — Space in local-part** (P1)
+
+- Action: Enter `foo bar@example.test`, submit.
+- Oracle: No navigation; UI error.
+
+**N6 — Cyrillic local-part (IDN)** (P1)
+
+- Action: Enter `пользователь@example.test`, submit.
+- Oracle: Accepted or rejected with a clear UI message. Flag the result — both outcomes are testable truths for a RU-locale site. No crash or unhandled exception.
+
+**N7 — XSS probe in email** (P1)
+
+- Action: Enter `<script>alert(1)</script>@example.test`, submit.
+- Oracle: (a) Form may or may not navigate — either is valid. (b) On the payment-method page, the email value rendered in the DOM must NOT execute as script. Assert `page.evaluate(() => window._xss_probe)` is undefined, or assert the raw text `<script>` appears escaped in any visible element.
+
+**N8 — Double-click "Оплатить"** (P1)
+
+- Action: Click `#qa-btn-submit-step1` twice in rapid succession.
+- Oracle: Exactly one navigation occurs. No duplicate order or duplicate form submission error on the next page.
+
+**N9 — Switch plan after entering email** (P1)
+
+- Action: Enter valid email, then change plan from `2_days` to `1_year`, then submit.
+- Oracle: Payment-method page reflects the new plan (`1_year`). Email is preserved in the GET query string.
+
+**N10 — Browser back from payment-method page** (P1)
+
+- Action: Submit form → land on payment-method page → click browser back.
+- Oracle: Home page is displayed; `#qa-input-email` retains the previously entered email; the plan radio retains the prior selection (or browser default — flag if state is lost as a UX finding).
+
+**N11 — Network error / 4xx on `/payment/`** (P2)
+
+- Action: Simulate network failure (Playwright `page.route` to abort `/payment/`) then submit.
+- Oracle: A non-fatal error UX is displayed (error banner, or safe page). No unhandled JS exception. No blank white screen with no user guidance.
+- Note: Per CONSTRAINTS §3, treat any 4xx/5xx as a real finding, quarantine with `test.fixme` + ticket ref.
+
+**N12 — Tampered hidden `gateway` value** (P2)
+
+- Action: Before form submit, use `page.evaluate` to set `document.querySelector('[name=gateway]').value = 'invalid_gateway_xyz'`, then submit.
+- Oracle: Server returns an error response or redirects to a safe error page. Assert no silent acceptance.
+
+**N13 — Disable JS** (P2)
+
+- Action: Launch browser with JS disabled; navigate to landing.
+- Oracle: Form is still present (it's `method=GET`). Submit behaviour with JS disabled: either navigates (if pure HTML) or shows a graceful degradation message. Flag result — the CSRF-like `ppg_nonce_1` hidden field may break server validation without JS. Document finding without asserting a specific outcome.
+
+**N14 — Email max-length boundary (64 local-part chars)** (P2)
+
+- Action: Enter 64-char local-part + `@example.test`.
+- Oracle: Accepted; form submits; payment-method page loads.
+
+**N15 — Email local-part 65 chars** (P2)
+
+- Action: Enter 65-char local-part + `@example.test`.
+- Oracle: Rejected with visible error OR accepted (flag whichever — RFC non-compliance is a finding).
+
+---
+
+## 8. Out of scope
+
+The following items are explicitly excluded. Downstream skill `gherkin-test-case-author` MUST NOT generate cases for these.
+
+- Real payment execution of any kind (card submit, crypto TX hash, Apple Pay sheet action)
+- 3DS / OTP handling
+- Crypto wallet authentication or address validation
+- Telegram-bot purchase channel (`t.me/Planet_Vpn_Key_Bot`) — alternate channel, not web E2E
+- VPN config delivery email (post-payment)
+- Account creation, login, session management
+- SBP confirmation flow inside the banking app (the STOP boundary is the SBP redirect, not the bank app)
+- Admin/backend validation of gateway or nonce fields beyond observable UI behaviour
+- Load / performance testing
+- Accessibility (WCAG) — not in assignment scope
+- Mobile app flows
+
+---
+
+## 9. Open questions and assumptions
+
+| #                | Question / Assumption                                                                                                                                                             | Impact if wrong                                                                       |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---- | ------------------------------ |
+| OQ-1             | **Payment method list on `/payment/` is unknown** (page not directly inspectable). Assumed: Card, Crypto, possibly SBP/YooMoney.                                                  | If crypto is absent → P0 blocker; report as finding                                   |
+| OQ-2             | **Terms-of-Service checkbox**: Site A (freevpnplanet.com) has a ToS checkbox. Does `/payment/` page also require checkbox acceptance before method selection?                     | If yes, add TC: assert checkbox present; assert method buttons disabled until checked |
+| OQ-3             | **`location` field**: Only `NL` exposed on landing. Are other locations available via URL param or a hidden UI element?                                                           | If yes → new EC-LOC rows needed                                                       |
+| OQ-4             | **`currency_code`**: Only `RUB` on landing. Same question.                                                                                                                        | If yes → new EC-CUR rows needed                                                       |
+| OQ-5             | **Is there a phone-number field** on the payment-method page? The landing only has email.                                                                                         | If yes → additional EC/BV rows for phone                                              |
+| OQ-6             | **Crypto provider identity**: Which provider handles crypto (Cryptomus? CoinPayments? BitPay?)? This determines the URL pattern assertion at STOP boundary.                       | If unknown, assert generic pattern `/.\*(crypto                                       | coin | pay).\*/i` and flag for update |
+| OQ-7             | **Email display on payment-method page**: Is the entered email echoed back in the UI (for XSS N7 oracle)?                                                                         | If not echoed, N7 oracle needs adjustment                                             |
+| OQ-8             | **`ppg_nonce_1` lifetime**: Is this a session-scoped nonce? Can the same nonce be replayed? Relevant for N8 double-click test.                                                    | If nonce is single-use, second submission fails with a clear error — document         |
+| **Assumption A** | Payment-method page has at least Card and Crypto options                                                                                                                          | See OQ-1                                                                              |
+| **Assumption B** | The GET query string reaching `/payment/` carries `offer_id`, `email`, `currency_code`, `location`. The `gateway` field is empty on submit and is set on the payment-method page. | Affects TC design for back-navigation state checks                                    |
+| **Assumption C** | No login/account is required before purchase on this RU landing page                                                                                                              | If a login gate appears → Scenario A-style auth flow must precede Scenario B          |
+| **Assumption D** | Faker SEED=1234 deterministic email domain is `@example.test` per CONSTRAINTS §2.4                                                                                                | Hard constraint — do not deviate                                                      |
+
+---
+
+## 10. Risk-prioritised test-condition list
+
+| ID       | Description                                                                                                                                                             | Risk | Rationale                                                                                    | Smoke |
+| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------- | ----- |
+| TC-RU-01 | Open landing; assert 3 plan cards visible with correct prices (49.99 ₽ / 499 ₽ / 2990 ₽); assert form `#PPG` present                                                    | P0   | Entry condition for all other tests; if landing is broken nothing else runs                  | Yes   |
+| TC-RU-02 | Select `1_year`, enter valid synthetic email, click "Оплатить"; assert navigation to payment-method page (URL contains `/payment/`)                                     | P0   | Core happy path; most revenue-impactful plan                                                 | Yes   |
+| TC-RU-03 | On payment-method page, select **Crypto** method; assert navigation to crypto payment page (URL matches provider); assert displayed amount = 2990 ₽ (or RUB equivalent) | P0   | Crypto coverage is mandatory per assignment; highest-value plan maximises regression surface | Yes   |
+| TC-RU-04 | Select `1_month`, valid email, "Оплатить"; select **Card** method; assert payment page loads; assert amount = 499 ₽; assert no error banners                            | P0   | Card is primary payment method; mid-tier plan                                                | No    |
+| TC-RU-05 | Select `2_days`, valid email, "Оплатить"; select **Card** method; assert payment page loads; assert amount = 49.99 ₽                                                    | P0   | Trial plan path; separate pricing oracle check                                               | No    |
+| TC-RU-06 | Select **Crypto** with `1_month` plan; assert amount = 499 ₽ on crypto page                                                                                             | P0   | Cross-plan crypto coverage                                                                   | No    |
+| TC-RU-07 | Select **Crypto** with `2_days` plan; assert crypto page loads; assert amount = 49.99 ₽                                                                                 | P1   | Full crypto × plan matrix                                                                    | No    |
+| TC-RU-08 | Select SBP/Other method (if present); assert payment page loads for that method                                                                                         | P1   | Additional RU payment method — flag if absent                                                | No    |
+| TC-RU-09 | Empty email + click "Оплатить"; assert no navigation; assert visible error or button state                                                                              | P0   | Primary validation gate; prevents spurious orders                                            | No    |
+| TC-RU-10 | Invalid email (`foo`) + submit; assert no navigation; assert validation error                                                                                           | P1   | Client-side validation contract                                                              | No    |
+| TC-RU-11 | XSS probe email (`<script>alert(1)</script>@example.test`) through full flow; assert no script execution on any page                                                    | P1   | Security hygiene; RU locale sites are high-frequency attack targets                          | No    |
+| TC-RU-12 | Change plan after entering email; submit; assert correct plan reflected on payment-method page                                                                          | P1   | State mutation during form fill — common regression source                                   | No    |
+| TC-RU-13 | Browser back from payment-method page; assert form state preserved                                                                                                      | P1   | UX correctness; prevents user confusion and re-entry errors                                  | No    |
+| TC-RU-14 | Double-click "Оплатить"; assert single navigation / no duplicate submission error                                                                                       | P1   | Idempotency — duplicate orders are a billing risk                                            | No    |
+| TC-RU-15 | Cyrillic local-part email; assert graceful accept or reject (no crash)                                                                                                  | P1   | IDN edge case relevant specifically to RU locale                                             | No    |
+| TC-RU-16 | Network abort on `/payment/`; assert non-fatal error UX                                                                                                                 | P2   | Resilience; external site may be flaky                                                       | No    |
+| TC-RU-17 | Tampered `gateway` value; assert server rejects gracefully                                                                                                              | P2   | Security — prevents bypassing payment provider                                               | No    |
+| TC-RU-18 | Email local-part = 64 chars; assert accepted                                                                                                                            | P2   | RFC 5321 compliance boundary                                                                 | No    |
+| TC-RU-19 | Email local-part = 65 chars; assert result (flag compliance)                                                                                                            | P2   | RFC 5321 boundary + 1                                                                        | No    |
+| TC-RU-20 | Disable JS; assert form renders and submit behaviour is documented                                                                                                      | P2   | Progressive-enhancement audit; informational                                                 | No    |
+
+**Smoke suite** (3 conditions): TC-RU-01, TC-RU-02, TC-RU-03.
+All items tagged `@ru`. Smoke items also tagged `@smoke`.
+Crypto path (TC-RU-03, TC-RU-06, TC-RU-07) tagged additionally `@crypto`.
+
+---
+
+## Selector reference (stable QA hooks for downstream authoring)
+
+| Element            | Primary selector          | Fallback                                     |
+| ------------------ | ------------------------- | -------------------------------------------- |
+| Plan card: 2 days  | `#qa-radio-offer-2-days`  | `input[name="offer_id"][value="2_days"]`     |
+| Plan card: 1 month | `#qa-radio-offer-1-month` | `input[name="offer_id"][value="1_month"]`    |
+| Plan card: 1 year  | `#qa-radio-offer-1-year`  | `input[name="offer_id"][value="1_year"]`     |
+| Email input        | `#qa-input-email`         | `input[type="email"][name="email"]`          |
+| Submit button      | `#qa-btn-submit-step1`    | `button[type="submit"]:has-text("Оплатить")` |
+| Currency radio     | `#qa-radio-currency`      | `input[name="currency_code"][value="RUB"]`   |
+| Location radio     | `#qa-radio-location`      | `input[name="location"][value="NL"]`         |
+| Form               | `#PPG`                    | `form[action="/payment/"]`                   |
+
+> Payment-method page selectors are **unknown** pending live inspection (OQ-1). The `gherkin-test-case-author` skill must perform a read-only DOM inspection of the payment-method page before generating cases for TC-RU-03 through TC-RU-08.
+
+---
+
+_Next pipeline step_: `gherkin-test-case-author` — consumes this file and produces `.feature` files under `tests/scenarios/ru/`.
diff --git a/docs/test-design/signup-flow.md b/docs/test-design/signup-flow.md
new file mode 100644
index 0000000..ae16532
--- /dev/null
+++ b/docs/test-design/signup-flow.md
@@ -0,0 +1,391 @@
+# Test Design — Sign Up Flow (Scenario A, EN)
+
+> **Status**: Draft — awaiting downstream authoring by `gherkin-test-case-author` / `playwright-test-author-ui`.
+> **Last updated**: 2026-04-28
+> **Author agent**: `test-design-agent` (requirements-to-test-design skill)
+
+---
+
+## 1. Scope and links
+
+| Item                 | Value                                                         |
+| -------------------- | ------------------------------------------------------------- |
+| Source PRD           | `docs/test-Assignment.pdf` §"Проверка Sign Up"                |
+| Canonical scenario   | `docs/CONSTRAINTS.md` §5 Scenario A                           |
+| Entry URL            | `https://freevpnplanet.com/`                                  |
+| Login form URL       | `https://account.freevpnplanet.com/login/`                    |
+| Order/Sign-up URL    | `https://account.freevpnplanet.com/order/`                    |
+| Exit boundary (STOP) | Payment page opens — assert URL pattern and page markers only |
+| Locale               | EN (default)                                                  |
+| Test data            | Faker `SEED=1234`, email domain `@example.test`               |
+
+**In scope:**
+
+- Navigation from Home → Log In link → `/login/` page → Sign Up link → `/order/` page
+- Email field on `/order/` (Form 1, email step)
+- Plan period selector on `/order/`
+- Payment method selection on `/order/` (Form 2: Credit Card vs Cryptocurrency)
+- Terms-of-use checkbox on `/order/`
+- "Get your subscription" submit button behaviour and the resulting redirect
+- Asserting the payment URL is generated and a recognisable payment page opens
+- Negative and edge-case paths for all form fields
+
+**Out of scope (per CONSTRAINTS §2.3 and project decisions):**
+
+- Clicking any final "Pay" / "Submit payment" button on the payment gateway page
+- Filling card numbers, CVV, expiry — including Stripe test cards
+- Crypto wallet addresses, TX hash submission
+- OTP / 3DS / SCA challenges
+- Apple Pay / Google Pay sheets
+- Stripe iframe internals (rendered inside cross-origin frame)
+- Cryptomus / Paddle internal payment-page validation
+- Account-already-registered scenario (no backend access to clean up)
+- Email confirmation link / inbox verification
+- Password reset / forgot-password flow
+- Login flow correctness (Login page is a navigation step only; its own correctness is a separate scenario)
+- RU-locale variants (separate Scenario B/C)
+- Cookie / GDPR consent modal behaviour (environmental, not functional)
+- Accessibility audit (separate workstream)
+
+---
+
+## 2. State diagram
+
+```
+[Home]
+  │  User clicks "Log In" nav link
+  ▼
+[Login Page — /login/]
+  │  User clicks "Sign Up" link
+  ▼
+[Order Page — /order/ — Email Step (Form 1)]
+  │  Guard: email field contains a well-formed address
+  │  User clicks "Next"
+  ▼
+[Order Page — Plan Step]
+  │  Guard: plan period is selected (default "1 year" is pre-selected)
+  │  (Plan selection may be done before or after email step; selector is on the same page)
+  ▼
+[Order Page — Payment Method Step (Form 2)]
+  │  Guard: payment method chosen (Credit Card or Cryptocurrency)
+  │
+  ├─[Terms NOT accepted]──► button "Get your subscription" disabled / error displayed
+  │
+  │  Guard: Terms checkbox checked
+  ▼
+[Terms Accepted + Method Chosen]
+  │  User clicks "Get your subscription"
+  ▼
+[Payment Page — STOP]
+  Assert: URL matches known payment-provider pattern
+  Assert: Payment page DOM markers visible (amount, currency, order reference)
+  Assert: No error banner present
+```
+
+**Negative transitions (annotated on the same diagram):**
+
+- Email step "Next" with empty/invalid email → stays on email step, error displayed
+- "Get your subscription" with terms unchecked → button disabled or error
+- "Get your subscription" with no payment method selected → error displayed
+- Double-click "Get your subscription" → only one redirect (idempotency)
+- Network offline before click → error banner / graceful failure, no crash
+
+---
+
+## 3. Equivalence classes
+
+### 3.1 Email field (both `/login/` and `/order/` Form 1 — same validation rules assumed)
+
+| Field | Class ID | Valid / Invalid    | Representative value          | Notes                                                                           |
+| ----- | -------- | ------------------ | ----------------------------- | ------------------------------------------------------------------------------- |
+| Email | EC-E-01  | Valid              | `faker@example.test`          | Well-formed, standard TLD                                                       |
+| Email | EC-E-02  | Valid              | `user+tag@example.test`       | Plus-addressing (RFC 5321 compliant)                                            |
+| Email | EC-E-03  | Valid              | `a@b.test`                    | Minimal valid length                                                            |
+| Email | EC-E-04  | Valid (edge)       | `user@subdomain.example.test` | Subdomain in domain part                                                        |
+| Email | EC-E-05  | Valid (edge)       | `"quoted space"@example.test` | Quoted local-part (RFC 5321) — server may reject                                |
+| Email | EC-E-06  | Invalid            | `notanemail`                  | No `@` or domain                                                                |
+| Email | EC-E-07  | Invalid            | `user@@example.test`          | Double `@`                                                                      |
+| Email | EC-E-08  | Invalid            | `@example.test`               | Missing local part                                                              |
+| Email | EC-E-09  | Invalid            | `user@`                       | Missing domain                                                                  |
+| Email | EC-E-10  | Invalid            | ` user@example.test`          | Leading whitespace                                                              |
+| Email | EC-E-11  | Invalid            | `user@example.test `          | Trailing whitespace                                                             |
+| Email | EC-E-12  | Invalid            | `` (empty)                    | Empty field                                                                     |
+| Email | EC-E-13  | Invalid (boundary) | 255-char email string         | Exceeds RFC 5321 254-char max                                                   |
+| Email | EC-E-14  | Invalid            | `<script>@example.test`       | XSS payload in local-part                                                       |
+| Email | EC-E-15  | Valid (i18n)       | `用户@例子.test`              | Internationalised (IDN); server may accept or reject — observe actual behaviour |
+
+### 3.2 Password field (`/login/` only — Sign Up has no password field on `/order/`)
+
+| Field    | Class ID | Valid / Invalid   | Representative value                 | Notes                                    |
+| -------- | -------- | ----------------- | ------------------------------------ | ---------------------------------------- |
+| Password | EC-P-01  | Valid             | Faker-generated 12-char alphanumeric | Nominal valid                            |
+| Password | EC-P-02  | Invalid           | `` (empty)                           | Empty                                    |
+| Password | EC-P-03  | Invalid (assumed) | `abc` (3 chars)                      | Below assumed min of 8                   |
+| Password | EC-P-04  | Invalid (assumed) | `password`                           | Common weak password — server may reject |
+| Password | EC-P-05  | Valid (edge)      | 128-char string                      | At assumed max                           |
+| Password | EC-P-06  | Invalid (assumed) | 129-char string                      | Above assumed max                        |
+| Password | EC-P-07  | Valid (edge)      | Unicode glyphs `Пароль123!`          | Non-ASCII password                       |
+
+### 3.3 Plan period selector (`/order/`)
+
+| Field | Class ID | Valid / Invalid | Representative value | Notes                                          |
+| ----- | -------- | --------------- | -------------------- | ---------------------------------------------- |
+| Plan  | EC-PL-01 | Valid           | `1 year`             | Default; pre-selected                          |
+| Plan  | EC-PL-02 | Valid           | `1 month`            | Shorter period — inferred from site            |
+| Plan  | EC-PL-03 | Valid           | `2 days`             | Trial/short — inferred from RU sister site     |
+| Plan  | EC-PL-04 | Invalid         | No plan selected     | If selector can be cleared — observe behaviour |
+
+### 3.4 Payment method (`/order/` Form 2)
+
+| Field   | Class ID | Valid / Invalid | Representative value | Notes                                    |
+| ------- | -------- | --------------- | -------------------- | ---------------------------------------- |
+| Payment | EC-PM-01 | Valid           | Credit Card          | Standard button                          |
+| Payment | EC-PM-02 | Valid           | Cryptocurrency       | "Select cryptocurrency 16+" button       |
+| Payment | EC-PM-03 | Invalid         | Neither selected     | Neither button clicked; submit attempted |
+
+### 3.5 Terms checkbox (`/order/` Form 2)
+
+| Field    | Class ID | Valid / Invalid     | Representative value                  | Notes                       |
+| -------- | -------- | ------------------- | ------------------------------------- | --------------------------- |
+| Terms    | EC-TC-01 | Valid               | Checked                               | Prerequisite for submission |
+| EC-TC-02 | Invalid  | Unchecked (default) | Must prevent submission or show error |
+
+---
+
+## 4. Boundary values
+
+**Note:** HTML5 `required`, `minLength`, `maxLength`, and `pattern` attributes are absent on all observed fields. The boundaries below are inferred from RFC 5321 (email), common industry conventions (password), and inspection data (plan options). The downstream test author MUST verify each assumption against actual server behaviour.
+
+### 4.1 Email length (RFC 5321 max = 254 chars total)
+
+| Boundary | Value                                                                       | Expected                                 |
+| -------- | --------------------------------------------------------------------------- | ---------------------------------------- |
+| Min−1    | 0 chars (empty)                                                             | Validation error                         |
+| Min      | 1-char local + `@` + domain = shortest well-formed (~6 chars, e.g. `a@b.c`) | Likely accepted                          |
+| Nominal  | ~20 chars (Faker default)                                                   | Accepted                                 |
+| Max−1    | 253-char valid email                                                        | Accepted                                 |
+| Max      | 254-char valid email                                                        | Accepted (RFC limit)                     |
+| Max+1    | 255-char string                                                             | Expected rejection; observe actual error |
+
+### 4.2 Password length (ASSUMED: min=8, max=128 — see §9 open questions)
+
+| Boundary | Value     | Expected           |
+| -------- | --------- | ------------------ |
+| Min−1    | 7 chars   | Rejected (assumed) |
+| Min      | 8 chars   | Accepted (assumed) |
+| Min+1    | 9 chars   | Accepted           |
+| Nominal  | 12 chars  | Accepted           |
+| Max−1    | 127 chars | Accepted (assumed) |
+| Max      | 128 chars | Accepted (assumed) |
+| Max+1    | 129 chars | Rejected (assumed) |
+
+**Note:** Password field appears only on the `/login/` page (existing account login), not on `/order/`. The sign-up flow on `/order/` does NOT prompt for a password — the user receives credentials by another mechanism (email link or auto-generated password). This is flagged as assumption A-05 in §9.
+
+### 4.3 Plan period (inferred from inspection + RU sister site)
+
+| Boundary | Value          | Expected                        |
+| -------- | -------------- | ------------------------------- |
+| Shortest | 2 days (trial) | Accepted — maps to cheapest SKU |
+| Mid      | 1 month        | Accepted                        |
+| Longest  | 1 year         | Accepted — default              |
+
+**Note:** If the dropdown exposes raw period IDs or if additional options (3 months, 6 months) exist, boundaries expand. Flag any selector value not listed here.
+
+---
+
+## 5. Decision table — payment method × terms acceptance × email validity
+
+Inputs:
+
+- **PM** = paymentMethod ∈ {Credit Card (CC), Cryptocurrency (CR), None (N)}
+- **TC** = termsChecked ∈ {true (Y), false (N)}
+- **EV** = emailValid ∈ {true (Y), false (N)}
+
+| Rule | PM  | TC  | EV  | Button Enabled  | Redirect                   | Error shown                                  |
+| ---- | --- | --- | --- | --------------- | -------------------------- | -------------------------------------------- |
+| R01  | CC  | Y   | Y   | YES             | Payment page (Stripe-like) | No                                           |
+| R02  | CR  | Y   | Y   | YES             | Payment page (Crypto)      | No                                           |
+| R03  | N   | Y   | Y   | NO or disabled  | No                         | Method-required error                        |
+| R04  | CC  | N   | Y   | NO or disabled  | No                         | Terms-required error                         |
+| R05  | CR  | N   | Y   | NO or disabled  | No                         | Terms-required error                         |
+| R06  | N   | N   | Y   | NO              | No                         | Method + Terms errors                        |
+| R07  | CC  | Y   | N   | Depends on step | No                         | Email-invalid error (Form 1 blocks progress) |
+| R08  | CR  | Y   | N   | Depends on step | No                         | Email-invalid error (Form 1 blocks progress) |
+| R09  | N   | Y   | N   | NO              | No                         | Email-invalid + method errors                |
+| R10  | CC  | N   | N   | NO              | No                         | Email-invalid + terms errors                 |
+| R11  | CR  | N   | N   | NO              | No                         | Email-invalid + terms errors                 |
+| R12  | N   | N   | N   | NO              | No                         | All three error conditions                   |
+
+**Collapsed / notes:**
+
+- R07/R08 collapse to "Form 1 prevents reaching Form 2 when email is invalid." The button state for Form 2 is moot because the user cannot advance past "Next". Treat R07-R12 as a single category: "invalid email blocks the entire flow before payment method is even choosable."
+- R03/R04/R05/R06: the exact UI manifestation (button disabled vs click produces inline error) is unknown and must be observed. The oracle records the actual behaviour on first run.
+- R01/R02 are the primary happy-path rules and must be smoke-tagged.
+
+---
+
+## 6. State transitions table
+
+| From State                      | Trigger                           | Guard                                     | To State                       | Negative Branch                                      |
+| ------------------------------- | --------------------------------- | ----------------------------------------- | ------------------------------ | ---------------------------------------------------- |
+| Home                            | Click "Log In" nav link           | Link present and clickable                | Login Page (`/login/`)         | Link absent → test blocked, surface as finding       |
+| Login Page                      | Click "Sign Up" link              | Link present                              | Order Page (`/order/`)         | Link absent → test blocked                           |
+| Order Page — Email Step         | Type valid email; click "Next"    | Email passes client-side validation       | Order Page — Plan/Method Step  | Invalid email → error displayed, stays on email step |
+| Order Page — Email Step         | Click "Next" with empty email     | —                                         | Error state (same page)        | —                                                    |
+| Order Page — Plan Step          | Select plan from dropdown         | Dropdown available                        | Plan selected state            | Default pre-selected; if dropdown broken → surface   |
+| Order Page — Payment Step       | Click "Credit Card" button        | Form 2 rendered                           | CC selected state              | Button absent → surface                              |
+| Order Page — Payment Step       | Click "Select cryptocurrency 16+" | Form 2 rendered                           | Crypto selected state          | Button absent → surface                              |
+| Terms unchecked + method chosen | Check terms checkbox              | Checkbox interactive                      | Terms accepted state           | Checkbox unresponsive → surface                      |
+| Terms accepted + method chosen  | Click "Get your subscription"     | Terms checked, method chosen, email valid | Payment Page (STOP)            | Error banner → record, do not proceed                |
+| Terms NOT accepted              | Click "Get your subscription"     | —                                         | Error state or button disabled | Assert error / disabled state                        |
+| Payment Page                    | —                                 | —                                         | STOP — no further transitions  | —                                                    |
+
+---
+
+## 7. Negative paths
+
+**NP-01 — Invalid email format, Form 1**
+
+- Precondition: On `/order/`, Form 1 visible
+- Action: Enter `notanemail` in email field; click "Next"
+- Expected: Form 1 does not advance; inline error message appears near the email field
+- Oracle: `expect(page.getByRole('alert')).toBeVisible()` OR error text adjacent to email input is visible; URL remains `/order/`
+
+**NP-02 — Empty email field, Form 1**
+
+- Precondition: On `/order/`, Form 1 visible, email field empty
+- Action: Click "Next"
+- Expected: Error indicating email is required; no navigation
+- Oracle: Error element visible; URL still `/order/`
+
+**NP-03 — Email with leading/trailing whitespace**
+
+- Precondition: On `/order/`, Form 1
+- Action: Enter `user@example.test` (spaces both sides); click "Next"
+- Expected: Either stripped and accepted, or rejected with trim error. Record actual behaviour.
+- Oracle: Observe whether form advances; if rejected, record error text verbatim
+
+**NP-04 — Terms checkbox NOT accepted**
+
+- Precondition: On `/order/`, valid email entered and "Next" passed, payment method chosen (CC), terms checkbox unchecked
+- Action: Click "Get your subscription"
+- Expected: Submission blocked; error or disabled state
+- Oracle: `getByRole('button', { name: 'Get your subscription' })` is disabled OR error text near checkbox is visible; no navigation away from `/order/`
+
+**NP-05 — No payment method selected**
+
+- Precondition: On `/order/`, valid email, terms accepted, neither CC nor Crypto button clicked
+- Action: Click "Get your subscription"
+- Expected: Submission blocked; error message indicating payment method required
+- Oracle: Error visible; URL remains `/order/`
+
+**NP-06 — Double-click "Get your subscription" (idempotency)**
+
+- Precondition: On `/order/`, all fields valid, terms checked, method chosen
+- Action: Double-click "Get your subscription" rapidly
+- Expected: Single redirect to payment page; no duplicate order created (observable: one payment URL, no error)
+- Oracle: Assert final URL matches payment pattern exactly once; assert no duplicate-order error banner
+
+**NP-07 — Back button after advancing to payment page**
+
+- Precondition: Happy path completed, payment page reached
+- Action: Press browser back button
+- Expected: Returns to `/order/` OR a confirmation/warning dialog. Observe actual behaviour.
+- Oracle: URL is `/order/` or an intermediate page; no crash; form state is observable
+
+**NP-08 — Network offline at click of "Get your subscription"**
+
+- Precondition: All fields valid, terms checked, method chosen; simulate offline via `context.setOffline(true)` before click
+- Action: Click "Get your subscription"
+- Expected: Graceful error (network-error banner, no white screen/JS crash)
+- Oracle: An error indicator is visible; no unhandled exception in console (collect via `page.on('pageerror')`)
+
+**NP-09 — Very long email input (255+ chars)**
+
+- Precondition: On `/order/`, Form 1
+- Action: Enter a 260-char syntactically-valid-looking email string in the email field; click "Next"
+- Expected: Rejection with error message; no server 5xx
+- Oracle: Error visible OR form does not advance; no `console.error` HTTP 500 logged
+
+**NP-10 — XSS payload in email field**
+
+- Precondition: On `/order/`, Form 1
+- Action: Enter `<script>alert(1)</script>@example.test` in email field; click "Next"
+- Expected: Input is sanitised — either rejected by validation or rendered as literal text (no JS execution)
+- Oracle: No `alert` dialog observed; error message (if shown) renders payload as escaped text; `page.on('dialog')` listener reports no unexpected dialogs
+
+**NP-11 — Email already registered (observable variant)**
+
+- Precondition: Attempt sign-up with an email that the server may consider already registered
+- Action: Complete Form 1 with a plausibly already-registered email (if detectable without real accounts)
+- Expected: Error message "email already in use" or equivalent, or redirect to login
+- Oracle: Observe and record response; this test is informational — exact assertion TBD (see §9 A-08)
+
+---
+
+## 8. Out of scope (explicit)
+
+- Clicking the final "Pay" / "Confirm payment" button on any payment gateway page
+- Filling card number, expiry, CVV — including Stripe test card numbers
+- OTP, 3DS / SCA authentication challenges
+- Crypto wallet address submission, TX hash upload
+- Apple Pay / Google Pay modal sheet behaviour
+- Stripe iframe internals (cross-origin, not inspectable)
+- Cryptomus / Paddle internal payment-page field validation
+- Real personal data in any form field
+- Account-already-registered cleanup via API (no backend access — see NP-11 caveat)
+- Email confirmation / magic-link inbox verification
+- Password reset / "Forgot password" flow
+- Login form correctness beyond using it as a navigation step
+- RU-locale variants of the sign-up flow (Scenarios B and C)
+- Cookie/GDPR consent modal (environmental noise, not functional)
+- Accessibility (WCAG audit — separate workstream)
+- Performance / load testing
+- OpenAPI / contract testing (CONSTRAINTS §2.1 — disabled for this project)
+
+---
+
+## 9. Open questions / assumptions for the test author
+
+| ID   | Assumption / Open question                                                                                                                                                                                                                                                  | Impact if wrong                                                                          |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| A-01 | Password minimum length is **8 characters**. Not stated in HTML attrs or PRD.                                                                                                                                                                                               | Boundary tests for password (EC-P-03, BV-P) may give false positives/negatives           |
+| A-02 | Password maximum length is **128 characters**. Industry default assumed.                                                                                                                                                                                                    | BV-P max/max+1 boundary tests may be inaccurate                                          |
+| A-03 | The `/order/` page plan dropdown includes **"2 days"** and **"1 month"** in addition to the default **"1 year"** (inferred from RU sister site). The EN locale may differ.                                                                                                  | EC-PL-02 / EC-PL-03 tests will fail if options are absent; update equivalence classes    |
+| A-04 | Validation on the email and password fields is **client-side JS or server-side** (HTML5 attrs absent). Error UI must be observed and recorded on first run; do not assume browser-native popup.                                                                             | Oracle assertions must use observed selectors, not `page.evaluate` on HTML5 validity API |
+| A-05 | The `/order/` sign-up flow **does NOT present a password field** — the user receives account credentials by email or auto-generated link. If a password field appears, re-scope accordingly.                                                                                | Password BV tests become in-scope for sign-up, not just login                            |
+| A-06 | The "Get your subscription" button is **disabled** when terms are unchecked (NP-04). Alternatively, the button is enabled but produces an inline error on click. The test author must observe actual behaviour on the first exploratory run and set the oracle accordingly. | NP-04 oracle may need adjustment                                                         |
+| A-07 | Both payment-method buttons ("Credit Card" and "Select cryptocurrency 16+") lead to **distinct payment provider URLs** (e.g. Stripe vs Cryptomus). The URL-pattern assertions for each must be confirmed on first run.                                                      | R01 and R02 URL-pattern assertions must be calibrated                                    |
+| A-08 | Testing "email already registered" is **deferred** because no backend exists to create or clean test accounts. If a pre-registered test email is ever provided, NP-11 can be promoted to a full assertion.                                                                  | NP-11 remains informational only                                                         |
+| A-09 | The form uses **method=GET** on `/login/` (observed). The `/order/` form submit mechanism (GET/POST/XHR) is not confirmed — affects whether URL parameters leak email on redirect. Inspect during first run.                                                                | Privacy/security observation, not a blocker                                              |
+| A-10 | Locale is fixed at **EN** for this scenario. The locale switcher is present on `/order/` but must NOT be interacted with during these tests.                                                                                                                                | Accidentally switching locale would invalidate selector text matching                    |
+| A-11 | The payment page URL pattern includes domains such as `*.stripe.com`, `*.cryptomus.com`, or a redirect via `account.freevpnplanet.com`. Exact patterns must be confirmed on first successful run and locked into `expect(page.url()).toMatch(/pattern/)`.                   | Without calibration, URL assertion is too loose and may pass on error pages              |
+
+---
+
+## 10. Risk-prioritised test-condition list
+
+| ID    | Description                                                                                                                                           | Risk   | Why                                                                         | Smoke |
+| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------- | ----- |
+| TC-01 | Happy path — Credit Card: Home → Login → Sign Up → valid email → 1-year plan → CC → accept terms → "Get your subscription" → assert payment URL opens | HIGH   | Core revenue path; if this breaks, no user can purchase                     | YES   |
+| TC-02 | Happy path — Cryptocurrency: same as TC-01 but choose "Select cryptocurrency 16+"                                                                     | HIGH   | Second primary payment path; crypto users represent distinct segment        | YES   |
+| TC-03 | Terms checkbox bypass — attempt submit with terms unchecked                                                                                           | HIGH   | Legal/compliance risk if terms can be skipped; also regression risk         | YES   |
+| TC-04 | Email validation — invalid format blocked at Form 1 "Next"                                                                                            | HIGH   | Broken email allows orphaned accounts, downstream failures                  | NO    |
+| TC-05 | Payment URL integrity — assert URL contains expected provider domain and non-empty order/amount params                                                | HIGH   | Open-redirect or wrong-page risk — user could land on a phishing/wrong page | NO    |
+| TC-06 | Empty email field — "Next" is blocked with error                                                                                                      | MEDIUM | UX correctness; also guards against server receiving empty strings          | NO    |
+| TC-07 | No payment method selected — "Get your subscription" blocked                                                                                          | MEDIUM | Form completeness guard                                                     | NO    |
+| TC-08 | Double-click idempotency — single order created                                                                                                       | MEDIUM | Duplicate-charge risk for users; financial impact                           | NO    |
+| TC-09 | XSS payload in email field — sanitised, no script execution                                                                                           | MEDIUM | Security hygiene; third-party site but reflects on QA coverage              | NO    |
+| TC-10 | Very long email (255+ chars) — rejected gracefully, no 5xx                                                                                            | MEDIUM | Input robustness; protects against server errors surfacing to users         | NO    |
+| TC-11 | Network offline during submit — graceful error, no crash                                                                                              | MEDIUM | Resilience on flaky connections; relevant for VPN product's audience        | NO    |
+| TC-12 | Plan period switching — 1 month plan reaches payment page                                                                                             | LOW    | Different SKU IDs may break payment URL params                              | NO    |
+| TC-13 | Back button after reaching payment page — no crash, state observable                                                                                  | LOW    | Browser navigation robustness                                               | NO    |
+| TC-14 | Trailing/leading whitespace in email — trimmed or clearly rejected                                                                                    | LOW    | UX polish; edge-case users copy-paste emails                                | NO    |
+| TC-15 | Internationalised (IDN) email — server accepts or rejects without crash                                                                               | LOW    | Niche audience; useful for robustness signal                                | NO    |
+
+**Smoke set (≤ 3 conditions blocking merge):** TC-01, TC-02, TC-03.
+Rationale: TC-01 and TC-02 prove both payment paths are reachable. TC-03 proves the legal gate cannot be bypassed. All three must pass before any PR merges.
+
+---
+
+_End of design document. Hand off to `gherkin-test-case-author` for test case authoring, then to `playwright-test-author-ui` for implementation._
diff --git a/docs/ux-findings.md b/docs/ux-findings.md
index 75cb436..250d5b7 100644
--- a/docs/ux-findings.md
+++ b/docs/ux-findings.md
@@ -5,6 +5,7 @@
 > которыми вы столкнулись в сопроводительном файле Google Document».
 >
 > Этот файл содержит находки, собранные с помощью:
+>
 > 1. Read-only инспекции DOM всех трёх сайтов через Playwright MCP.
 > 2. Программной воспроизводимости поведения UX и валидации.
 > 3. Реальных прогонов тестов с полными trace / скриншотами / видео в `test-results/`.
@@ -28,6 +29,7 @@
 **Критичность:** **High** — форма блокирует валидных пользователей (см. A-3), но пропускает мусор.
 
 **Шаги воспроизведения.**
+
 1. Открыть `https://account.freevpnplanet.com/order/`.
 2. Ввести `not-an-email-3` (без `@`) в поле Email.
 3. Снять фокус (Tab / blur).
@@ -46,6 +48,7 @@
 **Критичность:** Medium — ломает менеджеры паролей, плагины автозаполнения и инструменты доступности, которые имитируют ввод через DOM-мутации.
 
 **Шаги воспроизведения.**
+
 1. Открыть `https://account.freevpnplanet.com/order/`.
 2. В консоли DevTools:
    ```js
@@ -59,6 +62,7 @@
 **Что не так.** Vue-биндинг `v-model.lazy` (или эквивалентный кастомный) слушает только `change`/`blur`, но не `input`. Браузерные расширения-менеджеры паролей (1Password, Bitwarden, KeePassXC) обычно ставят `value` напрямую и отправляют только `input` — они **не** отправляют `change`. В итоге автозаполнение у этих пользователей молча не срабатывает.
 
 **Рекомендация.** Один из вариантов:
+
 - Перенести биндинг с `change` на `input`, ИЛИ
 - Внутри компонента после каждого `input` отправлять синтетический `change`, ИЛИ
 - Использовать паттерн с нативным сеттером `HTMLInputElement.prototype.value`, который применяют библиотеки React/Vue.
@@ -72,6 +76,7 @@
 **Критичность:** Medium — testId и видимый текст рассинхронизированы; что-то одно неверно.
 
 **Шаги воспроизведения.**
+
 1. Открыть `/order/`.
 2. Кликнуть на дропдаун плана.
 3. Проинспектировать третью опцию в DevTools.
@@ -88,6 +93,7 @@
 **Критичность:** Medium — ломает автозаполнение менеджеров паролей, усложняет a11y-тестирование.
 
 **Шаги воспроизведения.**
+
 1. Открыть `/login/`. Проинспектировать email-инпут → например, `id="_pv4saabywtomk574hj26s"`.
 2. Жёсткая перезагрузка.
 3. Проинспектировать снова → другой ID, например `id="_53t5ufjzqkywhx97zcehp"`.
@@ -103,6 +109,7 @@
 **Критичность:** Medium — риск доступности + расширенная поверхность для регрессий.
 
 **Шаги воспроизведения.**
+
 1. Открыть `/order/`.
 2. Проинспектировать `#payment-checkbox`. У нативного чекбокса нулевая видимая площадь; видимая область клика — это кастомно стилизованная обёртка.
 
@@ -129,6 +136,7 @@
 **Критичность:** Medium для UX, High по влиянию на доверие пользователя.
 
 **Шаги воспроизведения.**
+
 1. Открыть `https://planetconfig.com/`.
 2. Выбрать любой план, ввести email с фейковым TLD или несуществующим доменом (например, `qa.bot.1@example.test` или `qa.bot.1@nonexistent-domain-xyz.com`).
 3. Нажать **Оплатить**, перейти на `/payment/`.
@@ -139,6 +147,7 @@
 **Что не так.** Клиентская валидация email на лендинге пермиссивна (принимает любую строку с `@` и точкой). Серверная валидация строгая (проверка MX-записи). Из-за рассинхрона пользователь с опечаткой в домене (`@gmial.com` вместо `@gmail.com`) проходит выбор шлюза, а в финале получает общую "Транзакция отклонена" без действий по восстановлению — он не понимает, списались ли деньги, почему отказ и в email ли проблема вообще.
 
 **Рекомендация.**
+
 - Валидировать домен email уже **на форме лендинга** (синхронно по blur, асинхронно с MX-проверкой при сабмите формы), показывать инлайн-ошибки прямо там. Не пускать пользователя дальше выбора шлюза при некорректном email.
 - На `/payment/failed/` показывать реальную причину человеческим языком и CTA "Попробовать с другим email".
 
@@ -151,6 +160,7 @@
 **Критичность:** **High** относительно продуктового предложения — и прямое противоречие тексту тестового задания.
 
 **Шаги воспроизведения.**
+
 1. Открыть `https://planetconfig.com/`.
 2. Выбрать любой план + email, нажать **Оплатить**.
 3. Перейти на `/payment/`. Проинспектировать радио `name="gateway"`.
@@ -169,6 +179,7 @@
 **Критичность:** Low для UX, Medium по влиянию на аналитику.
 
 **Шаги воспроизведения.**
+
 1. Зайти на `https://planetconfig.com/payment/` напрямую (без referrer).
 2. Браузер редиректит на `/order/`, который отдаёт 404 со страницей "Page not found | planetvpn personal".
 
@@ -183,6 +194,7 @@
 **Критичность:** Low — но code-smell, требующий ревью.
 
 **Шаги воспроизведения.**
+
 1. Открыть `/payment/`.
 2. Проинспектировать радио для шлюза СБП: `<input type="radio" name="gateway" value="1Payment?i=4" id="qa-radio-gateway-fast-payments">`.
 
@@ -233,6 +245,7 @@
 **Критичность:** Medium — путь молчаливого отказа.
 
 **Шаги воспроизведения.**
+
 1. Открыть `/payment/` на сайте C (любой план).
 2. Не выбирая конкретную криптовалюту из дропдауна, нажать **Pay**.
 3. Наблюдение: ничего видимо не происходит — ни ошибки, ни перехода.
@@ -240,6 +253,7 @@
 **Что не так.** `<input type="radio" name="gateway" value="">` стоит рядом с кнопкой `Select cryptocurrency`. Пока пользователь не нажал на кнопку и не выбрал монету, value пустой. Сабмит формы с `gateway=""` — это тихий no-op, и кнопка Pay выглядит сломанной.
 
 **Рекомендация.** Один из вариантов:
+
 - Дизаблить кнопку Pay, пока крипто-монета не выбрана, при активном крипто-методе, ИЛИ
 - Показывать инлайн-ошибку при сабмите ("Please choose a cryptocurrency"), ИЛИ
 - По умолчанию выбирать самую распространённую монету (например, BTC), чтобы у сабмита всегда было значение.
@@ -276,18 +290,18 @@
 
 ## Соответствие находок результатам тестов
 
-| Находка | Тестовый артефакт |
-|---|---|
-| A-1 пермиссивный email | Негативный тест намеренно удалён, потому что утверждение "Next disabled" падало бы; задокументировано инлайн-комментарием. |
-| A-2 реактивность на input | `tests/pages/SignupPage.ts#fillEmail` обходит это программно. |
-| A-3 рассинхрон testId `3_years` | `tests/pages/SignupPage.ts` использует `'3_years'` как тип, тогда как текст в дропдауне — `"4 years"`. |
-| A-5, B-5 скрытые радио | Все page object'ы используют программный `evaluate` для установки `checked = true`, потому что `force: true` оказался недостаточен. |
-| B-1 отсутствие крипты | `tests/specs/purchase/personal-vpn-ru.spec.ts` содержит `test.fixme` со ссылкой на эту находку. |
-| B-2 404 на `/payment/` | `PaymentMethodsPage.url` задокументирован как state-зависимый URL. |
-| C-2 пустое значение крипты | `PaymentMethodsPage.selectCrypto(coinId)` сделан намеренно составным действием, потому что сабмит без выбора монеты — тихий no-op. |
+| Находка                         | Тестовый артефакт                                                                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| A-1 пермиссивный email          | Негативный тест намеренно удалён, потому что утверждение "Next disabled" падало бы; задокументировано инлайн-комментарием.          |
+| A-2 реактивность на input       | `tests/pages/SignupPage.ts#fillEmail` обходит это программно.                                                                       |
+| A-3 рассинхрон testId `3_years` | `tests/pages/SignupPage.ts` использует `'3_years'` как тип, тогда как текст в дропдауне — `"4 years"`.                              |
+| A-5, B-5 скрытые радио          | Все page object'ы используют программный `evaluate` для установки `checked = true`, потому что `force: true` оказался недостаточен. |
+| B-1 отсутствие крипты           | `tests/specs/purchase/personal-vpn-ru.spec.ts` содержит `test.fixme` со ссылкой на эту находку.                                     |
+| B-2 404 на `/payment/`          | `PaymentMethodsPage.url` задокументирован как state-зависимый URL.                                                                  |
+| C-2 пустое значение крипты      | `PaymentMethodsPage.selectCrypto(coinId)` сделан намеренно составным действием, потому что сабмит без выбора монеты — тихий no-op.  |
 
 ## Предлагаемые направления для следующего прохода (пока не подтверждены)
 
 Это наблюдения по ходу тестов, которые **могут** оказаться дополнительными продуктовыми багами, но я ещё не подтвердил их в ручном debug-проходе.
 
-- **Флоу покупки на B/C не редиректит после клика Pay в headless Chromium.** Все 6 purchase-тестов падают на проверке редиректа после `/payment/`. Возможные причины: (а) реальный баг, всплывающий только при определённых паттернах сабмита, (б) побочный эффект программного `acceptTerms()`, задевающего другие чекбоксы, (в) недостающее событие на радио шлюза. 5 минут ручного MCP-прогона должны это развести.
\ No newline at end of file
+- **Флоу покупки на B/C не редиректит после клика Pay в headless Chromium.** Все 6 purchase-тестов падают на проверке редиректа после `/payment/`. Возможные причины: (а) реальный баг, всплывающий только при определённых паттернах сабмита, (б) побочный эффект программного `acceptTerms()`, задевающего другие чекбоксы, (в) недостающее событие на радио шлюза. 5 минут ручного MCP-прогона должны это развести.
diff --git a/package.json b/package.json
index e4dc833..b4c3299 100644
--- a/package.json
+++ b/package.json
@@ -1,8 +1,8 @@
 {
-  "name": "sdet-playwright-project",
+  "name": "free-vpn-planet-test",
   "version": "0.1.0",
   "private": true,
-  "description": "TypeScript + Playwright SDET project scaffolded with the SDET Claude Code kit.",
+  "description": "Black-box E2E suite (TypeScript + Playwright) for the Free VPN Planet purchase flows, built with an AI-assisted SDET workflow.",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -12,20 +12,17 @@
   "scripts": {
     "test": "playwright test",
     "test:smoke": "playwright test --grep @smoke",
-    "test:api": "playwright test --project=api",
     "test:ui": "playwright test --ui",
     "test:debug": "PWDEBUG=1 playwright test",
     "test:headed": "playwright test --headed",
     "report": "playwright show-report",
-    "spec:gen": "openapi-typescript specs/openapi.yaml -o tests/api/generated/schema.d.ts",
-    "spec:lint": "redocly lint specs/openapi.yaml",
-    "spec:sync": "npm run spec:lint && npm run spec:gen",
-    "lint": "eslint ",
-    "lint:fix": "eslint  --fix",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "format": "prettier --write \"**/*.{ts,js,json,md,yml,yaml}\"",
     "format:check": "prettier --check \"**/*.{ts,js,json,md,yml,yaml}\"",
     "typecheck": "tsc --noEmit",
-    "verify": "bash scripts/verify.sh || true",
+    "validate": "bash tools/validate-layout.sh && tsx tools/factory-rules.ts && tsx tools/fixture-rules.ts && tsx tools/lint-ui-spec.ts",
+    "verify": "bash tools/verify.sh || true",
     "prepare": "husky || true"
   },
   "lint-staged": {
diff --git a/scripts/README.md b/scripts/README.md
deleted file mode 100644
index 1f3168a..0000000
--- a/scripts/README.md
+++ /dev/null
@@ -1,120 +0,0 @@
-# SDET greenfield add-on
-
-Companion pack for `sdet-claude-code-kit`. Closes the gaps that surface on a brand-new TS+Playwright repository: missing `package.json`, no `tsconfig.json`, no ESLint, no `husky`, no CI, no env scaffold, no first-run guidance.
-
-> Use the main kit alone if you already have a TS+Playwright project. Use this add-on **on top of** it for greenfield repos.
-
-## Contents
-
-```
-sdet-greenfield-addon/
-├── README.md                       # this file
-├── docs/
-│   └── greenfield-checklist.md     # sprint-by-sprint adoption plan
-├── scripts/
-│   ├── init.sh                     # one-shot bootstrap (entry point)
-│   ├── apply-kit.sh                # copy the SDET kit if init.sh did not find it
-│   └── verify.sh                   # repo health check after init
-└── templates/
-    ├── root/                       # files for the repo root
-    │   ├── package.json            # minimal deps + scripts (test, lint, format, spec:sync)
-    │   ├── tsconfig.json           # strict + path aliases (@pages, @api, @fixtures, ...)
-    │   ├── eslint.config.mjs       # flat config with playwright + custom rules
-    │   ├── .prettierrc.json
-    │   ├── .env.example            # validated by tests/infra/env.ts
-    │   ├── .gitignore
-    │   ├── .editorconfig
-    │   ├── .nvmrc
-    │   └── STARTER.md              # what to do in your first 30 minutes
-    ├── vscode/
-    │   ├── extensions.json
-    │   └── settings.json
-    ├── husky/
-    │   ├── pre-commit              # lint-staged + UI spec lint + secret scan
-    │   └── commit-msg              # Conventional Commits enforce
-    └── github-workflows/
-        └── tests.yml               # CI: lint, typecheck, sharded Playwright, blob report merge
-```
-
-## Two-pack workflow
-
-```
-sdet-claude-code-kit/        # the brain — skills, agents, hooks, slash commands
-sdet-greenfield-addon/       # the body — package.json, tsconfig, eslint, husky, CI
-```
-
-Both are independent. The kit can be used in any TS+Playwright repo. The addon assumes you also use the kit, but it does not force it: every template is opt-in.
-
-## Quick start (greenfield)
-
-```bash
-# 1. Get both packs side-by-side
-unzip sdet-claude-code-kit.zip
-unzip sdet-greenfield-addon.zip
-
-# 2. Create your target repo
-mkdir my-tests && cd my-tests
-
-# 3. Bootstrap
-bash ../sdet-greenfield-addon/scripts/init.sh
-```
-
-`init.sh` performs:
-
-1. `git init` if missing.
-2. Copies templates (idempotent — keeps existing files).
-3. Discovers and copies the SDET kit.
-4. Disables the OpenAPI skill until you have a spec.
-5. Runs `npm install`.
-6. `npx playwright install chromium`.
-7. Sets up husky.
-8. Drops `STARTER.md` with next steps.
-
-Then:
-
-```bash
-npm run verify      # health check (green = ready)
-claude              # open in Claude Code
-```
-
-In Claude Code, your first message:
-
-> Scaffold the test framework folders.
-
-This triggers `playwright-framework-bootstrap` from the kit and creates the layered layout.
-
-## What the addon solves
-
-| Gap on greenfield | Addon answer |
-|---|---|
-| No `package.json` → `npm install` fails | `templates/root/package.json` |
-| No `tsconfig.json` → typecheck-touched hook errors | `templates/root/tsconfig.json` with paths |
-| No ESLint → no rule-based anti-pattern catch | `eslint.config.mjs` with playwright plugin + custom rules |
-| No env scaffolding → secrets leak risk | `.env.example` + `.gitignore` rules + scanner hook |
-| No husky → no pre-commit gates | `templates/husky/{pre-commit,commit-msg}` |
-| No CI → tests pass locally only | `templates/github-workflows/tests.yml` |
-| OpenAPI skill expects a spec → red on day 1 | `init.sh` flips `openapi.enabled = false` |
-| No "where do I start" doc | `STARTER.md` + `docs/greenfield-checklist.md` |
-| Health checks scattered | `scripts/verify.sh` |
-
-## Idempotency guarantees
-
-- `init.sh` never overwrites an existing file. It only creates missing ones.
-- `.gitignore` is merged (sorted, deduped) instead of overwritten.
-- Re-running `init.sh` is safe — it will skip already-present files and only do the missing steps.
-
-## Customising
-
-- Don't want husky? Comment out the corresponding block in `init.sh` or delete `.husky/` after init.
-- Want different ESLint rules? Edit `eslint.config.mjs` after init — the addon does not enforce updates.
-- Want a different CI provider? Replace `templates/github-workflows/tests.yml` with your own.
-
-## Limitations
-
-- Tested mentally, not on a live empty repo. First real run may surface tooling-version mismatches (npm 9 vs 10, Node 18 vs 20). Adjust `engines` in `package.json` if needed.
-- Husky 9 changed its API. Templates target husky 9; older versions won't work.
-- The CI workflow assumes GitHub Actions. Translate to GitLab/CircleCI manually.
-
-## License
-
-MIT.
diff --git a/scripts/apply-kit.sh b/scripts/apply-kit.sh
deleted file mode 100755
index e106ac6..0000000
--- a/scripts/apply-kit.sh
+++ /dev/null
@@ -1,43 +0,0 @@
-#!/usr/bin/env bash
-#
-# apply-kit.sh — copy the SDET Claude Code kit into the current repo.
-# Use this if init.sh did not find the kit automatically.
-#
-#   bash apply-kit.sh /path/to/sdet-claude-code-kit
-#
-set -euo pipefail
-
-KIT_DIR="${1:-}"
-if [[ -z "$KIT_DIR" || ! -d "$KIT_DIR/.claude/skills" ]]; then
-  echo "Usage: $0 /path/to/sdet-claude-code-kit"
-  echo "       (the directory must contain .claude/skills)"
-  exit 2
-fi
-
-echo "Copying kit from: $KIT_DIR"
-echo "Target:           $(pwd)"
-read -rp "Continue? [y/N] " ans
-[[ "${ans,,}" == "y" ]] || { echo "Aborted."; exit 0; }
-
-cp -nR "$KIT_DIR/.claude"          .claude
-cp -n  "$KIT_DIR/CLAUDE.md"        CLAUDE.md           2>/dev/null || true
-cp -n  "$KIT_DIR/tests-config.json" tests-config.json   2>/dev/null || true
-cp -n  "$KIT_DIR/README.md"        SDET_KIT_README.md   2>/dev/null || true
-
-# make scripts executable
-chmod +x .claude/hooks/*.sh                 2>/dev/null || true
-chmod +x .claude/skills/*/scripts/*.sh      2>/dev/null || true
-chmod +x .claude/skills/*/scripts/*.ts      2>/dev/null || true
-
-# disable openapi skill on greenfield
-if [[ -f "tests-config.json" ]] && command -v node >/dev/null 2>&1; then
-  node -e '
-    const fs=require("fs");
-    const p="tests-config.json"; const cfg=JSON.parse(fs.readFileSync(p,"utf8"));
-    cfg.openapi = cfg.openapi || {};
-    if (cfg.openapi.enabled === undefined) cfg.openapi.enabled = false;
-    fs.writeFileSync(p, JSON.stringify(cfg,null,2)+"\n");
-  '
-fi
-
-echo "Done."
diff --git a/scripts/init.sh b/scripts/init.sh
deleted file mode 100755
index 0730ff6..0000000
--- a/scripts/init.sh
+++ /dev/null
@@ -1,168 +0,0 @@
-#!/usr/bin/env bash
-#
-# init.sh — bootstrap a greenfield TS+Playwright SDET repository in the current directory.
-#
-# Run from the EMPTY (or near-empty) target repo:
-#   bash /path/to/sdet-greenfield-addon/scripts/init.sh
-# Or pipe:
-#   bash <(cat /path/to/sdet-greenfield-addon/scripts/init.sh)
-#
-# What it does (idempotent — re-running is safe):
-#   1. Confirms the target directory.
-#   2. Initialises git if missing (greenfield-friendly: husky needs a git repo).
-#   3. Copies/merges template files (package.json, tsconfig.json, eslint, .env.example, .gitignore, .vscode, .husky).
-#   4. Copies the SDET kit (.claude/, CLAUDE.md, tests-config.json) if available alongside this script.
-#   5. Sets the OpenAPI skill to "disabled" by default for greenfield (re-enable later via tests-config.json).
-#   6. Installs npm deps, runs Playwright browser install, sets up husky.
-#   7. Writes a STARTER.md with the next 5 commands you should run.
-#
-set -euo pipefail
-
-ADDON_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-TARGET_DIR="$(pwd)"
-KIT_DIR=""
-
-# Try to discover the companion kit (sdet-claude-code-kit/) sibling to this addon
-for candidate in \
-  "$ADDON_DIR/../sdet-claude-code-kit" \
-  "$ADDON_DIR/../sdet-claude-code-kit-main" \
-  "$HOME/sdet-claude-code-kit" \
-  "$HOME/Downloads/sdet-claude-code-kit"
-do
-  if [[ -d "$candidate/.claude/skills" ]]; then
-    KIT_DIR="$candidate"; break
-  fi
-done
-
-echo "===  SDET greenfield bootstrap"
-echo "Target:    $TARGET_DIR"
-echo "Addon:     $ADDON_DIR"
-echo "Kit:       ${KIT_DIR:-(not found — kit copy will be skipped; run apply-kit.sh later)}"
-echo
-
-read -rp "Continue? [y/N] " ans
-[[ "${ans,,}" == "y" ]] || { echo "Aborted."; exit 0; }
-
-# 1. git init
-if [[ ! -d ".git" ]]; then
-  echo "[1/7] git init"
-  git init -q
-  git checkout -b main 2>/dev/null || true
-fi
-
-# 2. copy templates (root)
-echo "[2/7] applying templates"
-copy_if_absent() {
-  local src="$1" dst="$2"
-  if [[ -e "$dst" ]]; then
-    echo "    keep   $dst (exists)"
-  else
-    cp "$src" "$dst"
-    echo "    write  $dst"
-  fi
-}
-
-copy_if_absent "$ADDON_DIR/templates/root/package.json"        package.json
-copy_if_absent "$ADDON_DIR/templates/root/tsconfig.json"       tsconfig.json
-copy_if_absent "$ADDON_DIR/templates/root/eslint.config.mjs"   eslint.config.mjs
-copy_if_absent "$ADDON_DIR/templates/root/.prettierrc.json"    .prettierrc.json
-copy_if_absent "$ADDON_DIR/templates/root/.env.example"        .env.example
-copy_if_absent "$ADDON_DIR/templates/root/.editorconfig"       .editorconfig
-copy_if_absent "$ADDON_DIR/templates/root/.nvmrc"              .nvmrc
-
-# .gitignore — merge instead of overwrite
-if [[ -f ".gitignore" ]]; then
-  cat "$ADDON_DIR/templates/root/.gitignore" >> .gitignore.tmp
-  cat .gitignore        >> .gitignore.tmp
-  sort -u .gitignore.tmp -o .gitignore
-  rm  .gitignore.tmp
-  echo "    merge  .gitignore"
-else
-  cp "$ADDON_DIR/templates/root/.gitignore" .gitignore
-  echo "    write  .gitignore"
-fi
-
-# .vscode (recommended extensions + settings)
-mkdir -p .vscode
-copy_if_absent "$ADDON_DIR/templates/vscode/extensions.json" .vscode/extensions.json
-copy_if_absent "$ADDON_DIR/templates/vscode/settings.json"   .vscode/settings.json
-
-# 3. copy the SDET kit (if discovered)
-if [[ -n "$KIT_DIR" ]]; then
-  echo "[3/7] copying SDET kit from $KIT_DIR"
-  cp -nR "$KIT_DIR/.claude"          .claude        2>/dev/null || true
-  cp -n  "$KIT_DIR/CLAUDE.md"        CLAUDE.md       2>/dev/null || true
-  cp -n  "$KIT_DIR/tests-config.json" tests-config.json 2>/dev/null || true
-  cp -n  "$KIT_DIR/README.md"        SDET_KIT_README.md 2>/dev/null || true
-else
-  echo "[3/7] kit not found — skipping. Run scripts/apply-kit.sh later."
-fi
-
-# 4. mark OpenAPI as disabled by default for greenfield
-if [[ -f "tests-config.json" ]] && command -v node >/dev/null 2>&1; then
-  echo "[4/7] disabling openapi skill until you have a spec"
-  node -e '
-    const fs=require("fs");
-    const p="tests-config.json"; const cfg=JSON.parse(fs.readFileSync(p,"utf8"));
-    cfg.openapi = cfg.openapi || {};
-    if (cfg.openapi.enabled === undefined) cfg.openapi.enabled = false;
-    fs.writeFileSync(p, JSON.stringify(cfg,null,2)+"\n");
-  '
-fi
-
-# 5. npm install — scripts disabled for supply-chain safety.
-#    Lifecycle hooks of transitive deps are NOT executed.
-#    We re-run only the hooks we explicitly trust below.
-if command -v npm >/dev/null 2>&1; then
-  echo "[5/7] npm install (scripts disabled)"
-  npm install --no-audit --no-fund --ignore-scripts
-
-  # Re-run trusted lifecycle steps explicitly.
-  # husky: needed to install git hooks from templates/husky/.
-  if [ -d .git ] && [ -f node_modules/husky/bin.mjs ]; then
-    echo "[5/7] husky init (explicit, replaces skipped postinstall)"
-    npx --no-install husky || true
-  fi
-else
-  echo "[5/7] npm not found — install Node 20+ then run 'npm install --ignore-scripts' manually"
-fi
-
-# 6. playwright install — browsers (not the npm package)
-if command -v npx >/dev/null 2>&1; then
-  echo "[6/7] playwright install (browsers)"
-  npx --no-install playwright install --with-deps chromium
-fi
-
-# 6. playwright install
-if [[ -f "package.json" ]] && command -v npx >/dev/null 2>&1; then
-  echo "[6/7] playwright install"
-  npx --no-install playwright install --with-deps chromium 2>/dev/null \
-    || npx playwright install chromium 2>/dev/null \
-    || echo "    skip — run 'npx playwright install' manually"
-fi
-
-# 7. husky
-if [[ -d ".git" ]] && command -v npx >/dev/null 2>&1 && [[ -f "package.json" ]]; then
-  echo "[7/7] husky setup"
-  npx --no-install husky 2>/dev/null || true
-  mkdir -p .husky
-  cp "$ADDON_DIR/templates/husky/pre-commit" .husky/pre-commit
-  cp "$ADDON_DIR/templates/husky/commit-msg" .husky/commit-msg
-  chmod +x .husky/pre-commit .husky/commit-msg
-fi
-
-# Final hint
-cp "$ADDON_DIR/templates/root/STARTER.md" STARTER.md 2>/dev/null || true
-
-cat <<EOF
-
-===  Done.
-Next steps:
-  1. Read STARTER.md
-  2. Open the repo in Claude Code:    claude
-  3. First request:                   "Scaffold the framework folders"
-                                      → playwright-framework-bootstrap will do it
-  4. Add your first env values:       cp .env.example .env.local && edit
-  5. Commit baseline:                 git add -A && git commit -m "chore: scaffold SDET kit"
-
-EOF
diff --git a/tests-config.json b/tests-config.json
index ff2823b..47d1342 100644
--- a/tests-config.json
+++ b/tests-config.json
@@ -1,19 +1,11 @@
 {
   "layout": {
     "pages": "tests/pages",
-    "components": "tests/components",
-    "apiClients": "tests/api",
     "fixtures": "tests/fixtures",
     "factories": "tests/factories",
     "specs": "tests/specs",
-    "data": "tests/data",
     "infra": "tests/infra"
   },
-  "openapi": {
-    "enabled": false,
-    "source": "specs/openapi.yaml",
-    "generated": "tests/api/generated"
-  },
   "naming": {
     "pageClass": "PascalCase",
     "specFile": "kebab-case.spec.ts",
@@ -25,9 +17,7 @@
   },
   "stack": {
     "factories": "fishery",
-    "openapi": "openapi-typescript+openapi-fetch",
     "schemaValidation": "zod"
   },
-  "envs": ["local", "staging", "prod"],
   "version": 1
 }
diff --git a/tests/factories/_seed.ts b/tests/factories/_seed.ts
index 91f9eb2..0afcf3b 100644
--- a/tests/factories/_seed.ts
+++ b/tests/factories/_seed.ts
@@ -1,11 +1,12 @@
 import { faker } from '@faker-js/faker';
+import { env } from '@infra/env';
 
 /**
  * Determinism contract — see docs/CONSTRAINTS.md §2.4.
- * Default SEED=1234. Seed is applied once at import time.
- * Import this module at the top of every *.factory.ts file.
+ * Default SEED=1234 (validated in tests/infra/env.ts). Applied once at import
+ * time. Import this module at the top of every *.factory.ts file.
  */
-const seed = process.env.SEED ? Number(process.env.SEED) : 1234;
+const seed = env.SEED;
 faker.seed(seed);
 
 export const FAKER_SEED = seed;
@@ -19,6 +20,6 @@ export const FAKER_SEED = seed;
  * domains by routing the order to `/payment/failed/`. See docs/ux-findings.md
  * (B-payment-validation) and docs/CONSTRAINTS.md §2.4.
  *
- * Override with the SYNTHETIC_EMAIL_DOMAIN env var if needed.
+ * Sourced from the validated env loader (override via SYNTHETIC_EMAIL_DOMAIN).
  */
-export const SYNTHETIC_EMAIL_DOMAIN = process.env.SYNTHETIC_EMAIL_DOMAIN ?? 'yopmail.com';
+export const SYNTHETIC_EMAIL_DOMAIN = env.SYNTHETIC_EMAIL_DOMAIN;
diff --git a/tests/infra/env.ts b/tests/infra/env.ts
index aaf550c..25b47f8 100644
--- a/tests/infra/env.ts
+++ b/tests/infra/env.ts
@@ -15,6 +15,10 @@ const schema = z.object({
   BASE_URL_PERSONAL: z.string().url().default('https://personal.freevpnplanet.com/'),
   BASE_URL_PLANETCONFIG: z.string().url().default('https://planetconfig.com/'),
   SEED: z.coerce.number().int().nonnegative().default(1234),
+  // Synthetic-only email domain for factories. Default yopmail.com — disposable
+  // with valid MX, so the RU/EN sites' server-side validation accepts it.
+  // See docs/CONSTRAINTS.md §2.4.
+  SYNTHETIC_EMAIL_DOMAIN: z.string().min(1).default('yopmail.com'),
   CI: z.string().optional(),
 });
 
diff --git a/tests/specs/purchase/personal-vpn-ru.spec.ts b/tests/specs/purchase/personal-vpn-ru.spec.ts
index 680ba3f..9d494d4 100644
--- a/tests/specs/purchase/personal-vpn-ru.spec.ts
+++ b/tests/specs/purchase/personal-vpn-ru.spec.ts
@@ -47,6 +47,7 @@ test.describe('@ru Personal VPN purchase — RU (Scenario B)', () => {
     });
   }
 
+  // eslint-disable-next-line playwright/expect-expect -- deliberate unimplemented gap; body is intentionally empty
   test.fixme('@ru crypto gateway not exposed on planetconfig.com /payment/ — see docs/ux-findings.md', async () => {
     // Intentionally empty — surfaced as a known gap against the assignment.
   });
diff --git a/tools/README.md b/tools/README.md
new file mode 100644
index 0000000..d342e22
--- /dev/null
+++ b/tools/README.md
@@ -0,0 +1,34 @@
+# `tools/` — this repo's quality gates
+
+These scripts mechanically enforce the layered architecture described in
+[`../CLAUDE.md`](../CLAUDE.md) and [`../docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md).
+They turn the "hard rules" from prose into checks that fail the build, so the
+boundaries can't quietly erode.
+
+Run them all at once:
+
+```bash
+npm run validate     # layout + factory + fixture + spec checks
+npm run verify       # repo health check (tooling, files, kit, no leaked secrets)
+```
+
+| Script               | What it guards                                                                                                                                                 | Invoked by                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `validate-layout.sh` | specs don't import locators directly, `BasePage` has no `expect`, `*Page` classes live only under `tests/pages/`, no raw `axios`/`fetch` in specs              | `npm run validate`, `.husky/pre-commit`, CI |
+| `lint-ui-spec.ts`    | no `waitForTimeout`, no XPath, no raw HTTP client, no inline page-object construction, no stray `console.log`/`setTimeout` (severity-graded: blocker → exit 2) | `npm run validate`, `.husky/pre-commit`, CI |
+| `factory-rules.ts`   | factories stay pure: no network, no `Date.now()`/`Math.random()` (determinism), no inheritance, no top-level mutable state                                     | `npm run validate`, CI                      |
+| `fixture-rules.ts`   | every fixture calls `await use(...)`, no name collisions with Playwright built-ins, worker/test scope sanity                                                   | `npm run validate`, CI                      |
+| `verify.sh`          | repo health check: tooling present, required files exist, the `.claude/` kit is intact, no `.env` committed                                                    | `npm run verify`                            |
+
+All scripts read paths from [`../tests-config.json`](../tests-config.json) and exit
+non-zero on violation (`0` = pass).
+
+## Relationship to the `.claude/` kit
+
+The same validators ship inside the [`.claude/` SDET kit](../.claude/) as
+self-contained skill templates (e.g.
+`.claude/skills/playwright-test-author-ui/scripts/lint-ui-spec.ts`), so each skill
+remains portable into any TS + Playwright repo. The copies here in `tools/` are
+**this repository's wired-in, active gates** — referenced by `package.json`,
+the pre-commit hook, and CI. The kit is the source/template; `tools/` is the
+running instance.
diff --git a/scripts/factory-rules.ts b/tools/factory-rules.ts
similarity index 100%
rename from scripts/factory-rules.ts
rename to tools/factory-rules.ts
diff --git a/tools/fixture-rules.ts b/tools/fixture-rules.ts
new file mode 100755
index 0000000..2a3ba99
--- /dev/null
+++ b/tools/fixture-rules.ts
@@ -0,0 +1,62 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * fixture-rules.ts — static checks for tests/fixtures/*.ts files.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const root = process.cwd();
+const cfg = JSON.parse(readFileSync(join(root, 'tests-config.json'), 'utf8'));
+const fixturesDir = join(root, cfg.layout.fixtures);
+
+const builtins = new Set(['page', 'request', 'browser', 'context', 'browserName', 'playwright']);
+
+function collect(dir: string, acc: string[] = []): string[] {
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) collect(p, acc);
+    else if (p.endsWith('.ts')) acc.push(p);
+  }
+  return acc;
+}
+
+const files = collect(fixturesDir);
+let violations = 0;
+
+for (const file of files) {
+  const src = readFileSync(file, 'utf8');
+
+  // 1. Each fixture body must call `use(`
+  const fixtureBlocks =
+    src.match(/(\w+)\s*:\s*async\s*\(\s*\{[^}]*\}\s*,\s*use[^)]*\)\s*=>\s*\{([\s\S]*?)\n\s*\}/g) ??
+    [];
+  for (const block of fixtureBlocks) {
+    if (!/await\s+use\s*\(/.test(block)) {
+      console.error(`FAIL: ${file} — fixture without 'await use(...)' detected.`);
+      violations++;
+    }
+  }
+
+  // 2. Fixture names must not collide with built-ins
+  const declarations = [...src.matchAll(/^\s*(\w+)\s*:\s*async\s*\(\s*\{/gm)];
+  for (const [, name] of declarations) {
+    if (builtins.has(name)) {
+      console.error(`FAIL: ${file} — fixture name '${name}' collides with Playwright built-in.`);
+      violations++;
+    }
+  }
+
+  // 3. Worker-scope fixtures must not import test-scope ones (heuristic: scope tag in extend signature)
+  if (/\.extend<[^,]*,\s*\{[^}]+\}\s*>/.test(src) && /\bpage\s*:/.test(src)) {
+    // best-effort warning; full graph check requires AST
+    console.warn(
+      `WARN: ${file} — extends with worker fixtures referencing 'page'. Verify scope graph manually.`,
+    );
+  }
+}
+
+if (violations > 0) {
+  console.error(`\n${violations} fixture rule violation(s).`);
+  process.exit(1);
+}
+console.log(`OK: ${files.length} fixture file(s) clean.`);
diff --git a/tools/lint-ui-spec.ts b/tools/lint-ui-spec.ts
new file mode 100755
index 0000000..71afbea
--- /dev/null
+++ b/tools/lint-ui-spec.ts
@@ -0,0 +1,95 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * lint-ui-spec.ts — static checks for tests/specs/**\/*.spec.ts
+ *
+ * Severity:
+ *   blocker → exit 2
+ *   major   → exit 1
+ *   minor   → exit 0 (warning only)
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+interface Rule {
+  name: string;
+  re: RegExp;
+  severity: 'blocker' | 'major' | 'minor';
+  message: string;
+}
+
+const root = process.cwd();
+const cfg = JSON.parse(readFileSync(join(root, 'tests-config.json'), 'utf8'));
+const specsDir = join(root, cfg.layout.specs);
+
+const rules: Rule[] = [
+  {
+    name: 'no-hard-wait',
+    re: /\bwaitForTimeout\s*\(\s*\d+/,
+    severity: 'blocker',
+    message: 'page.waitForTimeout is forbidden. Use expect.poll or web-first assertions.',
+  },
+  { name: 'no-xpath', re: /xpath=/, severity: 'major', message: 'XPath in spec.' },
+  {
+    name: 'no-axios',
+    re: /from\s*['"]axios['"]/,
+    severity: 'blocker',
+    message: 'Raw HTTP client in spec. Use generated typed client.',
+  },
+  {
+    name: 'no-console-log',
+    re: /\bconsole\.log\(/,
+    severity: 'minor',
+    message: 'console.log in spec.',
+  },
+  {
+    name: 'no-set-timeout',
+    re: /\bsetTimeout\s*\(/,
+    severity: 'major',
+    message: 'setTimeout in spec.',
+  },
+  {
+    name: 'no-inline-page',
+    re: /new\s+\w+Page\s*\(\s*page\s*\)/,
+    severity: 'major',
+    message: 'Page object instantiated inline. Move to fixture.',
+  },
+];
+
+function collect(dir: string, acc: string[] = []): string[] {
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) collect(p, acc);
+    else if (p.endsWith('.spec.ts')) acc.push(p);
+  }
+  return acc;
+}
+
+const files = collect(specsDir);
+let blockerCount = 0;
+let majorCount = 0;
+let minorCount = 0;
+
+for (const file of files) {
+  const src = readFileSync(file, 'utf8');
+  const lines = src.split('\n');
+
+  for (const rule of rules) {
+    lines.forEach((line, idx) => {
+      if (rule.re.test(line)) {
+        const tag = rule.severity.toUpperCase();
+        console.error(`${tag}: ${file}:${idx + 1} [${rule.name}] ${rule.message}`);
+        if (rule.severity === 'blocker') blockerCount++;
+        else if (rule.severity === 'major') majorCount++;
+        else minorCount++;
+      }
+    });
+  }
+}
+
+console.log(
+  `\nSummary: ${blockerCount} blocker, ${majorCount} major, ${minorCount} minor across ${files.length} spec(s).`,
+);
+
+if (blockerCount > 0) process.exit(2);
+if (majorCount > 0) process.exit(1);
+process.exit(0);
diff --git a/tools/validate-layout.sh b/tools/validate-layout.sh
new file mode 100755
index 0000000..9572c15
--- /dev/null
+++ b/tools/validate-layout.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# validate-layout.sh — checks that the repo follows tests-config.json layout.
+# Exit codes:
+#   0 = OK
+#   1 = layout violation (see stdout)
+#   2 = config missing
+#
+set -euo pipefail
+
+ROOT="${1:-$(pwd)}"
+CFG="$ROOT/tests-config.json"
+
+if [[ ! -f "$CFG" ]]; then
+  echo "FAIL: tests-config.json missing at $CFG"
+  exit 2
+fi
+
+# Pull paths via jq if present; fall back to defaults
+if command -v jq >/dev/null 2>&1; then
+  PAGES=$(jq -r '.layout.pages' "$CFG")
+  SPECS=$(jq -r '.layout.specs' "$CFG")
+  FIXTURES=$(jq -r '.layout.fixtures' "$CFG")
+else
+  PAGES="tests/pages"
+  SPECS="tests/specs"
+  FIXTURES="tests/fixtures"
+fi
+
+violations=0
+
+# 1. specs/ must not import directly from pages/*/locators
+if grep -RE "from ['\"].*pages/.+/locators['\"]" "$ROOT/$SPECS" 2>/dev/null; then
+  echo "FAIL: specs/ imports locators directly. Use page object public API."
+  violations=$((violations + 1))
+fi
+
+# 2. BasePage must not import expect
+if [[ -f "$ROOT/$PAGES/BasePage.ts" ]] && grep -E "from ['\"]@playwright/test['\"]" "$ROOT/$PAGES/BasePage.ts" | grep -q expect; then
+  echo "FAIL: BasePage.ts imports expect. Assertions belong in specs."
+  violations=$((violations + 1))
+fi
+
+# 3. *Page classes must live under pages/
+if grep -RE "class [A-Za-z]+Page " "$ROOT" --include='*.ts' --exclude-dir node_modules \
+   | grep -v "$PAGES" \
+   | grep -v ".claude/skills/" >/dev/null 2>&1; then
+  echo "FAIL: *Page classes found outside $PAGES."
+  violations=$((violations + 1))
+fi
+
+# 4. specs/ must not contain raw axios/fetch
+if grep -RE "from ['\"]axios['\"]|new XMLHttpRequest|require\\(['\"]axios" "$ROOT/$SPECS" 2>/dev/null; then
+  echo "FAIL: specs/ contains raw HTTP client. Use generated typed client."
+  violations=$((violations + 1))
+fi
+
+if [[ $violations -gt 0 ]]; then
+  echo "Layout violations: $violations"
+  exit 1
+fi
+
+echo "OK: layout valid."
+exit 0
diff --git a/scripts/verify.sh b/tools/verify.sh
similarity index 90%
rename from scripts/verify.sh
rename to tools/verify.sh
index 34a91d2..afb24c9 100755
--- a/scripts/verify.sh
+++ b/tools/verify.sh
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# verify.sh — sanity check after init.sh.
+# verify.sh — repo health check (tooling, required files, the .claude kit, no leaked secrets).
 # Reports what is missing and what is good. Exit code 0 = green, 1 = warnings, 2 = failures.
 #
 set -uo pipefail
@@ -42,7 +42,7 @@ softcheck() {
   return 0
 }
 
-echo "===  SDET greenfield repo health check"
+echo "===  Free VPN Planet — repo health check"
 echo
 
 echo "[ Tooling ]"
@@ -66,9 +66,7 @@ check ".claude/skills/ has 15 skills"  "[[ \$(ls .claude/skills 2>/dev/null | wc
 check ".claude/agents/ has subagents"  "[[ \$(ls .claude/agents 2>/dev/null | wc -l) -ge 1 ]]"
 check ".claude/hooks/*.sh executable"  "[[ -x .claude/hooks/guard-bash.sh ]]"
 
-echo "[ Greenfield-specific ]"
-softcheck "OpenAPI skill disabled (recommended on greenfield)" \
-  "node -e 'const c=require(\"./tests-config.json\");process.exit(c.openapi&&c.openapi.enabled===false?0:1)' 2>/dev/null"
+echo "[ Environment ]"
 softcheck "node_modules installed"     "[[ -d node_modules ]]"
 softcheck "Playwright browsers installed" \
   "[[ -d \$(npm config get cache 2>/dev/null)/ms-playwright ]] || ls ~/.cache/ms-playwright 2>/dev/null | grep -q chromium"
diff --git a/tsconfig.json b/tsconfig.json
index 5dc430a..87a64dc 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -21,14 +21,11 @@
     "baseUrl": "./",
     "paths": {
       "@pages/*": ["tests/pages/*"],
-      "@components/*": ["tests/components/*"],
-      "@api/*": ["tests/api/*"],
       "@fixtures": ["tests/fixtures/index.ts"],
       "@fixtures/*": ["tests/fixtures/*"],
       "@factories": ["tests/factories/index.ts"],
       "@factories/*": ["tests/factories/*"],
-      "@infra/*": ["tests/infra/*"],
-      "@data/*": ["tests/data/*"]
+      "@infra/*": ["tests/infra/*"]
     },
     "noEmit": true,
     "incremental": true,