rcf-lite 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Pre-1.0, breaking changes are signalled by a minor version bump.
 
+## [Unreleased]
+
+## [0.17.0] - 2026-09-04
+
+The e2e verification contract for browser-facing projects. Verify pins `@playwright/mcp@0.0.80` with a preflight print and a `--playwright-mcp-version` override for emergency use; the effective pin lands on the report's runStats. Doctor gains four browser-facing checks (`playwright-present`, `browser-present`, `playwright-mcp-reachable`, `playwright-mcp-redundant`) routed by an applied blueprint's `browserSurface`, with a one-line skip on API-only projects. Init writes a Playwright MCP entry only when no scope-visible signature exists, falling back to a distinctly named `playwright-rcf` project-scope entry when it cannot prove absence, and opt-out via `--no-playwright-mcp`. `application-spa` v1.4.0 and `delivery-ci-workflows` v2.2.0 ship the paired `browserSurface` stories and the illustrative e2e job as a documentation contract per spec 2026-09-03 amendment A2; the runtime materialiser lands in a follow-up train.
+
+### Added
+
+- **`application-spa` v1.4.0 and `delivery-ci-workflows` v2.2.0: e2e as a declared test level.** The SPA blueprint's manifest carries a new top-level `browserSurface` object (`{ declared: true, routes: [...], themes: [...] }`) and contributes two browser-facing acceptance criteria via new stories `application-spa-US-1134` (icon renders on the home route across declared themes; binds `application-spa-REQ-011`) and `application-spa-US-1135` (unauthenticated visit to a protected route lands on the sign-in page; binds `application-spa-REQ-009`). A paste-in `assets/tc-templates/e2e.md` ships the `testLevel: e2e` test-case shape and names `rcf verify browser` as the driver seam so the same Playwright installation the invariants use drives the coverage anchor. The `delivery-ci-workflows` blueprint contributes `US-6124` binding `AC-6124-1` on the `e2e` elicited check: the materialised `pull-request-checks` workflow contains a distinct `e2e` job (runs `testLevel: e2e` cases against a local preview or a `--parity-env` runtime, uploads screenshots and HTML captures, writes `.rcf/reports/ci/e2e.json` with `checkKind: "e2e"`) iff at least one applied blueprint declares `.browserSurface.declared: true` and `checkSet.e2e` is not explicitly false. The illustrative GHA `pull-request-checks.yml` and the alternate-provider `notes.md` (GitLab CI, CircleCI, Buildkite, Jenkins) each ship the e2e job as a documented example. `browserSurface` lives on the source `blueprint.json` only: the applied blueprint record carries no new field (the `appliedBlueprintRecord` schema in rcf-schemas 0.5.1 is `additionalProperties: false`); doctor and any workflow-materialiser both read `browserSurface` from the applied record's `source` reference. See CONCERNS in the shipping PR: an additive schema field on `appliedBlueprintRecord` is a separate rcf-schemas release, deliberately outside this train. Trace: spec 2026-09-03, section 2; chain: `packages/rcf-lite/rcf/user-stories/us-1102.json` on REQ-011.
+
+- **`rcf init` writes a Playwright MCP entry only when no scope-visible entry exists.** Detection is by command signature: any `mcpServers[<name>].args` string whose command tail matches `/^@playwright\/mcp(@|$)/` (spec 4.1). If the project-scope `.mcp.json` carries one, init leaves it alone and prints the key. Otherwise init shells out to `claude mcp list` (5-second timeout, text-output parser) and, if it finds a Playwright entry at any scope the harness reports, prints the scope and writes nothing. When init cannot prove the absence of a user-scope entry (no `claude` on PATH, non-zero exit, output unparseable) it writes a distinctly named `playwright-rcf` project-scope entry that shadows nothing by naming convention, and prints the `could not probe` notice explaining what it did and how to opt out. `rcf init --no-playwright-mcp` suppresses the write step entirely; the probe still runs so the print-out remains honest. Every probe is injectable via `deps.probeClaudeCodeMcp` for tests. Trace: spec 2026-09-03, section 4; chain: `packages/rcf-lite/rcf/user-stories/us-1104.json` on REQ-011.
+
+- **`rcf doctor` checks Playwright and a browser on browser-facing projects.** `@playwright/mcp` and `playwright` are declared as optional peer dependencies (`peerDependenciesMeta.<pkg>.optional: true`) in `packages/rcf-lite/package.json` so npm and pnpm do not fail install when they are absent. Doctor adds four checks routed through `src/setup/playwright-checks.js`: `playwright-present` (`require.resolve('playwright', { paths: [projectRoot] })`), `browser-present` (system Chrome on PATH, then a Playwright-managed cache directory, then `npx --no-install @playwright/mcp browser-status --json` as a first-party fall-back), `playwright-mcp-reachable` (`npx --no-install @playwright/mcp --help`, 15-second diagnostic ceiling), and `playwright-mcp-redundant` (project-scope + user-scope shadowing, browser-facing only, no `--fix`). The three run only when at least one applied blueprint's source `blueprint.json` declares `browserSurface`; non-browser-facing projects print one skip line naming the three checks. Passing a Playwright check name to `--check` on an API-only project overrides the skip. All probes are injectable via `deps.*Impl` seams so the unit suite runs without any of these tools installed. Trace: spec 2026-09-03, section 3 + 4.5; chain: `packages/rcf-lite/rcf/user-stories/us-1103.json` on REQ-011.
+
+- **Verify pins the Playwright MCP version.** `rcf verify run` no longer provisions `npx -y @playwright/mcp@latest`; the launcher composes the pin from an exported `PLAYWRIGHT_MCP_VERSION` constant in `packages/rcf-lite/src/verify/engine/launcher.js` and the DEFAULT_MCP_CONFIG is a `playwrightMcpConfig(PLAYWRIGHT_MCP_VERSION)` composition. Preflight prints `Playwright MCP: pinned to @playwright/mcp@<version>` on stderr; the effective pin (default or overridden) lands on the report as `run.runStats.playwrightMcpVersion` so a report re-render tells the operator which browser tooling this pass ran against. `--playwright-mcp-version <semver>` overrides the pin for one run (emergency use only), fires a loud stderr override notice, and refuses exit 2 with `--playwright-mcp-version expects a semver string, got '<value>'` on a non-semver value. Bump discipline: a pin change is a deliberate rcf-lite change, with its own commit, its own CHANGELOG line, and, where behaviour is affected, a re-run of the verify test set against the pinned tooling. Trace: `projects/rcf-lite-wsd/specs/rcf-lite-e2e-contract-spec-2026-09-03.md`, section 1; chain: `packages/rcf-lite/rcf/user-stories/us-1101.json` on REQ-011.
+
+## [0.16.0] - 2026-09-03
+
+External blueprint libraries complete. Phase 2c lands git and tarball fetchers with a checked-in on-disk cache so a fresh clone lists library blueprints without a re-fetch, and a refresh path that re-resolves annotated-tag or tarball digest and refuses on drift. Amendment A2 makes plain-path adds library-aware so an author's local edit loop stamps the same effective slug and identity a qualified add would. Amendment A3 adds a blueprint paragraph to the managed agent-instructions block so the agent conversationally offers blueprints and registered libraries and the operator chooses. A library-authoring standard doc plus a worked-example fixture binds the doc against the shipped tooling.
+
+### Added
+
+- **External blueprint libraries phase 2c: git and tarball fetchers + on-disk cache.** `rcf define blueprint library add` now accepts `git+<url>#<annotated-tag-or-sha>` and tarball URLs (with `--sha256 <hex>` for the pin). Fetched content lands under `rcf/.blueprint-libraries/<libraryPrefix>/<libraryRef>/`, checked into git as ordinary tree content so a fresh clone can `rcf define blueprint list` without a re-fetch (spec section 4.4). Floating branches (`main`, `master`, `HEAD`, `latest`, `develop`, `trunk`) refuse categorically; lightweight tags refuse with a diagnostic pointing at annotation as the fix; a tarball digest mismatch refuses the fetch and writes nothing. `rcf define blueprint library refresh <prefix>` re-resolves the tag's peeled commit (git) or re-downloads and re-verifies the digest (tarball) and refuses on drift per spec sections 6.4 / 9.12. `rcf define blueprint library remove <prefix>` now drops the on-disk cache for network sources. Zero new runtime dependencies: the git side shells out to the ambient `git` CLI; the tarball side uses built-in `fetch()`, `zlib`, and a bundled minimal POSIX-ustar parser. Auth remains out of scope for v1 (spec section 9.4): ambient git access is the model, no-access is definitive.
+- **Amendment A2: library-aware local path (2026-09-03).** `rcf define blueprint add <path>` now walks up from the target directory looking for `library.json`; on a hit the resolver requires the target to sit at `<library-root>/blueprints/<slug>` and stamps the same effective slug and identity a qualified `<prefix>:<slug>` add would after registration. Library-qualified addressing and plain-path addressing now produce identical slugs and stamped ids. A path with no `library.json` in any ancestor keeps the phase-1 route unchanged, byte-for-byte. The trade-off (spec: an unregistered local library bypasses review-on-add) is accepted because the alternative kills the "author now, test now" loop; the `local` provenance warning on apply is the mitigation.
+- **Amendment A3: blueprint paragraph in the managed agent-instructions block (2026-09-03).** New paragraph inside the "How to talk to your operator" section teaches the plain-language shape: agent enumerates blueprints and registered libraries and offers one that fits; the operator chooses, the agent never picks; qualified names and command lines belong in files and `rcf` output, not in the conversation. Hash regenerated via `scripts/gen-managed-artefacts.mjs`; harness template mirrored automatically.
+- **Library authoring standard doc.** `packages/rcf-lite/docs/library-authoring.md` documents the library shape, `library.json` field contract, prefix and band rules, the local-path authoring loop (A2), registration, refresh / drift, and interaction with core. Ships with a minimum-viable worked-example library at `test/fixtures/library-authoring-example/` (prefix `wla`, one blueprint with one REQ and one ADR) that doubles as the fixture body for `test/blueprint/library-authoring-example.test.js`; the fixture binds the doc against the shipped tooling so a drift in either trips the suite.
+
 ## [0.15.0] - 2026-08-31
 
 Same-evening fix wave on top of 0.14.0. Four PRs closing off the WSD-handover surface: durable library-ownership stamping on applied records (paired with `@stravica-ai/rcf-schemas` 0.5.1), `blueprint supersede --incoming` accepting the same source forms as `add`, the review-on-add card gaining its section 8.1 global-topics and prefix-check lines, and the `delivery-ci-workflows` v2.1 additive shape resolving the four P1 findings from the second dogfood run.

