@1aboveio/skills 0.10.0

package/skills/cicd-pipeline/mergify/scripts/watch-pr-delivery.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from './watch-pr-delivery-core.mjs'
+
+runCli(process.argv.slice(2)).then((code) => { process.exitCode = code })

package/skills/cicd-pipeline/podman/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/cicd-pipeline/podman/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: podman
+description: "Debug, design, or fix Podman: rootless/rootful containers, pods, podman-compose, the socket and systemd services, Docker-compatible API (DOCKER_HOST/CONTAINER_HOST), networking, volumes, SELinux labels, Docker migration, and CI/SSH provisioning of rootless sockets (user lingering, XDG_RUNTIME_DIR). Covers FailedToOpenSocket and systemctl --user DBUS/XDG errors."
+---
+
+# Podman Operations
+
+## Core Rule
+
+Treat Podman as its own container runtime first. Use Docker-compatible behavior deliberately, and always verify whether a problem belongs to Podman itself, the compatibility socket/API, networking, storage, SELinux, or compose translation.
+
+## Decision Path
+
+1. Classify the environment.
+   - Rootless or rootful.
+   - Direct `podman` CLI, `podman-compose`, or Docker-compatible API.
+   - Single containers, pods, or compose-managed services.
+   - For the triage checklist, read [troubleshooting.md](references/troubleshooting.md).
+
+2. If Docker-compatible tooling is involved, verify the socket/API layer.
+   - Prefer explicit `DOCKER_HOST` over assuming `/var/run/docker.sock`.
+   - Mount socket directories instead of socket files when a container needs access to a rootless socket.
+   - Keep the API service lifetime explicit when long-lived clients depend on it.
+   - A systemd `User=` **system** service does not get `XDG_RUNTIME_DIR`; set it (or `CONTAINER_HOST`/`DOCKER_HOST`) in a unit drop-in to reach that user's rootless socket. Provisioning `systemctl --user` over SSH needs explicit `XDG_RUNTIME_DIR` + `DBUS_SESSION_BUS_ADDRESS` and lingering on.
+   - For details, read [rootless-services-and-sockets.md](references/rootless-services-and-sockets.md).
+
+3. If ports or connectivity fail, inspect Podman networking before changing application code.
+   - Check port publishing, rootless networking backend, host/container address assumptions, pod membership, and DNS.
+   - For details, read [networking-and-ports.md](references/networking-and-ports.md).
+
+4. If compose behavior differs from Docker Compose, isolate compose translation from runtime behavior.
+   - Compare generated containers, pods, networks, volume mounts, environment variables, and health checks.
+   - For details, read [compose-compatibility.md](references/compose-compatibility.md).
+
+## Fast Checks
+
+Inspect runtime mode and version:
+
+```bash
+podman info
+podman version
+podman system connection list
+```
+
+Inspect containers, pods, networks, and published ports:
+
+```bash
+podman ps -a
+podman pod ps
+podman network ls
+podman port --all
+```
+
+Verify the rootless socket from the host:
+
+```bash
+systemctl --user status podman.socket podman.service
+test -S /run/user/$(id -u)/podman/podman.sock
+curl --unix-socket /run/user/$(id -u)/podman/podman.sock \
+  http://localhost/v4.0.0/libpod/info
+```
+
+## Review Heuristics
+
+- Do not hide Podman runtime issues by hard-coding fixed host ports or privileged containers.
+- Do not mount a rootless socket file directly when the socket may be restarted; mount the socket directory.
+- Do not assume Docker Compose behavior maps exactly to `podman-compose`; inspect the realized containers.
+- Persist socket, service, SELinux, and network fixes in provisioning or preflight code.
+- Validate fixes with live `podman` commands, not only static config review.
+

package/skills/cicd-pipeline/podman/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Podman"
+  short_description: "Podman runtime diagnostics"
+  default_prompt: "Use $podman to diagnose and fix a Podman container, socket, network, compose, or rootless service issue."

