@@ -30,10 +30,14 @@ coverage/
 *.tsbuildinfo
 .vite/
 .playwright-cli/
+.playwright-mcp/
 
 # Verification skill state, logs, and evidence
 .verify/
 
+# CI failure artifacts downloaded by `npm run ci:failures`
+.ci-failures/
+
 # Playwright artifacts
 test-results/
 playwright-report/
@@ -62,16 +66,12 @@ deno.lock
 tasks.txt
 humanizer.md
 
-# Local notes/docs, except the project README
-*.md
+# Local notes. Other Markdown files are not ignored: a blanket *.md rule
+# silently dropped new root-level docs.
+/TASKS.md
+*.local.md
 *.txt
 *.info
-!README.md
-!AGENTS.md
-!**/README.md
-!docs/**/*.md
-!plans/**/*.md
-!.claude/skills/**/*.md
 .vercel
 .env*
 .worktrees/
@@ -0,0 +1 @@
+22
@@ -7,8 +7,18 @@
 # once collide in Docker, not just on a socket. Use this instead of calling
 # `supabase db start` directly whenever more than one workspace might be
 # active.
+#
+# --db-only stops after `npm run test:db` (pgTAP and the database scripts),
+# still holding the lock and stopping the stack on exit.
 set -euo pipefail
 
+DB_ONLY=false
+case "${1:-}" in
+  --db-only) DB_ONLY=true ;;
+  "") ;;
+  *) echo "usage: $0 [--db-only]" >&2; exit 2 ;;
+esac
+
 DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$DIR/lib/lock.sh"
 
