> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundchecklive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent runbook

> How a coding agent runs the Soundcheck QA test plans: which environment to use, how to sign in, how to drive web and mobile, what it must never do, and how to report results.

This page is for agents (Claude Code, Codex, Cursor, Devin, and others) that run a [test plan](https://docs.soundchecklive.io/qa/scope.md). Read the [QA testing guide](https://docs.soundchecklive.io/qa.md) first. Its test data rules apply to agents without exception.

## Rules an agent never breaks

These rules hold even when a test plan step seems to need otherwise. Stop and ask the person who started the run instead.

* **Never publish a draft gig that has invitations.** Publishing sends pending invitations by push, text, and email.
* **Never message, @mention, invite, or text a person who is not a test account.**
* **Never change a feature flag, an org setting, or a role** unless the person who started the run asked for that exact change. One PostHog project serves dev, QA, and production.
* **Never delete data.** Archive what you created, and list it in the report so a person can clean it up.
* **Never write to a database through SQL.** Read-only `SELECT` queries on the dev database are fine for checking what was stored.
* **Never print a password, token, or key.** Read test credentials with a script that does not echo them.
* **Never act in a customer org.** Production test runs stay in the test org the run was given.

## Pick the backend

| You need | Use |
| - | - |
| A local stack you can reset | `npm run dev:emulator` in `api-events/` and `web/` from your worktree, with the seeded personas. See `docs/engineering/guides/local-testing.mdx` in the repository. |
| The shared dev environment | `https://dev.app.soundchecklive.io` and a simulator dev client pointed at the dev API |
| What testers see in TestFlight | Production, in the test org only. Ask the person who started the run before you write anything there. |

To refresh a row in [What's ready](https://docs.soundchecklive.io/qa/scope.md), check every merged PR for each ticket in its **Tickets** column against each branch:

```bash theme={null}
git fetch origin qa main
for pr in $(gh pr list --state merged --base dev --search "<ticket> in:title" --json number --jq '.[].number'); do
  sha=$(gh pr view "$pr" --json mergeCommit --jq .mergeCommit.oid)
  git merge-base --is-ancestor "$sha" origin/qa && echo "PR $pr in qa"
  git merge-base --is-ancestor "$sha" origin/main && echo "PR $pr in main"
done
```

A row is **Yes** for an environment only when every PR for its tickets has reached that branch. A mobile change that reached `qa` is in the next TestFlight build. A web or API change that reached `main` is live in production.

## Drive the API

`npm run api` calls the API as a seeded persona, so you do not hand-build tokens. It needs `npm run worktree:setup -- e2e mcp-ts`.

```bash theme={null}
npm run api -- personas
npm run api -- ops chat
npm run api -- call v1EventsDetail --as owner.busy --path eventId=<id>
```

Against dev, pass `--env dev` and a token. Every write against dev is held until you add `--yes`, so read the printed request before you confirm it.

## Drive the mobile app

Use a local iOS simulator first. It is free and it covers most checks. Follow `docs/engineering/mobile/agent-screenshots.mdx` in the repository for the setup:

1. Claim a simulator with `node scripts/sim/claims.mjs claim --note "<test plan> run"`, so no other session uses it.
2. Start your own Metro with `npm run shots:metro -- --port 8085`.
3. Sign in with `npm run sim:e2e-login -- --as member` for the crew account, or `--as user` for the owner account. The helper reads the test accounts from `.env.e2e` without printing them.
4. Open the screen under test with a deep link, for example `soundcheck://events/<eventId>` or `soundcheck://events/<eventId>/chats/<chatId>`.

Checks that need two accounts at once, such as a chat message going from one person to another, need two simulators with one account each.

Use Revyl only for checks a simulator cannot prove, such as a store build loading an update. Run only the saved tests that cover the area, not a full pass. Picking the tests and running them are two steps:

1. `npm run revyl:select -- --out <scratchpad>/plan.json <files of the area>` picks the saved tests and writes the plan. It runs nothing.
2. `node scripts/revyl-flows/run.mjs --plan <scratchpad>/plan.json --out <scratchpad>/results.json` runs each test in the plan and writes the results. Add `--dry-run` first to see the commands without starting a device.

Checks marked **Needs a real device** need a person with a phone. List them as not run.

## Drive the web app

Use the built-in browser or Playwright against the web URL that matches the backend. Sign in as the persona the check names. Never sign in with a person's own account.

## Report the results

Post one table per run, in the Linear issue or PR the run was for. Use one row per check ID and one of four results:

| Result | Meaning |
| - | - |
| `PASS` | The expected result happened. Evidence attached. |
| `FAIL` | Something else happened. A bug is filed in the Linear **QA** team and linked. |
| `BLOCKED` | The check could not start, for example because the flag is off for the org or the build is missing the change. Say what blocked it. |
| `NOT RUN` | Out of reach for this run, for example **Needs a real device**. Say why. |

```markdown theme={null}
Run: chat test plan, dev backend, simulator iPhone 17 Pro Max iOS 26.2, dev at 4094344f9a
| Check | Result | Evidence |
| --- | --- | --- |
| CHAT-01 | PASS | shots/chat-01-light.png |
| CHAT-09 | FAIL | QA-12, shots/chat-09.png |
| CHAT-20 | NOT RUN | needs a real phone for SMS |
Left on dev: gig "QA CHAT-01 smoke" (draft), chat "QA CHAT-01"
```

End every report with what you left in the environment, even when the list is empty.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.