package/skills/cicd-pipeline/podman/assets/templates/podman-compose-socket-directory.yml

@@ -0,0 +1,6 @@
+# Compose fragment for a container that needs rootless Podman's Docker-compatible API.
+# Mount the socket directory rather than the socket file so socket restarts do not stale the mount.
+environment:
+  DOCKER_HOST: "unix:///run/user/1000/podman/podman.sock"
+volumes:
+  - /run/user/1000/podman:/run/user/1000/podman:z

package/skills/cicd-pipeline/podman/assets/templates/podman-service-override.conf

@@ -0,0 +1,3 @@
+[Service]
+ExecStart=
+ExecStart=/usr/bin/podman system service --time=0

package/skills/cicd-pipeline/podman/references/compose-compatibility.md

@@ -0,0 +1,70 @@
+# Compose Compatibility
+
+Use this reference when `podman-compose` or `docker compose` against a Podman socket behaves differently from Docker Compose.
+
+## Debug The Realized State
+
+Do not rely only on the compose file. Inspect what Podman actually created:
+
+```bash
+podman ps -a
+podman pod ps
+podman network ls
+podman volume ls
+podman inspect <container>
+```
+
+Check:
+
+- container names
+- pod membership
+- networks and DNS names
+- published ports
+- bind mounts and SELinux labels
+- environment variables
+- health check command and status
+
+## Environment Loading
+
+`podman-compose` behavior around `.env` files and shell environment may differ from Docker Compose. If substitution is unreliable, explicitly load environment variables before invoking compose:
+
+```bash
+set -a
+. ./.env
+set +a
+podman-compose up -d
+```
+
+## Socket-Based Docker Compose
+
+Some environments use Docker Compose as a client against Podman's Docker-compatible API:
+
+```bash
+export DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock"
+docker compose up -d
+```
+
+When doing this, validate the API service and socket first with [rootless-services-and-sockets.md](rootless-services-and-sockets.md).
+
+## Health Checks
+
+If compose waits forever or reports unhealthy:
+
+```bash
+podman inspect <container> --format '{{json .State.Health}}'
+podman logs <container>
+```
+
+Confirm the image contains the health-check binary. For example, `pg_isready` exists in official Postgres images, but a minimal custom image may not include the tool your compose file expects.
+
+## SELinux Volume Labels
+
+On SELinux systems, bind mounts often need labels:
+
+```yaml
+volumes:
+  - ./data:/var/lib/app:z
+```
+
+Use `:z` for shared access and `:Z` for private relabeling. Avoid relabeling system paths.
+

package/skills/cicd-pipeline/podman/references/networking-and-ports.md

@@ -0,0 +1,74 @@
+# Networking And Ports
+
+Use this reference when Podman containers cannot connect to each other, host services are unreachable, or published ports collide.
+
+## Inspect Networking
+
+```bash
+podman network ls
+podman network inspect <network>
+podman pod ps
+podman ps --format 'table {{.Names}}\t{{.Networks}}\t{{.Ports}}'
+podman port --all
+```
+
+## Port Publishing
+
+Avoid fixed host ports when multiple containers may run concurrently on the same host:
+
+```bash
+podman run -p 5432 postgres:17
+```
+
+Podman will choose an available host port. Discover it with:
+
+```bash
+podman port <container> 5432
+```
+
+Use fixed ports only when the host owns that port and concurrency is impossible:
+
+```bash
+podman run -p 5432:5432 postgres:17
+```
+
+## Rootless Host Reachability
+
+Rootless networking can differ by Podman version and backend. Validate the actual host alias instead of assuming Docker behavior:
+
+```bash
+podman run --rm alpine getent hosts host.containers.internal
+podman run --rm alpine sh -c 'ip route && cat /etc/resolv.conf'
+```
+
+If a container needs to reach a host service, test from inside a minimal container on the same network:
+
+```bash
+podman run --rm --network <network> curlimages/curl:latest \
+  curl -v http://host.containers.internal:<port>
+```
+
+## Pods
+
+Containers in the same pod share a network namespace. Publish pod ports on the pod, then add containers:
+
+```bash
+podman pod create --name app-pod -p 8080:8080
+podman run -d --pod app-pod --name app app-image
+podman run -d --pod app-pod --name sidecar sidecar-image
+```
+
+Do not debug pod members as if each has independent port publishing.
+
+## DNS And Service Names
+
+For named containers on a user-defined network:
+
+```bash
+podman network create app-net
+podman run -d --name db --network app-net postgres:17
+podman run --rm --network app-net alpine getent hosts db
+```
+
+If DNS fails, inspect the network backend and generated container/network configuration.
+