package/blueprints/application-spa/assets/tc-templates/e2e.md

@@ -0,0 +1,85 @@
+# e2e test-case template (application-spa blueprint)
+
+A paste-in shape for a `testLevel: e2e` test suite plus one test case bound
+to a browser-facing acceptance criterion contributed by this blueprint.
+Copy the fenced blocks into your project chain, fill in the placeholders,
+and author the pointed-to test file under `tests/e2e/`.
+
+This template is the driver-seam contract between blueprint-contributed
+browser-facing ACs and the project's e2e suite. It uses the same
+`rcf verify browser` driver seam the browser-verify pack uses, so the
+same Playwright installation the invariants drive against also drives
+the e2e case (one browser, two responsibilities).
+
+## What this covers, and what it does not
+
+- **Covers:** the AC end to end at a user-observable browser surface. One
+  test case per AC. Sits in the project chain as coverage that
+  `rcf audit coverage --strict` reads, and runs in the pull-request-checks
+  `e2e` CI job the delivery-ci-workflows blueprint materialises.
+- **Does not cover:** every rendering variation the browser-verify
+  invariants already cover. If the concern is "is the CSP stamped
+  correctly?" or "does the layout reflow at 360px?", write it as an
+  invariant on the browser-verify TAC, not as a project e2e test.
+
+## Test-suite shape
+
+```json
+{
+  "tsId": "TS-N01-application-spa-e2e",
+  "prdId": "PRD-001",
+  "reqId": "application-spa-REQ-011",
+  "version": "1.0.0",
+  "status": "draft",
+  "title": "Application e2e",
+  "description": "End-to-end test cases against the shipped application, driven by a real browser through the browser-verify driver seam. One test case per browser-facing AC.",
+  "testLevel": "e2e",
+  "testCases": [
+    {
+      "id": "TC-N01-nav-renders-home-signed-in",
+      "description": "Primary-nav icon renders at the expected size on the home route in a real browser across the SPA blueprint's declared themes",
+      "acCoverage": ["application-spa-AC-1134-1"],
+      "testPointer": "tests/e2e/nav.spec.js::navRendersOnHomeSignedIn",
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "<ISO-8601>",
+  "updatedAt": "<ISO-8601>"
+}
+```
+
+## Test file shape (Playwright, project-owned)
+
+```js
+// tests/e2e/nav.spec.js
+// Driven through the same Playwright installation the browser-verify TAC
+// uses. `rcf verify browser <fbs-id>` covers the invariant sweep on this
+// page; this file covers the AC end to end.
+
+import { test, expect } from '@playwright/test';
+
+test('nav renders on home signed in', async ({ page }) => {
+  await page.goto('/');
+  const icon = page.locator('[data-nav-icon="primary"]');
+  await expect(icon).toBeVisible();
+  const box = await icon.boundingBox();
+  // Read from the project's iconAlias size token for the primary-nav slot.
+  expect(box.width).toBe(24);
+  expect(box.height).toBe(24);
+});
+```
+
+## The driver seam, in one sentence
+
+The e2e test drives the app through the same Playwright installation that
+the browser-verify pack drives, so the invariant sweep and the coverage
+anchor run against the same shipped runtime and the same headless browser.
+When `@playwright/mcp` is pinned in `rcf verify run`, the same pin is what
+CI installs to run this file.
+
+## Non-goal
+
+The e2e case is the coverage anchor for one AC. It is not the place to
+enumerate every rendering variation the browser-verify invariants already
+cover, and it is not a substitute for a `rcf verify run` pass at the ship
+gate. Both run in CI; neither replaces the other.

