tinybeeai 0.0.0-stage → 0.16.1

package/docs/SETUP.md

@@ -0,0 +1,776 @@
+# Setup
+
+Connect each service from the **Setup** page of the app. Every row on that page has a **Connect** button that opens a short flow: pick how localdost signs in, paste a key or press a sign-in button, press **Test**, then press **Connect**. The service starts working at once, with no restart. Each row links to its section of this guide, and the guide opens inside the app.
+
+Environment variables still work, and they win. A service that an environment variable sets shows **Set by environment** on the Setup page, and the app shows it read-only. To manage it from the app instead, remove the variable and restart the server.
+
+## Connect from the app
+
+Open Setup from the side bar, or from the banner that appears while a service needs attention. The rows that need you come first.
+
+| Button | What it does |
+|---|---|
+| **Connect** | Opens the flow for a service that is not connected yet |
+| **Test** | Checks the values in the form, or the saved connection, against the real service and shows the result in the row. Test saves nothing |
+| **Edit** | Opens the flow again with the saved choices filled in. Secrets show only their last 4 characters |
+| **Disconnect** | Deletes the saved values. The service goes back to demo mode, or to the environment value when there is one |
+| **Check again** | Runs a detection again, for example for Docker or a signed-in CLI |
+
+Saved secrets are encrypted at rest in the data folder (`LOCALDOST_DATA_DIR`) with a key that localdost creates there on first use. The server never sends a saved secret back to the browser. Back up the whole data folder, because the saved values cannot be read without the key next to them.
+
+The Setup page uses the same API as the rest of the app. On your own machine it works with no token. On any other host, set `LOCALDOST_TOKEN` first and enter the token on the Join screen of a new server or in Settings, so only token holders can connect services.
+
+## Start a team server
+
+A new server opens the setup flow at `#/welcome`. The flow is for the person who sets the server up. It has eleven steps, and a reload keeps you on the step you were on. While the flow is open, a **Getting started** link in the sidebar (and in the More menu on a phone) opens it again. **Close setup** ends it for now, and the Dots page then shows a Next steps card with what is left.
+
+Start the server first. Set the token and the public URL, then build and start:
+
+```bash
+npm ci && npm run build
+LOCALDOST_TOKEN=$(openssl rand -hex 24) LOCALDOST_PUBLIC_URL=https://localdost.example.com npm start
+```
+
+| Step | What it does |
+|---|---|
+| Welcome | You choose **A team server** or **My laptop**. The team choice checks `LOCALDOST_TOKEN` and `LOCALDOST_PUBLIC_URL` and says what is missing. The check never blocks. **Try the demo** shows on a demo server only |
+| Event delivery | The step says webhooks only after a signed delivery from GitHub reached this server (a ping counts, for up to 7 days). An https public URL and a webhook secret are not enough: a token has no webhook until you add one to each repo (Settings, Webhooks, Add webhook, payload URL `<public URL>/hooks/github`, content type `application/json`, the secret, and the events Pull requests, Pushes, Workflow runs, Deployment statuses, Issue comments, Issues), and a GitHub App made before the public URL was set has none either. Until a delivery arrives the dot polls GitHub every `POLL_GITHUB_SEC` seconds, and Check again on the step reads the server once you have added the hook. Polling does not see CI failures, preview deployments, or `/localdost review` comments |
+| Model | A signed-in Claude or Codex login that localdost found is offered, never used before you say so. On a server with `LOCALDOST_TOKEN`, localdost picks none on its own. The Claude account email is hidden from anyone who is not on the server's machine. On a team server, use a team API key. **Continue** shows after any working choice |
+| GitHub | Connect with a gh login, a GitHub App, or a token. On a first pass no repo is picked yet, so **Test access** here checks the connection. The Repos step then tests each picked repo and its issues endpoint by itself, and Create dot tests the code repos and the tracker repo together, and both name SAML SSO when GitHub asks for it. See [GitHub](#github) for the permissions |
+| Repos | Each repo is an **App** repo (reviewed and tested), a **Tests** repo (the repo that holds the end-to-end suite, which the dot runs on PRs and merges of the app repos, see [Tests repo](#tests-repo)), or **Issues only** (read for tickets, not watched). An App repo can narrow its pull requests to some authors, and skip drafts and bots (the dot obeys it, see [PR scope](#pr-scope)), and it has a **Run tests for this repo** switch, on by default: turn it off for a back end with no Playwright suite and the dot reviews its pull requests and runs no tests (see [Run tests per repo](#run-tests-per-repo)). A Tests repo and an Issues only repo have no scope and no Run tests switch |
+| Tracker | **GitHub Issues** comes first, with a picker for any repo the connection can read (it may hold no code). The repo starts as the Issues only repo you picked on the Repos step, else the first app repo. You choose the issue types (Feature, Task, Bug, Story), the labels an issue needs one of, and a milestone. The step counts the open issues that match, with the rule the dot uses. Linear and Jira are under **Other trackers** |
+| Tests | Each app repo shows its own setup steps, test command, and QA base URL, filled in from the scan and the CI workflow. **Try once** runs them. A field saves when you leave it. A repo with Run tests off is left out and named. The dot runs one command for its app repos: the one of the first app repo that runs tests. A Tests repo has its own command and setup (see [Tests repo](#tests-repo)). Name the sign-in variables of the app under test in the dot dialog afterwards (**Test login variables**, see [Test login](SANDBOX.md#test-login)) |
+| Slack | Connect Slack or skip it. Pick the channel (stored by its id, which is what routes mentions) and list the approvers by Slack member ID (`SLACK_ALLOWED_USERS`) |
+| Rules | One list of every outward action with its level. The **shadow week** is on by default: for 7 days, PR comments and checks wait in the Inbox for your approval, then they post on their own |
+| Create dot | The dot watches the repos with their roles, reads tickets from the tracker repo alone (an Issues only repo that is not the tracker repo is named as unread), and posts to the Slack channel. It marks an app repo with Run tests off as `(app, no tests)`. It refuses to be made with no app repo, says why on the button, and shows how it listens: `Listening: webhooks` or `Listening: polling every 60 s` |
+| First review | **Review without posting** is the main button: the dot writes the review and its comment and check wait in the Inbox. **Post a comment and a check on PR #N** posts them, and shows only when no shadow week runs: during the shadow week both buttons leave the comment and the check in the Inbox, so the step says so with the end date |
+
+While the shadow week runs, Settings shows it above the Rules of the dot with its end date and an **End shadow week** button, and the dot page lists it under Sources. Saving the dot dialog does not end it: only a rule you change by hand leaves the week.
+
+In sandbox mode (`LOCALDOST_SANDBOX=1`) jobs do not run, so the Repos and First review steps say so and offer no scan or review.
+
+After the flow, the Next steps card has a **Connect True Platform** row. Enter the https address of your Katalon MCP server. localdost adds it as an HTTP connection from the `katalon-true-platform` preset. If the server needs a token, put the request headers as JSON in `KATALON_MCP_HEADERS` on the localdost server. More: [CONNECTIONS.md](CONNECTIONS.md#presets).
+
+### The shadow week
+
+A dot made by the flow has `shadowWeek` on it: the end date, the rules it holds (`pr_comment` and `check_run`), and the levels they go back to. A server job runs at boot and every 5 minutes, and a check inside the rules gate reads an ended week as its old level at once, so a stopped timer cannot keep a dot silent. A rule you set by hand during the week leaves the week and keeps your level. Only a rule that acts on its own is held back. A rule already at Ask first, When asked, or Hand off stays as it is. To start or end a week yourself, send `shadowWeekDays` (1 to 30, or 0 to end it now) to `PATCH /api/dots/:id`.
+
+## Settings files
+
+You can also keep settings in files. `localdost start` loads `.env.localdost` from the repo folder, and a variable already set in your shell wins over the file. `localdost init` writes two files in the target repo:
+
+- `.env.localdost` holds settings and references, never secrets. `localdost init` adds it to `.gitignore`.
+- `.localdost/config.json` holds the detected repo, tracker, test command, port, model, and dot id. It has no secrets and is safe to commit.
+
+A value in `.env.localdost` can be a literal or a reference:
+
+| Form | Example | Result |
+|---|---|---|
+| Literal | `PORT=4319` | The value as written |
+| `${env:NAME}` | `LINEAR_API_KEY=${env:LINEAR_API_KEY}` | `NAME` from the shell that runs `localdost start` |
+| `${cmd:...}` | `GITHUB_TOKEN=${cmd:gh auth token}` | The output of one read-only command, run without a shell |
+
+A `${cmd:...}` reference runs only `gh auth token`, `op read`, `security find-generic-password`, `security find-internet-password`, or `pass show`. Any other command stays unresolved, and `localdost start` prints a warning for it. A relative `LOCALDOST_DATA_DIR` resolves against the repo folder.
+
+Docker Compose reads `.env` next to `compose.yml` instead. `.env.example` in the localdost folder lists the common variables. The Setup page, `GET /api/setup`, and `localdost doctor` run the same readiness checks.
+
+## Server
+
+Server settings are read once at boot, so they have no Connect flow. Set them in the environment.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PORT` | `4319` | Listen port |
+| `HOST` | `127.0.0.1` without a token, `0.0.0.0` with one | Listen address. A non-loopback `HOST` without `LOCALDOST_TOKEN` stops the server at boot |
+| `LOCALDOST_TOKEN` | unset | Bearer token for `/api/*` and `/artifacts/*`, sent only in the `Authorization` header. Without it, `/api` answers only requests whose `Host` header is a loopback name, and webhooks answer only with their secret set (see `LOCALDOST_ALLOW_UNSIGNED_WEBHOOKS`) |
+| `LOCALDOST_ALLOW_UNSIGNED_WEBHOOKS` | off | `1` lets `/hooks/*` accept events from a source whose webhook secret is unset, as older versions did. The server logs a warning at start. For local demos only: anyone who can reach the URL can queue jobs. `LOCALDOST_DEMO` does not turn it on |
+| `LOCALDOST_PUBLIC_URL` | unset | HTTPS origin used in links in comments, pushes, and Slack. See [Public URL](#public-url) |
+| `LOCALDOST_SERVER_NAME` | unset | The name the Join screen shows, for example `Agentic pod QA`. Without it the screen shows the host name. See [Join a team server](#join-a-team-server) |
+| `LOCALDOST_DEMO` | off | `1` seeds the Checkout dot and starts the sample shop |
+| `LOCALDOST_SAMPLE_PORT` | `4320` | Port of the demo sample shop |
+| `LOCALDOST_SANDBOX` | off | `1` serves the app and the API over the existing data and lets nothing leave. See [Sandbox mode](#sandbox-mode) |
+| `LOCALDOST_DATA_DIR` | `data/` in the localdost folder, `.localdost/data` under `localdost start` | Database, push keys, saved connections and their key, artifacts, checkouts, eval candidates |
+| `LOCALDOST_DB` | `<LOCALDOST_DATA_DIR>/localdost.db` | SQLite file. `:memory:` keeps it in memory |
+| `LOCALDOST_WEB_DIR` | `dist/web` | Built PWA folder |
+| `LOCALDOST_COMMIT_SHA` | git, else unset | Commit this build came from, for `GET /api/health`. Set it in an image or host that has no `.git` folder. See [Version](#version) |
+| `LOCALDOST_DISK_MIN_FREE_GB` | `2` | Free space the data folder must keep. Under it, new test runs wait. `0` turns the check off. See [Disk space](#disk-space) |
+| `LOCALDOST_ARTIFACTS_MAX_GB` | `2` | Most artifact space one dot may use. Over it, the oldest runs lose screenshots, videos, and traces. `0` turns the cap off. See [Disk space](#disk-space) |
+| `LOG_LEVEL` | `info` | Fastify log level |
+| `LOCALDOST_USE_DIST` | unset | `1` makes `bin/localdost.js` run the built `dist/` code even when `src/` exists |
+
+Flag variables (`LOCALDOST_DEMO`, `LOCALDOST_SANDBOX`, `LOCALDOST_POLL`) accept `1`, `true`, or `yes`.
+
+## Join a team server
+
+A team server is one localdost that several people use. The admin sets it up once and invites each person. A teammate needs no admin token and no setup of their own.
+
+### Invite a teammate
+
+1. Open **Settings** and press **Invite a teammate**, or press **Invite** on the Invite a teammate row of the Next steps card on the Dots page.
+2. Pick how long the code lasts: 1 hour, 1 day, or 7 days, and the role the teammate joins as: **Member** or **Editor** (see [Roles](#roles)). Press **Make invite code**.
+3. The sheet shows the code with its role, a link, and a message for Slack. Press **Copy message** and send it to one person.
+
+A code works once, so make one per person: **Make another code** adds one, and **Cancel open invites** cancels every code nobody has used. A code is stored as a hash, never as text, and it survives a restart.
+
+The expiry in the Slack message carries the time zone of your browser, for example `GMT+7`, so a teammate in another zone can read it. After a code is made, the Expires in and Joins as choices are for the next code, and the code on screen keeps the ones it was made with.
+
+The link uses the address the sheet shows. The sheet leads with the address of the page you have open when a teammate can use it, then Tailscale, the Public URL, and the same Wi-Fi. A page that is open on localhost gives a teammate nothing to open, so the sheet says so and points to [Public URL](#public-url). Set `LOCALDOST_SERVER_NAME` to give the server a name on the Join screen.
+
+### Join as a teammate
+
+1. Open the server link. A browser with no token shows a Join screen with the server name, not an error. On a server with no dot yet, the same screen also asks **Admin? Enter the server token**: paste `LOCALDOST_TOKEN` (the service Variables on Railway, or the `.env` file next to `compose.yml`), and **Save and open Getting started** checks the token and opens the setup flow. A wrong token says so at the field and keeps nothing.
+2. Type your name and the code. The server keeps the device under your name, and the name goes next to every draft you approve or reject. A name another device already uses is refused: add a last name or the device, for example `Cy Nguyen (laptop)`.
+3. Pick your updates: everything, only what needs you, or off, with optional quiet hours. They apply to your device only. Settings keeps them afterwards.
+4. Read the three cards: Inbox, a run page, and `@dot` in Slack. **Open Inbox** ends the tour.
+
+A wrong or old code gets "Ask your admin for a new one". One client may send 5 wrong codes in 10 minutes before it is locked out, and 20 wrong codes from anyone cancel the open phone code. Invites are not cancelled that way: they stay until you cancel them or they expire.
+
+A teammate's device is a paired device with a role. An admin revokes it, or changes its role, under **Setup**, then **Phone**, in the Paired devices list.
+
+### Roles
+
+The invite gives the device a role. The server holds the role on every call, and the app shows a device only the controls its role may use. A refused action says "Ask your localdost admin".
+
+| | Member | Editor | Admin token |
+|---|---|---|---|
+| Approve and reject drafts, chat, rerun tests, ask for a review, record manual results | yes | yes | yes |
+| Pause and resume a dot | yes | yes | yes |
+| Dot settings and rules, a dot's memory, Try it on the saved test command, card actions (Comment, Change status) | no | yes | yes |
+| The test command, setup steps, test login variables, copy files, Docker image, runner mode, folders of a dot or a test repo, and the deploy wait | no | no | yes |
+| The repositories of a dot and their roles, the branch of each, the repos a test repo exercises and its ref and framework, and the test branches | no | no | yes |
+| Send to True Platform: the switch, the address, the project, and the connection check | no | no | yes |
+| Setup, connections, the model, invites, pairing, a new dot, archive, restore, and delete a dot | no | no | yes |
+
+What runs on the server as its user stays with the admin: an editor sees the test command, setup steps, test login variables, copy files, Docker image, runner mode, and working folder read-only in the dot form, with "Ask your localdost admin to change test commands.", and the server answers a change to them with a 403 and the same sentence. The deploy wait ([Waiting for the deploy](#waiting-for-the-deploy)) is read-only for an editor the same way, with "Ask your localdost admin to change the deploy wait." Try it runs the saved command for an editor, never a new one. Which code a run checks out stays with the admin too: an editor sees the repository, its default branch, and the test branches read-only in the dot form, with "Ask your localdost admin to change repositories.", and the server answers a change to them with a 403 and that sentence. Try it clones only the dot's own repo and branch for an editor. Path filters, the PR scope, and the Run tests switch stay open to an editor. A phone paired before roles existed could archive and restore a dot; it is a member now and cannot, and neither can an editor. The dot's chat follows the same line: a member asks and reruns, and a request to remember something needs an editor.
+
+No device can take the name `admin`: approvals made with the admin token are recorded under that name, and a teammate with the same one could not be told apart. A device paired before roles existed, a device paired with a phone code, and the Tailscale owner are members. Change a role at any time in the Paired devices list; the device's next request uses it.
+
+### Pair this computer under your name
+
+A decision made with the admin token is recorded as `admin`, and no device may use that name. In **Settings**, under This device, press **Pair this computer as <name>** to make a device in your name (an editor, not counted as a teammate). The browser uses that key from then on, so each approval carries your name. The admin token stays in the browser: **Use the admin token on this computer** switches back for Setup, connections, and removing a dot, and **Use <name> for approvals** switches again.
+
+### Who approved a draft
+
+Every approval keeps `decidedBy` when a named person decided it: a paired device by its name, the Tailscale owner by login, or a Slack user as `Slack <name>`, the name Slack sends with the button press (`Slack <user id>` when it sends none). The Inbox card, the Recent decisions rows, and the run step show it. The shared admin token is recorded as `admin`. A local browser on a server with no token names no one, so a draft it decides shows no name. A card action (Comment, Change status) keeps who asked on the run step (`Asked on a card by <name>`) and on the draft (`meta.askedByName`).
+
+## Version
+
+localdost versions follow [Semantic Versioning](https://semver.org/) and stay at major 0 until the public launch. `package.json` holds the version, and [CHANGELOG.md](https://github.com/duonghaijoe/localdost/blob/main/CHANGELOG.md) lists what changed in each one.
+
+- The app shows **localdost X.Y.Z** under Settings, About, and as a tooltip on the status line at the bottom of the sidebar.
+- `localdost --version` prints the same words.
+- `GET /api/health` returns `version` and `commit`, and `timeZone` and `tzOffsetMin`, the zone and offset of the server clock that the nightly test run follows. The commit comes from `LOCALDOST_COMMIT_SHA`, then from `RAILWAY_GIT_COMMIT_SHA` or `SOURCE_COMMIT`, then from `git rev-parse HEAD` when the folder is a git checkout. It is `null` when none of them knows.
+
+## Sandbox mode
+
+`LOCALDOST_SANDBOX=1` starts a server that only serves the app and the API over the data it already has. Use it to look at a copy of real data without any chance of a comment, a ticket, a Slack post, or a phone alert going out. Not to be confused with the [Docker runner](#sandbox) below, which runs tests in containers.
+
+What stays off:
+
+- The job queue does not start or claim jobs. Queued jobs stay queued, and a job that was running when the last server stopped is left as it was.
+- Pollers, HTTP and browser probes, status-page checks, and digests do not run.
+- Webhooks answer `503` with a plain message (`/hooks/github`, `/hooks/jira`, `/hooks/linear`). Nothing is checked or queued.
+- Slack does not connect.
+
+What is refused: every outward write. A GitHub comment, check run, or commit status, a pull request branch, a GitHub, Linear, or Jira issue or comment, a Slack post, a phone push or ntfy message, and an MCP tool that changes data. Each refusal logs one line, `sandbox: refused <kind> to <target>`, and sends nothing over the network. A draft you approve in the Inbox stays there with that reason.
+
+What still works: the app, the API, chat, and model calls, so a chat with a dot still gets a real answer. Reads from GitHub, Linear, and Jira work as before.
+
+The app shows the banner **Sandbox: nothing leaves this server.** at the top of every page. `GET /api/health` returns `"sandbox": true` and the same text as `sandboxBanner`. Restart the server without the flag to leave sandbox mode.
+
+## Disk space
+
+A full disk used to stop the server with "database or disk is full". Two settings keep it up. Both count in GB, where 1 GB is 1,000,000,000 bytes, the way macOS counts. A value of `0` turns that setting off. A blank or invalid value uses the default.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LOCALDOST_DISK_MIN_FREE_GB` | `2` | Free space the data folder must keep |
+| `LOCALDOST_ARTIFACTS_MAX_GB` | `2` | Most artifact space one dot may use |
+
+**Low free space.** localdost reads the free space under `LOCALDOST_DATA_DIR` (and the folder of `LOCALDOST_DB` when it is elsewhere) at start and every 3 minutes. Under `LOCALDOST_DISK_MIN_FREE_GB`, the dot takes no new test runs: PR checks, post-merge runs, CI failure reviews, reruns, and repo scans stay queued. Outage and recovery alerts, ticket reviews, and digests still run. The app and the API keep answering. The app shows a **Disk almost full** banner with a link to this section, and one push goes out for each time the space runs short. The queued jobs start by themselves at the first check that finds enough space again. A run that is already going is not stopped.
+
+**A write that finds the disk full.** If SQLite reports "database or disk is full", localdost logs the error, keeps the server running, answers the request with status `507`, pauses new test runs the same way, and shows a **Disk full** banner. The pause ends after a minute with no failed write, once the free space is back over the threshold. A job that could not save its result stays as it was. The next start marks its run interrupted, and Retry runs it again.
+
+**Artifact cap.** Run artifacts live in `<LOCALDOST_DATA_DIR>/artifacts/<run id>/`. When a dot's runs use more than `LOCALDOST_ARTIFACTS_MAX_GB`, localdost deletes files from its oldest runs first. Inside a run it deletes the largest screenshot, video, or trace first, and it stops as soon as the dot is under the cap. It never deletes a run record, a log, or a JSON report, and it skips a run that is still going, so a dot can stay a little over the cap when only those are left. localdost checks the cap when a run ends and on each disk check, and it logs what it removed.
+
+**Free space by hand.** Delete old folders under `artifacts/` and `checkouts/` in the data folder, remove Docker images you no longer use, or empty the Trash. Then wait for the next check (up to 3 minutes) or restart the server.
+
+## Model
+
+The model writes verdicts, ticket scores, action reviews, PR reviews, and chat replies. It can run on your Claude subscription, your ChatGPT plan through the Codex CLI, or an Anthropic API key.
+
+**In the app.** On the Model row, press **Connect** and pick one:
+
+- **Claude subscription** uses your Claude Pro or Max plan, with no API billing. When the server finds a signed-in Claude CLI, the flow says so and **Use it** connects in one click. Otherwise run `claude setup-token` on any machine with the Claude CLI, sign in with your Claude account in the browser it opens, and paste the token it prints (it starts with `sk-ant-oat` and lasts a year). A token works on a server where nobody can sign in to the CLI.
+- **Codex subscription** uses your ChatGPT plan through the Codex CLI, with no API billing. Run `codex login` on the server first. When the server finds a signed-in Codex CLI, **Use it** connects in one click and sets `LOCALDOST_LLM=codex-cli`. **Test** runs `codex login status`, which spends no usage.
+- **API key** uses the Anthropic API and bills per use. Create a key in the Anthropic Console, paste it (it starts with `sk-ant-`), press **Test**, then **Connect**. This fits a shared server.
+
+**Switch models.** The Model sheet and Settings, Model, list every way this server can reach a model: a signed-in Claude CLI, a signed-in Codex CLI, a saved Claude token, and a saved Anthropic key. The one in use is marked. **Switch** runs a test round trip first, then saves the choice; the dots pick it up without a restart. Switching to the signed-in Claude CLI removes a saved Claude token.
+
+**When a model hits a quota or spend cap.** A model call can fail because the plan ran out, the workspace owner set a spend cap, the provider rate limits you, or the sign-in expired. One classifier reads the error of every backend (Codex CLI, Claude CLI, Anthropic API, and the PR review passes) and sorts it into `quota`, `spend_cap`, `rate_limit`, `auth_expired`, or `other`. For the first four:
+
+- The model is marked unavailable with the reason and a time to check again (the provider's retry-after when it gives one, else 1 minute for a rate limit, 5 for an expired sign-in, 15 for a quota, 30 for a spend cap; each failed check doubles the wait, up to an hour). The Model row in Setup and the entry in the model list read `Model unavailable: <reason>`.
+- The call moves to the next model on the list that is signed in or has a saved key, in list order, and the run gets a "Model fallback" step. One push says which model took over. The mock model is never a fallback. A subscription (Claude CLI, Codex CLI) never falls back to a paid per-use API key unless you turn on **Allow paid fallback** in Settings > Model (`LOCALDOST_ALLOW_PAID_FALLBACK=1` also works). It is off by default. With it off, a capped subscription and only a paid key left ends the run as "Model unavailable", and the step names the capped subscription and says that paid fallback is off. A server with `LOCALDOST_TOKEN` is shared, so it never falls back to a Claude or Codex CLI login of its machine either, unless an admin chose that login: Keep this login on the Model step and the model switcher both save the choice, and a login localdost picked on its own does not count. A saved Claude token is a team credential and stays a fallback. A model an admin picks for a stage of a dot is a choice too, so a stage set to a CLI login keeps using it. When nothing allowed is left, the run ends as "Model unavailable" and the step says that this is a team server and which login was not used.
+- When the wait is over, the next call tries the first model again, and a check every 30 seconds does the same when no work is queued. A push says when it works again. A new key, token, or login saved in Setup clears the mark at once.
+- When no model works, a run stops as interrupted with `Model unavailable: <reason>`, no verdict, and a Retry button. The dot's health does not change, since nothing was concluded about the product. Test results already collected stay on the run. Chat answers `Model unavailable: <reason>`. One high-urgency push says that no model works, at most once an hour.
+
+**First start.** When no model is chosen (nothing saved, no `LOCALDOST_LLM`, no key or token in the environment), localdost uses the first signed-in subscription it finds, the Codex CLI first, then the Claude CLI, instead of the mock model. Demo mode keeps the mock model. A server with `LOCALDOST_TOKEN` is shared, and a CLI login on it belongs to one person, so it picks nothing: the Model step of the setup flow lists the logins it found and waits for you. On a server without a token, the Model step asks whether to keep the login localdost picked. The server hides the Claude account email from every caller that is not on its own machine (a loopback socket and a loopback `Host` header).
+
+**With environment variables.** `LOCALDOST_LLM` picks the backend:
+
+| Value | Backend |
+|---|---|
+| `claude-cli` | The local `claude` CLI in print mode, signed in with your own Claude login or `CLAUDE_CODE_OAUTH_TOKEN`. No API key needed |
+| `codex-cli` | The local `codex` CLI (`codex exec`), signed in with your own ChatGPT login. No API key needed |
+| `anthropic` | The Anthropic API with `ANTHROPIC_API_KEY` |
+| `mock` | Deterministic canned verdicts, used by demo mode and the e2e suite |
+| unset | `anthropic` when `ANTHROPIC_API_KEY` is set, else `mock` |
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LOCALDOST_LLM` | unset | Backend, see above |
+| `ANTHROPIC_API_KEY` | unset | Anthropic API key. Analysis uses `claude-sonnet-5-5`, scores and action reviews use `claude-haiku-4-5-20251001` |
+| `CLAUDE_CODE_OAUTH_TOKEN` | unset | Subscription token from `claude setup-token`, used by the `claude-cli` backend |
+| `LOCALDOST_MODEL`, `LOCALDOST_FAST_MODEL` | see `ANTHROPIC_API_KEY` | Main and fast model for either backend. The Setup page saves these names |
+| `LOCALDOST_CLAUDE_BIN` | `claude` | Path to the Claude CLI when it is not on `PATH` |
+| `LOCALDOST_CLAUDE_MODEL` | `sonnet` | CLI model for analysis and chat, 180 s timeout. Wins over `LOCALDOST_MODEL` |
+| `LOCALDOST_CLAUDE_FAST_MODEL` | `haiku` | CLI model for scores and action reviews, 60 s timeout. Wins over `LOCALDOST_FAST_MODEL` |
+| `LOCALDOST_REVIEW_MODEL` | `LOCALDOST_CLAUDE_MODEL` on the CLI, `claude-sonnet-5-5` on the API | Model for the PR review reviewer pass |
+| `LOCALDOST_VERIFY_MODEL` | the review model | Model for the PR review verifier pass |
+| `LOCALDOST_CLAUDE_REVIEW_TIMEOUT_SEC` | `300` | Timeout of one PR review call on the CLI |
+| `LOCALDOST_CODEX_BIN` | `codex` | Path to the Codex CLI when it is not on `PATH` |
+| `LOCALDOST_CODEX_MODEL` | the CLI default | Codex model for analysis, chat, and the PR review |
+| `LOCALDOST_CODEX_FAST_MODEL` | `LOCALDOST_CODEX_MODEL` | Codex model for scores and action reviews |
+| `LOCALDOST_CODEX_EFFORT` | the CLI default | Reasoning effort passed to `codex exec` |
+| `LOCALDOST_CODEX_TIMEOUT_SEC` | 240 analysis, 180 chat, 120 scores, 300 PR review | One timeout for every Codex call |
+| `LOCALDOST_CODEX_USER_CONFIG` | unset | `1` loads your `~/.codex/config.toml`. Off by default, see below |
+
+In `claude-cli` mode each call runs `claude -p` in a new empty temp folder with built-in tools off, no settings files, and no saved session. Only a chat turn attaches an MCP server: the localdost chat tools (`src/agent/chat-mcp.ts`), allowed by exact name with `--allowedTools`, and no other MCP server. The prompt goes in over stdin, so ticket and diff text never shows in the process list. The PR review starts the CLI with an allowlisted environment. Other calls remove `GITHUB_*`, `LINEAR_*`, `JIRA_*`, `NTFY_*`, `VAPID_*`, webhook secrets, and `LOCALDOST_TOKEN` from the CLI's environment. A reply that fails to parse is retried once. After that the dot falls back to the canned verdict with confidence capped at 0.3 and a note in the summary. An analysis on `sonnet` takes about 90 seconds.
+
+In `codex-cli` mode each call runs `codex exec --json --sandbox read-only --ephemeral` in a new empty temp folder. The CLI runs in its own process group, so a timeout stops any process it started too. User MCP servers are off, and shell, browser, computer use, apps, plugins, hooks, and memories are turned off with `-c features.<name>=false`. A chat turn adds one MCP server through `-c mcp_servers.localdost=...`: the localdost chat tools, limited to their names with `enabled_tools`. Codex runs them without asking, because the tools check the dot rules themselves. The prompt goes in over stdin, and the answer comes back through `--output-last-message`. The child environment is an allowlist (`HOME`, `PATH`, `CODEX_HOME`, proxy and CA variables), so `OPENAI_API_KEY`, `ANTHROPIC_*`, and tracker credentials stay out. Your `~/.codex/config.toml` is ignored by default: a model it pins can be one a ChatGPT login rejects, and its plugin MCP servers and hooks would still start. Analysis, scores, and action reviews expect JSON. A reply that fails to parse is sent back once with the problem. After that the run falls back to the rule-based verdict and adds a "Model fallback" step with the reason. An action review without a model decision always goes to a person. Each call costs about 17K input tokens, mostly skill descriptions the CLI loads.
+
+Chat on both CLI backends calls the localdost tools for real (KAT-133). The CLI starts `chat-mcp.ts` as a stdio MCP server for the turn. The server holds no data: it forwards each call over a loopback HTTP bridge (`src/agent/chat-bridge.ts`, a random token per turn) to the running localdost server, which runs the same chat tool the Anthropic backend uses. Read-only tools answer directly, actions go through `gate()`, and only a tool the model calls shows as a card. The answer streams: `claude -p --output-format stream-json --include-partial-messages` and `codex exec --json` events reach the chat as they arrive. Chat runs at low reasoning effort unless `LOCALDOST_CODEX_EFFORT` is set.
+
+A Claude CLI or Codex CLI login lives on one machine. On a server, use a subscription token or an API key. The boot log names the active backend.
+
+## GitHub
+
+**In the app.** On the GitHub row, press **Connect** and pick one:
+
+- **GitHub CLI login** reuses `gh` on the server. When `gh` is signed in, **Use GitHub CLI login** connects, and localdost reads the token from `gh` each time it starts. This is the fastest way on your own machine.
+- **GitHub App** creates an App for you. Enter an organization, or leave it empty for your personal account, and press **Create GitHub App**. GitHub opens with the permissions filled in. Create the App, install it on your repos, and GitHub sends you back to Setup connected. This fits a team server.
+- **Personal access token** takes a fine-grained token that you paste. It starts with `github_pat_` or `ghp_`.
+
+After you connect, pick the repos your dots watch. Permissions, webhooks, and polling: [GITHUB.md](GITHUB.md).
+
+**What an organization needs.** An owner has to approve a GitHub App, or a fine-grained token, before it can read the organization's repos. When the organization enforces SAML SSO, authorize the token for it. Until then GitHub answers as if the repo did not exist, and **Test access** in the setup flow names SSO. Set the public URL before you press **Create GitHub App**: the App gets a webhook only when an https public URL is already set.
+
+**Test.** The Test button on the GitHub row checks who the credentials are, then reads every repo in the workspace and its issues endpoint with them. It fails and names the repo when one cannot be read, and it names SAML SSO when GitHub asks for it. Connect runs the identity check only. **Test access** in the setup flow does the same for the repos you picked there.
+
+**Token permissions.** A fine-grained token needs Contents read, Metadata read, Pull requests read and write, Commit statuses read and write, Issues read and write, Actions read, and Deployments read.
+
+**With environment variables.**
+
+| Variable | Purpose |
+|---|---|
+| `GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY` | GitHub App mode. The key is the PEM text (with `\n` escapes allowed) or a path to the `.pem` file. The installation is looked up per repo |
+| `GITHUB_TOKEN` | PAT mode, used when the App variables are unset |
+| `GITHUB_WEBHOOK_SECRET` | HMAC secret for `/hooks/github`. Unset: the route answers 503 and queues nothing |
+| `GITHUB_API_URL` | API base, default `https://api.github.com`. Set it for GitHub Enterprise Server |
+| `GITHUB_SERVER_URL` | Web and clone base, default `https://github.com` |
+| `LOCALDOST_MIRROR_CHECKOUT` | `1` takes PR review checkouts as worktrees of one partial mirror per repo in `LOCALDOST_DATA_DIR/mirrors`, in place of a fresh clone per review. Off by default. Repo scans (`localdost scan`, the `repo_scan` job) always use the mirror |
+
+With no connection, GitHub runs in demo mode, and comments and check runs go to the outbox.
+
+## Jira
+
+**In the app.** On the Jira row, press **Connect**. Enter your site (for example `acme.atlassian.net`), the email of your Atlassian account, and an API token from your Atlassian account settings. Press **Test**, then **Connect**, then pick the projects your dots watch. Jira has no poller, so it also needs a webhook and a [public URL](#public-url): [TRACKERS.md](TRACKERS.md#jira).
+
+**With environment variables.**
+
+| Variable | Purpose |
+|---|---|
+| `JIRA_BASE_URL` | Site URL, for example `https://acme.atlassian.net`. A dot's `tracker.baseUrl` wins over it |
+| `JIRA_EMAIL`, `JIRA_API_TOKEN` | Jira Cloud Basic auth |
+| `JIRA_WEBHOOK_SECRET` | HMAC secret for `/hooks/jira`. Unset: the route answers 503 and queues nothing |
+| `JIRA_AC_FIELD` | Custom field id that holds acceptance criteria, for example `customfield_10042`. Unset: the dot reads them from the description |
+| `JIRA_BOT_ACCOUNT_ID` | Account id whose events the dot ignores, so its own comments never trigger a review |
+
+## Linear
+
+**In the app.** On the Linear row, press **Connect**. The flow links to the page in Linear where you create a personal API key (Settings, Security and access, New API key). Paste the key (it starts with `lin_api_`), press **Test**, then **Connect**, then pick the team and project your dots watch. Linear works with polling, so it needs no public URL: [TRACKERS.md](TRACKERS.md#linear).
+
+**With environment variables.**
+
+| Variable | Purpose |
+|---|---|
+| `LINEAR_API_KEY` | Personal API key for GraphQL reads, comments, and polling |
+| `LINEAR_WEBHOOK_SECRET` | Signing secret for `/hooks/linear`. Unset: the route answers 503 and queues nothing |
+| `LINEAR_API_URL` | GraphQL endpoint for polling, `localdost init`, and `localdost doctor`, default `https://api.linear.app/graphql` |
+| `LINEAR_BOT_USER_ID` | User id whose issues the dot ignores |
+
+## Poll mode
+
+Poll mode lets a dot work without a public webhook URL. `localdost init` turns it on.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LOCALDOST_POLL` | off | Polls GitHub and Linear for every dot. One dot can opt in with `pollGithub: true` or `pollLinear: true` (a dot save accepts `pollGithub`; the setup flow sends it, `true` unless webhooks reach the server) |
+| `POLL_GITHUB_SEC` | `60`, minimum 10 | GitHub poll interval |
+| `POLL_LINEAR_SEC` | `60`, minimum 10 | Linear poll interval |
+
+The first poll after boot records a cursor and queues nothing, except that a new dot takes the 5 most recently updated open PRs of its repos on its own first poll. After a restart of under an hour, polling catches up from the stored cursor. After a longer gap (KAT-363) GitHub polling takes the open PRs updated since the old cursor, and the issues of a GitHub tracker changed since, and Linear and Jira polling take the issues or tickets created or edited since, newest first, at most 5 per dot after the dot's scope, and each run starts with a "Caught up after a gap" step that names the gap; the commits of the gap start no post-merge run. A merge run that waits for a deploy looks at the deployments on GitHub every 30 s for a polling dot, see [Waiting for the deploy](#waiting-for-the-deploy). A dot made in the app polls GitHub when the server has no public URL or no webhook secret. The dot page and the dot list say which route a dot uses: "Listening: polling every 60 s", "Listening: webhooks", or "Not listening: ..." with what to fix. Jira has no poller. How each poller works: [GITHUB.md](GITHUB.md#polling) and [TRACKERS.md](TRACKERS.md#linear).
+
+## Slack
+
+**In the app.** On the Slack row, press **Connect** and follow the four steps in the flow:
+
+1. Copy or download the app manifest. It turns on Socket Mode, so Slack needs no public URL.
+2. Open Slack apps from the flow, create the app from the manifest, and install it to your workspace.
+3. In OAuth and Permissions, copy the Bot User OAuth Token (`xoxb-`).
+4. In Basic Information, App-Level Tokens, generate a token with the `connections:write` scope (`xapp-`).
+
+Paste both tokens, press **Test**, then **Connect**, and pick the channel for notices. Allowlists and mentions: [SLACK.md](SLACK.md).
+
+**With environment variables.**
+
+| Variable | Purpose |
+|---|---|
+| `SLACK_APP_TOKEN` | App-level token (`xapp-`) for Socket Mode |
+| `SLACK_BOT_TOKEN` | Bot token (`xoxb-`) |
+| `SLACK_ALLOWED_TEAM` | Comma list of workspace ids that may ask the dots |
+| `SLACK_ALLOWED_USERS` | Comma list of user ids that may ask the dots |
+
+Slack starts only when both tokens are set.
+
+## Push
+
+**In the app.** Push needs no key. The server creates web push keys on first boot, and the Push row shows them as ready. Turn on alerts for each phone or browser in Settings. **Test** checks the push setup.
+
+On iPhone, open the app from the Home Screen first: iOS delivers web push only to Home Screen apps. Open the app URL, tap Share, then Add to Home Screen, then open it from the Home Screen and turn on alerts in Settings. Web push needs HTTPS, except on `localhost`, so a phone also needs a [public URL](#public-url).
+
+**With environment variables.**
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY` | generated into `<LOCALDOST_DATA_DIR>/vapid.json` on first boot | Web push keys. Set them to keep the same keys across hosts |
+| `VAPID_SUBJECT` | your `LOCALDOST_PUBLIC_URL` when it is https, else the project page | Contact the push services see. Apple refuses a `localhost` contact, so iPhone alerts fail with 403 |
+| `NTFY_TOPIC` | unset | ntfy topic. Alerts go there too, with no app install |
+| `NTFY_URL` | `https://ntfy.sh` | ntfy server |
+| `NTFY_TOKEN` | unset | Bearer token for a protected ntfy server |
+
+Push to the same key repeats at most once per 10 minutes.
+
+## Public URL
+
+The public URL is the HTTPS origin where people reach the app, for example `https://qa.example.com`. Links in PR comments, check runs, pushes, ntfy, and Slack use it. Without it those links have no run page. Push and the installable app also need HTTPS.
+
+**In the app.** On the Public URL row, press **Connect** and pick one:
+
+- **Quick tunnel** starts a Cloudflare quick tunnel with one click and shows the address it got. It needs `cloudflared` on the server and no Cloudflare account. The address changes each time the tunnel starts.
+- **My own address** takes a URL that stays the same, such as your own domain, a named Cloudflare tunnel, or Tailscale Funnel. [DEPLOY.md](DEPLOY.md#your-machine-plus-cloudflared) shows how to set one up.
+
+Set `LOCALDOST_TOKEN` before you start any tunnel. A tunnel makes the app reachable from the internet.
+
+**With environment variables.** Set `LOCALDOST_PUBLIC_URL` to the origin. To run a quick tunnel yourself:
+
+```bash
+cloudflared tunnel --url http://localhost:4319
+```
+
+On the same Wi-Fi, a server that listens on `0.0.0.0` prints a LAN address such as `http://192.168.1.20:4319` at boot. That works for the app, but push and the installable app still need HTTPS.
+
+## Sandbox
+
+Each dot picks a runner mode in `runner.mode`: `local`, `docker`, or `demo`. Docker mode needs a Docker daemon the server can reach.
+
+**In the app.** The Docker runner row detects Docker by itself and has nothing to paste. When Docker is not reachable, start Docker Desktop or the Docker daemon on the server and press **Check again**. Runs still work in local or demo mode without it. Details: [SANDBOX.md](SANDBOX.md#docker).
+
+**With environment variables.**
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LOCALDOST_LIVE_FRAMES` | on for demo runs, off for local runs | `1` turns on browser frames for local runs, `0` turns them off. Docker runs never stream frames |
+| `PLAYWRIGHT_VERSION` | `1.63.0` | Playwright image tag for Docker runs when the checkout does not declare `@playwright/test` |
+| `LOCALDOST_RUN_LEASE_MS` | `60000`, minimum 5000 | How long a run lease lasts before a dead worker's run turns interrupted |
+| `LOCALDOST_RUN_MAX_MS` | `3600000`, minimum 60000 | A run that never ends stops renewing its lease after this long |
+| `STATUSPAGE_INTERVAL_SEC` | `180` | Statuspage poll interval |
+
+`LOCALDOST_QUEUE_CONCURRENCY` sets how many jobs run at once (default 2, max 8). Each run gets its own ports and checkout, so a machine with spare CPU and memory can raise it.
+
+`LOCALDOST_CDP_PORT` is set by the runner for each run. Do not set it yourself.
+
+`LOCALDOST_RUN_PORT` and `LOCALDOST_RUN_PORT_2` are two free ports the runner gives each local run (not docker runs). Setup steps and the test command both see them. A suite that starts its own servers should listen on them, so two reviews can run at the same time. A value set in the test command wins.
+
+## Voice
+
+Calls with a dot use browser speech by default. An OpenAI key turns on realtime voice.
+
+**In the app.** On the Voice row, press **Connect**, paste an OpenAI API key (it starts with `sk-`), press **Test**, then **Connect**. Realtime calls also need `LOCALDOST_TOKEN` on the server. Without it, calls keep using browser speech. Details: [VOICE.md](VOICE.md).
+
+**With environment variables.**
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `OPENAI_API_KEY` | unset | Turns on OpenAI Realtime calls. The server mints a 10-minute client token per call and never sends the key to the browser |
+| `OPENAI_REALTIME_MODEL` | `gpt-realtime-2.1` | Realtime model |
+| `OPENAI_REALTIME_VOICE` | `marin` | Realtime voice |
+
+## AI-Vision
+
+AI-Vision runs natural-language browser cases next to Playwright, on an AI-Vision server (Veesan) or the open-source Midscene CLI. A dot turns it on with `runner.aivision`; see [SANDBOX.md](SANDBOX.md#ai-vision-cases).
+
+**Found on this machine.** At start, when Setup opens, and every 3 minutes, localdost looks for a running server through `/aivision/health` at `AIVISION_PORT`, then `VEESAN_ENGINE_URL`, then `http://127.0.0.1:5880`. It looks for an installed copy at `AIVISION_CHECKOUT`, then `~/code/*aivision*`, then the folders next to the localdost checkout. A running server connects with nothing to type; the row reads Connected with its address and version. Detection asks for the web checks (`?platform=web`); a server that reports a failed check is shown with the check named and connects once it passes. When the copy is there but the server is down, the sheet offers **Start AI-Vision**: localdost runs `npx tsx apps/playground/demo/aivision-server.mts` in that folder as its own child process, with an allowlisted environment (paths, locale, proxies, and `VEESAN_*`, `AIVISION_*`, `MIDSCENE_*`, `PUPPETEER_*`, OpenAI and Codex variables), keeps its log, connects when it answers, and stops it when localdost stops. AI-Vision always runs on `gpt-5.6-luna`: localdost sets `VEESAN_MODEL_NAME` for the server it starts and for the AI-Vision CLI, whatever the dot's Codex model says. Without a model address it starts the server on the Codex CLI (`VEESAN_MODEL_BASE_URL=codex://`) and, on a Mac, with the installed Google Chrome. `LOCALDOST_AIVISION_DETECT=0` turns the search off.
+
+**Dots.** While AI-Vision is connected, each dot that made no choice gets the AI-Vision MCP preset (from the found folder), and each dot with a repo and a base URL gets vision tests turned on. This happens once per dot: detach the preset or turn off **AI-Vision tests** in the dot's Test runner settings, and it stays off.
+
+**A different server.** In the sheet, **Use a different server** takes an address, an access token when the server asks for sign-in, and the AI-Vision folder. A saved address wins over a found one. For a found server that asks for sign-in, the address is filled in, so only the token is left to type. The token goes only to the saved address, or to a server localdost started itself, never to another service that answers on a candidate port. **Test** lists the server's tests. A dot with the `server` backend and no `serverUrl` of its own uses this server.
+
+**With environment variables.**
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `AIVISION_SERVER_URL` | unset | AI-Vision server for dots that name no `serverUrl` |
+| `AIVISION_INTERNAL_TOKEN` | unset | Access token, sent as the `x-veesan-internal` header |
+| `AIVISION_CHECKOUT` | unset | Absolute path of an AI-Vision checkout, for the MCP preset and Start |
+| `AIVISION_PORT` | unset | Port to look for a running server on, and to start one on |
+| `LOCALDOST_AIVISION_DETECT` | `1` | `0` turns off the search for AI-Vision on this machine |
+
+## Test engines
+
+Two engines can cover the **new scenarios** of a change: the What to test items of a PR review that no existing spec covers. The **Test engines** section of the Setup page lists both.
+
+| Engine | What it runs | Ready when |
+|---|---|---|
+| **Playwright e2e** | Writes a real Playwright test for each new scenario from the running app, runs it, and keeps it when it passes or finds a bug | Chromium is installed on the server (`npx playwright install chromium`) |
+| **AI-Vision** | Runs each new scenario as a plain-language browser case that a vision model drives and checks by sight | An AI-Vision server is connected, see [AI-Vision](#ai-vision) |
+
+Each row shows **Ready** or **Not ready** with what is missing, one sentence about what the engine runs, and a **Default** switch. The switches set the **workspace default**, which every dot without an engine of its own uses:
+
+| Switches on | Workspace default | Dot dialog and dot page |
+|---|---|---|
+| Both | `auto` | Playwright e2e, then AI-Vision |
+| Playwright e2e | `playwright` | Playwright e2e only |
+| AI-Vision | `aivision` | AI-Vision only |
+
+At least one engine stays on. A dot can still choose **Both on every item** in its own settings.
+
+**Existing specs.** The Playwright specs in your repo always run through the dot's test command. The engine choice never changes that. It covers new scenarios only.
+
+**New installs.** The first time the server starts with nothing chosen, the default is `auto` when both engines are ready, otherwise the one that is ready (AI-Vision when neither is). While the default is chosen this way, it follows the engines: connect AI-Vision later and it becomes `auto`. Moving a switch saves your choice, and **Choose automatically** goes back. An install that already has runs starts on `aivision`, so its dots behave as before; change it on the Setup page. Demo mode (`LOCALDOST_DEMO=1`) stays on `aivision`.
+
+**Dots.** In the dot dialog, under the Change reviewer stage, **Engine for new scenarios** reads **Uses the workspace default (&lt;name&gt;)** until you pick another choice: **Playwright e2e, then AI-Vision**, **Playwright e2e only**, **AI-Vision only**, or **Both on every item**. The header of the dot page shows the engines the dot uses, with a **Change** link. AI-Vision cases also need **AI-Vision tests** turned on for the dot.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LOCALDOST_TEST_ENGINE` | unset | `auto`, `playwright`, or `aivision`. Sets the workspace default. The environment wins: the Setup page shows the switches read-only |
+
+The Setup page saves the default through `PUT /api/setup/engines` and reads it with `GET /api/setup/engines`, see [API-V2.md](API-V2.md#test-engines).
+
+## True Platform
+
+A dot with **Send to True Platform** on copies its work into one True Platform project: every test case it designs or edits, every automated run it makes, and every manual result a tester records (KAT-406). localdost stays the place where the work happens. True Platform becomes the record that test managers read. A slow or down True Platform never stops a localdost run.
+
+The switch is off by default. It is a group on the dot settings (**True Platform**) with the switch, the address, the project ID, a connection check, and a Details fold. The switch, the address, and the project are the admin's, like the test command: an editor or a member sees them read-only with "Ask your localdost admin." Save them through `PATCH /api/dots/:id` with `trueSync: { enabled, tenantUrl, projectId }`, see [API-V2.md](API-V2.md#true-platform-sync).
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LOCALDOST_KATALON_API_KEY` | unset | The True Platform API key. The environment of the server only: it is never stored in the database, never sent to the model, never given to a test process, and hidden in logs and errors |
+| `LOCALDOST_KATALON_API_KEY_FILE` | unset | The path of a file that holds the key, used when `LOCALDOST_KATALON_API_KEY` is empty. The file is read when needed and kept for 5 minutes, and a change of its modified time or size is seen at once. Run `chmod 600` on it: a file that others can read still works, with a warning |
+| `LOCALDOST_KATALON_HOSTS` | unset | A comma list of extra origins that may get the key, for example `http://127.0.0.1:4901`. The tests use it for a fake server. Leave it unset in real use |
+| `LOCALDOST_KATALON_OPS_URL` | `https://testops.katalon.io` | The host of the upload service. Change it only for a test |
+
+Neither key variable can be set from the app, and the Setup page does not read them. `GET /api/dots/:id` says `trueKey: { set, source }` and nothing else about the key.
+
+**Where the key may go.** The key, its Basic form, and the bearer token that the login returns go only to `https://testops.katalon.io` and to `https://<name>.katalon.io` hosts: https, port 443, no user name in the address. The check runs on every request, so an address that was saved before this rule, or written into the database by hand, is still refused. A redirect from True Platform is not followed. The signed upload addresses that True Platform gives get no key. A saved address that is not https on a katalon.io host is refused with "Use your True Platform address, for example https://your-team.katalon.io."
+
+**Check connection.** The button is an admin call (`POST /api/dots/:id/true/check`). It logs in, reads the key owner and the repository, and answers `Connected to "<project name>"`, or one sentence: `The key was rejected`, `Project 3517762 was not found for this key`, or `True Platform did not answer`. It checks the values on screen even before they are saved, and a good check of the saved project ends a hold.
+
+**What goes where.** A folder `Test Cases/localdost/<dot name>` holds the dot. Its folders mirror the case tree of the dot, so the ticket folders of the test designer (`PROD-123 Short title` under `PROD`) stay as they are, and a case with no folder goes to `Unfiled`. The path is fixed at the first send, so renaming the dot does not move it. A case is named `<key> <title>`, with every character outside letters, digits, spaces, and `( ) . , _ - + & = '` turned into a space, and cut at 200 characters.
+
+| localdost | True Platform |
+|---|---|
+| Case title, steps, expected results | Name, steps, expected results. Steps have no test data column in localdost, so it is sent empty |
+| Priority must, should, could | HIGH, MEDIUM, LOW |
+| Status draft, ready, retired | DRAFT, PUBLISHED, INACTIVE. A retired case is never deleted |
+| Kind manual, playwright, aivision | MANUAL_ONLY, AUTOMATION_COMPLETE, AUTOMATION_COMPLETE, and the description says `Automated in localdost: Playwright, <spec path>` or `Automated in localdost: AI-Vision`. The case stays a manual case in True |
+| Ticket refs | A Jira ref that True Platform has is linked as a requirement. True Platform has requirements only for Jira and Azure DevOps items its own integration syncs, so a Linear or GitHub ref is never looked up, and a Jira ref True does not have yet is looked for again every day for 30 days |
+| (none) | The description ends with `localdost case TC-12 (id <case id>)`, and a link back to the case when the dot has `LOCALDOST_PUBLIC_URL` |
+
+**Runs.** Every PR check, merge run, Tests repo run, rerun, and AI-Vision run that finishes with a report becomes one automated run in True Platform with a result for each test (passed, failed, skipped; flaky is passed with the line `Passed on retry <n>`, a time-out is failed with `Timed out`), its duration, and, when `LOCALDOST_PUBLIC_URL` is set, lines with the link to the run page, the video, and the trace. A test that a case owns is named `[TC-12] <test title>`. A run whose tests did not run sends nothing and says so. localdost replays its own report into the Katalon reporter (`@katalon/playwright-reporter`, pinned at 0.0.3) and uploads the files the way the reporter does: a login, signed URLs, a PUT per file, and an end report per suite. The key never enters the test process.
+
+**Manual test runs.** A manual test run in localdost makes one suite and one run in True Platform (named `<name> (localdost <short id>)`), records each result with its step notes and a comment `Tested by <name> in localdost.`, and ends the run when the test run is marked done, with every case that has no result as SKIPPED. True Platform lets only the user who made the run record on it, and not on an ended run. A test run that is reopened after its True run ended starts a second round: a new run named `... round 2` in the same suite, with the latest result of every case. The page links to the newest round and lists the earlier ones under Details.
+
+**Queue and retry.** Nothing is sent from the request that made the change. Each case, run, result, and end waits in a queue (the `true_outbox` table, kept apart from the job queue) with these rules:
+
+- A network error, a time-out, a 5xx, or a 429 waits 1 minute, 5 minutes, 15 minutes, 1 hour, and then every hour (a `Retry-After` header wins when it is longer). An item gives up after 24 hours of failing, not counting the time the dot was held.
+- Any other 4xx answer gives the item up at once with the server's words, cut to 300 characters and hidden of secrets. A 401 or 403 holds every item of the dot as "key rejected" and checks again after an hour, or at once when the key file or the variable changes. A missing key holds the dot until a key appears. A 404 on the project holds it as "project not found".
+- When no call of a dot gets an answer for 5 minutes, the dot is held as "unreachable", its items stop aging, and one cheap call every 15 minutes finds out when True Platform is back. A day-long outage ends with the queue sending in order, and nothing gives up because of it.
+- An item that depends on one that gave up (a result of a case that was not sent) gives up with "Not sent because TC-12 was not sent." **Send again** on an item, or **Send all again** in the Details of the setting, puts them back in the queue in order with a fresh 24 hours.
+- At most 5 requests a second go out from the server.
+- In [sandbox mode](#sandbox-mode) and in demo mode nothing leaves, and items are held with "Not sent: sandbox mode."
+
+**The status line.** The run page, the manual test run page, and the case drawer each get one line under the title when the dot sends: `Sent to True Platform` with a link, `Sending to True Platform...`, `Not sent yet: True Platform did not answer. Trying again at 14:05.`, `Not sent: gave up after 24 hours.` with **Send again**, and the other states of the queue. Details lists each item that waits, with its last error in words and its number of tries.
+
+**Not yet confirmed against the real service.** The shapes of the test case, folder, requirement, manual run, and result calls come from the Katalon MCP server source and earlier captures, and the tests use a fake server. The first live run needs the admin's go-ahead, in a scratch folder `Test Cases/localdost/_probe` of the chosen project. Open points: whether the tenant host takes the API key (`Authorization: Basic base64(":<key>")` with `x-project-id`) on the test case and manual run routes as it does on `/v2/schedules`, which field of the run list carries the execution uuid (until it is known the line links to the project's Executions page), and whether a second end report for the same suite adds results twice. `@katalon/playwright-reporter` has no licence field in its package: ask Katalon before a public release depends on it.
+
+## Approvals and connections
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `LOCALDOST_APPROVAL_TTL_MS` | `86400000` (24 h), minimum 60000 | A pending approval expires after this long. Deciding it later returns 410 |
+| `LOCALDOST_ALLOW_STDIO` | unset | `1` lets a non-loopback client add a stdio MCP connection while `LOCALDOST_TOKEN` is unset. See [CONNECTIONS.md](CONNECTIONS.md) |
+
+## Compose-only variables
+
+`compose.yml` reads two more variables from `.env`. `LOCALDOST_PORT` (default `4319`) is the host port. `CLOUDFLARE_TUNNEL_TOKEN` feeds the optional `tunnel` profile. The server itself does not read either.
+
+## Dot fields
+
+Dots live in the database, and you edit them in the app or through `POST /api/dots` and `PATCH /api/dots/:id`. The fields that connect a dot to the services above:
+
+| Field | Example | Purpose |
+|---|---|---|
+| `repo` | `{ "owner": "acme", "name": "shop-web", "defaultBranch": "main", "pathFilters": ["web/**"] }` | GitHub repo the dot watches |
+| `tracker` | `{ "kind": "jira", "baseUrl": "https://acme.atlassian.net", "projectKeys": ["SHOP"] }` or `{ "kind": "linear", "teamKeys": ["ENG"], "projectName": "Checkout" }` | Ticket source. `projectName` narrows Linear polling to one project, and is the project the dot files defects in |
+| `baseUrl` | `https://staging.shop.acme.com` | App URL the tests run against, passed as `BASE_URL` |
+| `runner` | `{ "mode": "local", "workdir": "/home/me/shop-web", "command": "npx playwright test", "passEnv": ["LOCALDOST_TEST_USER"] }` | See [SANDBOX.md](SANDBOX.md). `passEnv` names the host variables that carry the test login, see [Test login](SANDBOX.md#test-login) |
+| `probes` | `[{ "url": "https://shop.acme.com/health" }]` | HTTP or browser probes. `expectStatus`, `expectText`, `timeoutMs`, `kind`, `selector`, and `steps` are optional |
+| `probeIntervalSec` | `60` | Probe interval |
+| `statusPages` | `["https://www.githubstatus.com"]` | Statuspage sites to poll |
+| `rules` | `{ "ticket_comment": "act" }` | Rule level per action kind. Unset kinds use the defaults |
+| `digestHour` | `18` | Local hour of the daily digest |
+| `slackChannel` | `qa-alerts` | Channel for notices and for routing mentions |
+| `connections` | `["<connection id>"]` | MCP connections attached to the dot |
+| `review` | `{ "enabled": true, "blockOn": "high" }` | PR review options, see [PR-REVIEW.md](PR-REVIEW.md#options) |
+| `stages` | `{ "designer": { "on": true, "rules": "Cover the empty cart." } }` | Switch and extra rules per stage: `analyst`, `designer`, `reviewer`, `regression`, `watcher`, `guard`. A save merges per stage. An empty `rules` removes them. See [STAGES.md](STAGES.md#5-rules-model-and-toggles-per-stage) |
+| `stageModels` | `{ "reviewer": "codex-cli" }` | Model per stage: `claude-cli`, `codex-cli`, `claude-token`, or `anthropic`. `null` puts a stage back on the dot default |
+| `stagesNotice` | `"dismissed"` | Closes the one-time offer of the new stages on a dot that predates them. The server sets the offer at boot, and a dot created later starts with it dismissed; a save can only dismiss it |
+| `pollGithub`, `pollLinear` | `true` | Poll mode for this dot only. `POST /api/dots` sets `pollGithub` when the server has no webhook route. The routes check that `pollGithub` is true or false, and the setup flow always sends it |
+| `shadowWeekDays` | `7` | Save-only. `POST` or `PATCH` holds the PR comment and the check run at Ask first for this many days (1 to 30), and stores the end date and the old levels in `shadowWeek`. `0` ends the week now. See [The shadow week](#the-shadow-week) |
+| `testDocsOnlySkip` | `true` | A PR or push that changes only docs (`*.md`, `docs/**`), `CHANGELOG.md`, or the `version` field of `package.json` and `package-lock.json` still gets the review and report, but no test run. Default `true` |
+| `testDebounceSec` | `120` | A PR check waits this many seconds of quiet before it starts. A newer head of the same PR drops the queued job and cancels a running one. `0` turns it off. Default `120`, maximum `3600` |
+| `prTestTarget` | `"base"` | What a PR check tests against when no preview of the PR is known: `base` (default), `preview-only`, or `none`. See [PR tests without a preview](#pr-tests-without-a-preview) |
+| `waitForPreviewSec` | `120` | A PR check holds up to this many seconds for a deployment of the PR head to be reported, then tests what it has: the preview if one came, else `baseUrl` as `prTestTarget` says. A whole number from 0 to 3600, default 0. See [PR tests without a preview](#pr-tests-without-a-preview) |
+| `nightlyRun` | `{ "on": true, "time": "02:00", "days": [1, 2, 3, 4, 5] }` | The nightly test run of a dot with a Tests repo: off by default, `time` is `HH:MM` on the server's clock (default `02:00`), `days` are 0 (Sunday) to 6 (Saturday) (default Monday to Friday), `null` turns it off. A save that turns it on needs a Tests repo and a Base URL. See [Nightly test run](#nightly-test-run). `nightlyLastSlot` on the dot is the server's record of the last time it handled, and a save cannot write it |
+| `testRepoOnPr`, `testRepoOnMerge` | `false` | Whether the Tests repo of the dot runs on app PRs and on merges. Both default to on, and `true`, `false` and `null` (back to the default) are the values the routes take. See [Tests repo](#tests-repo) |
+| `waitForDeploySec` | `900` | A merge run waits up to this many seconds for a successful deploy of the merge commit to `deployEnvironment` before it tests. A whole number from 0 to 3600. `0`, `null`, and unset turn the wait off (the default). A wait needs `deployEnvironment`. See [Waiting for the deploy](#waiting-for-the-deploy) |
+| `deployEnvironment` | `"qa"` | The GitHub deployment environment the merge deploys to, one line of up to 100 characters. The admin changes it and `waitForDeploySec` with the runner settings |
+| `reuseMergeResults` | `true` | A merge whose commit has the same git tree as the PR head that last passed its tests reuses those results instead of running the suite again. Default `true` |
+| `dailyModelCap` | `200` | Model calls the dot may make per day, counted from the local midnight of the server. At the cap new reviews of the dot wait for the reset and chat answers say so. A whole number from 1 to 100000; `0` and `null` turn the cap off (the default). See [Daily model cap](#daily-model-cap) |
+| `trueSync` | `{ "enabled": true, "tenantUrl": "https://your-team.katalon.io", "projectId": 3517762 }` | Send the dot's test cases, runs, and results to a True Platform project. Off by default. The admin changes it. The server keeps its own state in the same object (`repositoryId`, `folderPath`, `ownerUuid`, `blocked`), and a request never sets those. See [True Platform](#true-platform) |
+| `kind` | `"lead"` | `dot` (the default) or `lead`. Set on `POST /api/dots` only; a dot never changes kind. A lead names member dots and holds no repo, tracker, site check, runner, review options, or stages of its own. See [Lead QA dot](#lead-qa-dot) |
+| `memberIds` | `["<dot id>", "<dot id>"]` | The dots a lead names: 1 to 8, in the order the team page lists them. A dot is in at most one lead. A save that leaves it out keeps the members |
+
+### Lead QA dot
+
+A Lead QA dot (KAT-405) gives a team of dots one page: the team health, a daily team digest, one place to ask about every member, shared test cases, one bug report per bug, and a release call. It holds no repos, tracker, site checks, or runner. Each member keeps its own repos, tracker, rules, and Inbox, and a lead changes none of them. Everything the lead shows is built from rows the members already store, and the lead posts nothing to GitHub or a tracker. The full spec is [LEAD-DOT.md](LEAD-DOT.md).
+
+- **Make one.** On the Dots page choose **New Lead QA for a team** in the new dot dialog, name it, and add 1 to 8 dots in the order you want the team page to list them. Or send `POST /api/dots` with `{ "name": "Lead QA", "kind": "lead", "memberIds": ["<dot id>", "<dot id>"] }`. A dot can be in one lead only, a lead cannot be a member, and an archived dot cannot be added. Each refusal says which rule it broke.
+- **The page.** The title row has three buttons: **Digest now**, **Ask** and **Settings**. **Pause** and **Remove dot** sit in a row at the foot of the page, and the goal (mission, tell me when, never) is edited in Settings. On a phone the page starts with the team word, then the three buttons, then one tap row per member, then the release call with its three first reasons and **See the reasons**.
+- **Team health.** The lead page shows one status word for the team, the worst of its members (Failing, Needs you, Not watching, Healthy), and one row per member with its job and the one thing that needs a person. **Open** goes to the member's page, or to the fix the member's own health answer gives when it is a link (Setup, the bug already filed). A paused or archived member shows as such and does not count. The dot list shows the team word on the lead's row. The count at the top of the list leaves leads out, so one Failing member reads "1 needs you", not 2.
+- **Daily team digest.** At the lead's **Digest time** the lead posts one message to its own chat and to its **Slack channel** when one is set. **Digest** says Every day or Every Monday, for the week. **Digest now** on the lead page makes the same message at once and shows it in your chat only. It is built by code, makes no AI call, and counts nothing against **Daily AI calls**, which cover the answers of the lead's chat only. When dots share a Slack channel, a message that names no dot goes to the lead, and a message that names a member goes to that member.
+- **Ask the lead.** The lead chat answers about every member and routes an action to the member whose job it is: "Review PR 412 again" goes to the dot that reviews PRs, under its own rules and cap, and the answer says "Asked PR Reviewer to review PR 412." One turn sends at most 3 such requests.
+- **Shared test cases.** A test case a member designed for a ticket is found by the other members: the PR check and the after-merge run use it, and a result lands on the case's own dot. A PR check of a dot with no tracker reads the tickets of its lead's trackers.
+- **One bug, one draft.** When two members find the same bug, the Inbox holds one draft. It names both finders, and a rejection counts for both. Approving it files the bug the way a member's draft is filed. The lead has no Inbox of its own.
+- **Release call.** The lead page and the chat answer "Can we release 2026.11?" with Ready, Ready with risk, or Not ready, and the reasons, from the members' requirements, bugs, results, and Inbox items. It never posts and says readiness only. With no milestone picked it answers for the nearest open milestone, or for the newest one when every requirement passes.
+- **Removing members.** Archiving a member keeps it in the lead. Deleting a member takes it out of the lead and removes the test run items of other members that pointed at its test cases; the delete dialog lists them first. A lead keeps at least 1 member, so the last member cannot be deleted before the lead.
+
+### Fewer test runs
+
+Three settings keep a dot from running the suite when it learns nothing new (KAT-344). They are on by default, and `PATCH /api/dots/:id` turns each off: `{ "testDocsOnlySkip": false }`, `{ "testDebounceSec": 0 }`, `{ "reuseMergeResults": false }`. The route rejects a non-boolean switch and a `testDebounceSec` that is not a whole number from 0 to 3600. The run step "Tests skipped: only docs or the changelog changed" marks a skip, and the step "Same code as the tested PR head ..." marks a reuse and links the PR run. A merge finds its PR from the number in the commit title (`(#120)` or `Merge pull request #120`). The server variable `LOCALDOST_TEST_DEBOUNCE_DEFAULT_SEC` changes the default quiet period of every dot that sets none; the test scripts set it to 0.
+
+### Run tests per repo
+
+A repo entry can carry `runTests: false` (KAT-361). The dot then reviews the pull requests and merges of that repo and runs no tests for them, so a back end with no Playwright suite does not report "Tests did not run" on every PR. The run says "Tests skipped: Run tests is off for acme/api" and the verdict is a pass with no test counts. Only `false` is stored: a repo with no switch runs its tests. The switch applies to app repos; `POST /api/dots` and `PATCH /api/dots/:id` answer 400 for a test or docs repo, or for a value that is not a boolean. The dot dialog has it under Sources, next to the PR scope, and the Repos step of setup has it on each App card. More: [SANDBOX.md](SANDBOX.md#run-tests-per-repo).
+
+### Tests repo
+
+A team often keeps its end-to-end suite in a repo of its own, and its app repos have no Playwright suite. Give the dot that repo with the role **Tests** (Repos step of setup, or `repos` on `POST /api/dots` and `PATCH /api/dots/:id`), and it runs the suite after every PR check and every merge of an app repo, against the same app (KAT-86). The app repo's own tests, when it has any, run first. Turn Run tests off for an app repo with no suite: it is still reviewed, and the Tests repo is its test run.
+
+```json
+{
+  "repos": [
+    { "repo": "acme/ai-platform", "role": "app", "runTests": false },
+    { "repo": "acme/test-management", "role": "app", "runTests": false },
+    { "repo": "acme/true-dogfood-tests", "role": "test", "test": { "framework": "playwright", "label": "True Platform", "passEnv": ["LOCALDOST_TEST_USER", "LOCALDOST_TEST_PASSWORD"] } }
+  ],
+  "baseUrl": "https://qa.example.com",
+  "waitForDeploySec": 900,
+  "deployEnvironment": "qa"
+}
+```
+
+What a person sees: the PR comment and the GitHub check each get one line, "Ran 24 True Platform tests from true-dogfood-tests: 23 passed, 1 failed.", and the failed test is a bug (or, on the shared QA build, a risk to test) that names the spec of the Tests repo. The run page lists each case as `owner/name:path`. The commit that ran, the ref, why that ref, the tests chosen and the URL are under Details for developers. All fields of `test` are in [SANDBOX.md](SANDBOX.md#tests-repo); the repos a Tests repo exercises are `targets` on its entry (default: every app repo of the dot).
+
+**Which version of the tests.** The first rule that applies picks the branch or tag of the Tests repo for a PR check:
+
+1. The PR description holds a line `localdost-tests-ref: <branch>` and the Tests repo has that branch. This covers a change that lands as two PRs, the app change and its tests. A branch the Tests repo lacks is said in a step and ignored.
+2. The Tests repo's `ref` is `match_branch` and it has a branch with the name of the app PR's branch.
+3. `ref` is `{ "fixed": "release-1" }`: that branch or tag. A fixed ref that does not exist stops the run with a sentence.
+4. The default branch of the Tests repo, as GitHub reports it.
+
+A merge uses rules 3 and 4 only: the branch of a merged PR is a branch of the past. A PR from a fork never uses rules 1 and 2, since its description and branch name are written by someone outside the team. GitHub gives the commit of the chosen ref, and the run tests that commit only.
+
+**Where it runs.** A PR check runs it against the preview of the PR when one is known, else against the dot's `baseUrl` as `prTestTarget` says (see [PR tests without a preview](#pr-tests-without-a-preview): `none` and `preview-only` hold the Tests repo back like the app tests, and a failure on the shared QA build is no bug). A merge runs it against `baseUrl` after the deploy wait (see [Waiting for the deploy](#waiting-for-the-deploy)); an app repo with Run tests off waits for the deploy when its merge runs a Tests repo, since that suite tests the deployed build. Without a preview and without a `baseUrl` there is nothing to test against, so the run says so and skips the batch. A change of only docs skips it too.
+
+**Which tests run.** The whole suite, unless `test.areas` maps the areas of the change to tests. `areas` maps an area name, as the PR review names it, to a Playwright `--grep` text: `{ "checkout": "checkout|payment" }`. When the review's regression scope is area or narrow and every changed area is mapped, only those tests and the quick tests (the `smokeGrep` text, `@smoke`) run. A wide scope, an area that is not mapped, a change with no review, and a selection that matches no test run the whole suite, since nobody can say what covers an unmapped area and a pass with no test is no pass.
+
+**Switches.** The dot has two: **Run the Tests repo on app PRs** and **Run the Tests repo on merges** (`testRepoOnPr` and `testRepoOnMerge`), both on. They are in the Test runner section of the dot dialog, for a dot that has a Tests repo. A switch that is off says so in a step, and the other switch is not touched. `test.on` on the repo entry does the same per repo.
+
+**Fork PRs and the login.** A fork PR does not run the Tests repo on this machine. In Docker mode it runs only when the Tests repo has no test login to hand over, because the preview of a fork PR is controlled by the fork's author; otherwise it is skipped with a sentence. A fork PR never picks the ref; see [Fork safety](SANDBOX.md#tests-repo). The suite gets the test login from `test.passEnv`, else from the dot's `runner.passEnv`; names must start with `LOCALDOST_TEST_`, see [Test login](SANDBOX.md#test-login). The command, the setup, the folder and the login of a Tests repo are the admin's, like the runner settings.
+
+### Nightly test run
+
+A dot with a Tests repo can run that suite on a timer (KAT-390), against its **Base URL**, with no PR or merge behind it. It is off by default. In the dot dialog the controls are under **Advanced**, in **Test settings** (Test runner section): the **Nightly test run** switch, the **Time** (server time) and the **Days** (Monday to Friday unless you pick others). The main section of the dialog has a **Nightly test run** line of its own, under the Tests repo switches. It says what the dot does and on which clock, such as "Runs the tests every weekday at 02:00, server time (Asia/Bangkok, UTC+7).", or "The tests do not run at night.", and its button opens Advanced on the switch. The hint under the **Time** field names the same clock (`timeZone` and `tzOffsetMin` of `GET /api/health`: the zone name of the server and the minutes its clock is behind UTC now). On the API it is `nightlyRun: { on, time?, days? }` (see the settings table above); a save that turns it on and has no Tests repo or no Base URL (a demo dot needs none) is a 400.
+
+- **When.** The server checks every minute and at start. A time of day on an allowed day is one *slot*. A slot queues one `nightly_run` job, once: the job key holds the dot and the slot, and the dot records the last slot it handled (`nightlyLastSlot`), so a restart or a second check queues nothing twice. A slot that passed while the server was down runs at the first check after it starts when it is under 6 hours old, and the run says "Started late"; an older slot is lost. Turning the schedule on, or changing it, forgets the slots before the save: switching it on at 03:00 for 02:00 does not run at once. A save that sends the same schedule changes nothing, which the dot dialog does on every save.
+- **What runs.** Every repo of role Tests in the dot, at the default branch of the Tests repo (or the fixed `ref` of its settings), with the same checkout, setup, command and test login as for a PR, and no selection: the whole suite. `test.on` and `targets` do not apply, since no app repo and no job named it. The report lists each case as `owner/name:path` and the run page shows the Tests repo line. The verdict is the one of a merge run: the model reads the report. A night with no result, because the Tests repo could not be checked out or its setup failed, says so as a verdict that says nothing about the app.
+- **What it respects.** A paused or archived dot, a dot whose Regression runner stage is off, a Lead QA dot, and a server in sandbox mode (no timer at all) run nothing, and the slot is recorded as skipped, so resuming later does not bring it back. The job is queued like any other: it waits for a free place in the queue, stays queued while the disk is short, and waits for the reset when the dot has reached its daily AI limit (the run says "Waiting for the daily model cap"). Pause or archive after the slot was queued, and the job ends with no run. A dot that lost its Tests repo or its Base URL since the setting was saved gets a run that says "The nightly test run cannot start" and needs a person; a save that takes the Tests repo away turns the schedule off.
+- **Where it shows.** Activity and the run list name the job beside the dot **Nightly check** (not "After merge": nothing was merged) and put the slot on the chip, "Fri 23 Oct, 02:00" (the run page and text updates say "Nightly test run, Fri 23 Oct, 02:00"). The model is told that nothing was merged and is asked for a headline with neither the word nightly nor the test counts, since the row shows both. It counts as a check in the morning digest (a pass is one more passed check; a failure is a bug found, as for a merge) and in the Room. A pass sends nothing. A failure, or a night that could not start, sends one alert (`push_notify`, under the dot's rule). The run can be retried with **Check again** like any run. It files no defect by itself.
+
+**Not built yet.** Playwright is the only framework that runs. A PR or merge of the Tests repo itself starts no test run (it gets CI failure triage), a merged result is not linked to the Tests repo's own issues, and the review does not read the Tests repo's specs to pick tests. See [MULTI-REPO.md](MULTI-REPO.md#5-build-tasks).
+
+### Daily model cap
+
+A dot can have a daily cap on its model calls (KAT-362), so one busy dot cannot spend a shared model account. It is off by default. Set **Daily model calls** in the dot form (Model use), as one number in the Rules step of the setup flow, or send `{ "dailyModelCap": 200 }` to `PATCH /api/dots/:id` (`0` or `null` removes the cap).
+
+- **What counts.** One answered call through the model guard is one call: a ticket analysis, a score, a safety review, a review or verifier pass, a generated spec, a chat answer. A call that fails writes nothing. A call the guard moves to another model counts once, for the model that answered. The mock model counts nothing. Each call is a row in `model_calls` with the dot, the run, the stage (or `chat`, or `other`), the backend, and the token counts when the backend reported them: Anthropic API and Claude CLI replies carry `usage`, and the Codex CLI reports it in its event stream. A backend that sends no count leaves the row with no tokens.
+- **The day.** The count starts at the local midnight of the server (the time zone of the server process, the one `Daily digest at` uses) and starts over at the next one.
+- **At the cap.** A review job of the dot (`pr_check`, `post_merge`, `ci_failure`, `ticket_review`, `test_design`, `rerun`) does not start. It goes back to the queue with its attempt, to start at the reset, and a run stays behind: an interrupted run with the step `Waiting for the daily model cap` and the line `Daily model cap reached, resumes at 00:00 UTC` (the time zone of the server, since the people reading it are often elsewhere). The run page says the review starts again at that time and offers no Retry, and the dot's health does not change. The prod watcher, the daily digest, and repo scans go on, since a cap must not silence an outage alarm; their calls still count. A run already going finishes, so a dot can end a day a few calls over its cap. One `Blocked: daily model cap reached` update goes out per dot per day.
+- **Edits while it waits.** A ticket edited while its review waits for the cap keeps one review: the newer edit replaces the queued job of the same ticket for the same dot, keeps its wait for the reset, and the run that says `Waiting for the daily model cap` follows it. The reset then starts one review of the newest text and posts one draft, where it used to start one review per edit (KAT-408). A review that already runs is not stopped, and a review a person asked for stays asked, in the chat or Slack thread where it was asked too. An edit made before the queued one (a late or repeated delivery) is ignored. **Rerun** on a ticket review replaces the queued review of the same ticket the same way: the rerun reads the text of the queued review, which is the newest, and keeps its wait.
+- **Chat.** A dot at its cap answers a question with the same line (server time zone included) and does not call the model. A question a stored view answers without the model still gets its answer.
+- **Seeing it.** The dot page and the dot list show `Daily model cap reached, resumes at <time>` (the time in the viewer's clock), and the dot view carries `modelCap: { cap, used, reached, resetsAt }` while a cap is set. The Room page says `Waits for the daily AI limit to reset` on each held job, in the Next row of its dot card and on its Board card, and `waitsForLimit` in `GET /api/room` counts the jobs of a dot that wait for it.
+- **Going on early.** Raising the cap above the calls made today, or turning it off, starts the waiting reviews at once.
+
+The **Model use** card on the dot page shows calls and tokens today and over the last 7 local days (today included), per stage, with a totals row and, when a cap is set, how much of it is used. Tokens add input and output of the calls that reported them (cached input counts as input); the card says so when some calls reported none. `GET /api/dots/:id/model-usage` returns the same numbers: `{ cap, today, week, stages[], todayFrom, weekFrom }`. Rows older than 35 days are removed, and deleting a dot removes its rows. The card starts empty on a server upgraded from 0.9.0, since earlier calls were not recorded.
+
+### PR tests without a preview
+
+A PR check tests against a preview of the PR when one is known: the `deployment_status` webhook records the preview URL of a head, and a PR check uses it. A dot that polls GitHub never receives that webhook, so its PR has no preview, and the tests ran against the dot's `baseUrl`, a build that shared QA work deployed. A new spec of the PR then ran against an old build and failed, and the failure became a defect draft (KAT-363). `prTestTarget` says what a PR check does when no preview is known:
+
+| Value | What a PR check does with no preview |
+|---|---|
+| `base` (default) | Tests run against `baseUrl`. The run says so in a "Tests run against the shared QA build" step, the report carries the sentence "Tests ran against the shared QA build, not a build of this PR." next to the counts (in the PR comment and the check), and with a failure it adds that the failure may be the PR's new or changed spec running against an older build. The failure is a risk to test, never a bug: the PR comment says "no bugs found, 1 risk to test" and lists it under Risks to test as "failed against the shared QA build", the check stays neutral, the verdict is needs attention with no suspected cause, and no defect and no high push follow. A risk the review found by reading the code, or one the PR's own CI reproduced, still counts. A merge never reuses the results |
+| `preview-only` | Tests run only against a preview of the PR. A PR with no preview gets the review and no test run ("Tests skipped: this dot tests PRs only against a preview of the PR, and this PR has none") |
+| `none` | A PR check runs no tests, even with a preview. The review still runs |
+
+A PR with a preview is tested on it under every value, as before. A dot can hold the check for the preview: with `waitForPreviewSec` above 0, a PR check whose tests will run waits up to that many seconds for the deployment of its head to be reported (a `deployment_status` delivery, which a dot on webhooks gets), then tests the preview if it came, else the base URL as the value above says. The run shows the steps "Waiting for the PR preview" and then "PR preview found" or "No PR preview appeared". The check keeps its place in the queue while it waits, and a cancel stops the wait. A PR whose tests are skipped (`none`, docs only, Run tests off with no Tests repo) does not wait. The Tests repo of the dot is tested against the same target. A `baseUrl` on this machine (`localhost`, `127.0.0.1`, `[::1]`) and a dot with no `baseUrl` are the PR's own build, since the test project starts the app from the checkout of the PR, so they carry no label and keep drafting defects; the same holds for the demo shop. Merges and pushes are not affected: `post_merge` runs its tests under every value. A review a person asks for follows the same value. In the app the setting is Tests on PRs, in the Test runner section of the dot settings. The pilot default is `base` with a QA base URL; choose `preview-only` when the repos deploy a preview per PR, and `none` for a repo that has no QA build to test against yet.
+
+### Waiting for the deploy
+
+A merge reaches the QA environment a few minutes after it lands. A merge run that starts at once tests the build from before the merge (KAT-368). With `waitForDeploySec` above 0 and a `deployEnvironment`, the post-merge job of a merge into the default branch waits for a successful deployment of the merge commit, or of a later commit that contains it, to that environment. The tests start after that. The dot form has Deploy environment and Wait for deploy in the Test runner section, after Test branches.
+
+- **What counts as deployed.** All the deployments of one commit in the environment are one set, since one push may deploy several services, each as its own deployment. The merge is deployed when every deployment of the set has a `success` status. The set is the one for the merge commit, or the one for a later commit that GitHub says contains the merge commit (the compare of the merge commit against it says behind or identical) and that is on the default branch (the compare of the default branch against it says behind or identical). A feature branch built on the merge holds the merge commit too, with code that is not merged, so a deploy of it does not count until that commit is on the default branch. A deployment that GitHub marked `inactive` because a newer one replaced it counts, since it was deployed. A failed deployment that was retried is not a failed service: only the newest attempt of each service counts, so a failure followed by a retry that succeeded is deployed. Attempts of one service are told apart by the service the deployment names in a field made for it (`payload.service`, `name`, `app`, `component` or `project`, else a `task` other than `deploy`) and, when it names none or only the description does, by the time: a deployment of the same commit and environment that GitHub made after the failure was written replaces it, and one made before it (another service deployed in parallel) does not. For a service named in `payload` or `task` the newer deployment (the higher id) replaces the failure of the older one even when it was made before that failure was written, since a retry is often made while the first attempt still runs. A name read from the description is a guess, since parallel jobs of one pipeline share it (`Deploy (job 1)` and `Deploy (job 2)` are both `deploy`), so there the time decides: a job made before the failure was written is another job, and its success does not hide the failure. A description that carries a run, attempt, build or job number, a `#number`, a long number, a commit, or a time names the service without them (`Deploy web (run 8841)` and `Deploy web (run 8842)` are the service `deploy web`), so a retry made after the failure replaces the failed attempt. When the deployments of the merge commit itself cannot be read on GitHub, the look goes on with the later commits of the environment: one that holds the merge and deployed ends the wait as deployed, a failure that a delivery reported ends it as failed only after the later commits were read, and a later commit that cannot be read keeps the wait going. A set with a deployment that still runs is not deployed yet, and a `deployment_status` that says one deployment of the set succeeded does not end the wait by itself. Each look reads the statuses of every deployment it needs, one GitHub call each, so a deployment that has succeeded is read once and kept in memory: a later look reads only the deployments that have not succeeded yet.
+- **A failed deploy.** When the newest attempt of one deployment of the set ends in `failure` or `error`, the wait stops and nothing tests, but only after the later commits that contain the merge were looked at: a later commit on the default branch that deployed successfully is the deploy of the merge, and the tests run. When GitHub cannot list the later commits, the wait goes on and the next look decides. The run shows the step `The QA deploy of this merge failed, so the tests did not run.` (the environment `qa` reads as QA, any other name as typed), with the commit and the deployment id under Details. The run ends as cancelled by the failed deploy, the GitHub check of the commit closes as neutral with the title `The QA deploy failed`, and the job is done. No test ran, so there is no verdict about the product and no defect is drafted. A deployment of a later commit that holds the merge commit and fails stops the wait the same way, unless a deployment of the merge commit itself is still running: that one may still succeed, so the wait goes on, and a later commit that deployed still stands in for it. A failed deployment of a commit that does not hold the merge says nothing about it. A check a person asks for does not wait for a deploy.
+- **How the dot finds out.** With webhooks, a `deployment_status` success for the repository and the environment wakes the job at once. The job also looks at GitHub every 5 min, so a delivery the server missed is found. With polling there is no such delivery, so the job looks every 30 s. A look reads `GET /repos/{owner}/{repo}/deployments?sha=<merge commit>&environment=<environment>` and the statuses of each deployment, then the newest 5 deployments of the environment for a later commit. A `deployment_status` of `failure` or `error` wakes the job too, so a failed deploy is found at once and not at the next look. A delivery that says a deployment succeeded counts for itself only when GitHub lists no deployment of that commit, or cannot be read. A delivery that says one failed or errored stands the same way: when GitHub cannot be read or lists nothing of the commit, the wait stops on it, and one failed delivery of a commit outweighs a success of another service of that commit, whichever came last. When GitHub lists the commit, its list decides. The GitHub connection needs the Deployments: read permission, see [GITHUB.md](GITHUB.md#permissions). A look that fails is not an answer: the job waits on, and the step at the end names the error.
+- **No queue slot.** A look is a short visit to the queue. When the merge is not deployed yet, the job goes back to the queue with `runAfter` set to the next look, the way a review waits for the daily model cap, and the slot is free for other jobs. A waiting job survives a restart, and its time counts from the first look.
+- **On the run page.** The run of the merge starts with the wait. The Feed and the run page show Waiting for deploy, and the run has the step `Waiting for the qa deploy` with the merge commit and the time: "Merge commit abcdef0 has no successful deploy to qa yet. Waited 4 min 10 s of 15 min so far." Each look rewrites that step. The run has no verdict and no Retry, and the dot's health does not change. The GitHub check of the commit says "Waiting for the qa deploy" in place of "waiting for a free runner". When the deploy is found, the step `Deployed to qa` follows, and the same run goes on and tests. When a deployment of the set gives an `environment_url` (an `https` address, or `http` on this machine) that is the root of a site (never a path such as `/health`) on the origin of the dot's `baseUrl`, or on the host or origin the repo names in `deployUrlMatch`, the tests of the merge run against that address and the step says so ("The tests start now, against https://platform.qa.example.com."). The address is kept without its query string, fragment and sign-in, and one over 300 characters is not used. GitHub gives this address, and anyone who can write a deployment status in the environment chooses it, so a dot that has a test login (`runner.passEnv`, a file the dot copies in with `runner.copyFiles`, a Tests repo's `passEnv`, or an AI-Vision credential variable) uses it only when it is on the site of the dot's `baseUrl`: the same host or a subdomain of it. For any other address the step says so as a warning and the tests run against the `baseUrl`, so the login never goes there. To let a deploy address of another host take the login, set the `baseUrl` to a parent site such as `https://example.com`. Without one they run against the dot's base URL as before. A base URL with a path (`https://web.qa.example.com/app`) keeps its path: a deployment that gives the bare address of the site (`https://web.qa.example.com`) makes the target `https://web.qa.example.com/app`, and an address of the same site with another path is not used. Anyone who can write a deployment status to the repo can set that address. A dot with no test login runs its tests against whatever address the status gives, so set `environment_url` in your deploy workflow only to an address you trust with your tests. On a phone the Feed row says Waiting for deploy in words too. The run began when the wait began, so Started shows the merge, and Took leaves the wait out: it counts the tests, not the minutes before them.
+- **When the time is up.** The run tests anyway, after the step `Tested before the QA deploy finished; the build may be older than this merge`. Its detail says how long it waited and for which commit.
+- **A newer merge.** A newer merge into the same branch of the same repo ends the wait of the older one, when the newer merge waits for its own deploy. Its job ends, and its run is cancelled with the step `Superseded by a newer merge`, which names the merge that tests instead. A merge that does not wait, such as a docs-only merge the dot skips, tests nothing, so it ends no wait. Newer means later in the branch: GitHub's compare of the two merge commits says which one holds the other. The order of the events says nothing, since each merge sends a pull request event and a push event and a delivery can be late. When a late event of an older merge arrives, the older merge ends and the newer one goes on. When GitHub cannot say which is later, both keep waiting and each tests its own deploy. One merge that arrives twice is not a newer merge.
+- **No wait.** A merge run starts at once when a person asked for it (a review on demand, a rerun), when the merge is into a branch that is not the default branch (a release branch listed in `testBranches`), when the repo has Run tests off and its merge runs no Tests repo (an app repo with Run tests off still waits when its merge runs a Tests repo, since that suite tests the deployed build), when the merge changes only docs and the dot skips those (`testDocsOnlySkip`), and on a server with no GitHub connection. A job that waited does not wait a second time when the queue runs it again.
+- **While a job waits.** Pausing the dot stops the wait at once, on webhooks and on polling: the run is cancelled with the step `Stopped waiting for the deploy`. Archiving the dot does the same. Saving the wait (off, or another environment) makes the waiting jobs look again now, and a wait that was turned off lets their runs test at once.
+
+#### Deploy wait of one repo
+
+A dot with several app repos often has repos that deploy to different environments, or to none that GitHub reports. Each app repo may set its own `deployEnvironment` and `waitForDeploySec` in `repos`. The dot's two fields are the default for a repo that sets none, and a field left out falls back on its own: a repo with only `deployEnvironment` waits the dot's seconds on its own environment. A repo with `waitForDeploySec: 0` does not wait while the dot waits for the others, and a repo can wait when the dot does not (it needs an environment from itself or from the dot). A merge waits on the settings of its own repo, and its look reads that repo's deployments of that environment. A push that deploys several services to one environment gives several addresses, and an API host such as `https://api.qa.example.com/health` is not the page the tests open: `deployUrlMatch` names the host (`web.qa.example.com`) or the origin (`https://web.qa.example.com`) of the site, an admin setting like the other deploy fields. With no `baseUrl` and no `deployUrlMatch`, an address is used only when every deployment that gives one gives the same origin.
+
+```json
+{
+  "waitForDeploySec": 900,
+  "deployEnvironment": "qa",
+  "repos": [
+    { "repo": "acme/shop", "role": "app", "deployEnvironment": "staging", "waitForDeploySec": 600 },
+    { "repo": "acme/api", "role": "app", "waitForDeploySec": 0 },
+    { "repo": "acme/payments", "role": "app" }
+  ]
+}
+```
+
+In the dot form, a dot with two or more app repos has a row for each repo under Advanced, in the Test runner section after Wait for deploy (the fold is closed unless a repo already has its own wait, and a save that fails on one of its fields opens it): its Environment and its Wait (seconds). An empty field shows the dot's value as its placeholder and uses it. A dot with one app repo has no rows, since the dot's two fields are that repo's. The routes and the form refuse seconds outside 0 to 3600, an environment over 100 characters or on several lines, deploy fields on a test or docs repo, and a repo that waits with no environment of its own or the dot's. The form and the route `repo` of the first app repo carry its two fields too, and a body with only `repo` that leaves them out keeps the ones the repo has.
+
+The wait is the admin's with the runner settings, since it decides when a run starts on the server. This holds for the fields of each repo too. An editor sees all of them read-only in the dot form, and `PATCH /api/dots/:id` answers an editor who changes either with a 403, the code `runner_admin_only`, and "Ask your localdost admin to change the deploy wait." A save that sends the same values back is a save. A pilot setup: `deployEnvironment` the name your deploy workflow gives the QA environment (`qa`), and `waitForDeploySec` a little above the longest deploy you have seen.
+
+### Path filters
+
+A repo entry can carry `pathFilters`, a list of globs such as `["web/**"]` (a plain folder like `web` covers everything inside it). With filters set, a PR or push reaches the dot only when at least one changed file matches a filter, so two dots can split one repo by area. Push payloads list their files. A PR's file list is read from GitHub once per head and shared by every dot on the repo. A repo entry without `pathFilters` takes every event. If the file list cannot be read (network, auth, or a push payload past GitHub's 20-commit cap), the event still matches and the run shows a "Path filters not applied" step. Polled PRs carry no file list, so they match every dot until the webhook path is used. The dot settings show the filters in the repo form.
+
+### PR scope
+
+Several dots, or several teams, can share one repo that most of the PRs are not theirs. A repo entry can carry `prScope` to say which PRs the dot takes (KAT-354):
+
+| Field | Example | What it does |
+|---|---|---|
+| `authors` | `["alice", "bob"]` | GitHub logins, case-insensitive. A PR by one of them is in scope |
+| `team` | `"acme/web-team"` | A GitHub team slug. A PR by a member is in scope. The members are read from GitHub through the connected token or App and kept for 10 minutes. That needs the organization permission Members: read, see [GITHUB.md](GITHUB.md#permissions) |
+| `linkedIssueLabels` | `["pod:agentic"]` | Labels, case-insensitive. A PR is in scope when an issue or ticket it links carries one of them. The links are the ones the PR check records: a closing keyword in the title or body (`Closes #12`, `Fixes acme/product#7`), an issue GitHub lists as closed by the PR (the Development sidebar), a link an issue timeline recorded, an issue the title or body mentions with no keyword (`Part of acme/product#412` or an issue URL; a bare `#412` is no mention, since it also matches a color or a step, and counts only after a closing keyword; for the scope only, since the PR check records no link and closes nothing for it; a mention that names no issue the token can see, such as a private repo, a deleted issue or a pull request, is ignored and never makes the rule unread; at most 10 issues are read per PR, closing links first), and, on a dot with a Jira or Linear tracker, a ticket key of that tracker in the title, branch or body (`TO-1234`). GitHub issue labels are read through the issues API, ticket labels through the dot's tracker connection |
+| `skipDrafts` | `true` | A draft PR is not reviewed. When it leaves draft state it is, because `ready_for_review` queues a PR check |
+| `skipBots` | `true` | A PR whose author is a Bot account or whose login ends in `[bot]` is not reviewed |
+
+`authors`, `team`, and `linkedIssueLabels` are alternatives: with any of them set, a PR needs to match one. `skipDrafts` and `skipBots` keep PRs out whatever else matches. A repo with no `prScope` takes every PR. The scope applies to the PRs of app repos: a PR to review, a merged PR, and the push that brings a merge into the default branch. A push has no author, so the dot reads the merged PR of the head commit from GitHub (one call per push, only for a repo with a scope) and applies the same rules to it. That keeps the post-merge run of a PR the scope kept out from starting, with webhooks and with polling alike. A direct push has no PR and runs as before. A push that carries several merges follows the newest one. A listed test branch is not scoped.
+
+A PR the scope keeps out is recorded, never dropped without a trace: the event row and the log say `out of scope: <rule>` (`draft`, `bot`, or the inclusion rules that were set, for example `authors, team`), and the webhook answer carries the reason. When GitHub or the tracker cannot say (a token with no access to the org's teams, a linked issue or ticket it cannot read), the PR still runs, but the dot does not trust it (KAT-363): the log says so once, the run shows a "PR scope not applied" step with what could not be read, its PR comment and check wait in the Inbox with the same reason (under any rule that would post on its own), and the dot list and the dot page show "PR scope not applied: could not read the members of team acme/web" until a later PR reads the rule. The dot view carries it as `scopeNotApplied` (`reason`, `hint`, `at`); the server keeps it in memory, so a restart clears the line and the next PR that cannot be read brings it back. A review you ask for (the dot page or chat) always runs, and so does a simulated event. The dot settings show the scope in the repo form under Path filters. The new dot dialog (a PR scope row) asks for it too, and the Repos step of setup asks for authors, skip drafts, and skip bots per app repo, so a dot's scope is set before its first poll runs. `POST /api/dots` and `PATCH /api/dots/:id` check it and answer 400 for a login or team slug that is not valid, an unknown rule, or a scope on a test or docs repo.
+
+`npm run seed -- --help` lists flags that create a dot from the shell.
+
+## Release notes and evidence packs
+
+Both read what the dots already stored. They have no setting, no variable and no cost: neither makes a model call or asks a tracker.
+
+- **Release notes** is a page in Reports (**Release notes**, `#/reports/release-notes`). It lists the note of every merged PR a dot reviewed, grouped by milestone and then by the issue the PR names, with a Breaking flag, who the note is for (Users, Admins or Developers) and what the tests said (Passed, Bug found, Partly tested or Not tested). Pick a dot or a milestone at the top. It is a table on a computer and a list on a phone. A note exists only when an after-merge check reviewed the merged PR and found the change user-visible. An issue has a milestone only when a ticket review or the GitHub poller read it.
+- **Evidence pack** is a page for a check that names an issue (**Steps, screenshots and video** on the run page, `#/runs/<id>/evidence`): the issue, each test with its video and its steps with one screenshot each, the verdict and links. **Copy JSON** copies the same data as the API. The steps are in the order they ran, the step a failed test stopped at says "Failed here", and each screenshot has a Full size link. It shows steps and screenshots when the dot keeps them: a Playwright run saves screenshots after each step and records video for tests that fail, and set **Keep video of** to Every test in the dot's Test runner settings to keep the video of passing tests too (see [Sandbox](SANDBOX.md)).
+
+A skill reads the same data with the server token (`LOCALDOST_TOKEN`), as the rest of the API:
+
+```bash
+curl -s -H "Authorization: Bearer $LOCALDOST_TOKEN" "$LOCALDOST_URL/api/v2/release-notes?dot=PR%20Reviewer&milestone=2026.11&format=md"
+curl -s -H "Authorization: Bearer $LOCALDOST_TOKEN" "$LOCALDOST_URL/api/v2/runs/$RUN_ID/evidence-pack"
+```
+
+The screenshot and video paths in a pack (`/artifacts/<runId>/<file>`) need the same header. The pack hides tokens, cookie values and passwords in every text (a value a test typed too), and leaves out the trace, the test command and the test output. It cannot read pixels, so check a screenshot of a page that shows a secret before you share it. The fields and rules are in [API-V2.md](API-V2.md#release-notes-kat-391) and [API-V2.md](API-V2.md#evidence-pack-kat-392).
+
+## Troubleshooting
+
+**`localdost doctor` reports FAIL.** Each FAIL line carries a `fix:` command. Run it, or ask the person who owns the login to run it, then run `localdost doctor` again until it exits 0. `warn` lines are optional services.
+
+**The server will not start: "Refusing to listen on HOST=... without LOCALDOST_TOKEN".** Without `LOCALDOST_TOKEN` the API has no auth, so the server listens on 127.0.0.1 only. Set `LOCALDOST_TOKEN` (`openssl rand -hex 24`) before you set `HOST` to a LAN address or run the container image, which sets `HOST=0.0.0.0`.
+
+**The app gets 403 "LOCALDOST_TOKEN is unset, so the API answers on localhost only".** You opened the app through a tunnel, a LAN address, or a proxy while the server has no token. Set `LOCALDOST_TOKEN`, restart, and enter the token in the app's Settings. The Setup page needs the same access.
+
+**`vite build` fails with "Tsconfig not found @ljharb/tsconfig".** The Rolldown transform looks for a tsconfig that includes each client file. The root `tsconfig.json` covers only `src/**/*.ts`, so without an explicit tsconfig the search walks past the project into parent folders and picks up any stray `tsconfig.json` there. One such file sits in `~/Library/Mobile Documents/iCloud~md~obsidian/`, above an iCloud vault, and extends a package that is not installed. `vite.config.ts` sets `tsconfig: tsconfig.client.json`, which stops the search. If a build still fails this way, look for a `tsconfig.json` in a parent folder of the checkout, or build from a clone outside iCloud, for example `~/code/localdost`.
+
+**The model check fails with `LOCALDOST_LLM=claude-cli`.** Run `claude auth login` in your own terminal, or set `LOCALDOST_CLAUDE_BIN` to the full path of `claude`. On a server where nobody can sign in, connect the Model row with a subscription token from `claude setup-token` instead. `localdost init --skip-model-check` skips the round trip.
+
+**A row shows Set by environment and has no Edit or Disconnect.** An environment variable sets that service, and the environment wins over values saved in the app. Remove the variable from the shell, `.env.localdost`, or `.env`, restart the server, and connect the service from the Setup page.
+
+**Connect in the app returns "This server does not support connecting from the app yet".** The server is older than the app. Update localdost, or set the variables listed in the service's section above.
+
+**Saved connections are gone after a move to a new host.** Saved values live in the data folder, encrypted with a key in the same folder. Copy the whole `LOCALDOST_DATA_DIR` to the new host, or connect the services again.
+
+**The model check fails with `LOCALDOST_LLM=codex-cli`.** Run `codex login` in your own terminal, or set `LOCALDOST_CODEX_BIN` to the full path of `codex`. `localdost doctor` runs `codex login status`, which spends no usage. A "Model fallback" step on a run names the Codex error, for example a model your account cannot use or a usage limit.
+
+**Setup says "Model unavailable: spend cap reached".** The provider refused the call, and localdost is waiting before it tries that model again. Ask the owner of the workspace to raise the cap or wait for it to reset, or switch models in the Model sheet. Runs that stopped have a Retry button.
+
+**Webhooks return 503.** The secret for that source is unset. The answer names the setting (`GITHUB_WEBHOOK_SECRET`, `JIRA_WEBHOOK_SECRET`, or `LINEAR_WEBHOOK_SECRET`). Set it to the secret on the webhook, or use polling. For a local demo only, `LOCALDOST_ALLOW_UNSIGNED_WEBHOOKS=1` accepts unsigned events and logs a warning at start.
+
+**Webhooks return 401.** The secret in localdost and in the webhook settings differ. Linear deliveries more than 60 seconds off the server clock are also rejected, so check the server clock.
+
+**A run says "Tests did not run: no test report came back".** The test command must honour `--reporter=json`. localdost appends `--reporter=json` and reads the report from `PLAYWRIGHT_JSON_OUTPUT_FILE`. A command that wraps Playwright in a script must pass the arguments through. The command runs without a shell, so install and build steps go in Setup steps (`runner.setup`); see [Setup steps](SANDBOX.md#setup-steps). **Try it** in the dot dialog runs both once and shows the output.
+
+**A Docker run fails with "Executable doesn't exist".** The image tag and the checkout's `@playwright/test` version differ. localdost pins the image to the version in the checkout's `package.json`. Set `runner.image` to a matching `mcr.microsoft.com/playwright:v<version>-noble` image.
+
+**The app shows "Disk almost full" or "Disk full".** New test runs wait until there is room. See [Disk space](#disk-space) for what localdost does and how to free space.
+
+**A screen says "localdost is slow to answer."** The files of that screen did not arrive in time, usually because the server host is short of memory or swapping. The app asks for a file again after 1 second and after 3 seconds, each time on a new `?retry=` address, because the browser keeps the failure of an address it already asked for. The message shows at most 45 seconds after you opened the screen, and a screen that arrives later replaces it.
+
+A screen can also fail because of a file that other screens share. The browser names only the chunk that was asked for, and it keeps the failure of the shared file until the page closes. So the app finds the files of the chunk that do not load, asks for those on a new address, and runs the chunk from a copy that points at them. A `Content-Security-Policy` in front of localdost that leaves `blob:` out of `script-src` stops that copy from running, and **Reload page** is the way out.
+
+The **Try again** button starts over only the screen on display, and it becomes **Reload page** when it fails a second time. It loads or waits for the styles of that screen first, so the screen never opens without them. When you leave a screen that failed and come back, the app asks the server again with no button to press. Check the load of the host (`uptime`) before you look at localdost.
+
+**A list says "Still loading. localdost is slow to answer right now." under its loading rows.** The list request has waited 10 seconds. Activity, Inbox, Reports, Dots, Room, Test cases, Test runs, and Traceability do this, and the Inbox says it under both of its lists, To review and Decided. A list that was already waiting when you opened its screen shows its loading rows at once, together with the line, and so does the Decided list of the Inbox when To review has waited. The line goes away when the rows arrive, and nothing is retried: the request is still running.
+
+**A screen says "localdost was updated. Reload to get the new version."** The page in your browser was built by an older version, and the server no longer has the files it asks for, because every build renames them. Press **Reload**. The server answers its app page for a path it does not know, so a file that is gone can come back as that page instead of a 404, and the app treats both the same. Safari does not say which file failed, so there the app asks the server for its app page and compares the script it starts with the one your page started with: when they differ, the page is from an older build. A screen that fails while it draws is a different case and still says "This screen crashed".
+
+**Port 4319 is in use.** `localdost init` picks the next free port when 4319 is taken. Set `PORT` in `.env.localdost` to choose one.
+
+**Deciding an approval returns 410.** It expired. Rerun the run to get a new draft, or raise `LOCALDOST_APPROVAL_TTL_MS`.