package/skills/cicd-pipeline/podman/references/rootless-services-and-sockets.md

@@ -0,0 +1,156 @@
+# Rootless Services And Sockets
+
+Use this reference when long-running tools, nested containers, or Docker-compatible clients need to reach rootless Podman through a socket.
+
+## Socket Paths
+
+Rootless Podman usually exposes the API at:
+
+```bash
+/run/user/$(id -u)/podman/podman.sock
+```
+
+Rootful Podman commonly uses:
+
+```bash
+/run/podman/podman.sock
+```
+
+Prefer explicit environment configuration for Docker-compatible clients:
+
+```bash
+export DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock"
+```
+
+## Mount Directory, Not Socket File
+
+When a container needs access to a rootless Podman socket, mount the socket directory rather than the socket file:
+
+```yaml
+environment:
+  DOCKER_HOST: "unix:///run/user/1000/podman/podman.sock"
+volumes:
+  - /run/user/1000/podman:/run/user/1000/podman:z
+```
+
+Use `assets/templates/podman-compose-socket-directory.yml` for a copyable compose fragment.
+
+Why:
+
+- Socket activation can replace the socket inode.
+- A direct file mount can become stale after `podman.socket` restarts.
+- A directory mount lets the container see the replacement socket.
+
+## Keep The API Service Alive
+
+The socket-activated API service can exit after an idle timeout. If long-lived clients need stable access, install a user-level override:
+
+```bash
+mkdir -p ~/.config/systemd/user/podman.service.d
+cat > ~/.config/systemd/user/podman.service.d/override.conf <<'EOF'
+[Service]
+ExecStart=
+ExecStart=/usr/bin/podman system service --time=0
+EOF
+
+systemctl --user daemon-reload
+systemctl --user restart podman.socket
+systemctl --user restart podman.service
+```
+
+Use `assets/templates/podman-service-override.conf` for the override file.
+
+Persist this in provisioning or preflight. Make it idempotent:
+
+- write the override if missing or changed
+- run `systemctl --user daemon-reload` only after changes
+- start `podman.socket`
+- start or restart `podman.service`
+- verify the socket exists
+
+## Reaching A Rootless Socket From A System Service (`User=`)
+
+A common deploy shape: a long-running binary runs as a **systemd system service** with
+`User=svcuser` and needs to reach `svcuser`'s **rootless** Podman socket.
+
+Failure signature — the client falls back to `http://localhost` because it has no
+socket path:
+
+```
+Error: Was there a typo in the url or port?
+  path: "http://localhost/v4.0.0/libpod/pods/create"  code: FailedToOpenSocket
+```
+
+Cause: a `User=` **system** unit is not a user unit, so systemd does **not** set
+`XDG_RUNTIME_DIR`. The Podman/Docker client then builds an empty
+`$XDG_RUNTIME_DIR/podman/podman.sock` path and fails.
+
+Fix — make the socket path explicit in a drop-in (pick one):
+
+```ini
+# /etc/systemd/system/<svc>.service.d/podman.conf
+[Service]
+# either point XDG_RUNTIME_DIR at the user's runtime dir...
+Environment=XDG_RUNTIME_DIR=/run/user/<uid>
+# ...or set the client host directly (equivalent, more explicit):
+# Environment=CONTAINER_HOST=unix:///run/user/<uid>/podman/podman.sock
+# Environment=DOCKER_HOST=unix:///run/user/<uid>/podman/podman.sock
+```
+
+Then `daemon-reload` and restart the service. The user's `podman.socket` must also be
+running and lingering enabled (next section). Compute `<uid>` at provision time
+(`id -u svcuser`) — do not hard-code 1000.
+
+## Enabling A User Socket Non-Interactively (provisioning / SSH)
+
+`systemctl --user …` run via `sudo` over SSH (no login session) fails with:
+
+```
+Failed to connect to user scope bus via local transport:
+  $DBUS_SESSION_BUS_ADDRESS and $XDG_RUNTIME_DIR not defined
+```
+
+There is no user D-Bus/session for the target user in that context. Provide both
+explicitly (lingering must be on so `/run/user/<uid>` exists):
+
+```bash
+sudo loginctl enable-linger svcuser
+UID_AG=$(id -u svcuser)
+sudo -u svcuser \
+  XDG_RUNTIME_DIR=/run/user/$UID_AG \
+  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$UID_AG/bus \
+  systemctl --user enable --now podman.socket
+```
+
+(`machinectl shell svcuser@` is an alternative that sets up the session for you.)
+Make this idempotent in provisioning: enable-linger → enable+start `podman.socket`
+with explicit env → verify the socket file exists.
+
+## Validation
+
+```bash
+systemctl --user status podman.socket podman.service
+curl --unix-socket /run/user/$(id -u)/podman/podman.sock \
+  http://localhost/v4.0.0/libpod/info
+```
+
+For a system service that uses the drop-in above, confirm it resolved the socket
+(not `http://localhost`) in its own logs after restart.
+
+For Docker-compatible clients:
+
+```bash
+DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock" docker version
+```
+
+For stability after socket/service changes:
+
+```bash
+for i in 1 2 3 4 5; do
+  DOCKER_HOST="unix:///run/user/$(id -u)/podman/podman.sock" \
+    docker version --format '{{.Server.Version}}' >/dev/null || exit 1
+  sleep 1
+done
+echo stable
+```
+