package/blueprints/application-spa/blueprint.json

@@ -1,6 +1,6 @@
 {
   "slug": "application-spa",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "category": "application",
   "contributions": [
     {
@@ -273,6 +273,16 @@
       "kind": "us",
       "path": "user-stories/application-spa-us-1133.json"
     },
+    {
+      "id": "application-spa-US-1134",
+      "kind": "us",
+      "path": "user-stories/application-spa-us-1134.json"
+    },
+    {
+      "id": "application-spa-US-1135",
+      "kind": "us",
+      "path": "user-stories/application-spa-us-1135.json"
+    },
     {
       "id": "TAC-201-application-spa-app-shell",
       "kind": "tac",
@@ -383,5 +393,17 @@
       "kind": "adr",
       "path": "adrs/adr-209-application-spa-telemetry-naming.json"
     }
-  ]
+  ],
+  "browserSurface": {
+    "declared": true,
+    "routes": [
+      "/",
+      "/sign-in",
+      "/dashboard"
+    ],
+    "themes": [
+      "light",
+      "dark"
+    ]
+  }
 }

package/blueprints/application-spa/contributions/user-stories/application-spa-us-1134.json

@@ -0,0 +1,24 @@
+{
+  "usId": "application-spa-US-1134",
+  "prdId": "PRD-001",
+  "reqId": "application-spa-REQ-011",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Primary-nav icon renders at the expected size across declared themes on the home route in a browser (e2e)",
+  "asA": "operator relying on the iconography discipline the application-spa blueprint declares",
+  "iWant": "an end-to-end test that a real browser navigating the home route of the shipped application observes the primary-navigation icon rendered at the expected size across every theme declared on the blueprint's browserSurface",
+  "soThat": "the iconography discipline (application-spa-REQ-011: one icon set, consistent construction, semantic aliases) is verified end-to-end at a user-observable surface rather than assumed from component-library conformance alone",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1134-1",
+      "description": "The icon at the primary navigation slot renders at the expected size across all declared themes when the app loads its home route in a browser. Verification navigates a real browser through the same production entry-point construction the app ships (no header-stripping harness, no app.inject substitute), reads the rendered icon's computed bounding box, and asserts it equals the blueprint's iconAlias size token for that slot. A rendered box that resolves to the browser default (or to zero) refuses ship with a per-theme diagnostic naming the observed and expected sizes.",
+      "given": "the application booted through its production entry point with the primary navigation registered on the home route",
+      "when": "a real browser loads / in each theme declared on the blueprint's browserSurface and getBoundingClientRect() is read for the primary-nav icon",
+      "then": "the icon's rendered box equals the iconAlias size token for the primary-nav slot in every theme; a mismatch, a zero-size box, or a missing icon refuses ship with a per-theme diagnostic",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "2026-09-03T17:00:00Z",
+  "updatedAt": "2026-09-03T17:00:00Z"
+}

