# Repository settings (.andon/settings.json)

A team's automation settings can live in its repository, so every Andon instance with a clone of that repository
uses the same ones. Andon creates the file. What you change in Andon afterwards is an override for that instance
only: Andon never rewrites the file.

## How it works

- On each sync, the agent reads `.andon/settings.json` from the default branch of every clone linked to a team
  (`origin/<branch>` as last fetched, else the local branch), never from the files checked out. An edit in the clone,
  or a commit on another branch, changes nothing until it is merged to the default branch. A folder that isn't a git
  repository, or has no default branch, reports nothing.
- **Only an admin's machine applies the file.** A file is applied only from a machine whose owner is an owner or
  admin of the workspace, since changing a team's automation is an admin action. A member's machine still writes the
  file where there is none (below), but what it reports changes nothing. A team whose clones are all on members'
  machines keeps the file's settings an earlier sync applied (none, for a new team) until an admin's clone reports
  the file.
- **No file on the default branch:** the agent writes one into the clone, untracked, unless the clone already has
  one. It holds the settings the team sets itself (not what it inherits from a parent team or the defaults, so those
  keep reaching it), or, once another clone has reported a file, that file's settings: overrides made in Andon never go
  into it. Commit and merge it to share the settings. Remove it before switching to a branch that has one.
- **A file:** its settings become the team's base settings. What the team already sets in Andon stays and overrides
  the file: picking up a file never clears a value someone set. Clear a value on the team's page to let the file
  decide it.
- **Changing the file waits for a person.** `.andon/settings.json` is one of the standard never-auto-merge paths, so a
  pull request (or a merge without one) that changes it never merges on its own.
- **Overrides:** a change in **Settings → Teams**, on a team (its level, model or subscription on the team's page, or
  a setting found by searching Settings, such as **Protect the standard paths**), is saved in Andon and wins over the
  file, in that instance only. The setting then shows *Overrides the repository's .andon/settings.json here.* Settings that come
  from the file show *From the repository's .andon/settings.json.* On the team's page, a row whose value comes from
  the file reads *Repository: <value>*, and choosing that first option drops the team's own value for it. No single
  button drops every override at once.
- Which setting wins, from strongest to weakest:
  1. the team's own setting in Andon;
  2. the team's file;
  3. a parent team's setting in Andon;
  4. the parent's file;
  5. the workspace's automation (changing it changes every team that sets nothing of its own);
  6. Andon's defaults.

  A team stores a value only when it differs from what it would get from those: saving the inherited value stores
  nothing, and clearing a value returns the team to the inherited one.
- A file Andon can't use (bad JSON, an unknown key, a value out of range) shows its error under the team page's Overrides.
  The last good settings stay in use until the file is fixed.
- When a team has clones on more than one machine, the first admin's clone to report a file provides it, until that
  clone leaves the team.
- **A file that isn't on the default branch yet** (untracked, uncommitted, or committed on another branch) and says
  something else than what the team runs with is called out under the team page's Overrides: *Your clone on
  <machine> has unmerged changes to .andon/settings.json: they apply once merged to <branch>*, with each key that
  differs, its value in the file and the applied one. A key the team sets in Andon is marked as overriding the file,
  since merging won't change it. The agent reports these clones with its heartbeat after each sync; a file that agrees
  with the applied settings (the one Andon wrote, say) says nothing. Only each team's linked clone is read, not its
  worktrees: an edit in a card's worktree applies once it is merged and the clone is on it.
- The agent only touches clones inside the policy's `workspaceRoots`. It never replaces an existing file and never
  follows a symlink.

## The file

Most files are one line, a team preset:

```json
{ "preset": "ship" }
```

`preset` is `manual`, `assist` or `ship`, the team's level on its page. In the file it stands for the automation
keys the preset sets:

| `preset` | `autoReview` | `autoMerge` | `autoDone` | `maxReviewRounds` |
|---|---|---|---|---|
| `manual` | `false` | `false` | `false` | (as it is) |
| `assist` | `true` | `false` | `true` | (as it is) |
| `ship` | `true` | `true` | `true` | `2` |