package/skills/cicd-pipeline/podman/references/troubleshooting.md

@@ -0,0 +1,98 @@
+# Podman Troubleshooting
+
+Use this reference for general Podman failures before applying targeted fixes.
+
+## First Classification
+
+Answer these before editing configuration:
+
+- Is Podman running rootless or rootful?
+- Is the failing path using `podman`, `podman-compose`, or Docker-compatible API calls?
+- Is the workload a single container, a pod, or compose-managed services?
+- Is the failure in image pull, container create, network setup, health check, volume mount, permission, or cleanup?
+
+## Core Commands
+
+```bash
+podman info
+podman version
+podman system df
+podman ps -a
+podman pod ps
+podman images
+podman network ls
+podman volume ls
+podman events --since 30m
+```
+
+For a specific container:
+
+```bash
+podman inspect <container>
+podman logs <container>
+podman top <container>
+podman port <container>
+```
+
+## Rootless Checks
+
+```bash
+id
+echo "${XDG_RUNTIME_DIR:-unset}"
+test -d /run/user/$(id -u)
+test -S /run/user/$(id -u)/podman/podman.sock
+systemctl --user status podman.socket podman.service
+```
+
+If user services are unavailable after login/session changes, check lingering:
+
+```bash
+loginctl show-user "$(id -un)" --property=Linger
+```
+
+If a client reports `FailedToOpenSocket` and falls back to `http://localhost/...`
+(e.g. `path: "http://localhost/v4.0.0/libpod/..."`), `XDG_RUNTIME_DIR` is unset or
+the socket path is empty. For a systemd `User=` system service reaching a rootless
+socket, or for enabling `podman.socket` non-interactively over SSH, see
+[rootless-services-and-sockets.md](rootless-services-and-sockets.md).
+
+## Storage And Permission Checks
+
+```bash
+podman info --format '{{.Store.GraphRoot}}'
+podman unshare cat /proc/self/uid_map
+podman unshare cat /proc/self/gid_map
+```
+
+For host mounts:
+
+```bash
+ls -ldZ <host-path>
+podman unshare ls -ld <host-path>
+```
+
+SELinux symptoms often appear as permission denied despite Unix permissions looking correct. Prefer `:z` or `:Z` mount labels where appropriate:
+
+```bash
+podman run --rm -v "$PWD/data:/data:z" alpine ls -la /data
+```
+
+## Cleanup
+
+Inspect before removing:
+
+```bash
+podman ps -a
+podman pod ps
+podman network ls
+podman volume ls
+```
+
+Then clean targeted resources by ID/name. Use broad pruning only when the environment owns all local Podman state:
+
+```bash
+podman container prune
+podman pod prune
+podman network prune
+```
+

package/skills/engineering/e2e-test/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/engineering/e2e-test/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: e2e-test
+description: "Playwright end-to-end standard: the 3-tier suite (render-health / functional / journey), generated route manifest, presentation sweep, and CI route gates. Use when browser routes or user flows ship or change, or a Playwright test flakes. NOT for non-browser tests, defining what to test (ensure-coverage), or the curated ALIVE/DEAD gate (smoke)."
+---
+
+# E2E Testing Standard
+
+This file is the **spine** — tiers, rules, and where this fits. Mechanics (route discovery, manifest projection, the presentation sweep, Playwright config, CI wiring) live in `references/`; load one only when the step needs it (see [Reference Map](#reference-map)).
+
+## Where this fits (pipeline)
+
+Not a pipeline stage — invoked by the stages as the **executable browser layer** for `ensure-coverage`'s doctrine. `ensure-coverage` defines *what must be proven* (required levels, the Coverage Ledger, the presentation floor) and owns the gate *contract* (`ensure-coverage/references/enforcement/ci-contract.md`); this skill is *how* browser/journey surfaces get proven and *the scripts CI runs*.
+
+| Stage | This skill's role |
+|---|---|
+| `resolve-issues` | **orchestrate**: the issue→merge-ready loop that invokes this skill at the implement/verify steps |
+| `to-issues` | route/journey discovery so issues are sliced as vertical journeys |
+| `implement-and-pr` | **produce**: write tiered tests, regenerate the manifest, tag `@covers/@level`, run the presentation sweep locally |
+| `review-pr` | **verify**: the [reviewing checklist](references/reviewing.md); confirm the sweep ran and the manifest isn't stale |
+| **CI build** | **enforce**: route-detect, manifest-validate, the functional/journey suite, and the **presentation sweep as a separate blocking job** |
+
+The **gate contract** lives in `ensure-coverage`; the **runnable templates** that satisfy it are in this skill's `assets/` (`ci-gates.cloudbuild.yaml`, `ci-gates.github.yml`). A repo copies a template; `ensure-coverage`'s `ci-audit.mjs` verifies it stays wired.
+
+## Test Tiers
+
+| Tier | Name | What to test | Required when |
+|------|------|-------------|---------------|
+| 1 | **Render-health** | Route loads, no crash, heading visible, no console errors (the `presentation:render-health` spine) | Every route/endpoint |
+| 2 | **Functional** | Forms, filters, auth, API responses, error states | Routes with user interaction |
+| 3 | **Journey** | Multi-step flows crossing pages/APIs — the **golden paths**: critical business flows whose failure means do-not-ship | Core business flows |
+
+**Tier 3 is where the golden paths live.** A *golden path* is a Tier-3 journey whose failure alone means do-not-ship — not a separate test type. `smoke` authors nothing new: it **selects a curated `@smoke`-tagged subset of this tier** and gates it (ALIVE/DEAD) as the per-PR liveness floor, adding only curation, a binary verdict, and target-safety. Breadth across *all* core journeys is Tier 3's job; the do-not-ship *subset* is `smoke`'s.
+
+## Verify e2e changes locally before the batch
+
+A repo's merge queue re-validates the full browser matrix on the merged
+candidate, so one e2e regression (or a bug in the e2e test/helper code itself)
+fails the whole batch and resets every PR in it — 20-30 min per round. Before
+relying on that gate, verify affected specs locally:
+
+1. **Check the environment before assuming it can't run.** Docker/Podman +
+   PostgreSQL + cached Playwright browsers may all be present even when a doc
+   says the lane is "unavailable" — actually probe (`docker info`, `pg_isready`,
+   `ls ~/Library/Caches/ms-playwright`).
+2. **Run the affected specs, not the whole suite** (repo-local runner, e.g.
+   `pnpm test:functional:shard 1 --grep <pattern>`; see the repo's E2E.md for
+   the exact command). A focused run is minutes; the full matrix is the
+   batch's job.
+3. **Docker-space gotcha**: a full Docker VM disk surfaces as `tar: Cannot
+   create symlink ... No space left on device` inside the run — free it with
+   `docker system prune --volumes -f` and retry.
+4. **Unit-test your own test/helper changes** where possible (a hydration
+   marker, a wait helper, a retry loop are all testable with mocked page/locator
+   objects) — that catches bugs the e2e run itself would only expose as flakes.
+
+## Directory Structure
+
+```
+e2e/
+├── route-manifest.json       # generated projection (see references/route-manifest.md)
+├── route-manifest.overlay.json  # curated tier/ignore deviations
+├── render/                   # Tier 1 (render-health)
+├── functional/               # Tier 2 (subdirs by feature: auth/, filters/, forms/)
+├── journeys/                 # Tier 3 (golden paths; do-not-ship subset tagged @smoke)
+├── fixtures/                 # Shared auth, test data
+└── utils/                    # Helpers
+```
+
+Backend: `tests/e2e/` with `endpoint-manifest.json`, same tier subdirectories, `conftest.py`.
+
+## Writing Tests
+
+1. Every new route/endpoint needs at least a Tier 1 render-health test.
+2. Interactive routes need Tier 2 tests (success + error + edge cases).
+3. Core business flows need Tier 3 journey tests (the golden paths); tag the do-not-ship subset `@smoke` so the smoke gate selects it.
+4. The manifest is **generated**, not hand-edited — regenerate it (see [route-manifest.md](references/route-manifest.md)); put curation in the overlay.
+5. Use Given/When/Then comments; use `getByRole`/`getByLabel`/`getByText`, never CSS selectors; never `waitForTimeout()`.
+6. Auth in shared fixtures — never duplicate across files.
+7. **Tag every test with `// @covers <surface-id>` and `// @level <level>`** so ensure-coverage's `coverage-ledger.mjs` resolves your evidence. Untagged specs are invisible to the accounting gate. Use the presentation tokens for sweep/instrument specs.
+8. **Never skip a test.** The committed suite contains only tests that run and assert — no `test.skip`/`xit`/`describe.skip`, no conditional skip, no disguised `if (!x) return`. A missing precondition is the test's *arrange* step. Pick the non-skip path by case:
+
+   | Situation | Instead of skip |
+   |---|---|
+   | Missing data / session / migration / flag / entity-state | **seed it** |
+   | Third-party dependency | **sandbox at the boundary** |
+   | Un-sandboxable external **or** genuine flake | **quarantine lane** (`@quarantine` tag — non-blocking, still runs+reports, graded `Unverified`) |
+   | Platform/capability-specific | **route** via project/matrix/tag |
+   | Behavior not built yet | **land the test with it** (TDD red→green) |
+   | Obsolete / wrong test | **delete it** |
+   | Can't run in any env we control | **manual-check doc**, tracked |
+
+   Full rationale + enforcement: [authoring/test-skipping.md](references/authoring/test-skipping.md). The `lint-tests.mjs` gate (`no-skip` rule) fails CI on a skip added in a PR; it also carries `no-fixed-timeout` (no `waitForTimeout`).
+
+Locator patterns, tier examples, mocking → [authoring/playwright-patterns.md](references/authoring/playwright-patterns.md). Playwright config + AGENTS.md snippet → [authoring/playwright-config.md](references/authoring/playwright-config.md). No-skip policy (seed/quarantine/route/delete — never disable a test) → [authoring/test-skipping.md](references/authoring/test-skipping.md). Auth surfaces (login/signup/forgot-password — assert authenticated state not form presence; fake the email boundary) → [authoring/auth-flows.md](references/authoring/auth-flows.md).
+
+**Lead every coverage deliverable with the verdict.** Whether you added tests, wrote a `notes.md`, or reviewed a PR, put a one-line verdict at the *top*: is this surface covered, do gaps remain, is it ship-ready? Then what the new tests prove (and deliberately do *not*), and concrete **follow-up action items** for anything uncovered (owner/level where known). The reader's first question is "is this safe to ship?" — answer it before the spec detail.
+
+## Route Discovery & Coverage
+
+Never audit coverage from memory — produce a deterministic route/endpoint inventory and classify reachability **first**. Full protocol + per-framework discovery sources: [route-discovery.md](references/route-discovery.md). The route manifest is a **generated projection** of ensure-coverage's surface inventory (no drift by construction): [route-manifest.md](references/route-manifest.md).
+
+## Presentation Sweep (the third axis)
+
+A green functional suite can pass while a route throws on render — if its only spec intercepts the route's own API, the real render path is never exercised. The **presentation sweep** opens every manifest route in a real browser (no first-party interception) and asserts the presentation floor **spine first** (`presentation:render-health`: no `pageerror`/`console.error`/error-boundary/5xx). It is a **separate gate** from the functional suite — a green functional run is not the presentation gate. The floor levels auto-apply to every route; **`presentation:visual`** is an **opt-in** pixel-baseline level a surface raises via its `*.coverage.yml`, run CI-only in a pinned Playwright container (`toHaveScreenshot()`). Instruments, the sweep command, fixtures, "mutate-health" (render-health held *through* a write), and the visual job/evidence step: [presentation-sweep.md](references/presentation-sweep.md).
+
+## CI Enforcement
+
+Blocking gates, each a separate job (per ensure-coverage's CI contract). The **per-PR floor**: inventory freshness, accounting (`coverage-ledger.mjs validate`), the presentation sweep, no-over-mock (`lint-tests --rules mock-internal-seam`), the Review-Contract checklist validate, quarantine auto-resurface, and the **curated E2E smoke gate** (gate 8 — boots the real app and drives the do-not-ship golden journeys; for browser paths a tiny curated subset driven through this skill's Playwright layer). Manifest validation proves a spec was *authored*; only the sweep proves the page *renders*; only smoke proves the selected golden journeys are *alive*. The **broad functional + journey suite (gate 4)** is **demoted off the per-PR critical path to the integration lane** (the integration-branch push; nightly optional) — required before release, not per-PR. Commands, templates, and the post-deploy pattern: [ci-integration.md](references/ci-integration.md).
+
+**Wiring conventions** (encoded in the templates; `ci-audit.mjs` checks they stay):
+
+- **Docker-preferred.** Every browser job runs in the **pinned official Playwright
+  container** (`mcr.microsoft.com/playwright:<version>`) — browsers ship in the image
+  (no per-job install), so the rendering environment is identical across jobs. The
+  plain-runner + `playwright install` alternative stays sanctioned but is not the
+  default. A missing browser shared library such as `libnspr4.so` means the job is in
+  the wrong container. Options, `docker run` for self-hosted runners,
+  `services.postgres` networking, native `container:` caveats:
+  [ci-playwright-container.md](references/ci-playwright-container.md).
+- **5-minute PR lane.** PR-lane jobs carry `timeout-minutes: 5` / `timeout: 300s`;
+  golden paths run in parallel (workers; matrix fan-out when needed) so wall clock ≈
+  the slowest path. Actions/assertions time out at **15s**
+  ([authoring/playwright-config.md](references/authoring/playwright-config.md)). Longer
+  leashes are for the integration-lane suite and auxiliary (quarantine/visual) jobs —
+  never the PR-lane gates.
+- **One umbrella check.** On GitHub Actions, branch protection requires only the
+  **`all-gates`** job (it `needs:` every blocking gate) — a renamed or added gate can't
+  silently fall out of protection. Cloud Build needs none: the build's single status is
+  the check.
+
+**Three lanes.** *PR lane* = the per-PR floor above. *Integration lane* = the broad functional/journey suite, on the integration-branch push (where the `resolve-issues` epic gate boots + smokes the assembled branch). *Release lane* = a **promotion to production**: don't re-run the mutating suite on prod — where the promotion fast-forwards, prod is the exact SHA the PR + integration gates already passed, so gate on *that* result (under GitHub Flow the release branch is rebased first, which demotes that result to a pre-filter). Prod gets only a **read-only smoke, run against a 0%-traffic candidate before traffic shifts**, under a **read-only production profile** (`prod-preview`/`prod-active`) — against production a declared synthetic tenant is not sufficient. See [ci-integration.md](references/ci-integration.md) → Three lanes.
+
+## Reviewing PRs
+
+Checklist + comment template: [reviewing.md](references/reviewing.md). Block on: route discovery not run, a new route without a manifest entry, an interactive route without Tier 2, or a browser-route change with the presentation sweep absent/warn-only.
+
+## Reference Map
+
+| When you need to… | Read |
+|---|---|
+| write tests (locators, tiers, mocking) | [authoring/playwright-patterns.md](references/authoring/playwright-patterns.md) |
+| Playwright config + AGENTS.md snippet | [authoring/playwright-config.md](references/authoring/playwright-config.md) |
+| no-skip policy + per-case solutions map | [authoring/test-skipping.md](references/authoring/test-skipping.md) |
+| test auth flows (login / signup / forgot-password) | [authoring/auth-flows.md](references/authoring/auth-flows.md) |
+| discover routes / classify reachability | [route-discovery.md](references/route-discovery.md) |
+| (re)generate the route manifest, understand the projection | [route-manifest.md](references/route-manifest.md) |
+| run/understand the presentation sweep + mutate-health | [presentation-sweep.md](references/presentation-sweep.md) |
+| drive a route's real render when there's no in-app way in (prefer `agent-browser`) | [presentation-sweep.md → "No in-app way to view it"](references/presentation-sweep.md#no-in-app-way-to-view-it-is-not-blocked) |
+| wire CI / gate templates / post-deploy pattern | [ci-integration.md](references/ci-integration.md) · `assets/ci-gates.*` |
+| run Playwright in the pinned official container (preferred; incl. self-hosted Docker/Podman) | [ci-playwright-container.md](references/ci-playwright-container.md) |
+| review a PR for E2E coverage | [reviewing.md](references/reviewing.md) |
+| debug a failing E2E | [debugging.md](references/debugging.md) |
+
+## Scripts
+
+`detect-routes-nextjs.mjs` · `detect-routes-fastapi.py` (discovery) · `project-route-manifest.mjs` · `validate-manifest.mjs` (manifest) · `presentation-sweep.mjs` + `presentation-{render-health,checks,perceivability,reachability,temporal,visual}.mjs` (the sweep + instruments; `presentation-visual.mjs` is the **opt-in**, CI-only pixel-baseline gate) · `post-visual-evidence.mjs` (upserts the baseline/diff evidence comment to the issue + PR after baseline-regen).