@wardby/cli 0.3.0 → 0.4.1

package/docs/agent-recipes.md

@@ -0,0 +1,383 @@
+# Agent recipes
+
+Two complete agent setups you can ask your MCP client to build, made only from
+shipped Wardby features:
+
+- [Recipe A: an architecture keeper](#recipe-a-an-architecture-keeper), three
+  cooperating agents that keep a repository's architecture knowledge accurate.
+- [Recipe B: a builder per language](#recipe-b-a-builder-per-language), a
+  coding agent that turns an `@mention` into a draft pull request, with notes for
+  Node/TypeScript, Python, and other languages.
+
+Each recipe gives the one-paragraph ask you paste into Claude or Codex, the
+configuration that results, and what it produces. Both use `your-org/your-repo`
+as a placeholder repository.
+
+Agent names are unique across the whole instance, so the examples use
+repo-scoped names such as `<repo>-architect`. The sub-agent bound names
+(`architect`, `builder`) stay fixed so the delegate tools keep their names.
+
+## Before you start
+
+These recipes go beyond the quickstart. Check each item.
+
+1. **Version.** The recipes require Wardby 0.4.0 or later. The knowledge note in
+   coding runs, `wardby knowledge check`, and the `push` trigger are not in
+   earlier releases.
+2. **Coding-agent setup.** The quickstart runs native agents only: it does not
+   install a GitHub App or build worker images. Both recipes use coding agents,
+   so complete [Coding-agent setup](coding-agent-setup.md) first: a GitHub App
+   installed on the repository, a worker image, the coding proxy, and a Docker or
+   Kubernetes job launcher. Run `wardby coding preflight` to check it. For a
+   hosted deployment, [Getting started on GKE](getting-started-gke.md) covers
+   this.
+3. **A GitHub account link.** Link your GitHub account once with
+   `link_host_account`. Creating a coding agent or linking a repository checks
+   that you have write access to the repository
+   ([details](code-review-agents.md#who-may-give-an-agent-a-repository)).
+4. **A public HTTPS URL for GitHub webhooks.** The event triggers (`push` for the
+   merge watcher, `pull_request` for the reviewer, `mention` for the router) work
+   only when GitHub can deliver webhooks to your Wardby instance. Set the App's
+   webhook URL to `https://<your-host>/hosts/github/events` and its webhook
+   secret to the value of `GITHUB_APP_WEBHOOK_SECRET`
+   ([registering the App](code-review-agents.md#registering-the-github-app)). A
+   laptop install is not reachable from GitHub by default, so it needs a public
+   HTTPS endpoint in front of it (the
+   [runtime architecture](architecture-runtime.md) diagram shows an HTTPS tunnel
+   in front of the local server) or a hosted deployment such as
+   [GKE](getting-started-gke.md). Scheduled and manually triggered runs need no
+   webhook.
+5. **App events.** Tick the events each trigger needs in the App's settings:
+   Pull request and Check run for reviews; Issue comment, Pull request review
+   comment, and Issues for mentions; and **Push** for the merge watcher. Each is
+   its own checkbox
+   ([registering the App](code-review-agents.md#registering-the-github-app)).
+6. **Models.** Pick ids from `list_models` ([Models and pricing](models.md)). The
+   examples use `claude-sonnet-5` for the capable coding model and
+   `claude-haiku-4-5` for the small fast one; use whatever your deployment has
+   enabled. A coding agent's model must be supported by its coding provider.
+
+## Recipe A: an architecture keeper
+
+**What it does.** Keeps `docs/knowledge/` (see
+[Architecture knowledge bundles](knowledge.md)) accurate and growing, and lets
+coding agents and reviewers use it. **Triggers:** the architect runs weekly on a
+schedule; the merge watcher runs on every merge to the default branch; the
+reviewer step runs on every pull request.
+
+### The MCP ask
+
+> Set up an architecture keeper for `your-org/your-repo`. Create a Claude Code
+> coding agent called `<repo>-architect` with the reference architecture-agent prompt
+> from the Wardby knowledge guide and a $3 per-run budget. Trigger it once and
+> show me the run; don't schedule it yet. After I've reviewed its first pull
+> request, schedule it for Mondays at 6:00 AM. Then create a small, cheap native
+> agent called `<repo>-merge-watcher` with the reference watcher prompt, attach
+> `architect` to it as a sub-agent named `architect`, and link it to the
+> repository with the `push` trigger. Finally, add the reviewer step to my
+> existing code-review agent's prompt.
+
+### The resulting configuration
+
+Do the steps in this order; each depends on the one before.
+
+1. **Create the architect.**
+2. **Trigger it once by hand** (`trigger_agent`) and review the draft pull
+   request it opens.
+3. **Schedule it** (`set_schedule`).
+4. **Create the watcher**, attach the architect, tick **Push** in the App's
+   events, and link it with `push`.
+5. **Add the reviewer step** to your review agent's prompt.
+
+<details>
+<summary>Architect (coding agent)</summary>
+
+| Setting           | Value                                                                                                    |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `name`            | `<repo>-architect`                                                                                       |
+| `kind`            | `coding`                                                                                                 |
+| `model`           | a capable coding model, for example `claude-sonnet-5` with `provider: "claude-code"`                     |
+| `budgetUsd`       | `3` per run (docs-only work)                                                                             |
+| `codingProfile`   | `provider`, `repository: "your-org/your-repo"`, `baseRef` (your default branch), and `defaultTask` below |
+| `schedule`        | `0 6 * * 1` with your `timezone`, set after the first manual run (`set_schedule`)                        |
+| Tools, sub-agents | None                                                                                                     |
+| Repository checks | May be skipped; the work is docs-only                                                                    |
+| System prompt     | The architect prompt in [Architecture knowledge bundles](knowledge.md#set-up-an-architecture-agent)      |
+
+`defaultTask`, required before a coding agent can be scheduled:
+
+```text
+Weekly knowledge review. Run the full cycle described in your instructions for
+this repository. Your file changes are collected into a pull request for review;
+don't try to commit or open one yourself.
+```
+
+The prompt is published once, in the knowledge guide, so this page cannot drift
+from it. Copy it from there, unchanged, as the agent's `systemPrompt`.
+
+</details>
+
+<details>
+<summary>Merge watcher (native agent)</summary>
+
+| Setting       | Value                                                                                                                          |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `name`        | `<repo>-merge-watcher`                                                                                                         |
+| `kind`        | `native`                                                                                                                       |
+| `model`       | a small fast model, for example `claude-haiku-4-5`                                                                             |
+| `budgetUsd`   | Sized for the architect's per-run cost: the run tree shares one budget, so at least `3` plus a little for the watcher itself   |
+| Sub-agent     | `attach_subagent` with `parentAgentId` the watcher, `childAgentId` the architect, `boundName: "architect"`                     |
+| Link          | `link_repository` with `access: "write"`, `triggers: ["push"]`, no `checkName`                                                 |
+| System prompt | The reference watcher prompt in [Drift runs on merge](knowledge.md#set-up-the-merge-watcher), copied unchanged from that guide |
+
+The bound name gives the watcher a `delegate_to_architect` tool, which the
+reference prompt calls.
+
+```json
+{
+  "agentId": "<watcher agent id>",
+  "repository": "your-org/your-repo",
+  "access": "write",
+  "triggers": ["push"]
+}
+```
+
+Only pushes to the default branch start it. If the watcher already has a run
+pending or running, the next merge starts nothing; the weekly run catches up.
+
+</details>
+
+<details>
+<summary>Reviewer knowledge step</summary>
+
+Append the "Reviewer step" section from
+[Architecture knowledge bundles](knowledge.md#reviewer-step) to the system
+prompt of a code-review agent ([Code-review agents](code-review-agents.md)). No
+other setting changes. It makes reviews read the bundle's index, apply the
+concepts that match the changed files, and report stale citations on knowledge
+pull requests as suggestions only.
+
+</details>
+
+### What it produces
+
+- A weekly draft pull request that touches only `docs/knowledge/` and an
+  `AGENTS.md` pointer, adding cited concepts and re-anchoring stale ones. A
+  person reviews and merges it.
+- After each merge that touches a concept's files, a drift run limited to the
+  affected concepts, as another draft pull request.
+- Reviews that cite the relevant concepts.
+- Every later coding run for the repository (Recipe B) receives the knowledge
+  index and base commit automatically.
+
+Run `wardby knowledge check` locally or in CI to validate the bundle. The
+format, the check's codes, and drift behavior are in
+[Architecture knowledge bundles](knowledge.md).
+
+## Recipe B: a builder per language
+
+**What it does.** Turns an `@mention` on an issue or pull request into a draft
+pull request. A native router agent reads the request and delegates to a coding
+builder agent. **Trigger:** the router is linked with `mention`; only people with
+write access to the repository can start it.
+
+### The MCP ask
+
+> For `your-org/your-repo`, create a Codex coding agent called `<repo>-builder` with a
+> $5 per-run budget and a 30 minute timeout, starting from the default branch.
+> Allow it to install these packages from the registry: (your dependencies).
+> Then create a small native agent called `<repo>-router` with a $6 budget, attach
+> `builder` to it as a sub-agent named `builder`, and link it to the repository
+> with the `mention` trigger. The router should ask for details when a request is
+> unclear and otherwise delegate one precise task to the builder. Never merge
+> anything.
+
+Pick the language section below for the toolchain and package settings.
+
+### Common configuration
+
+<details>
+<summary>Router (native agent)</summary>
+
+| Setting     | Value                                                                                                  |
+| ----------- | ------------------------------------------------------------------------------------------------------ |
+| `name`      | `<repo>-router`                                                                                        |
+| `kind`      | `native`                                                                                               |
+| `model`     | a small fast model, for example `claude-haiku-4-5`                                                     |
+| `budgetUsd` | The builder's budget plus a little: the run tree shares one budget                                     |
+| Sub-agent   | `attach_subagent` with `parentAgentId` the router, `childAgentId` the builder, `boundName: "builder"`  |
+| Link        | `link_repository` with `access: "write"`, `triggers: ["mention"]` (one `mention` agent per repository) |
+
+```json
+{
+  "agentId": "<router agent id>",
+  "repository": "your-org/your-repo",
+  "access": "write",
+  "triggers": ["mention"]
+}
+```
+
+System prompt:
+
+The prompt is published once, in the [builder-agent help article](../help/builder-agent.md#router-prompt). Copy it unchanged as the agent's `systemPrompt`.
+
+The router's final reply is posted where the mention was, so never instruct it
+to include secrets or internal details. See
+[What the mention agent receives](code-review-agents.md#what-the-mention-agent-receives).
+
+</details>
+
+<details>
+<summary>Builder (coding agent) fields that matter</summary>
+
+| Field (`codingProfile`) | What to set                                                                                                                                                  |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `model` (agent field)   | A capable coding model the chosen provider supports, for example `gpt-5.6-terra` with `codex` or `claude-sonnet-5` with `claude-code`; a mismatch is refused |
+| `provider`              | `codex` or `claude-code`; the agent's `model` must be one that provider supports                                                                             |
+| `repository`            | `your-org/your-repo`; your linked GitHub account needs write access                                                                                          |
+| `baseRef`               | The branch runs start from, usually your default branch                                                                                                      |
+| `toolchain`             | `node` or `node-python` (per language below)                                                                                                                 |
+| `toolchainVersion`      | `"3.12"` for `node-python`; omit for `node`                                                                                                                  |
+| `packageAllowlist`      | Top-level packages per ecosystem (`npm`, `pypi`). Needs `packages:approve` or `agents:admin`                                                                 |
+| `packagePolicy`         | Optional `minReleaseAgeDays` (0 to 30)                                                                                                                       |
+| `services`              | Catalog service names the agent may start, for example `["postgres"]`; see [Services](coding-services.md)                                                    |
+| `protectedPaths`        | Globs a run may not change, for example `[".github/**", "CODEOWNERS"]`. `.wardby/**` is always protected except `.wardby/services.yaml`                      |
+| `timeoutSec`            | 60 to 7200; for example `1800`                                                                                                                               |
+| `workerImageRef`        | Digest-pinned custom image; needs `agents:admin` (see "Other languages")                                                                                     |
+| `defaultTask`           | Needed only to schedule the agent                                                                                                                            |
+| Agent `budgetUsd`       | Per-run budget, reserved at dispatch, for example `5`                                                                                                        |
+
+The agent's `systemPrompt` is placed ahead of each request as standing
+instructions. The template below is generic.
+
+</details>
+
+<details>
+<summary>Builder system prompt template</summary>
+
+The prompt is published once, in the [builder-agent help article](../help/builder-agent.md#builder-prompt), so this page cannot drift from it. Copy it unchanged as the agent's `systemPrompt`.
+
+Adjust the numbered rules to your project; keep rules 1, 5, and 6.
+
+</details>
+
+Package error codes are in [Installing packages in coding runs](coding-packages.md).
+Make sure the repository's `AGENTS.md` lists the test and lint commands, because
+the builder takes them from there.
+
+### Node / TypeScript
+
+Use the stock worker image: `toolchain: "node"`, no `toolchainVersion`. The
+agent runs `npm ci` or `npm install` through the registry proxy, so enable the
+packages your project needs (top-level entries only; the dependency graph is
+added automatically):
+
+```json
+{
+  "provider": "codex",
+  "repository": "your-org/your-repo",
+  "baseRef": "main",
+  "toolchain": "node",
+  "timeoutSec": 1800,
+  "packageAllowlist": {
+    "npm": ["react@^19", "vitest", "@testing-library/*"]
+  },
+  "packagePolicy": { "minReleaseAgeDays": 3 },
+  "protectedPaths": [".github/**", "CODEOWNERS"]
+}
+```
+
+Test commands come from `AGENTS.md` (for example `npm test` and `npm run lint`).
+Lockfile installs are verified against the registry before npm runs; see
+[Installing packages in coding runs](coding-packages.md).
+
+### Python
+
+Use the `node-python` toolchain with version `3.12`, which adds Python 3 with
+`pytest` and `ruff` next to Node. Pip installs go through the registry proxy
+into a virtual environment, and only wheels are served (source distributions are
+refused), so allow packages that publish wheels. Extras such as `[binary]` are not accepted in an allowlist entry; list the wheel package's own name instead (`psycopg-binary`, not `psycopg[binary]`):
+
+```json
+{
+  "provider": "codex",
+  "repository": "your-org/your-repo",
+  "baseRef": "main",
+  "toolchain": "node-python",
+  "toolchainVersion": "3.12",
+  "timeoutSec": 1800,
+  "packageAllowlist": {
+    "pypi": ["flask>=3", "sqlalchemy>=2", "psycopg-binary>=3"]
+  },
+  "services": ["postgres"]
+}
+```
+
+`services` is optional. When the tests need a database, commit
+`.wardby/services.yaml` to the base branch:
+
+```yaml
+services:
+  postgres: "16"
+```
+
+Each run then gets a fresh, empty PostgreSQL instance and a `DATABASE_URL`
+variable; say so in `AGENTS.md` so tests read it. See
+[Services for coding runs](coding-services.md) for the catalog, variables, and
+errors. For Claude Code on `node-python`, the operator also sets
+`CODING_CLAUDE_TOOL_RUNNER_IMAGE_NODE_PYTHON_3_12` (see
+[Coding-agent setup](coding-agent-setup.md)).
+
+### Other languages (Go, Java, Rust, ...)
+
+Wardby ships worker images only for `node` and `node-python`. For any other
+toolchain, build your own image on Wardby's driver base image and point the
+agent at it with `workerImageRef`, a digest-pinned reference (a mutable tag is
+rejected). Setting it needs the `agents:admin` scope and the admin role. The
+Dockerfile shape, the driver image, and what Wardby does and does not verify are
+in [Bring-your-own worker images](coding-worker-byo-images.md).
+
+```json
+{
+  "provider": "codex",
+  "repository": "your-org/your-repo",
+  "baseRef": "main",
+  "toolchain": "node",
+  "workerImageRef": "registry.example.com/your-org/worker-go@sha256:<64 hex>",
+  "timeoutSec": 1800
+}
+```
+
+`toolchain` is still required; the worker image's own toolchain is what runs.
+
+What the package registry covers: only **npm and PyPI** are mediated. A Go,
+Maven, Cargo, or other ecosystem has no registry proxy, and the worker has no
+direct network access, so those dependencies must be baked into your image or
+already vendored in the repository. The registry still applies to any npm or
+pip use inside the same run, and `packageAllowlist` has no entry for other
+ecosystems. If services are allowed, the image must be built on driver v11 or
+later.
+
+### Together with Recipe A
+
+Coding runs automatically receive the repository's knowledge index and base
+commit when `docs/knowledge/index.md` exists on the base branch
+([how coding runs use the bundle](knowledge.md#how-coding-runs-use-the-bundle)),
+so the builder works from recorded pitfalls and invariants. Recipe A keeps that
+bundle current.
+
+### What it produces
+
+A mention from someone with write access gets a "Working on it" status comment
+from the App. The router either asks a question or delegates, the builder
+pushes a unique branch and opens at most one draft pull request, and the App
+edits the status comment with the pull request link or the failure. A person
+reviews and merges; Wardby never merges for you. A later mention on that pull
+request continues the same branch.
+
+## Next steps
+
+- [Architecture knowledge bundles](knowledge.md)
+- [Code-review agents](code-review-agents.md)
+- [Coding-agent setup](coding-agent-setup.md)
+- [Models and pricing](models.md)

package/docs/code-review-agents.md

@@ -136,6 +136,14 @@ PR description:
   the same GitHub App that receives the mention. A router agent that
   delegates coding work can pass that run id on so the existing branch and
   PR are continued rather than a new one being opened.
+- Before the mention runs, wardby checks that the marker's run is one this
+  deployment recorded, in the same repository, and that it opened this PR.
+  When it is not (most often because another wardby deployment sharing the
+  same GitHub App opened the PR), no run starts: the App replies that this
+  deployment cannot continue the PR, so ask the deployment that opened it.
+  If a router agent passes a `continuePriorRun` id that this deployment
+  cannot continue, the delegation returns a `continuation_refused` tool
+  error to the agent instead of failing its run.
 - The header reads `[GitHub issue #<n>]` on an issue. For a mention inside an
   inline review thread, the `Requested by` line ends with
   `(in review thread <id>)`.
@@ -273,8 +281,10 @@ with:
   below) — generate it with `openssl rand -hex 32` or similar; the ingress
   endpoint answers 404 until this is set.
 - **Subscribe to events**: Pull request, Issue comment, Pull request review
-  comment, Check run, and Issues (needed for mentions in a newly opened or
-  edited issue; without it only comment mentions are seen).
+  comment, Check run, Issues (needed for mentions in a newly opened or
+  edited issue; without it only comment mentions are seen), and Push (needed
+  for the `push` trigger, which starts merge-watcher agents; it is its own
+  checkbox, separate from the others, and must be ticked explicitly).
 - **Repository permissions**:
 
   | Permission    | Access         |
@@ -386,6 +396,23 @@ review command:
 }
 ```
 
+**A merge watcher**, which starts on every merge to the repository's default
+branch (see [Drift runs on merge](knowledge.md#drift-runs-on-merge)):
+
+```json
+{
+  "agentId": "<agent-id>",
+  "repository": "owner/name",
+  "access": "write",
+  "triggers": ["push"]
+}
+```
+
+The `push` trigger is for native agents only and takes no `checkName`. Unlike
+`mention`, several agents may hold it on one repository, but one watcher per
+repository is the recommended shape. Only pushes to the default branch start a
+run; tags, other branches, and branch deletions are ignored.
+
 Only one agent per repository may hold the `mention` trigger, and only one
 link per repository may use a given `checkName` (whatever its triggers; the
 database enforces it); linking a second agent the same way returns a 409

package/docs/coding-agent-setup.md

@@ -131,6 +131,9 @@ terminal cleanup; investigate any retained resource as a cleanup failure.
 
 See [release verification](release-verification.md) for the complete gate.
 
+If the repository has `docs/knowledge/index.md`, every coding run's prompt
+includes it. See [Architecture knowledge bundles](knowledge.md).
+
 ## Budgets
 
 A coding run's budget is reserved when it is dispatched: the agent's own

package/docs/coding-worker-isolation.md

@@ -125,7 +125,9 @@ deeply to process is refused with `request_nesting_too_deep`.
 
 - **Anthropic Messages** (`parseAnthropicRequest`): a fixed set of keys,
   text/`tool_use`/`tool_result`/thinking blocks, exactly the two Wardby tool
-  names, and the reviewed beta values.
+  names, the reviewed beta values, the thinking mode the run's model catalog
+  entry names, and only effort levels that entry lists in `efforts` (top-level,
+  or on an effort-only system message for models that change effort per turn).
 - **OpenAI Responses** (`parseOpenAiRequest`), built from what the pinned
   Codex CLI actually sends (recorded in
   `src/providers/coding-proxy/fixtures/codex-<version>-responses-requests.json`
@@ -166,10 +168,37 @@ deeply to process is refused with `request_nesting_too_deep`.
     forces `store: false` and `background: false` and adds a
     `max_output_tokens` ceiling when Codex omits it.
 
-Upgrading the pinned `@openai/codex-sdk` means re-recording that fixture
-against a local fake upstream and rerunning the compatibility test. A Codex
-release that sends a new key or item type fails closed at the proxy rather
-than silently widening what reaches OpenAI.
+A Codex release that sends a new key or item type fails closed at the proxy
+rather than silently widening what reaches OpenAI. Upgrading the pinned
+`@openai/codex-sdk` is therefore one command plus a review:
+
+1. Change the pin in `src/coding-worker/package.json` (a dependency bot's
+   pull request does this). Until the fixture is re-recorded, the "pinned
+   Codex version" test fails with `Codex SDK bump detected (...)`.
+2. On that branch, run `npm run codex:rerecord` on a machine where npm
+   installs the host's Codex binary. It sets the root devDependency
+   `@openai/codex-sdk` to the worker's pin and installs it, drives the pinned
+   Codex CLI through a fixed set of scenarios (responses-lite and classic tool
+   layouts, code-mode `exec` with `view_image` and `apply_patch`, namespaced
+   tool calls, a spawned sub-agent, local context compaction) against a local
+   fake of the proxy's `/v1/responses` endpoint — nothing is sent to OpenAI —
+   and writes `codex-<version>-responses-requests.json`, replacing the
+   previous version's fixture. Paths, ids, timestamps and long prompt texts
+   are normalized so a re-record of the same version is byte-identical. It
+   then runs the compatibility test (the real Codex through the real proxy)
+   and the proxy's fixture-replay tests, and prints a request-shape diff
+   against the previous fixture: new or removed top-level keys, input item
+   and content types, tool types, `include`/`reasoning`/`text`/`tool_choice`/
+   `service_tier` values and `client_metadata` keys.
+3. Review that diff. If the tests pass and the diff is empty or shows only
+   shapes the allowlist already accepts, commit the new fixture with
+   `package.json` and `package-lock.json`. If the proxy refuses a request
+   (an `openai_*_not_allowed` code in the test output), do not widen the
+   allowlist to make it pass: first find out what the new key, item, tool
+   type or value does (Codex's changelog and source) and whether it can
+   reach anything outside the worker or bill outside the metered tokens,
+   then widen `parseOpenAiRequest` only for what that review accepts, and
+   document it in the list above.
 
 The proxy also binds a second listener, the **deny port** (`8788`,
 `CODING_PROXY_DENY_PORT`), which serves nothing: it accepts a connection,
@@ -413,6 +442,11 @@ Operating the queue across replicas:
   (`--depth 1`); the worker never receives Git history and finalization needs
   only the base commit.
 
+Every wardby process also polls the model catalog on
+`WARDBY_MODEL_CATALOG_REFRESH_SECONDS` (default `45`), which decides whether
+a coding run's model is still available and how it is priced at dispatch; see
+[Models and pricing](models.md).
+
 The GitHub adapter requires `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`; the
 App installation is checked while preparing the workspace, before the
 billable proxy session is created. Upstream keys remain behind

package/docs/getting-started-gke.md

@@ -40,7 +40,7 @@ Install and authenticate:
 
 - Google Cloud CLI (`gcloud`)
 - Terraform 1.10 or newer
-- Docker with `linux/amd64` build support
+- Docker with the `buildx` plugin and `linux/amd64` build support
 - `kubectl`
 - Helm 3 or later (installs External Secrets Operator)
 - Node.js 24 and npm
@@ -255,16 +255,20 @@ through the Cloud SQL Auth Proxy, via Workload Identity from one Kubernetes
 service account. What each may do inside the database comes from a `NOLOGIN`
 group role in `deploy/gke/database-grants.sql`:
 
-| Workload      | Google service account   | Kubernetes service account | May do                                                                                                                                                                 |
-| ------------- | ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Control plane | `<name_prefix>-app`      | `wardby-control-plane`     | `wardby_app`: read/write every table, including the durable executor's in schema `dbos`; never change a schema                                                         |
-| Coding proxy  | `<name_prefix>-proxy`    | `wardby-coding-proxy`      | `wardby_proxy`: only its budget ledger — `CodingProxySession`/`CodingProxyRequest`, plus update `tokensIn`, `tokensOut` and `costUsd` on `Run`, and read only its `id` |
-| Migrations    | `<name_prefix>-migrator` | `wardby-migrator`          | Acts as the table owner (`SET ROLE`), so `prisma migrate deploy` and `dbos schema` can alter and create tables                                                         |
+| Workload      | Google service account   | Kubernetes service account | May do                                                                                                                                                                                          |
+| ------------- | ------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Control plane | `<name_prefix>-app`      | `wardby-control-plane`     | `wardby_app`: read/write every table, including the durable executor's in schema `dbos`; never change a schema                                                                                  |
+| Coding proxy  | `<name_prefix>-proxy`    | `wardby-coding-proxy`      | `wardby_proxy`: only its budget ledger — `CodingProxySession`/`CodingProxyRequest`/`RunModelUsage`, plus update `tokensIn`, `tokensOut`, `costUsd` and `turns` on `Run`, and read only its `id` |
+| Migrations    | `<name_prefix>-migrator` | `wardby-migrator`          | Acts as the table owner (`SET ROLE`), so `prisma migrate deploy` and `dbos schema` can alter and create tables                                                                                  |
 
 `deploy/gke/bootstrap-database-iam.sh` applies the grants as the built-in
 owner, from a short-lived Job inside the cluster. Run it whenever
-`database-grants.sql` changes, and as part of the orders below. The grants run
-in one transaction, so a statement the database refuses leaves nothing applied.
+`database-grants.sql` changes, before deploying the release that needs the new
+grants (`bootstrap-database-iam.sh --check`, then `bootstrap-database-iam.sh`,
+then `up.sh`), and as part of the orders below. A release deployed ahead of its
+grants fails with "permission denied" wherever it uses one it doesn't have yet.
+The grants run in one transaction, so a statement the database refuses leaves
+nothing applied.
 
 The built-in owner is not a Terraform resource: `bootstrap-database-iam.sh`
 creates it if it's missing, sets a one-time password on it through the Cloud
@@ -300,6 +304,12 @@ own role, for every privilege `database-grants.sql` gives `wardby_proxy`
 grants instead of letting the proxy fail registry requests with "permission
 denied".
 
+After upgrading an existing deployment to a release with cost attribution,
+re-run `bootstrap-database-iam.sh` so the coding proxy can record per-model
+usage for coding runs (used by the `cost_report` tool's `model` grouping).
+Until then coding runs still work, but their per-model breakdown isn't
+recorded.
+
 `bootstrap-database-iam.sh --check` runs the grants inside a transaction that
 is then rolled back, and reports success or the exact statement the database
 refused, without changing anything. Run it before the real run on a live
@@ -397,9 +407,10 @@ server answers `415`, because it checks the content type before the token.
 Create the first self-hosted login credential. It is printed once.
 `--role admin` makes this operator account an admin. Only admins can use all
 the privileged operations: `make_owner`, BYO `workerImageRef`, package
-approval, and service catalog changes. A `package-approver` can approve
-packages only, and a `service-manager` can change the service catalog only.
-Users created without `--role` have no roles. See
+approval, service catalog changes, and model catalog changes. A
+`package-approver` can approve packages only, a `service-manager` can change
+the service catalog only, and a `model-manager` can change the model catalog
+only. Users created without `--role` have no roles. See
 [roles and privileged operations](security-deployment.md#roles-and-privileged-operations).
 
 ```sh
@@ -443,6 +454,12 @@ images, pushes them, substitutes immutable digests, leaves Secret Manager values
 as they are, waits for rollouts, and then checks the public endpoint: discovery
 must answer `200` and an unauthenticated MCP request `401`, or the deploy fails.
 
+`up.sh` builds every image in one `docker buildx bake` run
+(`deploy/gke/docker-bake.hcl`), so Docker's `buildx` plugin is required (Docker
+Desktop includes it). The images build concurrently, and the stages that only
+compile JavaScript run on your machine's own architecture, so building the
+`linux/amd64` images from an arm64 machine emulates only what actually ships.
+
 A control-plane restart is designed not to drop requests, at the cost of a
 slower rollout. A new pod must stay Ready for three minutes before the old one
 is retired, because the load balancer can take well over a minute to start