A key under `automation` wins over the preset, so `{ "preset": "ship", "automation": { "maxReviewRounds": 3 } }` is
Ship with three rounds (still Ship on the team page: review rounds never change a team's level). Whether cards are done by hand and Autopilot aren't in
the file: they belong to each Andon, set with the level on the team page. The file Andon writes says `"preset"`
when the team's own settings hold all of a preset's keys, and lists under `automation` only what differs from it.
An agent older than the `preset` key reports such a file as one it can't use (*unknown key*): update it.

Every key in full:

```json
{
  "automation": {
    "autoReview": true,
    "autoMerge": true,
    "mergeMethod": "squash",
    "deleteBranch": true,
    "maxReviewRounds": 2,
    "maxCiFixAttempts": 2,
    "neverMergePaths": ["infra/**"],
    "deleteWorkspaceOnDone": true,
    "autoDone": true,
    "finishClassifier": true,
    "reviewProvider": "claude",
    "reviewModel": "default",
    "runtime": "auto",
    "executor": "claude",
    "model": "default",
    "reviewRequest": { "method": "comment", "reviewer": "review-bot", "comment": "@review-bot review", "waitMinutes": 60 }
  }
}
```

Every key is optional. A missing key falls back to the parent team or the default. The values match the Runs and Pull requests
sections: `mergeMethod` is `squash`, `merge` or `rebase`; `reviewProvider` and `executor` are `claude`, `codex` or `gemini`;
`runtime` is `auto`, `orca` or `terminal`; a model is `default` or a model id; `maxReviewRounds` is 1 to 10 and
`maxCiFixAttempts` is 0 to 10. `reviewRequest` asks another reviewer (a review bot, say) after Andon's own review and fixes
what it asks for: `method` `comment`, `reviewer` or `off`, the reviewer's GitHub `reviewer` login, an optional
`comment` and `waitMinutes` (5 to 1440, default 60).

`runtime`, `finishClassifier` and `deleteWorkspaceOnDone` have no control in Settings: where a card
runs, judging unreported runs and deleting the workspace after Done are fixed behaviour. A file that sets them is
still read, so leave them out to keep the fixed behaviour.

`neverMergePaths` **adds** to the standard paths; an empty list never removes them. While a team protects the standard
paths (the default), a PR that changes any of these never merges on its own: `supabase/migrations/**`,
`db/migrations/**`, `.github/**`, `**/*.lock`, `**/pnpm-lock.yaml`, `**/package-lock.json`, `.env*`, `**/.env*` and
`.andon/settings.json` (the lockfile patterns don't hold back Dependabot or Renovate PRs). On a repository with no
GitHub remote, the same paths hold back Andon's merge of a card's branch into the base. The paths a team uses are the standard ones, then the
nearest list (the team's own in Andon, its file, a parent's), so `[]` means the standard paths alone and a missing key
falls back to the parent's list. The file Andon writes, and the unmerged-file notice, hold only the additions; standard
entries repeated in a file are harmless.

`protectStandardPaths` turns the standard paths off on purpose: with `false`, only what `neverMergePaths`
adds still waits for a person, so a team that lists nothing protects nothing and its migrations, CI config, lockfiles,
.env files and `.andon/settings.json` merge like any other change. It resolves like every other key (the team's own in Andon, its file, a
parent's) and is on unless something says `false`. It is its own key because a saved `[]` once removed every
protection without anyone meaning it. Search Settings for **Protect the standard paths** to find the switch, above the
list, which shows the standard paths while they apply; turning it off asks first and
lists what will then merge on its own (turning it back on doesn't ask). A machine whose policy doesn't
allow auto merge still merges nothing, and a person's **Merge now** still merges after a look.

Accounts (`claude_account`, `codex_account`) belong to a single instance and never go in the file. Nor does "When usage
credits run out" (search Settings for it): its list names this instance's accounts. Files from before that
change may still hold `creditsFallback`; it is accepted and ignored.
