@miroshnik/elves 0.0.0 → 2026.1018.0

package/docs/parallel-checkouts.md

@@ -0,0 +1,220 @@
+# Parallel checkouts: the task's Compose stack, addresses through the proxy, shared `.git/config` — for "Subagents and worktrees"
+
+Reference for the "Subagents and worktrees" section of `AGENTS.md`: the full
+rule, what the project's compose file holds, what moves with the address,
+callbacks of external services, the runner config and the sandbox. The stack
+itself — its names, the e2e stack and its variables, profiles, taking it
+down — is the `task-env` skill; here are links to it, not a copy. Shared git
+config — the "Shared `.git/config`" section at the end.
+
+## Rule
+
+**Parallel checkouts share ports, databases and cookies.** Two sessions of
+one project on ports of the host fight over a port, migrate one database to
+different branches and share Redis, queues and mail; on `localhost` they share
+cookies too — cookies don't tell ports apart, and the agent's browser and the
+owner's log each other out. So the task's apps, databases, queues, mail and
+e2e run in its own Docker Compose stack — a copy of the project's compose
+file, the `task-env` skill:
+
+```bash
+bun --no-env-file <skill dir>/scripts/task-env.ts up                           # the task's stack by the branch, its addresses
+bun --no-env-file <skill dir>/scripts/task-env.ts e2e -- npx playwright test   # the e2e stack anew, the run with its addresses
+```
+
+- **The stack** — Compose project `<project>-<N>` by the number from the
+  branch, e2e — `<project>-<N>-e2e` on clean volumes, the main checkout —
+  `<project>`; the e2e variables `TASK_ENV_*`, heavy services in `profiles`,
+  `env.http` in `.agents/elves.json`, taking it down (`task-env down`;
+  stacks of closed tasks left on the machine — `task-env prune`) and the
+  limit of Docker's subnets — the `task-env` skill,
+  section "The task's stack".
+- **The addresses** — `http://<service>.<N>.<project>.localhost`, e2e —
+  `http://<service>.e2e.<N>.<project>.localhost`: one proxy per machine
+  (Traefik) routes them to containers by their labels, nothing is published
+  on the host, a different host has its own cookies — the `task-env` skill,
+  section "The proxy". The addresses of the tasks in progress are on the
+  dashboard's Sessions tab (the `dashboard` skill). A database or a queue has
+  no address: inside the stack it is reached by the service name
+  (`db:5432`), from the host — by a published `127.0.0.1::5432` (`docker
+  compose -p <stack> port db 5432`, in e2e — `TASK_ENV_DB_5432`).
+- **Other stacks aren't mine.** A stack is taken down only by `task-env down`
+  of my own task (`task close` of the `github` skill calls it); `docker
+  compose down`, `stop` or `rm` of another stack — never: the stack's name
+  carries the task number (`docker compose ls`). A bare `docker compose down
+  -v` without `-p` goes to the project Compose picks by itself — the
+  directory or the file's `name:` — and may wipe the main checkout's stack.
+- **A busy port of the host** (the proxy's 80, an app outside the stack) —
+  first its owner: `lsof -nP -iTCP:<port> -sTCP:LISTEN` and the process's cwd
+  (`lsof -a -p <PID> -d cwd -Fn`). Someone else's — I don't kill it: `kill`
+  by port breaks someone else's run; the proxy takes another port
+  (`ELVES_PROXY_PORT`, the `task-env` skill, section "Settings").
+
+## Everything in the compose file
+
+The task's environment is the project's compose file and nothing else: what
+runs outside it — an app started on the host, a shared database container,
+the machine's Redis — is shared by all tasks again, with its port and data.
+
+- **Every app and everything it reaches** — databases, queues, cache, mail,
+  storage, emulators of external services — is a service of the compose
+  file. Apps reach them by the service name, as in the project
+  (`postgres://db:5432/app`): no host variables, no names per task.
+- **HTTP services** and their ports in the container — `env.http` in
+  `.agents/elves.json` (`{"env": {"http": {"web": 3000}}}`): only they get an
+  address; in a compose file a database's port doesn't differ from an app's.
+- **The code** — the worktree's: a build (`build: .`) or a bind mount by a
+  relative path (`./src:/app/src`); the dev server's HMR in a container works
+  (the `task-env` skill, section "Checked on the machine").
+- **A heavy service** (ClickHouse, Elasticsearch, Kafka) — in `profiles`:
+  every task gets its own copy, hundreds of MB, so only the tasks that need it
+  start it (`up --profile <name>`).
+- **The isolation rules** — no `container_name`, no fixed host port, volumes
+  and networks without `name:` and `external`, code by relative paths: each
+  of the four breaks isolation silently. The project's `check` (and the
+  session start hook) names each violation; after editing the compose file —
+  `task-env check` before the commit. The table with the fixes — the
+  `task-env` skill, section "Compose file isolation rules".
+
+## What moves with the address
+
+The task's app lives at `http://web.<N>.<project>.localhost`, not at
+`localhost:3000`: everything that builds absolute links follows the address.
+
+- **The app's base URL** (`APP_URL`, `NEXTAUTH_URL` / `AUTH_URL`, `ORIGIN`) —
+  from a variable, not only from the request: `task-env up` and `e2e` give
+  Compose the stack's addresses in `TASK_ENV_<SERVICE>_URL`, and the compose
+  file passes them on with a default for CI —
+  `APP_URL: ${TASK_ENV_WEB_URL:-http://localhost:3000}` (the `task-env`
+  skill, section "The task's stack"); a public variable baked in at build
+  (`NEXT_PUBLIC_*_URL`, `VITE_*_URL`) — into `build.args` the same way. A
+  framework with the address in its settings doesn't read the request; one
+  that does may take it from there: the proxy passes the client's `Host` on
+  (Traefik's `passHostHeader` is on by default) — Auth.js behind a proxy with
+  `AUTH_TRUST_HOST=true` and without `AUTH_URL`. A value written in the
+  compose file as is — the same for every task.
+- **Links in emails** — the stack's own mail catcher (Mailpit as a service of
+  the compose file) shows them with the task's address.
+- **Callbacks of external services** — the next section.
+- **Check:** no host port of the app is left —
+  `grep -rn "localhost:3000" *compose*.y*ml .env* playwright.config.*`.
+
+## Callbacks of external services
+
+- **OAuth redirect URI** — the task's address:
+  `http://web.<N>.<project>.localhost/api/auth/callback/<provider>`. The
+  redirect goes through the user's browser, and the browser resolves
+  `*.localhost` itself. Providers match the URI exactly: Google doesn't take
+  wildcards, takes plain `http` only for localhost and wants a host on the
+  public suffix list — whether it takes a `*.localhost` subdomain, its docs
+  don't say: check in the console; GitHub matches exactly, with wildcard
+  matching on — by the host without subdomains and the port, so the callback
+  `http://<project>.localhost/…` covers every task's address. A dev OAuth app
+  of its own, not the production one; what a provider doesn't take — a stub in
+  e2e (`docs/testing.md`, "e2e").
+- **Webhooks** come from the internet and don't reach `*.localhost`: the
+  forwarder is a service of the task's stack and delivers by the service
+  name. Stripe — its CLI:
+
+  ```yaml
+  services:
+    stripe:
+      image: stripe/stripe-cli
+      profiles: [stripe]
+      command: listen --api-key ${STRIPE_SECRET_KEY:-} --forward-to http://web:3000/api/webhooks/stripe
+  ```
+
+  The signing secret doesn't change between runs of `listen` (the Stripe CLI
+  docs): `stripe listen --print-secret` once — and it goes into the app's
+  `STRIPE_WEBHOOK_SECRET`. The key is a test-mode one, from the environment or
+  the project's `.env`, not from the compose file. Every running `listen`
+  receives every event of the account: one task's app also gets the other
+  tasks' events and answers `2xx` to an object it doesn't have rather than
+  failing. A tunnel (ngrok, cloudflared) is the same — one per stack, its
+  address in the provider's settings.
+
+## Runner config: the e2e stack's address
+
+```ts
+// playwright.config.ts — `task-env e2e -- npx playwright test` gives the e2e stack's address;
+// without it (CI, a run not through task-env) everything stays as before
+import { defineConfig } from '@playwright/test';
+
+const stack = process.env.TASK_ENV_WEB_URL;      // http://web.e2e.42.shop.localhost
+const baseURL = stack ?? 'http://localhost:3000';
+
+export default defineConfig({
+  use: { baseURL },
+  webServer: stack ? undefined : {              // the stack serves the app: the runner starts no server
+    command: 'npm run build && npm run start',
+    url: baseURL,
+    reuseExistingServer: false,                 // a busy port is an error, not someone else's server
+  },
+});
+```
+
+- The address is `TASK_ENV_<SERVICE>_URL` of the HTTP service: `web` →
+  `TASK_ENV_WEB_URL`. The stack's database for factories and seeds —
+  `TASK_ENV_DB_5432` (`127.0.0.1:<port>`) when its `db` publishes
+  `127.0.0.1::5432`: the run builds **all** its connection variables from it
+  (`DATABASE_URL`, `DIRECT_URL`, `PG*`) — one forgotten variable sends seeds
+  into another database.
+- The e2e stack is created anew with clean volumes on every run and stays
+  until the next one: a failed run is examined on it (`docker compose -p
+  <project>-<N>-e2e logs`).
+- Without the variable — the runner's own server on its port, as in CI.
+  `reuseExistingServer: !process.env.CI` from the Playwright template, outside
+  CI, silently picks up the neighbor's server on the same port: the tests run
+  against someone else's code and database. The behavior of `webServer` is
+  checked against the Playwright docs ("Web server", `TestConfig.webServer`):
+  `reuseExistingServer: false` fails if something is already listening on
+  `url`.
+
+## The sandbox
+
+Docker doesn't work inside the Claude Code sandbox, and the addresses
+`*.localhost` aren't reachable from it by default — the `task-env` skill,
+sections "Docker and the sandbox" and "Checked on the machine".
+
+- **The `task-env` script** — a separate Bash call outside the sandbox: no
+  `excludedCommands` entry takes out a script run by `bun`; inside the sandbox
+  it exits with code 2 and says so.
+- **The e2e run** is the script's child and runs outside the sandbox with it.
+- **Docker itself** (`docker compose -p <stack> logs`, `exec`, `ps`) — the
+  owner's step: `sandbox.excludedCommands` in `~/.claude/settings.json`
+  (`docker compose *`, `docker ps *`), a call without pipes and redirections.
+  Access to Docker is access to the whole machine.
+- **The task's addresses from sandboxed commands** (curl, a test runner) —
+  with `sandbox.network.allowLocalBinding: true`, the owner's setting: it
+  opens the loopback only, Docker stays outside — the `task-env` skill,
+  section "Local ports and task addresses". Without it — only an unsandboxed
+  command.
+- **The agent's browser pane** is outside the sandbox and opens the task's
+  addresses itself.
+
+## Shared `.git/config`
+
+All worktrees of a repository — and the main checkout — read one
+`.git/config`: each copy has its own `HEAD`, index and working files, but the
+config, hooks and branches are shared. `git config user.name` or `user.email`
+in any copy changes the commit author for all sessions of the repository, not
+just its own. The host may not deploy a commit whose author has no access to
+the project: the deploy doesn't run, and the site quietly falls behind
+`main`.
+
+- **No `git config` in copies or in subagent assignments:** not `--local`,
+  not `--global` (that one changes every repository on the machine), not
+  `--worktree`: without `extensions.worktreeConfig` it writes to the same
+  place, and the extension itself is turned on in the shared config.
+- **A test commit with a different author** — a setting for one command:
+  `git -c user.name=… -c user.email=… commit`.
+- **Git experiments** (hooks, settings, history) — `git clone` into a temp
+  folder, not in the shared repository.
+- **A branch rename writes the config too** — the branch's section
+  (upstream): another checkout's git holds the lock, `git branch -m` fails
+  with `could not lock config file`, the ref renamed, the section not. The
+  task branch — `github task status <N> "In progress" --branch …`: it retries
+  on the lock.
+- **After a commit** — `git log -1 --format=%ae`: the author is who it should
+  be. Someone else — first `git config --show-origin user.email`: where it
+  came from, rather than a fix by feel.