package/blueprints/application-spa/contributions/user-stories/application-spa-us-1135.json

@@ -0,0 +1,24 @@
+{
+  "usId": "application-spa-US-1135",
+  "prdId": "PRD-001",
+  "reqId": "application-spa-REQ-009",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Unauthenticated visit to a protected route lands on the sign-in page in a browser (e2e)",
+  "asA": "operator relying on the auth-surface discipline the application-spa blueprint declares",
+  "iWant": "an end-to-end test that a real browser making an unauthenticated request against a protected route in the shipped application lands on the sign-in page rather than the protected surface",
+  "soThat": "the arrival-and-auth discipline (application-spa-REQ-009: landing, sign-in, sign-out, expiry, recovery, onboarding, deep-link redirects) is verified end-to-end at a user-observable surface. Verify's auth-smoke pass is adversarial and complementary; this e2e case is the coverage anchor.",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-1135-1",
+      "description": "An unauthenticated visit to a protected route lands on the sign-in page in a browser. Verification navigates a real browser (fresh context, no persisted session, no injected cookies) to a protected route the blueprint declares under browserSurface.routes, and asserts the browser's final URL path is the sign-in route rather than the protected route. The check drives the same server construction the production entry point boots (no header-stripping harness, no app.inject substitute). A landing path equal to the requested route, or to any other page, refuses ship with a diagnostic naming the requested, landed and expected sign-in paths.",
+      "given": "the application booted through its production entry point with a protected route and a sign-in route both registered",
+      "when": "a real browser with no session state navigates to the protected route",
+      "then": "the browser's final URL path equals the sign-in route path; any other landing (protected route rendered without auth, arbitrary other page, error page) refuses ship with a diagnostic naming requested, landed and expected paths",
+      "testable": true,
+      "scope": "deployed"
+    }
+  ],
+  "createdAt": "2026-09-03T17:00:00Z",
+  "updatedAt": "2026-09-03T17:00:00Z"
+}

