@opengroundplan/core 0.1.1

package/templates/layers/security-supply-chain/files/docs/security-supply-chain.md

@@ -0,0 +1,124 @@
+# Supply-chain security
+
+OWASP moved supply-chain failures to **A03:2025** and broadened the category. Everything here
+is Top-10 material, not optional hardening.
+
+## What you must do in the GitHub UI
+
+Files cannot express repository settings. These take about five minutes and are the highest
+-value controls in this document.
+
+1. **Settings → Code security → Secret scanning: on, and Push protection: on.**
+   Push protection blocks the commit. The `secret-scan.yml` workflow only tells you afterwards.
+2. **Settings → Actions → General → require actions to be pinned to a full-length commit SHA.**
+   Shipped 2025-08-15 at org/enterprise level, together with a `!`-prefixed blocklist that acts
+   as an incident-response kill switch.
+3. **Branch protection on `main`:** require PR review, require the CodeQL and Dependency Review
+   checks, and — if you use a merge queue — make those checks trigger on `merge_group`, or the
+   queue stalls until the status-check timeout ejects the PR.
+4. **Private repos:** CodeQL and Dependency Review need GitHub Code Security. Until it is
+   enabled those jobs skip themselves rather than fail; set repository variable
+   `ENABLE_CODE_SCANNING=true` once you have it.
+
+## Why the Actions are pinned by SHA
+
+**CVE-2025-30066 (`tj-actions/changed-files`, 2025-03-14).** An attacker with a stolen PAT
+repointed *every existing version tag* — `v1` through `v45` — at one malicious commit that
+dumped runner process memory into the workflow log. ~23,000 repositories were affected.
+Old commits were never touched, so SHA pinning would have neutralized it completely.
+
+"Immutable actions" did **not** ship. [github/roadmap#1103](https://github.com/github/roadmap/issues/1103)
+is closed as not planned; what went GA in 2025-10 was immutable *Releases*, which does nothing
+for `uses:` refs. SHA pinning is still the only mechanism.
+
+⚠️ **The `# vX.Y.Z` comment beside each SHA is load-bearing.** Dependabot parses it to know
+what to bump. Strip the comments and you get pins that never update — immutability plus
+permanent staleness. [`pinact`](https://github.com/suzuki-shunsuke/pinact) rewrites tags into
+SHA-plus-comment automatically; run it after adding any new action.
+
+## Why there is a cooldown
+
+The 2025 postinstall worms — Nx s1ngularity (Aug), chalk/debug (Sept), Shai-Hulud (Sept) and
+Shai-Hulud 2.0 (Nov, 25,000+ repos) — all published a malicious version that was yanked within
+days. A cooldown delays *version* update PRs past that window. **Security updates are exempt**
+and still arrive immediately, so the cooldown costs you nothing on the updates that matter.
+
+`.npmrc`'s `ignore-scripts=true` is the control that actually *prevents* rather than detects,
+because all four worms executed from a pre/postinstall script.
+
+- **pnpm 10+** already blocks dependency scripts; allowlist the ones you need with
+  `onlyBuiltDependencies: [esbuild, sharp]` in `pnpm-workspace.yaml`.
+- **npm/yarn** honour `.npmrc`. After reviewing a package that genuinely needs to build,
+  run `npm rebuild <pkg>` explicitly.
+- Your own `prepare` script is disabled as a side effect, so hook installers must be invoked
+  directly rather than relied on at install time.
+
+## Workflow rules this repo follows
+
+- **Never `pull_request_target`.** It gave the Nx attacker a write-scoped `GITHUB_TOKEN`.
+- **Never interpolate `${{ github.event.* }}` into a `run:` block.** Pass it through `env:`
+  and read the shell variable — that is why `secret-scan.yml` uses `$GITLEAKS_VERSION`.
+- **`permissions: contents: read` at workflow level.** Job-level `permissions` *replaces* the
+  workflow block rather than extending it, so a job that needs `id-token: write` must
+  re-declare `contents: read` or checkout breaks.
+- **`persist-credentials: false` on every checkout**, so a compromised later step cannot reuse
+  the token.
+- **`language: actions` in the CodeQL matrix**, which is what finds script injection in your
+  own workflows.
+
+## SBOM
+
+`sbom.yml` runs Syft twice and produces both formats in one job:
+
+| File | Format | Why both |
+|---|---|---|
+| `sbom.cdx.json` | CycloneDX JSON | Primary. CycloneDX 1.7 is ECMA-424. |
+| `sbom.spdx.json` | SPDX JSON | Procurement, and the only format GitHub's SBOM export API speaks. |
+
+Locally: `syft scan dir:. -o cyclonedx-json=sbom.cdx.json -o spdx-json=sbom.spdx.json`
+
+**Attestation is deliberately not in this workflow.** An attestation binds an SBOM to a
+*built artifact*, and this layer does not know what you build. Add this to whichever workflow
+produces your release binary or image:
+
+```yaml
+    permissions:
+      contents: read
+      id-token: write
+      attestations: write
+    steps:
+      # ... build, then:
+      - uses: actions/attest-sbom@c604332985a26aa8cf1bdc465b92731239ec6b9e # v4.1.0
+        with:
+          subject-path: dist/your-artifact
+          sbom-path: sbom.cdx.json
+      - uses: actions/attest@f7c74d28b9d84cb8768d0b8ca14a4bac6ef463e6 # v4.2.0
+        with:
+          subject-path: dist/your-artifact
+          predicate-type: https://slsa.dev/provenance/v1
+```
+
+Use `actions/attest`, not `attest-build-provenance` — the latter is now only a wrapper.
+SLSA v1.1 is retired; v1.2 is current.
+
+## Local secret scanning
+
+`.githooks/pre-commit` runs gitleaks against staged changes. Enable it per clone:
+
+```sh
+git config core.hooksPath .githooks
+chmod +x .githooks/pre-commit   # no-op on Windows
+```
+
+The hook does nothing except scan for secrets. That is intentional — hooks that also lint,
+format and test get disabled within a week, and a disabled hook scans nothing.
+
+If gitleaks is not installed the hook warns and lets the commit through, so a fresh clone is
+never blocked. CI is the enforcing gate; the hook is the fast feedback loop.
+
+## Credentials
+
+The direction of travel is **no static secrets at all**: OIDC to your cloud, trusted publishing
+to your registry, and platform-issued short-lived workload identity (SPIFFE/SPIRE) in the
+runtime. When you do bind an OIDC trust policy, scope it to an **environment**
+(`repo:org/repo:environment:prod`) — `repo:org/repo:*` is barely better than a static key.

package/templates/layers/security-supply-chain/files/npmrc

@@ -0,0 +1,13 @@
+# The single control that stops the postinstall worms (Shai-Hulud, chalk/debug, Nx
+# s1ngularity). Everything else in this layer detects; this one prevents.
+#
+# Cost: packages that build native code at install time now need an explicit opt-in.
+#   npm/yarn — run `npm rebuild <pkg>` after review.
+#   pnpm 10+ — already blocks scripts by default; allowlist in pnpm-workspace.yaml:
+#              onlyBuiltDependencies: [esbuild, sharp]
+# Your own `prepare` script is disabled too, so hook installers must be run explicitly.
+ignore-scripts=true
+
+# Publishing: use OIDC trusted publishing from Actions (`permissions: id-token: write`),
+# not a long-lived NPM_TOKEN. Sigstore provenance is then generated automatically — do not
+# set `provenance=true` here, it breaks any publish attempted outside CI.

package/templates/layers/security-supply-chain/files/renovate.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "config:recommended",
+    ":dependencyDashboard",
+    "helpers:pinGitHubActionDigestsToSemver"
+  ],
+  "minimumReleaseAge": "{{ depCooldownDays }} days",
+  "internalChecksFilter": "strict",
+  "osvVulnerabilityAlerts": true,
+  "vulnerabilityAlerts": {
+    "minimumReleaseAge": null,
+    "labels": ["security"]
+  },
+  "packageRules": [
+    {
+      "matchManagers": ["github-actions"],
+      "pinDigests": true,
+      "groupName": "github actions"
+    },
+    {
+      "matchUpdateTypes": ["minor", "patch"],
+      "groupName": "non-major"
+    }
+  ]
+}