@@ -25,7 +35,12 @@ if [ "$LIVE_PROVIDERS" = 1 ] && { [ -z "${LIVE_OPENROUTER_API_KEY:-}" ] || [ -z
   echo "LIVE_PROVIDERS=1 requires LIVE_OPENROUTER_API_KEY and LIVE_EXA_API_KEY" >&2
   exit 1
 fi
+if [ "$DB_ONLY" = true ] && [ "$LIVE_PROVIDERS" = 1 ]; then
+  echo "--db-only runs the database tests, which LIVE_PROVIDERS=1 skips" >&2
+  exit 2
+fi
 stack_started=false
+provider_started=false
 runtime_dir=""
 owned_pids=()
 
@@ -44,7 +59,10 @@ cleanup() {
   trap - EXIT
 
   stop_owned_processes
-  docker rm -f "$FAKE_PROVIDER" >/dev/null 2>&1 || true
+  # The container name is shared by every worktree, so only remove our own.
+  if [ "$provider_started" = true ]; then
+    docker rm -f "$FAKE_PROVIDER" >/dev/null 2>&1 || true
+  fi
 
   if [ -n "$runtime_dir" ] && [ -f "$runtime_dir/function.env" ]; then
     rm -- "$runtime_dir/function.env"
@@ -83,6 +101,7 @@ for attempt in 1 2 3; do
   sleep $((attempt * 30))
 done
 if [ "$LIVE_PROVIDERS" != 1 ]; then npm run test:db; fi
+if [ "$DB_ONLY" = true ]; then exit 0; fi
 
 status_json="$(supabase status -o json 2>/dev/null)"
 status_value() {
@@ -114,6 +133,7 @@ fi
 
 # Edge Functions reach the fake provider by container name on the stack network.
 docker rm -f "$FAKE_PROVIDER" >/dev/null 2>&1 || true
+provider_started=true
 docker run -d --rm --name "$FAKE_PROVIDER" --network "supabase_network_$project_id" \
   "${provider_mode[@]}" -p 127.0.0.1:18090:8787 -v "$(pwd)/e2e/full-stack/fake-openrouter.mjs:/fake.mjs:ro" \
   node:22-alpine node /fake.mjs >/dev/null
 
@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Prints this worktree's port for the credential-free Playwright server.
+# Every worktree used to run `npm run verify` on 18080, so two worktrees
+# verifying at once failed on "port already in use". Ports come from
+# 18100-18179 through the same registry dev.sh uses, keyed by worktree.
+set -euo pipefail
+
+DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$DIR/lib/lock.sh"
+
+PORTS_LOCK="$HOME/.superset/debatelab-ports/lock"
+WORKSPACE_KEY="e2e:$(git -C "$DIR/.." rev-parse --show-toplevel)"
+
+lock_acquire "$PORTS_LOCK" 30 >&2
+trap 'lock_release "$PORTS_LOCK"' EXIT
+node "$DIR/lib/port-alloc.cjs" allocate "$WORKSPACE_KEY" 18100 18179
@@ -25,6 +25,16 @@ function readData() {
   }
 }
 
+// Keys are worktree paths, optionally prefixed ("e2e:/path"). Drop entries
+// whose worktree is gone so deleted worktrees don't hold ports forever.
+function pruneRemoved(data) {
+  for (const key of Object.keys(data)) {
+    const dir = key.replace(/^[a-z0-9]+:(?=\/)/, '');
+    if (path.isAbsolute(dir) && !fs.existsSync(dir)) delete data[key];
+  }
+  return data;
+}
+
 function writeData(data) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, JSON.stringify(data, null, 2));
@@ -38,7 +48,7 @@ if (!cmd || !workspace) {
 }
 
 if (cmd === 'allocate') {
-  const data = readData();
+  const data = pruneRemoved(readData());
   if (data[workspace]) {
     console.log(data[workspace]);
     process.exit(0);
 
@@ -12,6 +12,7 @@ PORTS_LOCK="$HOME/.superset/debatelab-ports/lock"
 
 lock_acquire "$PORTS_LOCK" 30
 node "$DIR/lib/port-alloc.cjs" release "$WORKSPACE_KEY" || true
+node "$DIR/lib/port-alloc.cjs" release "e2e:$(git rev-parse --show-toplevel)" || true
 lock_release "$PORTS_LOCK"
 
 if command -v supabase >/dev/null 2>&1 && supabase status >/dev/null 2>&1; then
 
@@ -5,7 +5,7 @@
 - The repository is DebateLab. Never infer its directory from an old repository name.
 - Run `git rev-parse --show-toplevel` and stay inside that returned worktree. On Adam's VPS, `/home/codex/Projects/DebateLab` is the primary checkout, but Superset and other agents use linked worktrees elsewhere.
 - Before editing, inspect the branch and working tree. Preserve unrelated changes.
-- Use Node 22, npm, and the committed `package-lock.json`. Install with `npm ci`.
+- Use Node 22, npm, and the committed `package-lock.json`. `.nvmrc` pins 22, but the VPS default is Node 24: check `node -v` and run `nvm use` (with `NVM_DIR=$HOME/.nvm` set) when it isn't 22. Install with `npm ci` when `node_modules` is missing.
 
 ## Parallel Superset workspaces
 
@@ -30,7 +30,7 @@ The frontend is hosted on Vercel at `https://debate.pi-stack.org`. Merging to `m
 ## Normal ports
 
 - Vite development server: `8080` by default outside Superset; Superset allocates `8080-8179` per worktree.
-- Automated browser server: isolated `127.0.0.1:18080`, never an existing dev server.
+- Automated browser server: a per-worktree port from `18100-18179`, printed by `bash .superset/e2e-port.sh`, never an existing dev server. Protected staging keeps `127.0.0.1:18080`, the origin deployed CORS allows.
 - Tailnet previews for Adam: `npm run dev:preview` listens locally on `9200-9299` and is published on tailnet HTTPS `9100-9149`; it pins the app to staging. See [docs/development.md](docs/development.md#preview-on-the-tailnet).
 - Local Supabase: CLI defaults beginning at `54321`. The stack is not parallel-safe across worktrees.
 
@@ -46,17 +46,20 @@ npm test
 npm run test:collaboration
 npm run test:edge
 npm run build
-CI=1 PORT=18080 PLAYWRIGHT_BASE_URL=http://127.0.0.1:18080 npm run test:e2e
+P=$(bash .superset/e2e-port.sh) && CI=1 PORT=$P PLAYWRIGHT_BASE_URL=http://127.0.0.1:$P npm run test:e2e
 ```
 
 `npm run verify` runs the credential-free ladder with the desktop Chromium `@smoke` browser set (about a minute). `npm run verify:full` adds the full desktop and mobile suite.
 
 If GitHub Actions jobs fail within 2 to 5 seconds with no logs, they did not run: the account is out of Actions minutes (billing), not failing on the code. In that case run the same checks locally at the final head (`npm run verify` and the database gate) and record the exact results in the PR. A local pass is not a CI pass; say which one you have.
 
+When a CI job fails, start with `npm run ci:failures -- <pr>`. It prints the failing jobs and specs, downloads the failure artifact into `.ci-failures/`, and shows each failed test's error and the dialogs and headings on the page from its `error-context.md`. Read that before guessing at timeouts or infrastructure.
+
 Database migrations and pgTAP policies use a separate Docker-backed gate. In Superset, use the locking wrapper:
 
 ```bash
 ./.superset/db-gate.sh
+./.superset/db-gate.sh --db-only   # pgTAP and database scripts only
 ```
 
 Outside Superset, run the underlying commands directly:
@@ -73,7 +76,7 @@ WebKit is a separate release smoke test:
 
 ```bash
 npx playwright install --with-deps webkit
-CI=1 PORT=18080 PLAYWRIGHT_BASE_URL=http://127.0.0.1:18080 npm run test:e2e:webkit
+P=$(bash .superset/e2e-port.sh) && CI=1 PORT=$P PLAYWRIGHT_BASE_URL=http://127.0.0.1:$P npm run test:e2e:webkit
 ```
 
 ## Verifying features in the real app
@@ -134,7 +137,7 @@ Open only what the task needs:
 - [docs/testing.md](docs/testing.md): what each gate proves, browser matrices, staging, artifacts, and cleanup.
 - [docs/operations.md](docs/operations.md): CI, Vercel hosting, staging, deployment, rollback, and live verification.
 - [supabase/README.md](supabase/README.md): Edge Functions, shared backend modules, migrations, auth boundaries, and required secret names.
-- [plans/README.md](plans/README.md): work in progress, the backlog, and shipped plans. Every plan lives in `plans/`; write new plans there. Revalidate every plan against current source before executing it.
+- [plans/README.md](plans/README.md): work in progress, the backlog, and shipped plans. Every plan lives in `plans/` and opens with a `**Status:**` line; write new plans there. Commit a plan before splitting it across agent threads, and put its path in each thread's prompt. Revalidate every plan against current source before executing it.
 - [docs/README.md](docs/README.md): complete documentation index and freshness labels.
 
 When commands, ports, workflows, or runtime boundaries change, update the owning focused document in the same change. Do not copy large source trees, schemas, dependency lists, or model catalogs into documentation.
@@ -25,9 +25,10 @@ Never overwrite unrelated changes. Do not switch to the primary checkout because
 - Playwright browser binaries for browser gates
 - Xcode and CocoaPods or Swift Package Manager support for native iOS work
 
-Install the locked JavaScript tree:
+Install the locked JavaScript tree with the Node version from `.nvmrc`:
 
 ```bash
+nvm use
 npm ci
 ```
 
@@ -47,7 +48,7 @@ For another explicit local port:
 npm run dev -- --host 127.0.0.1 --port 8081
 ```
 
-Automated browser tests own `127.0.0.1:18080` by default and always start a fresh server.
+Automated browser tests always start a fresh server. `npm run verify` puts it on this worktree's port from `18100-18179` (`bash .superset/e2e-port.sh`); a bare Playwright run falls back to `127.0.0.1:18080`.
 
 ## Preview on the tailnet
 
@@ -142,7 +143,7 @@ Never point local tests at staging or production. Never apply a migration to an
 [`playwright.config.ts`](../playwright.config.ts) starts Vite on an isolated port and refuses to reuse an existing server.
 
 ```bash
-CI=1 PORT=18080 PLAYWRIGHT_BASE_URL=http://127.0.0.1:18080 npm run test:e2e
+P=$(bash .superset/e2e-port.sh) && CI=1 PORT=$P PLAYWRIGHT_BASE_URL=http://127.0.0.1:$P npm run test:e2e
 ```
 
 Failure artifacts go to ignored `test-results/` and `playwright-report/`. Protected staging disables traces, screenshots, and video.
 
@@ -36,7 +36,7 @@ If Actions jobs fail within 2 to 5 seconds with no runner and no logs, the accou
 
 ## Frontend hosting on Vercel
 
-Vercel builds and serves the frontend from the Git repository. Merging to `main` starts a production deployment to `https://debate.pi-stack.org`; pull requests get two preview deployments (see [Per-PR previews](#per-pr-previews)). The production canary runs after each successful Vercel `Production` deployment.
+Vercel builds and serves the frontend from the Git repository. Merging to `main` starts a production deployment to `https://debate.pi-stack.org`; pull requests get two preview deployments (see [Per-PR previews](#per-pr-previews)). For a staging-pinned preview on the tailnet, use `npm run dev:preview` (see [development.md](development.md#preview-on-the-tailnet)). The production canary runs after each successful Vercel `Production` deployment.
 
 [`vercel.json`](../vercel.json) owns:
 
@@ -66,14 +66,14 @@ The staging browser suite disables trace, screenshot, and video capture. It crea
 
 Do not enable the staging repository variable before every prerequisite is present. A skipped staging job is not a pass.
 
-`STAGING_E2E_ENABLED` has been `true` since 2026-09-18, and the job passed through 2026-09-23. Since then it has been skipped because the `Quality` run it waits for fails before any runner starts (see [When GitHub Actions cannot run](#when-github-actions-cannot-run)). Restoring Actions minutes restores the staging job; nothing in the workflow needs changing.
+`STAGING_E2E_ENABLED` has been `true` since 2026-09-18. The job runs after every successful `Quality` run from a push to `main`. Quality runs from pull requests also trigger it, and those show as skipped by design. Check the latest real result with `gh run list --workflow staging-e2e.yml` and `npm run ci:failures -- <run-id>`, not this page. The run uploads no artifact, so the job log is the only evidence.
 
 ## Staging sync
 
 Staging is project `debate-trainer-staging` (`brifeyypjauyusmkptkx`). Production is `debate-trainer` (`uziwdtkzofptihahfooo`). Every backend change goes to staging first, passes the staging browser suite, and only then goes to production. Steps 1 and 2 are read-only. Steps 3 and 4 change staging and need Adam's authorization each time.
 
 1. Confirm the target. `supabase projects list` must show the staging ref under the staging name. Stop if a command, link, or environment variable points at the production ref.
-2. Find what is pending. Run `npm run backend:status -- --project-ref brifeyypjauyusmkptkx --check` from a checkout of the commit you mean to ship. It compares staging with the committed tree and exits 1 when a migration is not applied. Where that script is not available, run its two read-only queries directly:
+2. Find what is pending. Run `npm run backend:status -- --project-ref brifeyypjauyusmkptkx --check` from a checkout of the commit you mean to ship. It compares staging with the committed tree and exits 1 when a migration is not applied. It also lists expected function secrets the project lacks (names only) and prints the Auth site URL and redirect allowlist. Where that script is not available, run its two read-only queries directly:
 
    ```bash
    supabase migration list --project-ref brifeyypjauyusmkptkx
@@ -110,7 +110,7 @@ The staging project's name must not start with `debate-navigator-`, or productio
 
 ## Backend drift check
 
-`npm run backend:status` shows what the current commit has that a Supabase project lacks. It inspects the project the Supabase CLI resolves, which is `SUPABASE_PROJECT_ID` when that is set and the linked project otherwise; `npm run backend:status -- --project-ref <ref>` inspects another one. It runs `supabase migration list` and `supabase functions list` and changes no schema, data, functions, or secrets. To connect to the database, the CLI creates its usual short-lived login role.
+`npm run backend:status` shows what the current commit has that a Supabase project lacks. It inspects the project the Supabase CLI resolves, which is `SUPABASE_PROJECT_ID` when that is set and the linked project otherwise; `npm run backend:status -- --project-ref <ref>` inspects another one. It runs `supabase migration list`, `supabase functions list` and `supabase secrets list`, reads the Auth site URL and redirect allowlist from the Management API with the CLI's access token (`SUPABASE_ACCESS_TOKEN`, or the `access-token` file in `SUPABASE_HOME`, default `~/.supabase`), and changes no schema, data, functions, or secrets. It prints secret names only, never values or digests. To connect to the database, the CLI creates its usual short-lived login role.
 
 The comparison uses the committed tree at `HEAD`, so commit or stash local edits first. It reports:
 
 
@@ -107,12 +107,12 @@ Run this after `npm run build`. It serves `dist/` through Vite preview and prove
 ## Credential-free browser gate
 
 ```bash
-CI=1 PORT=18080 PLAYWRIGHT_BASE_URL=http://127.0.0.1:18080 npm run test:e2e
+P=$(bash .superset/e2e-port.sh) && CI=1 PORT=$P PLAYWRIGHT_BASE_URL=http://127.0.0.1:$P npm run test:e2e
 ```
 
 Pull requests run only tests tagged `@smoke` on desktop Chromium (`npm run test:e2e:smoke`, about 30 tests). Tag a test `@smoke` only when it covers a whole user path that would otherwise go unchecked until the nightly run.
 
-Playwright starts a new Vite server on `127.0.0.1:18080` and runs:
+`.superset/e2e-port.sh` gives each worktree its own port from `18100-18179`, recorded in `~/.superset/debatelab-ports/allocations.json`, so two worktrees can run the gate at once. Without `PORT`, Playwright falls back to `18080`. Playwright starts a new Vite server on that port and runs:
 
 - desktop Chromium at 1280 by 800
 - mobile Chromium using the Pixel 5 device profile
@@ -165,7 +165,7 @@ In Superset, run:
 ./.superset/db-gate.sh
 ```
 
-The wrapper acquires `~/.superset/debatelab-db.lock`, starts full local Supabase, runs `npm run test:db`, then holds the same lock while a controlled Mailpit relay, collaboration process, fake model provider, and Vite client run the real-Auth desktop/mobile workspace and full-stack feature journeys. The `Database` workflow runs this same gate on pull requests that touch its paths, and retains its logs and browser traces on failure. It stops every owned process and the stack on exit, including after failure. Outside Superset, run only the database portion with:
+The wrapper acquires `~/.superset/debatelab-db.lock`, starts full local Supabase, runs `npm run test:db`, then holds the same lock while a controlled Mailpit relay, collaboration process, fake model provider, and Vite client run the real-Auth desktop/mobile workspace and full-stack feature journeys. The `Database` workflow runs this same gate on pull requests that touch its paths, and retains its logs and browser traces on failure. It stops every owned process and the stack on exit, including after failure. To run only the database portion under the same lock, use `./.superset/db-gate.sh --db-only`. Outside Superset, run it with:
 
 ```bash
 supabase db start
@@ -265,7 +265,7 @@ npx playwright install --with-deps webkit
 Run:
 
 ```bash
-CI=1 PORT=18080 PLAYWRIGHT_BASE_URL=http://127.0.0.1:18080 npm run test:e2e:webkit
+P=$(bash .superset/e2e-port.sh) && CI=1 PORT=$P PLAYWRIGHT_BASE_URL=http://127.0.0.1:$P npm run test:e2e:webkit
 ```
 
 This is the Safari-engine smoke gate. State explicitly when it did not run.
@@ -319,6 +319,8 @@ Tests are not the proof that a change works; using it is. Two local recipes that
 
 [`.github/workflows/live-e2e.yml`](../.github/workflows/live-e2e.yml) runs the live provider journeys, and [`.github/workflows/prod-canary.yml`](../.github/workflows/prod-canary.yml) runs the production canary. `main` has no branch protection or rulesets (checked 2026-10-01; GitHub Free does not enforce them on private repositories), so no check is required. Path-filtered workflows that skip therefore don't block merges. Read the PR's checks before merging.
 
+To see why a run failed, use `npm run ci:failures` (current branch's PR), `npm run ci:failures -- <pr>` or `npm run ci:failures -- <run-id>`. It works while the run is still going, as soon as a job fails. It lists failed jobs and steps, prints the Playwright or Vitest summary from each job log, downloads the `*-failure-<run-id>` artifacts into ignored `.ci-failures/`, and prints each failed test's error plus the dialogs and headings from its `error-context.md` page snapshot. A dialog the spec never answered shows up there. Protected staging uploads no artifact, so only its job log is available.
+
 Before calling CI green:
 
 1. identify the current head commit;