package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/github-actions/pull-request-checks.yml

@@ -72,3 +72,72 @@ jobs:
           path: .rcf/reports/ci/
           if-no-files-found: warn
           retention-days: 30
+
+  # e2e job (delivery-ci-workflows v2.2.0, application-spa v1.4.0):
+  # documentation contract per spec 2026-09-03 amendment A2. rcf-lite ships
+  # no workflow-materialiser at this train, so this block is copy-paste
+  # documentation for browser-facing projects, not runtime output. A
+  # non-browser project deletes this whole `e2e:` block (from the comment
+  # above down to the last step of the job) before committing; a browser
+  # project keeps it. The runtime iff wiring, which will add or omit this
+  # job based on `manifest.blueprints[].source.browserSurface.declared` on
+  # any applied blueprint AND
+  # `.rcf/config/delivery-ci-workflows.json:checkSet.e2e` not being
+  # explicitly false, lands in a follow-up train with its own TS entry.
+  #
+  # The job runs the project's testLevel: e2e cases against a local preview
+  # (or a --parity-env runtime) driven through the same Playwright
+  # installation `rcf verify browser` uses, uploads screenshots and HTML
+  # captures as workflow artefacts, and writes .rcf/reports/ci/e2e.json with
+  # `checkKind: "e2e"` so the aggregate pipeline report renders the e2e row
+  # separately from unit and integration.
+  e2e:
+    if: ${{ true }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: checkout
+        uses: actions/checkout@v4
+
+      # @@RCF-SUB-PKG-MGR-SETUP-BEGIN@@
+      - name: setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: setup node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+      # @@RCF-SUB-PKG-MGR-SETUP-END@@
+
+      # @@RCF-SUB-PKG-MGR-INSTALL-BEGIN@@
+      - name: install dependencies
+        run: pnpm install --frozen-lockfile
+      # @@RCF-SUB-PKG-MGR-INSTALL-END@@
+
+      # rcf-lite pins @playwright/mcp so the same browser tooling drives the
+      # e2e suite and `rcf verify browser`. Install the browser locally.
+      - name: install playwright browser
+        run: pnpm exec playwright install chromium --with-deps
+
+      # The project-owned e2e runner. It spawns whichever runner the project
+      # realises (Playwright test, Node --test with the browser-verify seam,
+      # Cypress, etc.), writes .rcf/reports/ci/e2e.json with checkKind:
+      # "e2e", and exits non-zero on any failing case.
+      - name: run e2e suite
+        run: node scripts/rcf-ci-e2e.js
+
+      - name: upload e2e browser artefacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: pull-request-checks-e2e-artefacts
+          path: |
+            .rcf/reports/ci/e2e.json
+            playwright-report/
+            test-results/
+          if-no-files-found: warn
+          retention-days: 30

package/blueprints/delivery-ci-workflows/assets/ci-provider-examples/notes.md

@@ -2,6 +2,24 @@
 
 The blueprint ships one illustrative provider example (GitHub Actions, four workflow files under `github-actions/`). Every mainstream provider hosts the same workflow set by translating four points per workflow and keeping the Node entry-point invocations unchanged. These notes are read alongside `guide/delivery-ci-workflows.md`, not instead of it.
 
+## The e2e job (v2.2.0)
+
+When a project applies at least one blueprint declaring `.browserSurface.declared: true` on its source `blueprint.json` (for example `application-spa` v1.4.0), the workflow-materialiser adds an `e2e` job to `pull-request-checks`. The GitHub Actions shape ships in `github-actions/pull-request-checks.yml`. Every provider hosts the same job by translating four points:
+
+1. **Trigger.** Same trigger as the check-set job on the same workflow; the e2e job is a peer, not a separate workflow.
+2. **Browser tooling install.** After Node + package-manager setup, install a Playwright browser: `npx playwright install chromium --with-deps` (or the provider's equivalent). rcf-lite pins `@playwright/mcp` for `rcf verify`; the same browser installation drives the project's e2e suite.
+3. **Runner invocation.** `node scripts/rcf-ci-e2e.js` (the project-owned e2e runner; writes `.rcf/reports/ci/e2e.json` with `checkKind: "e2e"`).
+4. **Browser-artefact upload.** Upload screenshots and HTML captures alongside the per-gate report so a failing run has visible evidence.
+
+The four provider translations follow the same substitution shape as the check-set job:
+
+- **GitLab CI.** Add an `e2e` job in `.gitlab-ci.yml`; `image: mcr.microsoft.com/playwright:v1.50.0-noble` or install chromium via `apt-get` then `npx playwright install`; invoke `node scripts/rcf-ci-e2e.js`; upload with `artifacts: { when: always, paths: [.rcf/reports/ci/e2e.json, playwright-report/, test-results/] }`.
+- **CircleCI.** Add an `e2e` job in `.circleci/config.yml`; `- browser-tools/install-browser-tools` orb + `npx playwright install chromium`; invoke as above; `store_artifacts: { path: playwright-report }` plus `store_artifacts: { path: .rcf/reports/ci/e2e.json }`.
+- **Buildkite.** Add an `e2e` step; install chromium via the pipeline setup hook or a Docker plugin (`docker#v5.0.0`); invoke as above; `artifact_paths: [".rcf/reports/ci/e2e.json", "playwright-report/**", "test-results/**"]`.
+- **Jenkins.** Add an `e2e` stage; install chromium via `sh 'npx playwright install chromium --with-deps'`; invoke as above; `archiveArtifacts artifacts: '.rcf/reports/ci/e2e.json, playwright-report/**, test-results/**', allowEmptyArchive: true`.
+
+Projects that apply no browser-facing blueprint delete the `e2e` job from the workflow (or the materialiser omits it on regeneration); the workflow reads byte-identical to a 2.1 project in that case.
+
 ## The workflow set the matrix materialises
 
 Which workflow files exist depends on `workflowShape`: