test(e2e): scaffold Playwright suite with a non-blocking CI job

.github/workflows/ci.yml

@@ -69,6 +69,35 @@ jobs:
       - run: npm ci
       - run: npm test
 
+  # End-to-end smoke tests against a production build. Not yet a required
+  # check — continue-on-error keeps failures visible without blocking merges
+  # while the suite is still being built out.
+  e2e:
+    name: e2e (non-blocking)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - name: Harden the runner (Audit all outbound calls)
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 24
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm run test:e2e
+      - name: Upload playwright report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 14
+
   # public/llms.txt, llms-full.txt, and AGENTS.md are generated from the route
   # tree and committed. They go stale whenever a route is added, renamed, or
   # removed, so this fails if they differ from a fresh generation (it also

.gitignore

@@ -28,6 +28,12 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
 .claude/worktrees/
 .agents/skills/
 .claude/skills/

AGENTS.md

@@ -74,7 +74,31 @@ of a single commit, use `SKIP_DOCS_HOOK=1` or put `[skip-docs]` in the message.
 
 ## Testing
 
-- Run the llms-kit suite: `node --test tests/`
+Two separate suites, for two separate purposes — don't mix their files.
+
+- **Unit/component/contract tests — Vitest.** `*.test.ts(x)`, colocated next to
+  the code they cover (e.g. `app/snapshots/networks.contract.test.ts`,
+  `deploy.config.test.mjs`). Run with `npm test`. Fast, no browser, no build —
+  this is where logic, data transforms, and contract/matrix assertions live.
+  Blocking CI job (`test`).
+- **End-to-end journeys — Playwright.** `e2e/*.spec.ts`. Run with
+  `npm run test:e2e`, which builds the app and drives it in a real browser
+  against that production build. Non-blocking CI job (`e2e (non-blocking)`,
+  `continue-on-error: true`) — failures are visible but don't block merges
+  while this suite is still young. `vitest.config.mts` excludes `e2e/**` from
+  Vitest's default test glob so the two runners never pick up each other's
+  files.
+
+  **When to add an e2e test**: only for surfaces that are stable — established
+  pages/journeys not expected to change shape week to week (e.g. the home
+  page, core nav, Snapshots, Upgrades). Do not add e2e coverage for a new demo
+  or anything still being iterated on (e.g. work under `app/vibenet/demos/`)
+  — the UI will keep shifting under the test faster than the test catches
+  real regressions, making it pure maintenance overhead. Add a smoke test
+  once a demo's surface has settled, not before.
+
+- Run the llms-kit suite (generation scripts under `scripts/`, unrelated to
+  the app tests above): `node --test tests/`
 - Include liveness checks against the deployed site: `LLMS_LIVE=1 node --test tests/`
 
 ## Analytics

README.md

@@ -30,6 +30,7 @@ to run the **internal** build locally with those sections visible. See
 - `npm run lint` — eslint (next/core-web-vitals)
 - `npm run typecheck` — `tsc --noEmit`
 - `npm test` — vitest
+- `npm run test:e2e` — playwright end-to-end tests (builds and serves the app first)
 - `npm run llms` / `npm run agents` — regenerate the agent index files
 - `npm run docs:check` — verify the agent index is current
 
@@ -49,6 +50,9 @@ to run the **internal** build locally with those sections visible. See
 - **public build excludes internal-only surfaces** — builds the default
   (external) target and asserts that internal-only routes 404 and never appear
   in the nav or sitemap, so the deployment matrix can't silently regress
+- **e2e (non-blocking)** — playwright smoke tests against a production build.
+  `continue-on-error`, so failures show up without blocking merges while the
+  suite is still being built out.
 
 CodeQL, StepSecurity, Heimdall, and the Vercel preview build are configured
 outside this repo at the org/platform level.

e2e/home.spec.ts

@@ -0,0 +1,8 @@
+import { expect, test } from '@playwright/test';
+
+test('home page loads and shows the landing copy', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page.getByText('Monitor and test Base, all in one place.')).toBeVisible();
+  await expect(page.getByRole('main').getByRole('link', { name: /vibenet/i })).toBeVisible();
+});