@1aboveio/skills 0.10.0

package/skills/engineering/e2e-test/assets/e2e-workflow.yml

@@ -0,0 +1,282 @@
+# E2E Tests — GitHub Actions Workflow
+#
+# Triggered by Cloud Build via repository_dispatch after successful deployment.
+# Posts structured results as PR comment + sets commit status.
+#
+# To use: copy to .github/workflows/e2e.yml and customize marked sections.
+
+name: E2E Tests
+
+on:
+  repository_dispatch:
+    types: [deploy-complete]
+
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: 'Environment (dev/prod)'
+        required: true
+        type: choice
+        options:
+          - dev
+          - prod
+      service_url:
+        description: 'Deployed service URL'
+        required: true
+        type: string
+      sha:
+        description: 'Git commit SHA'
+        required: false
+        type: string
+      pr_number:
+        description: 'PR number to comment on'
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  statuses: write
+  pull-requests: write
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    if: github.event.client_payload.commit != '' || github.event_name == 'workflow_dispatch'
+    timeout-minutes: 15
+    # DOCKER-PREFERRED: run in the official pinned Playwright container — browsers and
+    # OS deps ship in the image, so there is no per-run browser install. Keep the tag
+    # aligned with the repo's @playwright/test version and with ci-gates.github.yml.
+    # Alternative (plain runner): drop `container:` and add a step
+    # `npx playwright install --with-deps chromium` after the dependency install.
+    container:
+      image: mcr.microsoft.com/playwright:v1.61.0-noble
+      options: --ipc=host
+
+    env:
+      ENV: ${{ github.event.client_payload.env || inputs.environment }}
+      SERVICE_URL: ${{ github.event.client_payload.service_url || inputs.service_url }}
+      SHA: ${{ github.event.client_payload.commit || inputs.sha || github.sha }}
+      PR_NUMBER: ${{ github.event.client_payload.pr_number || inputs.pr_number }}
+
+    steps:
+      - name: Determine checkout ref
+        id: ref
+        run: |
+          if [[ "$ENV" == "dev" ]]; then
+            echo "ref=dev" >> $GITHUB_OUTPUT
+          else
+            echo "ref=$SHA" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.ref.outputs.ref }}
+          fetch-depth: 0
+
+      # ── CUSTOMIZE: Node version and package manager ──
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        # No browser install: the job container ships the browsers. If the image tag
+        # and @playwright/test versions can't be aligned, add
+        # `npx playwright install chromium` here (prefer aligning instead).
+
+      - name: Wait for service readiness
+        run: |
+          echo "Waiting for $SERVICE_URL to be ready..."
+          for i in $(seq 1 30); do
+            if curl -sf -o /dev/null "$SERVICE_URL"; then
+              echo "Service is ready"
+              exit 0
+            fi
+            echo "Attempt $i/30 — retrying in 10s..."
+            sleep 10
+          done
+          echo "Service not ready after 5 minutes"
+          exit 1
+
+      # ── CUSTOMIZE: test command and env vars ──
+      - name: Run E2E tests
+        id: run_tests
+        run: npm run test:e2e
+        continue-on-error: true  # Phase 1: non-blocking. Remove for Phase 2.
+        env:
+          BASE_URL: ${{ env.SERVICE_URL }}
+          CI: true
+          # Add repo-specific secrets:
+          # E2E_DASHBOARD_TOKEN: ${{ secrets.E2E_DASHBOARD_TOKEN }}
+
+      - name: Post E2E results to PR
+        if: always() && env.PR_NUMBER != ''
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            // Parse Playwright JSON results
+            let results = { total: 0, passed: 0, failed: 0, skipped: 0, duration: 0, failures: [] };
+            try {
+              const raw = JSON.parse(fs.readFileSync('e2e-results.json', 'utf8'));
+              const suites = raw.suites || [];
+              function walk(suite) {
+                for (const spec of (suite.specs || [])) {
+                  for (const test of (spec.tests || [])) {
+                    results.total++;
+                    const status = test.results?.[test.results.length - 1]?.status || 'unknown';
+                    if (status === 'passed' || status === 'expected') results.passed++;
+                    else if (status === 'skipped') results.skipped++;
+                    else {
+                      results.failed++;
+                      const err = test.results?.[test.results.length - 1]?.error?.message || 'Unknown error';
+                      results.failures.push({ title: spec.title + ' › ' + test.title, error: err.slice(0, 200) });
+                    }
+                    results.duration += (test.results?.[test.results.length - 1]?.duration || 0);
+                  }
+                }
+                for (const child of (suite.suites || [])) walk(child);
+              }
+              suites.forEach(walk);
+            } catch (e) {
+              console.log('Could not parse e2e-results.json:', e.message);
+            }
+
+            // Parse route manifest for coverage
+            let coverage = { covered: 0, total: 0 };
+            try {
+              const manifest = JSON.parse(fs.readFileSync('e2e/route-manifest.json', 'utf8'));
+              const routes = manifest.routes || manifest.endpoints || [];
+              coverage.total = routes.length;
+              coverage.covered = routes.filter(r => (r.specs || []).length > 0).length;
+            } catch (e) {
+              console.log('No route manifest found:', e.message);
+            }
+
+            const icon = results.failed > 0 ? '❌' : '✅';
+            const status = results.failed > 0 ? 'FAILED' : 'PASSED';
+            const durationStr = `${Math.floor(results.duration / 60000)}m ${Math.floor((results.duration % 60000) / 1000)}s`;
+            const coverageStr = coverage.total > 0
+              ? `${Math.round(coverage.covered / coverage.total * 100)}% (${coverage.covered}/${coverage.total})`
+              : 'N/A (no manifest)';
+
+            let body = `## 🧪 E2E ${status} — ${process.env.ENV}\n\n`;
+            body += `| Metric | Value |\n|--------|-------|\n`;
+            body += `| Total | ${results.total} |\n`;
+            body += `| ✅ Passed | ${results.passed} |\n`;
+            body += `| ❌ Failed | ${results.failed} |\n`;
+            body += `| ⏭️ Skipped | ${results.skipped} |\n`;
+            body += `| ⏱️ Duration | ${durationStr} |\n`;
+            body += `| 📊 Route coverage | ${coverageStr} |\n\n`;
+
+            if (results.failures.length > 0) {
+              body += `<details><summary>❌ Failed (${results.failures.length})</summary>\n\n`;
+              for (const f of results.failures) {
+                body += `- \`${f.title}\` — ${f.error}\n`;
+              }
+              body += `\n</details>\n\n`;
+            }
+
+            body += `> Commit: ${process.env.SHA?.slice(0, 7)} | [Workflow run](${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID})`;
+
+            // Post or update PR comment
+            const prNumber = parseInt(process.env.PR_NUMBER);
+            if (prNumber) {
+              const { data: comments } = await github.rest.issues.listComments({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+              });
+              const existing = comments.find(c => c.body?.startsWith('## 🧪 E2E'));
+              if (existing) {
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: existing.id,
+                  body,
+                });
+              } else {
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: prNumber,
+                  body,
+                });
+              }
+            }
+
+      - name: Set commit status
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const state = '${{ steps.run_tests.outcome }}' === 'success' ? 'success' : 'failure';
+            const env = '${{ env.ENV }}';
+            await github.rest.repos.createCommitStatus({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              sha: '${{ env.SHA }}',
+              state,
+              target_url: `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${process.env.GITHUB_RUN_ID}`,
+              description: state === 'success' ? `E2E ${env}: all tests passed` : `E2E ${env}: tests failed`,
+              context: 'e2e',
+            });
+
+      - name: Report to Discord
+        if: always() && github.event_name == 'repository_dispatch'
+        env:
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_WEBHOOK_URL }}
+        run: |
+          if [[ -z "$DISCORD_WEBHOOK_URL" ]]; then
+            echo "DISCORD_WEBHOOK_URL not set — skipping"
+            exit 0
+          fi
+
+          OUTCOME="${{ steps.run_tests.outcome }}"
+          RUN_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"
+          COMMIT_URL="https://github.com/${GITHUB_REPOSITORY}/commit/${SHA}"
+          REPO_NAME="${GITHUB_REPOSITORY#*/}"
+
+          if [[ "$OUTCOME" == "success" ]]; then
+            ICON="✅"; STATUS="PASSED"; COLOR=3066993
+          else
+            ICON="❌"; STATUS="FAILED"; COLOR=15158332
+          fi
+
+          # Built with node (always present in the Playwright image), not jq (not installed there).
+          PAYLOAD=$(node -e '
+            const [icon, status, env, commit, commitUrl, serviceUrl, runUrl, repo, color] = process.argv.slice(1);
+            console.log(JSON.stringify({ embeds: [{
+              title: `${icon} E2E ${status} — ${repo} (${env})`,
+              url: runUrl, color: Number(color),
+              fields: [
+                { name: "Commit", value: `[${commit}](${commitUrl})`, inline: true },
+                { name: "Environment", value: env, inline: true },
+                { name: "Service", value: serviceUrl, inline: false },
+              ],
+              footer: { text: `${repo} CI` },
+            }]}));
+          ' "$ICON" "$STATUS" "$ENV" "${SHA:0:7}" "$COMMIT_URL" "$SERVICE_URL" "$RUN_URL" "$REPO_NAME" "$COLOR")
+
+          curl -sf -X POST -H "Content-Type: application/json" -d "$PAYLOAD" "$DISCORD_WEBHOOK_URL" || true
+
+      # Phase 2: uncomment to make E2E blocking
+      # - name: Fail if tests failed
+      #   if: steps.run_tests.outcome == 'failure'
+      #   run: exit 1
+
+      - name: Upload artifacts on failure
+        if: failure() || steps.run_tests.outcome == 'failure'
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-results-${{ github.run_id }}
+          path: |
+            test-results/
+            playwright-report/
+            e2e-results.json
+          retention-days: 7

package/skills/engineering/e2e-test/references/authoring/auth-flows.md

@@ -0,0 +1,159 @@
+# Auth Flows (login, signup, forgot-password)
+
+> Read when: testing authentication surfaces — login, signup, password reset, magic link, OAuth callback. These span three tiers and cross an external boundary (email/SMS), which is why they are the most commonly mis-tested feature in a codebase.
+
+Auth is special on two counts, both easy to get wrong:
+
+1. **It spans all three tiers** — the same feature owes a render-health test, functional negatives, *and* a real journey. Confusing them produces a test that looks like a journey but proves nothing.
+2. **It crosses an external boundary you don't own** — reset/verification email. The token round-trip is the whole point, and must be proven without calling a live provider.
+
+## The anti-pattern this exists to kill
+
+A test tagged `@level journey` that only checks *a form element is visible*:
+
+```typescript
+// ✗ A smoke test wearing a journey label. Proves nothing; can't fail the way the
+//   name promises. When the form fails to render at all (e.g. a seed/cache race),
+//   the disjunction just goes falsy with no specific signal.
+test('Customer login page loads and renders login form', async ({ page }) => {
+  const response = await page.goto(`/${MERCHANT}/account/login`);
+  expect(response?.ok()).toBeTruthy();
+  const hasEmail = await page.getByLabel(/email/i).isVisible().catch(() => false);
+  const hasPassword = await page.getByLabel(/password/i).isVisible().catch(() => false);
+  const hasButton = await page.getByRole('button', { name: /login/i }).isVisible().catch(() => false);
+  expect(hasEmail || hasPassword || hasButton).toBeTruthy();   // weak disjunction
+});
+```
+
+Two syntactic tells — `.catch(() => false)` (swallows a locator throw, defeating web-first retry) and `expect(a || b || c).toBeTruthy()` (passes if *any* branch holds) — are flagged as leads by `review-pr`'s `scan-diff.mjs` (`swallowed-assertion`, `weak-assertion`). Writing them means a vacuous check, not a journey — replace with a real journey below.
+
+## Login
+
+Separate two jobs that get conflated:
+
+### 1. Proving the login flow itself
+
+A Tier-3 journey drives credentials to an **authenticated outcome** (not form presence), backed by Tier-2 functional negatives where most real bugs live.
+
+```typescript
+// @covers /[merchant]/account/login
+// @level journey
+test('customer logs in and lands authenticated', async ({ page }) => {
+  const user = await factory.customer({ password: 'Correct-horse-9' }); // seed real state
+  await page.goto(`/${MERCHANT}/account/login`);
+  await page.getByLabel(/email/i).fill(user.email);
+  await page.getByLabel(/password/i).fill('Correct-horse-9');
+  await page.getByRole('button', { name: /log in|sign in/i }).click();
+  // Assert a CONCRETE post-login signal — redirect + authed-only content:
+  await expect(page).toHaveURL(new RegExp(`/${MERCHANT}/account$`));
+  await expect(page.getByRole('heading', { name: /my account/i })).toBeVisible();
+});
+```
+
+Back it with **Tier-2 functional negatives** where most real bugs live — e.g. `@level functional` "wrong password shows error and stays unauthenticated": fill a bad password, assert the error text is visible *and* `toHaveURL(/login/)` (did NOT get in).
+
+Rules:
+
+- **Seed the user** with a factory/seed script — never depend on ambient data. Missing state is the test's *arrange* step, never a skip reason ([test-skipping.md](test-skipping.md)).
+- **Name every seeded account with the `e2e-` prefix** (see [the naming convention](#the-e2e--account-naming-convention) below) — the factory should emit it by default, not leave it to each call site.
+- **Assert authenticated state**, not form presence: a redirect to an authed route, an authed-only element, or the session cookie. "A button is visible" is Tier-1 render-health.
+- **Don't mock first-party auth endpoints** in the journey — real DB, real session. Intercepting `/api/auth/*` makes it `Over-mocked` (`ensure-coverage` → `references/depth/mock-policy.md`).
+
+### 2. Login as a precondition for other journeys
+
+Don't re-type credentials in every test. Log in once and reuse the session via a shared auth fixture (`storageState`) or `E2E_AUTH_BYPASS`; other journeys start already-authed and only the login spec proves login itself. This is the "Seed auth" path in [test-skipping.md](test-skipping.md) — the cure for "no session" is to seed it, never skip.
+
+## A session fixture asserts its own preconditions, and throws
+
+A minted session the app then rejects is the worst failure mode in this file: the request fails closed, nothing renders, and the spec dies on an **undiagnostic timeout**. Nothing in the diff looks wrong — there is no assertion against a 404 to spot, because the assertion was never reached. The lane goes on reporting green-or-flaky while proving nothing.
+
+The recurring cause is a value the **app and the harness each default independently**: a tenant/org slug, an auth secret, a base URL, an API version. They agree until one side's default moves.
+
+**Rules, in the order they close the hole:**
+
+- **One owner per shared value.** A single constant mirrors the app's own resolver (`getRequiredOrgSlug()`, not a re-typed `?? "skyee"`), and the Playwright config sets the env var *from that constant* — in `webServer.env` **and** any inline command string, which drift apart otherwise.
+- **Make the wrong value inexpressible.** Identities come from constructor functions (`authorizedIdentity()`, `denyOnlyIdentity()`) that fill the shared value themselves. If no call site can state it, no call site can state it wrongly — a rule prose cannot enforce, structure can.
+- **Assert at mint time and throw with a diagnosis.** The fixture checks the value as it mints and, on mismatch, throws naming the identity id, *both* values, and the owning constant's file path. A loud throw is the entire difference between a five-minute fix and a five-round one; a timeout names nothing.
+- **Close the vacuous-pass hole in deny fixtures.** A fixture that deliberately uses a wrong value opts in explicitly (`{ allowWrongOrg: true }`), and that flag is **rejected on a right-value identity** — otherwise a denial assertion passes for the wrong reason, and the negative test is as vacuous as the positive one.
+
+The first two rules are what make this stick: a value no call site can express is a value no call site can get wrong. (Named incident: `skyee-ai-risk` #1144 — a tenant slug defaulted independently in four files left authorized journeys minting sessions the app rejected, so the endpoint 403'd before any row rendered and those lanes **stayed green for five review rounds** while exercising nothing. Fixed in `f97f879e`, whose message records why structure rather than a fourth sentence: *"prose had already failed at this twice in these exact files."*)
+
+## The `e2e-*` account naming convention
+
+Every account, email, and tenant a test seeds carries an **`e2e-` prefix**:
+
+```
+account   e2e-<role>-<runid>@<test-domain>     e2e-customer-x7f2@example.test
+tenant    e2e-<name>                           e2e-synthetic
+username  e2e-<role>-<runid>                   e2e-admin-x7f2
+```
+
+Bake it into the **factory default** — `factory.customer()` emits a conforming email without the call site asking — so the convention can't erode one test at a time. Why a naming convention and not just "use seeded data":
+
+- **Identifiable at a glance.** In a DB dump, log line, admin UI, or bug report, `e2e-` says "test artifact" with no lookup.
+- **Bulk-cleanable.** `DELETE FROM users WHERE email LIKE 'e2e-%'` is a safe janitor job; without the prefix, cleanup needs a bookkeeping table that drifts.
+- **Mechanically guarded.** The app/monitoring can special-case the prefix (exclude from analytics/emails/billing), and `smoke`'s deployed-target rule builds on it: a mutating golden path off-`local` runs only against a declared synthetic tenant, and `smoke.mjs validate` warns when a tenant is not `e2e-`-prefixed. (Production is governed by the stricter **read-only production profile** (`prod-preview`/`prod-active`), where a tenant grants nothing — this convention is what makes *staging* runs safe, not prod ones.)
+- **Unambiguous in shared environments.** On staging/preview where real-ish data coexists, the prefix keeps a cleanup script or mutating smoke run from touching anything live.
+
+Use a **run-scoped suffix** (a short random id per run) so parallel workers and repeated CI runs never collide on unique columns — never a fixed `e2e-test@example.com` singleton, which serializes workers and flakes on re-runs.
+
+## Forgot password — the email boundary is the whole flow
+
+Email/SMS is an **external boundary you don't own** → *real internals, faked externals, nothing in between* (`mock-policy.md`).
+
+- ✗ Don't call a live email provider in CI (non-deterministic, flaky, leaks keys).
+- ✗ Don't skip it because "email is external" — the exact rationalization the no-skip policy forbids; **sandbox the boundary** instead.
+- ✗ Don't assert "the form renders" and call it a journey.
+
+✓ Fake the mail adapter so the app writes to a test outbox, then drive the **full durable-state** round-trip:
+
+```typescript
+// @covers /[merchant]/account/forgot-password
+// @level journey
+test('reset password end to end', async ({ page }) => {
+  const user = await factory.customer({ password: 'old-pass-1' });
+
+  // 1. Request reset
+  await page.goto(`/${MERCHANT}/account/forgot-password`);
+  await page.getByLabel(/email/i).fill(user.email);
+  await page.getByRole('button', { name: /reset|send/i }).click();
+  await expect(page.getByText(/check your (email|inbox)/i)).toBeVisible();
+
+  // 2. Read the token from the FAKE outbox (or directly from the DB token table —
+  //    both are real internals; live SMTP is the banned outward reach)
+  const link = await fakeMail.lastResetLink(user.email);
+
+  // 3. Complete the reset
+  await page.goto(link);
+  await page.getByLabel(/new password/i).fill('new-pass-2');
+  await page.getByRole('button', { name: /set|update/i }).click();
+
+  // 4. Prove the durable change: new password works
+  await login(page, { email: user.email, password: 'new-pass-2' });
+  await expect(page.getByRole('heading', { name: /my account/i })).toBeVisible();
+});
+```
+
+- Reading the token from the **fake outbox** also proves the send wiring; reading it from the **DB token table** proves only the token logic. Either is real-internal and valid — pick based on whether email dispatch is part of the contract you're proving.
+- Cover the negatives as Tier-2 functional against the real DB: **expired token**, **already-used token**, **unknown email** (should not reveal account existence).
+
+## CI wiring
+
+| Concern | Practice |
+|---|---|
+| **Where they run** | The **blocking** E2E lane. Once email is faked, both flows are fully hermetic — *no quarantine*. Quarantine is only for genuinely un-sandboxable externals (e.g. a real-provider deliverability check), which is a separate secret-gated test with a dedicated mailbox ([ci-integration.md](../ci-integration.md) → Quarantine lane). |
+| **Seed timing** | Migrate → seed → **start servers** → run. Seed the user/tenant *before* servers boot, or bypass caches for E2E (e.g. an `ALLOW_E2E_ROUTES` flag). A freshly-seeded row a cached read can't yet see is a classic auth-journey flake. |
+| **Email adapter** | Inject a fake/in-memory mail adapter via env in CI; never real keys, never a live provider. |
+| **Presentation** | The presentation sweep ([presentation-sweep.md](../presentation-sweep.md)) catches "the form didn't render at all" — the bug a green functional run sails past. It is a **separate gate**; the journey assertion is not a substitute. |
+| **Getting to green** | Never weaken assertions or skip to pass — `review-pr`'s manufactured-green check and the `weak-assertion`/`swallowed-assertion` leads flag exactly that. |
+
+## Checklist
+
+- [ ] Login journey asserts **authenticated state** (redirect / authed element / session cookie), not form presence.
+- [ ] User/session **seeded** before server boot; caches bypassed for E2E.
+- [ ] Values the app and harness share (tenant/org, secret, base URL) have **one owner**, and the session fixture **throws** on mismatch rather than letting the lane time out.
+- [ ] Seeded accounts/tenants carry the **`e2e-` prefix** with a run-scoped suffix (factory default, not per-call-site).
+- [ ] Forgot-password drives the **full reset → new-password-works** loop with a **faked mail boundary**.
+- [ ] Negatives (wrong password, expired/used token, unknown email) are **Tier-2 functional** against the real DB.
+- [ ] No first-party `page.route`/MSW interception in the journeys; no `.catch(() => false)`; no disjunctive `toBeTruthy()`.
+- [ ] Everything in the **blocking lane**; no skips; presentation sweep is a separate job.

package/skills/engineering/e2e-test/references/authoring/playwright-config.md

@@ -0,0 +1,71 @@
+# Playwright Config
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  // Timeout convention: 15s for any single action/assertion — a real state change
+  // arrives in seconds; anything slower is a bug the test should surface, not wait out.
+  // The per-test ceiling stays higher (a journey is many 15s-bounded steps).
+  timeout: 60_000,
+  expect: { timeout: 15_000 },
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  // Parallel in CI too — wall clock ≈ slowest spec, not the sum. E2E_WORKERS is the
+  // CI-side knob (see ../ci-playwright-container.md → Resource Envelope and Workers);
+  // 4 fits a 4 CPU / 16 GB job. Drop to 2 only on OOM/browser crashes.
+  workers: process.env.CI ? Number(process.env.E2E_WORKERS) || 4 : undefined,
+  reporter: process.env.CI
+    ? [['github'], ['json', { outputFile: 'e2e-results.json' }], ['html', { open: 'never' }]]
+    : [['list'], ['html', { open: 'never' }]],
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    actionTimeout: 15_000,
+    navigationTimeout: 15_000,
+    trace: 'retain-on-failure',
+    screenshot: 'only-on-failure',
+    ignoreHTTPSErrors: true,
+  },
+  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
+  webServer: {
+    command: 'npm run dev',
+    url: process.env.BASE_URL || 'http://localhost:3000',
+    timeout: 120_000,
+    reuseExistingServer: !process.env.CI,
+  },
+});
+```
+
+## Time budget (the 5-minute PR lane)
+
+The per-PR browser gates (render sweep, curated smoke) target **≤5 min wall clock**, enforced by `timeout-minutes: 5` / `timeout: 300s` on the CI job (`ci-gates.*` templates carry it; `ci-audit.mjs` checks it). The levers: **parallel workers** (above — wall clock is the slowest spec, not the sum); **curation** (the floor runs the `@smoke` subset + the sweep, never the broad suite — gate 4 is demoted to the integration lane, see [../ci-integration.md](../ci-integration.md)); the **15s action timeout** (a hung step fails fast); **matrix fan-out** if the curated set still can't fit (the commented `smoke-drive` variant in `assets/ci-gates.github.yml`). Longer leashes belong to the integration-lane suite (`timeout-minutes: 30`) and auxiliary quarantine/visual jobs (10–15) — never the PR-lane gates.
+
+## AGENTS.md section
+
+Drop into each repo's AGENTS.md or CLAUDE.md:
+
+```markdown
+## E2E Testing
+
+### Rules
+1. Every new route/endpoint MUST be added to `e2e/route-manifest.json` (CI will fail otherwise)
+2. Every new route needs at least a Tier 1 render-health test
+3. Interactive routes need Tier 2 functional tests (success + error + edge cases)
+4. Core business flows need Tier 3 journey tests — the golden paths (multi-step, real API); tag the do-not-ship subset `@smoke`
+5. Directory: `render/`, `functional/`, `journeys/`
+6. Use `getByRole`/`getByLabel`/`getByText` -- not CSS selectors
+7. No `waitForTimeout()` -- wait for real state
+8. Run route discovery and reachability analysis before E2E coverage audits; do not audit from memory, sampling, or file enumeration alone
+9. No `test.skip()` unless it matches the Test Skipping Policy: allowed category, GitHub issue/blocker link, and replacement verification
+10. Auth in shared fixtures (`e2e/fixtures/auth.ts`); test accounts and synthetic tenants carry the `e2e-` prefix (e.g. `e2e-customer-x1@example.test`, tenant `e2e-synthetic`)
+11. Timeouts: 15s per action/assertion (`actionTimeout`/`expect.timeout`); no per-test timeout raises without justification
+
+### CI Enforcement
+- Route detection runs on every PR -- adding a page/endpoint without a manifest entry fails CI
+- The presentation sweep runs as a separate blocking job -- a route that throws on render fails CI even when a functional spec passes
+- Browser jobs run in the pinned official Playwright container (docker-preferred); PR-lane jobs carry a 5-minute timeout
+- Branch protection requires only the `all-gates` umbrella job
+- Reviewer will block PRs with uncovered interactive routes without justification
+```