package/docs/pr-checks.md

@@ -0,0 +1,117 @@
+# Waiting for PR checks and merging — for "Git, PRs and merging"
+
+The principle is in `AGENTS.md` ("Git, PRs and merging": merge only with all
+checks green); the `ci-wait` skill does the waiting with a script. Here are the
+waiting and merging rules in full, the app's Auto-fix, then the polling
+mechanics. Rebase, the check before a push and cleaning up the merged branch —
+the `github` skill, section "Git, PRs and merging — mechanics".
+
+## Rules
+
+- **The full SHA:** I don't dig up the SHA of my merge — `wait-ci.sh merged
+  <N>` takes it from the PR itself (`git rev-parse origin/main` returns
+  someone else's, later commit during parallel merges); of my commit — `git
+  log -1 --format=%H`; I don't complete a short one or take a "similar" one
+  from memory: for a nonexistent SHA the API silently returns an empty status.
+- **Merge only with all checks green**, including the preview deploy; "a
+  known red first build" is no exception: I re-run my failed run (`gh run
+  rerun <id> --failed`) and wait for green; red for another reason — I fix it
+  before merging. I wait with a polling loop over the API: a PR — by its head
+  SHA, a commit — by the full SHA (mechanics and traps below; the `ci-wait`
+  skill). Green — then also `github pr premerge <N>`: if `main` moved after
+  CI — fast checks on the merge with a fresh `main` (`typecheck`,
+  `test:spec` — the scripts CI runs; standards and architecture go there
+  once, in a job of their own, not inside `test` and e2e — `ci.md` of the
+  `spec` skill); `main` is red by itself — exit code 3, I don't merge: one bug
+  for it, and I wait for it to close (the `github` skill).
+  An empty list or `no checks reported` means "not registered yet", not
+  "passed"; a failed check means "red" at once, without waiting for the rest.
+- **Actions jobs didn't start** with the annotation "The job was not started
+  because recent account payments have failed or your spending limit needs
+  to be increased" — this is the account owner's billing: neither a rerun nor
+  a code change will help. I don't re-run or fix — I tell the owner; the merge
+  waits.
+- **A merge that deploys** (deploy from `main`) isn't the end of the task yet:
+  before reporting "done" I wait for the statuses on the merge SHA — the
+  deploy and the checks after it (the `ci-wait` skill, `merged <N>`). A
+  production smoke test is a check in the project's CI, not a manual agent
+  step. Failed — logs and a fix at once: it blocks the report and closing the
+  task.
+- **Deploy — by the commit status, not by polling the site.** Whether the
+  merge rolled out is told by the host's status on the merge SHA (`ci-wait
+  merged <N>`), not by the page: frequent requests to the live site turn on
+  the host's bot protection, and from then on the site answers with a
+  challenge instead of the page — to the agent, or even to everyone from the
+  same address. Need to see the page — one request after a green status, not
+  a loop.
+
+## Auto-fix — off
+
+Auto-fix of the Claude Code app's CI monitor wakes the session with a
+`<ci-monitor-event>` on failed checks, a conflict and review comments, and on
+a conflict tells it to merge the base branch in, never rebase or force-push.
+The flow merges by rebase only (`github project fix` turns the other merge
+methods off): a merge commit in the PR's branch brings the conflict back at
+the rebase merge. In pilot #471 the event about an executor's PR came to the
+dispatcher session while the executor was in the middle of a rebase in its
+worktree: `main` merged in there would have broken it (#529).
+
+- **Off for the flow's PRs:** the app binds each new PR of the session with
+  Auto-fix on, so right after `gh pr create` — `get_status` (the newest PR is
+  the bound one, earlier ones go to `otherBoundPrs`); Auto-fix on for my PR —
+  `set_monitor` with `auto_fix: false` and the PR's url. Nothing is lost: red checks and a conflict come from
+  `ci-wait` (FAIL; ERROR "rebase onto origin/main"), and its completion
+  wakes the session.
+- **An event came anyway** (Auto-fix was on): a conflict — `git fetch
+  origin`, `git rebase origin/main`, `git push --force-with-lease`, then
+  `ci-wait` again; red checks — the root cause, as on FAIL; the base is never
+  merged in. Then Auto-fix off, as above.
+- **A dispatcher session:** the app binds the executors' PRs to it, and their
+  events come to it. An executor's PR isn't the dispatcher's step: the
+  executor drives it, the dispatcher doesn't touch its branch or worktree; an
+  executor that stopped (a limit, a dropped session) is continued with
+  `SendMessage`.
+
+## Polling mechanics
+
+- Decide only by `bucket` (`pending`, `fail`, `cancel`, `pass`, `skipping`).
+  The list is empty or has `pending` → wait. Merge — when the list is
+  non-empty, there is no `pending` and the snapshot repeated two polls in a
+  row (checks register with a delay). `fail` or `cancel` — the outcome is
+  known at once: a long check alongside (a preview deploy) won't change it.
+- By a commit's full SHA (deploy, an external check, a run on `main`) checks
+  live in two places: statuses of hosts and external services —
+  `gh api repos/{owner}/{repo}/commits/<sha>/status` (the `statuses` list by
+  context), GitHub Actions — `commits/<sha>/check-runs` (`status`,
+  `conclusion`). Wait for both: on a commit where all CI is Actions there are
+  no statuses at all. `gh pr checks` doesn't accept a SHA.
+- By PR number — on every poll `gh api repos/{owner}/{repo}/pulls/<N>`
+  (`head.sha`, `mergeable`, `base.ref`), checks — by the head SHA, as for a
+  commit: a new push changes the head. `gh pr checks` goes to GraphQL, whose
+  quota (5000 points per hour) is shared by all the user's sessions — with
+  parallel sessions it runs out before REST does.
+- `mergeable: false` — a conflict with the base: there is no merge ref,
+  workflows on `pull_request` don't start, and a non-empty snapshot of host
+  statuses alone gives a false outcome. Nothing to wait for — rebase. `null` —
+  GitHub is still computing: wait. Right after a push the API still returns
+  the previous head's `false`: a conflict — only when the next poll of the
+  same head repeats it.
+- The base branch's required checks — `rules/branches/<base>` (ruleset, rule
+  `required_status_checks`) and `branches/<base>`
+  (`protection.required_status_checks`, if `enforcement_level` isn't `off`):
+  while any of them is missing from the snapshot — wait.
+- Actions runs on a SHA — `actions/runs?head_sha=<sha>`: a run that failed
+  without a single job gives no check run — the workflow wasn't parsed (the
+  run's name is the file path, event `push`) or didn't start. That is "red",
+  not an empty spot: without it a snapshot of host statuses alone gives a
+  false "green". A workflow whose `on:` fires on the PR at the head SHA but
+  which produced no run — wait.
+- A response with `rate limit` isn't an error: wait until `reset` from `gh api
+  rate_limit` (that request doesn't spend quota), a secondary limit — a
+  minute.
+- Right after a push `gh pr checks` answers `no checks reported` with exit 1 —
+  that means "not registered yet", not "failed" and not "passed". Exit codes
+  0 / 1 (failed) / 8 (`pending`) are set only **without** `--json`; with
+  `--json` it exits 0 on both `pending` and `fail`.
+- Without branch protection `gh pr merge --auto` merges without waiting for
+  CI.

package/docs/testing.md

@@ -0,0 +1,304 @@
+# How to test: runs, environment, e2e, UI in a browser — for "Tests and code"
+
+The rule — which test is needed and how it can fail — is `AGENTS.md`,
+"Specification — decisions" (in full — `skills/spec/canon.md`), and
+`AGENTS.md`, "Tests and code"; the task's Compose stack, its addresses and
+the runner config — `docs/parallel-checkouts.md`.
+Here — how to run tests, read the result, write e2e tests that don't flake,
+and check UI in the agent's browser. The rules hold for any stack, the
+examples are Playwright. Three things depend on the framework: which env files
+each command reads, what is baked into the build, and how to serve a
+production build locally — they are in "Framework: three questions". Checked
+against the Playwright, Next.js, Vite, SvelteKit and Nuxt documentation.
+
+## Run and result
+
+- **A heavy run goes through the machine queue.** The flow install wraps the
+  project's checks (`lint`, `typecheck`, `test`, `test:*`) in `slot`: two runs
+  go at once, together on half the cores; the rest wait in order of arrival
+  and print whom they wait for (the `slot` skill). Without the queue,
+  neighboring sessions, the linter and another worktree's e2e share the cores —
+  timeouts and flakes that aren't about the code. Runner workers come from
+  `ELVES_SLOT_CPUS` (a quarter of the cores); CI has its own:
+
+  ```ts
+  maxWorkers: Number(process.env.ELVES_SLOT_CPUS) || undefined,                      // vitest.config.ts
+  workers: Number(process.env.ELVES_SLOT_CPUS) || (process.env.CI ? 2 : undefined), // playwright.config.ts
+  ```
+
+  A monorepo on turbo 2 — `"globalPassThroughEnv": ["ELVES_SLOT",
+  "ELVES_SLOT_CPUS"]` in `turbo.json`: otherwise strict env mode won't pass
+  them to tasks, and `env`/`globalEnv` would add them to the cache hash.
+
+  Compare time by CI or by CPU (`user` from `time`), not by wall clock: that
+  includes the queue wait. Check a flake by repeating it (`--repeat-each`) —
+  via a project script, in a slot, otherwise the repeat measures the
+  neighbors.
+- **A long run — under watch.** A full run, all the more with a queue, does
+  not go right up against the agent tool's timeout: on timeout the process is
+  killed mid-tests (`Killed: 9`), and the wrapper (`| tail`, `&& echo ok`, a
+  script without `set -o pipefail`) may return 0. Run it as a background
+  command with a generous timeout (in Claude Code — up to 2 h, completion
+  wakes the session) or in a terminal; wait for the process to finish, not
+  for a deadline.
+- **Before a commit — what the change affects; the full run is CI's.** A full
+  local run repeats what CI does anyway — in parallel jobs and shards, faster
+  and reproducibly; locally the agent waits twice — the queue and the run,
+  then CI — and the run holds the shared machine. An error before the push
+  is almost always caught by the tests the change itself affects. Before a
+  commit:
+  - `lint` and `typecheck` — in full: they are fast and incremental;
+  - `test:spec` — in full: standards read the code from disk and the
+    architecture model takes the whole tree, the import graph never selects
+    them;
+  - `test` — the affected: the runner's `--changed=origin/main` (Vitest,
+    `bun test`; Jest — `--changedSince=origin/main`) through the project's
+    script (`npm run test -- --changed=origin/main`) runs the test files that
+    import a file changed against `origin/main`, committed or not. Nothing
+    affected isn't an error: Vitest needs `--passWithNoTests` for it
+    (otherwise exit code 1), `bun test` passes by itself;
+  - tests that reach the code not by an import — a script started as a
+    process, a file read from disk, an app behind its server, a dynamic
+    `import()` — the graph doesn't see: a separate run by path — the tests
+    that name the changed file (`grep -rl <file> tests`) or its decision's
+    folder; a path together with `--changed` is their intersection, not a
+    union;
+  - `test` in full — when the change touches what every test depends on and
+    no import shows: the runner config, its global setup (`setupFiles`,
+    `globalSetup`, `preload` in `bunfig.toml`), the lock file;
+  - e2e — the changed specs (Playwright `--only-changed=origin/main
+    --pass-with-no-tests`): it follows the specs' own imports (fixtures, page
+    objects), not the app code the browser opens; the rest — CI;
+  - `test:slow` — when the change touches what it checks (below).
+
+  The full run is CI's; `github pr premerge` stays as it is: `typecheck` and
+  `test:spec` on the merge with a fresh `main` (`docs/pr-checks.md`).
+- **A slow level — a script of its own.** Tests that need Docker or a live
+  server go into a separate script (`test:slow`, by file name — the runner
+  selects files, not test blocks), so `test` stays fast before every commit.
+  CI runs every level; locally a slow level runs when the change touches what
+  it checks.
+- **The result — by the runner's summary, not the exit code.** Playwright's
+  summary: `passed`, `failed`, `flaky`, `skipped`, `did not run`,
+  `interrupted`; Vitest — the `Test Files` and `Tests` lines; `bun test` —
+  `pass` and `fail`. A run is good when the summary is there, there are no
+  failed, not-run or interrupted tests, and flakes are investigated
+  (`AGENTS.md`, "Tests and code": a flake is a defect). No summary — the run didn't finish,
+  whatever the exit code. Filtering the output by `Error:` lies: the app
+  server writes harmless errors (an expected 404, a cancelled request) to the
+  same stream.
+- **A failed test's artifacts — set aside at once.** The runner clears the
+  results folder at the start of a run (Playwright — `outputDir`, by default
+  `test-results/`): copy the trace, screenshots and video before rerunning.
+
+  ```bash
+  cp -R test-results "$TMPDIR/e2e-<task>-$(date +%H%M%S)"
+  npx playwright show-trace "$TMPDIR"/e2e-<task>-*/<test>/trace.zip
+  ```
+- **A build and a run against it — not in parallel.** The build directory
+  (section "Framework: three questions") is shared: rebuilding under a running
+  server swaps the chunks, and open pages fail loading them. Build first, then
+  run; don't build in another terminal of the same checkout.
+
+## Environment
+
+- **Each command reads its own env files, and the production server
+  sometimes none.** The dev server, the build and the production server of
+  one app take their environment from different places (table below). An env
+  pulled from the host (`vercel env pull`, `netlify env:import` and the like)
+  may carry production secrets and production addresses: a local production
+  build will take it and go to the production database.
+- **Exports win over files.** `.env*` doesn't override a variable already set
+  in the environment (Next.js, Vite and everything built on it, dotenv
+  without `override`), and a production server that reads no files sees only
+  the exports. Local build, production server and e2e — only with an
+  explicitly exported local environment:
+
+  ```bash
+  set -a; . ./.env.e2e; set +a        # own file, local addresses only
+  npm run build && npm run test:e2e
+  ```
+- **What is baked into the build can't be changed by an export.** Public
+  variables (and in some frameworks private ones — see the table) are
+  substituted into the code at build time: the build for e2e uses the same
+  local environment as the run; changed an address or a port — rebuild.
+- **Where the env points — check with a command, don't rely on memory:**
+
+  ```bash
+  grep -H -E '^[A-Z_]*_URL=' .env* | sed -E 's#(://[^:]+:)[^@]+@#\1***@#'
+  ```
+
+  A guard "a laptop doesn't connect to a remote database without an explicit
+  flag" is a project standard (`tests/standards/<name>`), not attentiveness.
+- **A fresh database per run.** CI starts from an empty database and catches
+  fixture races; a populated local database hides them — or the other way
+  round, its old rows show up in others' lists. The task's e2e stack starts
+  on clean volumes every run (`task-env e2e`, `docs/parallel-checkouts.md`).
+  A test that is green on CI's empty database and red on a populated local
+  one is a defect of the test (it depends on others' data), not of the
+  database.
+
+## e2e
+
+- **Against a production build, not the dev server.** In the task's e2e
+  stack the app is a service of the compose file, and for e2e it serves the
+  production build (table below) — a profile or a build target by a variable
+  set on the `task-env e2e` command: the script passes its environment to
+  Compose. Without the stack (CI) — `webServer.command` is the build and the
+  production server, not `dev`. The dev server changes code under a run:
+  Next.js compiles a route on its first request, Vite (and SvelteKit, Nuxt,
+  React Router built on it) re-bundles dependencies and reloads the page when
+  it meets a new dependency mid-run — timeouts and warnings that production
+  doesn't have.
+- **External services — stubs or emulators** via environment flags of the
+  e2e server (the service's `environment` in the stack, otherwise
+  `webServer.env`): email, payments, storage, LLM. A side effect ("email
+  sent", "payment created") — by polling your own database or the emulator,
+  not via a UI that itself depends on the external service.
+- **Shared data — a setup project, once per run.** What all parallel files
+  see (reference data, catalogs, users to log in with) is created by the
+  runner's setup project, not by a file's `beforeAll`: otherwise two files at
+  once see "missing — creating" (TOCTOU) and fail on a unique key or share one
+  row.
+
+  ```ts
+  // playwright.config.ts
+  projects: [
+    { name: 'setup', testMatch: /global\.setup\.ts/ },
+    { name: 'e2e', dependencies: ['setup'], use: { storageState: 'tests/.auth/user.json' } },
+  ],
+  ```
+- **Your own data — under a unique prefix.** Test data gets a prefix from the
+  worker, the time and a random suffix
+  (`` `e2e-${testInfo.workerIndex}-${Date.now()}-${rnd}` ``); creating and
+  cleaning up — directly in the database (factories in `tests/lib`), not via
+  the UI: UI setup steps are slow and fail in the wrong place.
+- **A fixture doesn't surface in others' lists.** Its creation date is in the
+  past (lists sort by it, a new row would push the expected one out of first
+  place); a test looks for a known entity by name, not for the table's first
+  row.
+- **Wait for the response — before the action and by its own URL.**
+
+  ```ts
+  const saved = page.waitForResponse((r) => r.url().includes(`/api/orders/${id}`) && r.request().method() === 'PATCH');
+  await page.getByRole('button', { name: 'Save' }).click();
+  expect((await saved).ok()).toBe(true);
+  ```
+
+  A wait registered after the click misses a fast response; without a URL
+  filter it catches someone else's request (analytics, prefetch).
+- **The first action after an SSR navigation may be lost** before hydration
+  (Next.js, Nuxt, SvelteKit, React Router, Astro islands): the button is
+  already in the HTML, the handler isn't there yet. Put the action together
+  with the check of its result into a retried block, not a pause:
+
+  ```ts
+  await expect(async () => {
+    await page.getByRole('button', { name: 'Filter' }).click();
+    await expect(page.getByRole('dialog')).toBeVisible({ timeout: 1_000 });
+  }).toPass({ timeout: 10_000 });
+  ```
+
+  `toPass` has a default timeout of 0 — it retries until the test timeout:
+  your own `timeout` is required. Only an idempotent action (open, select)
+  may be retried, not "create". A SPA without SSR doesn't have this race: the
+  button doesn't exist before render, and the runner waits for it. Navigate
+  straight to the canonical URL: a path redirect means an extra hydration and
+  a race. Assertions are web-first (`toHaveText`, `toBeVisible`), not
+  `textContent()` and a snapshot comparison.
+- **Log in with a saved session.** The setup project logs in once and writes
+  `storageState`; tests start with it instead of filling in the login form. A
+  visual check by the agent (the session's browser) uses the same
+  `storageState`, without typing a password; page state — from the DOM
+  (section "UI in the agent's browser"). The login form is checked by one test
+  of the login itself.
+- **A guard for a framework's dev warning** (React, Vue: hydration, list
+  keys) — a unit test in dev mode (jsdom, happy-dom): the production build
+  strips the warnings, so in e2e against it the guard can't fail (`AGENTS.md`,
+  "Tests and code").
+
+## UI in the agent's browser
+
+The browser of the agent's session (Claude Code's built-in browser, Chrome
+with the extension) is for looking at a page through a human's eyes: layout,
+look, the path through screens.
+
+- **State — from the DOM, a screenshot — only for the look.** Whether a popup
+  (popover, menu, calendar, dialog) is open and what a click did — read it
+  from the page: the accessibility tree (`read_page`, `find`) — is there an
+  element with role `dialog`, `menu`, `listbox`; JS on the page
+  (`javascript_tool`) — the state attribute and the animations, before the
+  action and after it:
+
+  ```js
+  ((el) => el && {
+    state: el.dataset.state ?? (el.hasAttribute('data-closed') ? 'closed' : 'open'),
+    anims: el.getAnimations({ subtree: true }).map((a) => a.playState),
+  })(document.querySelector('[role="dialog"], [role="menu"], [role="listbox"]'));
+  ```
+
+  The attribute depends on the library: `data-state="open|closed"` (Radix,
+  shadcn/ui), `data-open`/`data-closed` (Base UI, Headless UI); on the trigger
+  button — `aria-expanded`. No element — the popup is closed and unmounted.
+- **A screenshot lags behind the state.** A hidden browser pane or a
+  background tab is throttled: CSS animations and `requestAnimationFrame`
+  almost stand still. A popup that is closed by state (`closed`, exit
+  animation `running`) stays mounted until the animation ends and looks open
+  in a screenshot for seconds more; a screenshot may also show a frame from
+  before the last click.
+- **A "doesn't close", "doesn't open", "the click didn't work" bug — only
+  after checking the DOM.** `closed` with an exit animation running is not a
+  bug but throttling. A bug is when the state didn't change after the action,
+  or the animations have ended and the closed element is still visible. A
+  screenshot of the result — with the pane visible and after the animations
+  end, not after a pause.
+
+## Unit tests
+
+- **A mock goes at the external edge and behaves like the real thing.** A
+  mock of your own module hides its behavior (the framework's request queue,
+  form parsing, a transaction) and is forbidden by lint ("Specification —
+  decisions", `skills/spec/canon.md`). What is replaced is the boundary with
+  the outside world — a third-party API's HTTP, email, the clock — and the
+  way it really responds (codes, delays, error format per its docs).
+- **An entry point — through the same input as in production.** A form
+  handler gets a `Request` or `FormData` (a Next.js server action, a React
+  Router `action`, a SvelteKit form action), a route gets an HTTP request,
+  not a ready-made object passed straight into the validation schema:
+  otherwise the test doesn't see form parsing, type coercion and missing
+  fields.
+
+## Framework: three questions
+
+Before a project's first e2e run — answer from its framework's documentation
+and write the answer into the project's `docs/` (an environment recipe):
+
+1. Which env files the dev server, the build and the production server read,
+   and whether an already exported environment wins over them.
+2. What is baked into the build and doesn't change without a rebuild.
+3. How to serve a production build locally and where its directory is.
+
+| Framework | Who reads `.env*` | Baked in at build | Production build locally | Directory |
+|---|---|---|---|---|
+| Next.js | `dev` — `.env.development*`, `build` and `start` — `.env.production*`, `.env.local` and `.env` — both; under `NODE_ENV=test` `.env.local` isn't read | `NEXT_PUBLIC_*` | `next build && next start` | `.next` |
+| Vite (SPA) | `dev` — `.env.development*`, `build` — `.env.production*` (`--mode` changes it), `.env[.local]` — both; production is static files, no environment | `VITE_*` (`import.meta.env`) | `vite build && vite preview` — for checking only, not a production server | `dist` |
+| SvelteKit (adapter-node) | `dev` and build — as in Vite; `node build` doesn't read `.env` — `node --env-file=<file> build` | all of `$env/static/*`, private too; `$env/dynamic/*` — at runtime | `vite build && node --env-file=.env.e2e build` | `.svelte-kit`, `build` |
+| Nuxt | `dev`, `build`, `generate`, `preview` — `.env` (another file — `--dotenv`); `node .output/server/index.mjs` — reads none | `runtimeConfig` set via `process.env.<another name>`; at runtime only `NUXT_*` overrides it | `nuxt build && nuxt preview` (reads `.env`) | `.nuxt`, `.output` |
+
+A framework not in the table (React Router, Astro, a backend without a
+frontend) — the same three questions to its documentation; the answer goes
+into the project's `docs/`, not into memory.
+
+## Test knowledge in the project
+
+- The project's `docs/` — only recipes for its own environment: which env
+  files, containers, emulators, hosting, how to bring them up, the answers to
+  the three questions above.
+- A checkable rule about tests ("e2e tests don't mock their own API",
+  "fixtures get a prefix") is a standard `tests/standards/<name>`, not a
+  paragraph in a document.
+- Knowledge about a helper (what a factory creates, what it cleans up, what
+  permissions a user has) — in its JSDoc in `tests/lib`: the editor's hint
+  shows it, a document doesn't.
+- A lesson repeated in two projects is a task in Elves for this reference
+  (`AGENTS.md`, "This file and skills"), not the agent's memory.