package/templates/layers/testing-e2e/blueprint.yaml

@@ -0,0 +1,199 @@
+# End-to-end tests that drive a *running* deployment over HTTP.
+#
+# Paths under `files/` mirror the generated repo: plan.ts strips only the first `files/`
+# segment, so `files/e2e/config.ts` lands at `e2e/config.ts`. Per-stack folders would
+# survive that strip and land as junk directories in the output.
+id: testing-e2e
+kind: layer
+name: End-to-end tests
+description: >-
+  Playwright browser E2E for web bases and HTTP contract smoke for service bases, under one
+  layer id. Every suite drives a deployed URL rather than an in-process app, reads its target,
+  paths, and budgets from the environment, and skips instead of failing when nothing is
+  listening — so a plain unit-test run stays green on a machine with no deployment.
+
+tags:
+  - testing
+  - e2e
+  - playwright
+  - contract-testing
+  - smoke-tests
+  - quality
+
+# Nothing. Each stack's suite carries its own runner (Playwright, pytest, `go test`, xunit),
+# its own config module, and its own reachability guard, so the layer composes onto a bare
+# base. Requiring `testing-unit` would force a second runner and its config into repos that
+# only wanted a post-deploy smoke check.
+requires: []
+
+# Deliberately empty. A conflict must name a blueprint that already exists or the whole
+# catalog fails to load (loader.assertReferencesResolve), and nothing in the catalog owns
+# the same files: this layer writes only `e2e/`, `tests/e2e/`, `test/e2e/`, `tests/*.E2E/`,
+# `playwright.config.ts`, and its own dotenv sample. A competing E2E layer declares the
+# conflict from its own side — conflicts are symmetric at resolve time.
+conflicts: []
+
+# Capability names other blueprints key off instead of naming this layer. A CI layer wants
+# "there is an e2e suite to run after deploy", not "testing-e2e is installed". Nothing here
+# claims *browser* tests: that half is only true in browser mode, and a provides that is
+# sometimes false is worse than one that is absent.
+provides:
+  - e2e-tests
+  - smoke-tests
+  - e2e-config
+
+# Black-box by construction: the suite reaches the app through HTTP, so it is indifferent
+# to how the source behind that URL is arranged.
+supportsArchitectures: []
+
+variables:
+  # Web bases (nextjs-app, react-vite-spa) are `typescript`; service bases (hono-api,
+  # nestjs-api) are `node`. The monorepo base is `polyglot` and can be either, so the
+  # shape is asked rather than inferred.
+  - name: e2eMode
+    prompt: What does the E2E suite drive?
+    type: select
+    default: browser
+    required: true
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+    choices:
+      - { value: browser, label: 'A web UI — Playwright browser tests' }
+      - { value: api, label: 'An HTTP service — API contract smoke' }
+
+  - name: e2eEnvPrefix
+    prompt: Environment-variable prefix for E2E settings
+    type: string
+    default: E2E
+    required: true
+
+  # Bases listen on different ports (3000 Next/Nest, 5173 Vite, 8000 FastAPI, 8080 Go),
+  # so this is the first value to correct after generation.
+  - name: e2eBaseUrl
+    prompt: Origin the suite drives
+    type: string
+    default: http://localhost:3000
+    required: true
+
+  # Bases expose /health, /healthz, or /api/health — no default is right for all of them.
+  - name: e2eHealthPath
+    prompt: Health endpoint the contract smoke asserts on
+    type: string
+    default: /health
+    required: true
+
+  - name: e2eTimeoutMs
+    prompt: Per-test budget in milliseconds
+    type: number
+    default: 30000
+    required: true
+
+  # Retries hide flakes; one re-run separates a genuine race from a broken contract.
+  - name: e2eRetries
+    prompt: Re-runs of a failed test before it is reported
+    type: number
+    default: 1
+    required: true
+
+  - name: e2eBrowser
+    prompt: Browser engine Playwright drives by default
+    type: select
+    default: chromium
+    required: false
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+    choices:
+      - { value: chromium, label: Chromium }
+      - { value: firefox, label: Firefox }
+      - { value: webkit, label: 'WebKit (Safari engine)' }
+
+  # Empty means "something is already listening on the base URL". Playwright only manages
+  # a server when a command is given, which keeps the same suite usable against staging.
+  - name: e2eWebServerCommand
+    prompt: Command that boots the app before the suite runs (blank to drive an already-running target)
+    type: string
+    default: ''
+    required: false
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+
+  - name: dotnetTargetFramework
+    prompt: Target framework for the E2E test project
+    type: string
+    default: net10.0
+    required: false
+    when: "stack == 'dotnet'"
+
+files:
+  # ── every stack ─────────────────────────────────────────────────────────────
+  # The env names are identical across stacks; only the runner differs.
+  - from: files/.env.e2e.example
+  - from: files/docs/testing-e2e.md
+
+  # ── typescript / node / polyglot: Playwright ────────────────────────────────
+  # `.js` relative specifiers in the sources satisfy Hono's nodenext ESM, Nest's commonjs
+  # build, and the bundler resolution used by Next.js and Vite alike.
+  - from: files/playwright.config.ts
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+  - from: files/e2e/config.ts
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+
+  # Browser specs assert structure, never copy: they must stay green while the app is
+  # still being written.
+  - from: files/e2e/browser/*.spec.ts
+    when: "(stack == 'typescript' || stack == 'node' || stack == 'polyglot') && e2eMode == 'browser'"
+
+  # support.ts ships only with the contract specs that import it — an unused module in a
+  # browser-only repo is a question every reader has to answer once.
+  - from: files/e2e/api/*.spec.ts
+    when: "(stack == 'typescript' || stack == 'node' || stack == 'polyglot') && e2eMode == 'api'"
+  - from: files/e2e/support.ts
+    when: "(stack == 'typescript' || stack == 'node' || stack == 'polyglot') && e2eMode == 'api'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  # `tests/e2e/` rather than `tests/`: the unit suite owns the latter, and conftest here
+  # ignores the whole directory when the target is unreachable.
+  - from: files/tests/e2e/*.py
+    when: "stack == 'python'"
+
+  # ── go ──────────────────────────────────────────────────────────────────────
+  # Standard library only, so the package never has to know the base's module path.
+  - from: files/test/e2e/*.go
+    when: "stack == 'go'"
+
+  # ── dotnet ──────────────────────────────────────────────────────────────────
+  # Self-contained xunit.v3 project: it pins its own versions and opts out of central
+  # package management, so it drops into a repo that uses CPM and one that does not.
+  - from: files/tests/__solutionName.dot__.E2E/*
+    when: "stack == 'dotnet'"
+
+  # Code that imports a package the manifest never installs does not build (ADR 0005).
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+  # Central package management: versions live in Directory.Packages.props and projects
+  # reference without one. A bare Version= on a PackageReference fails restore (NU1008).
+  - from: files/Directory.Packages.props
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply:
+  # Manifest-only, matching the other layers: nothing here installs, so a pnpm or bun repo
+  # never gains an npm lockfile. docs/testing-e2e.md carries the install and the scripts.
+  - run: npm pkg set "devDependencies.@playwright/test"=^1.61.1
+    when: "stack == 'typescript' || stack == 'node' || stack == 'polyglot'"
+    optional: true
+
+  - run: uv add --dev "pytest>=9.1,<10" "httpx>=0.28,<1"
+    when: "stack == 'python'"
+    optional: true
+
+  # Glob expands in a POSIX shell only; docs/testing-e2e.md carries the literal command.

package/templates/layers/testing-e2e/files/.env.e2e.example

@@ -0,0 +1,32 @@
+# End-to-end test settings. Every key here has a typed default in the suite's config
+# module — set only what differs from it. Nothing in the tests reads a literal.
+
+# Origin the suite drives. Point it at a deployed environment, or at a local server.
+{{ e2eEnvPrefix }}_BASE_URL={{ e2eBaseUrl }}
+
+# Endpoint the contract smoke asserts on. Bases differ: /health, /healthz, /api/health.
+{{ e2eEnvPrefix }}_HEALTH_PATH={{ e2eHealthPath }}
+
+# Per-test budget in milliseconds.
+{{ e2eEnvPrefix }}_TIMEOUT_MS={{ e2eTimeoutMs }}
+
+# Reachability probe budget. Shorter than the test budget — it only decides run vs. skip —
+# but long enough to cover a cold HTTP client's first request.
+{{ e2eEnvPrefix }}_PROBE_TIMEOUT_MS=5000
+
+# Re-runs of a failed test before it is reported. Keep low — retries hide flakes.
+{{ e2eEnvPrefix }}_RETRIES={{ e2eRetries }}
+
+# ── Playwright only ─────────────────────────────────────────────────────────────
+# Engine to drive: chromium | firefox | webkit
+{{ e2eEnvPrefix }}_BROWSER={{ e2eBrowser }}
+{{ e2eEnvPrefix }}_HEADLESS=true
+{{ e2eEnvPrefix }}_EXPECT_TIMEOUT_MS=5000
+
+# Command that boots the app before the suite runs. Leave empty when something is
+# already listening on the base URL.
+{{ e2eEnvPrefix }}_WEB_SERVER_COMMAND={{ e2eWebServerCommand }}
+{{ e2eEnvPrefix }}_WEB_SERVER_TIMEOUT_MS=120000
+
+# Same-origin links checked on the landing page. A smoke test is not a site crawl.
+{{ e2eEnvPrefix }}_MAX_LINKS_CHECKED=10

package/templates/layers/testing-e2e/files/Directory.Packages.props

@@ -0,0 +1,7 @@
+<Project>
+  <ItemGroup>
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="18.8.1" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="3.1.5" />
+    <PackageVersion Include="xunit.v3" Version="3.2.2" />
+  </ItemGroup>
+</Project>

package/templates/layers/testing-e2e/files/__solutionName.dot__.slnx

@@ -0,0 +1,5 @@
+<Solution>
+  <Folder Name="/tests/">
+    <Project Path="tests/{{ solutionName | dot }}.E2E/{{ solutionName | dot }}.E2E.csproj" />
+  </Folder>
+</Solution>

package/templates/layers/testing-e2e/files/docs/testing-e2e.md

@@ -0,0 +1,106 @@
+# End-to-end tests
+
+This suite drives a **running deployment** over HTTP. It never imports the application,
+never touches an in-process test server, and holds no fixtures for internal state — that
+is what the unit and integration tests are for.
+
+Two shapes ship under one layer:
+
+| Shape | What it asserts | Where it runs |
+|---|---|---|
+| **Browser E2E** (Playwright) | the app renders, is navigable, and throws nothing | web bases |
+| **API contract smoke** | status codes, JSON shape stability, error hygiene | service bases |
+
+## Configuration
+
+Every value is read from the environment with a single typed default table in the suite's
+config module. No URL, path, port, or timeout appears at a call site.
+
+| Variable | Meaning |
+|---|---|
+| `{{ e2eEnvPrefix }}_BASE_URL` | origin the suite drives |
+| `{{ e2eEnvPrefix }}_HEALTH_PATH` | endpoint the contract smoke asserts on |
+| `{{ e2eEnvPrefix }}_TIMEOUT_MS` | per-test budget |
+| `{{ e2eEnvPrefix }}_PROBE_TIMEOUT_MS` | reachability probe budget (decides run vs. skip) |
+| `{{ e2eEnvPrefix }}_RETRIES` | re-runs of a failed test |
+| `{{ e2eEnvPrefix }}_BROWSER` | `chromium` \| `firefox` \| `webkit` (Playwright) |
+| `{{ e2eEnvPrefix }}_HEADLESS` | run without a visible browser (Playwright) |
+| `{{ e2eEnvPrefix }}_WEB_SERVER_COMMAND` | command that boots the app; empty = already running |
+| `{{ e2eEnvPrefix }}_MAX_LINKS_CHECKED` | link-reachability cap on the landing page |
+
+Copy `.env.e2e.example` and set what differs. **`{{ e2eEnvPrefix }}_HEALTH_PATH` is the one
+you will almost certainly change** — bases expose `/health`, `/healthz`, or `/api/health`.
+
+## Running
+
+### Playwright (TypeScript / Node)
+
+```bash
+npm install                                  # picks up @playwright/test
+npx playwright install --with-deps chromium  # once per machine and per CI image
+npx playwright test
+```
+
+Add the scripts once, so the command is the same for everyone:
+
+```json
+"test:e2e": "playwright test",
+"test:e2e:ui": "playwright test --ui"
+```
+
+Useful flags: `--ui` for the interactive runner, `--headed` to watch it, `--debug` to step,
+`npx playwright show-report` to open the last HTML report.
+
+Playwright is the one runner here that fails rather than skips when nothing is listening —
+it is never part of `npm test`, so a red run means you asked for E2E and got no target.
+
+The suite does **not** boot the app unless `{{ e2eEnvPrefix }}_WEB_SERVER_COMMAND` is set.
+Set it to your start command (for example a build-then-start line) and Playwright will start
+the server, wait for the base URL, and shut it down afterwards.
+
+### pytest (Python)
+
+```bash
+uv sync
+pytest tests/e2e
+```
+
+`tests/e2e/conftest.py` probes the base URL once at collection time. If nothing is listening
+every e2e test is marked skipped — not deselected — so a plain `pytest` stays green on a
+machine with no deployment while the report still shows the suite exists. The header line
+names the target that was probed and whether it answered.
+
+### go test (Go)
+
+```bash
+go test -tags e2e ./test/e2e/...
+```
+
+The build tag keeps `go test ./...` offline. An unreachable target skips rather than fails.
+
+### dotnet test (.NET)
+
+```bash
+dotnet test tests/*.E2E
+```
+
+Tests call `Assert.Skip` when nothing is listening, so a solution-wide `dotnet test` reports
+skipped rather than red when no environment is available.
+
+## Writing new tests
+
+- Assert the **contract**, not the content. Copy changes daily; status codes and payload
+  shapes are promises.
+- Prefer role- and label-based locators (`getByRole`, `getByLabel`) over CSS or XPath —
+  they survive restyling and assert accessibility at the same time.
+- No `sleep`. Use the runner's auto-waiting assertions; a fixed wait is either flaky or slow.
+- Keep each test independent: no shared mutable state, no ordering assumptions. The suite
+  runs in parallel.
+- One user journey per spec file. When a spec needs a comment to explain what journey it
+  covers, split it.
+
+## CI
+
+Run E2E after deploy against a real URL, not in the unit-test job — it needs a live target
+and browser binaries. Publish the HTML report and traces as artifacts; `trace: 'on-first-retry'`
+means a failure that reproduces on retry arrives with a full timeline attached.

package/templates/layers/testing-e2e/files/e2e/api/contract.spec.ts

@@ -0,0 +1,37 @@
+import { expect, test } from '@playwright/test';
+import { e2eConfig } from '../config.js';
+
+// Path that must never be routed; kept obviously synthetic so a real route cannot collide.
+const UNROUTED = '/e2e-unrouted-path-check';
+
+test.describe('http contract', () => {
+  test('unknown routes answer 404', async ({ request }) => {
+    const response = await request.get(UNROUTED);
+    expect(response.status(), `GET ${UNROUTED}`).toBe(404);
+  });
+
+  test('a not-found body carries no stack trace', async ({ request }) => {
+    const body = await (await request.get(UNROUTED)).text();
+
+    // Frame markers, not the word "error" — an error *message* in the body is fine.
+    expect(body, 'error response leaks internals').not.toMatch(/\bat\s+\S+\s+\(.*:\d+:\d+\)|Traceback/);
+  });
+
+  test('an unsupported method is rejected, not silently accepted', async ({ request }) => {
+    const response = await request.post(e2eConfig.healthPath, { data: {} });
+
+    // 405 is the correct answer; frameworks that route by method answer 404 instead.
+    expect([404, 405], `POST ${e2eConfig.healthPath} returned ${response.status()}`).toContain(
+      response.status(),
+    );
+  });
+
+  test('malformed JSON is rejected with a client error', async ({ request }) => {
+    const response = await request.post(e2eConfig.healthPath, {
+      headers: { 'content-type': 'application/json' },
+      data: '{ not json',
+    });
+
+    expect(response.status(), 'malformed body produced a server error').toBeLessThan(500);
+  });
+});

package/templates/layers/testing-e2e/files/e2e/api/health.spec.ts

@@ -0,0 +1,29 @@
+import { expect, test } from '@playwright/test';
+import { e2eConfig } from '../config.js';
+import { asJsonObject, shapeOf } from '../support.js';
+
+test.describe('health contract', () => {
+  test('answers 200 with a JSON object', async ({ request }) => {
+    const response = await request.get(e2eConfig.healthPath);
+
+    expect(response.status(), `GET ${e2eConfig.healthPath}`).toBe(200);
+    expect(Object.keys(await asJsonObject(response)).length).toBeGreaterThan(0);
+  });
+
+  test('keeps the same response shape across calls', async ({ request }) => {
+    const first = shapeOf(await asJsonObject(await request.get(e2eConfig.healthPath)));
+    const second = shapeOf(await asJsonObject(await request.get(e2eConfig.healthPath)));
+
+    expect(second, 'health payload shape drifted between calls').toEqual(first);
+  });
+
+  test('is not cached by an intermediary', async ({ request }) => {
+    const response = await request.get(e2eConfig.healthPath);
+    const cacheControl = response.headers()['cache-control'] ?? '';
+
+    // A cached probe reports a dependency that recovered minutes ago as still healthy.
+    expect(cacheControl, 'health response is cacheable for a long time').not.toMatch(
+      /max-age=(6[0-9]|[7-9][0-9]|[0-9]{3,})/,
+    );
+  });
+});

package/templates/layers/testing-e2e/files/e2e/browser/app.spec.ts

@@ -0,0 +1,27 @@
+import { expect, test } from '@playwright/test';
+
+// Deliberately content-free: this suite must stay green while the app is still being written.
+test.describe('application shell', () => {
+  test('serves the root document', async ({ page }) => {
+    const response = await page.goto('/');
+    expect(response, 'no response for /').not.toBeNull();
+    expect(response?.status() ?? 0, 'root document status').toBeLessThan(400);
+    await expect(page.locator('body')).toBeVisible();
+  });
+
+  test('declares a document language and a non-empty title', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('html')).toHaveAttribute('lang', /\S/);
+    expect((await page.title()).trim(), 'document title').not.toBe('');
+  });
+
+  test('renders without uncaught page errors', async ({ page }) => {
+    const errors: string[] = [];
+    page.on('pageerror', (error) => errors.push(error.message));
+
+    await page.goto('/');
+    await page.waitForLoadState('networkidle');
+
+    expect(errors, 'uncaught errors on the landing page').toEqual([]);
+  });
+});

package/templates/layers/testing-e2e/files/e2e/browser/navigation.spec.ts

@@ -0,0 +1,26 @@
+import { expect, test } from '@playwright/test';
+import { e2eConfig } from '../config.js';
+
+test.describe('navigation', () => {
+  test('every same-origin link on the landing page resolves', async ({ page, request }) => {
+    await page.goto('/');
+    const origin = new URL(page.url()).origin;
+
+    const hrefs = await page
+      .locator('a[href]')
+      .evaluateAll((nodes) => nodes.map((node) => (node as HTMLAnchorElement).href));
+
+    const targets = [...new Set(hrefs)]
+      .filter((href) => href.startsWith(origin))
+      // A bare fragment resolves to the page we are already on.
+      .filter((href) => new URL(href).pathname !== new URL(page.url()).pathname || !href.includes('#'))
+      .slice(0, e2eConfig.maxLinksChecked);
+
+    test.skip(targets.length === 0, 'landing page has no in-app links yet');
+
+    for (const target of targets) {
+      const response = await request.get(target);
+      expect(response.status(), `broken link: ${target}`).toBeLessThan(400);
+    }
+  });
+});