@wardby/cli 0.5.3 → 0.6.0

package/help/admin-viewer.md

@@ -3,7 +3,7 @@ id: admin-viewer
 title: Watch live runs with the admin viewer API
 summary: Read-only, deployment-wide live view of runs, sub-agent trees, triggers, outcomes and coding-run services for admins (admin:view).
 audience: operator
-tags: [viewer, admin, runs, live, sse, monitoring, desktop, app, infrastructure, kubernetes, pods, networkpolicy]
+tags: [viewer, admin, runs, live, desktop, infrastructure, kubernetes, download, openapi, api contract]
 appliesTo: ">=0.4.0"
 ---
 
@@ -33,9 +33,11 @@ must allow long-lived responses and not buffer `text/event-stream`.
 
 A desktop viewer for macOS is included in the source tree (`apps/viewer`). Add
 your server's canonical URI, sign in with an `admin` user in the browser, and it
-shows the live graph. Its README covers setup, and what an external identity
+shows the live graph. Each GitHub release has an unsigned macOS build of the viewer attached (see the README for opening it past Gatekeeper). Its README covers setup, and what an external identity
 provider client needs when the server runs in delegating mode.
 
+From Wardby 0.6.0, admins can also sign in to a mobile app for the same read-only live view; see the help article `mobile-app`.
+
 The Infrastructure tab shows the Kubernetes pods where your deployment runs
 coding jobs, read-only. It uses your kubeconfig (switchable per server) and
 requires a minimal read-only Kubernetes role. See the Infrastructure view
@@ -45,5 +47,7 @@ Armor, routes), each NetworkPolicy with a plain-English summary, and on GKE a
 link from each pod to the Google Cloud console. The run graph's zoom controls
 include **Fit width**, which fills the canvas with the graph's width.
 
+From Wardby 0.6.0 the API is also published as OpenAPI 3.1 (`docs/viewer-api.openapi.yml` in the package), an API contract you can feed to client generators such as `openapi-typescript`.
+
 For parameters, status codes, frame formats and schemas, follow
 [`docs/viewer-api.md`](../docs/viewer-api.md).

package/help/agent-recipes.md

@@ -181,6 +181,33 @@ builder's result includes `pullRequest` (`outcome`,
 `repository`, `number`, `url`) from Wardby's own record when it opened or
 pushed to one, so the lead can report the links.
 
+When the builders' changes must land in a particular order, pass `mergeOrder`
+(1 to 99, 1 first) in each `delegate_to_<name>` call — give a dependency a
+lower number than what calls it, and give two changes the same number when
+there is no order between them:
+
+```json
+{ "task": "Add the /quotes endpoint the client will call.", "mergeOrder": 1 }
+```
+
+```json
+{ "task": "Add the quotes page that calls /quotes.", "mergeOrder": 2 }
+```
+
+Leave `mergeOrder` out and the pull requests' **Related pull requests**
+section lists them in delegation order instead, labelled as a suggestion
+rather than a set order. It applies only to coding sub-agents; a native
+sub-agent ignores it. A follow-up that continues one of these pull requests
+with `continuePriorRun` and no `mergeOrder` of its own keeps the pull
+request's current value (the one most recently set for it, by the run that
+opened it or a later continuation); one that passes `mergeOrder` replaces
+it.
+
+With Wardby 0.6.0 or later, once a set has more than one `mergeOrder`, each
+pull request in it also gets a `wardby merge order` check run showing
+whether its earlier steps have merged yet; search help for "merge order
+check" for its states and for requiring it in branch protection.
+
 ## Step 3: confirm
 
 Summarize what you created: each agent's name and id, the sub-agent bindings,

package/help/architecture-agent.md

@@ -248,7 +248,7 @@ You are a senior software engineer doing a rigorous code review of one pull requ
 The task names the pull request, its repository and its head commit, e.g. "Review pull request #12 in owner/name (head <sha>)" or "Review pull request #3 in local:/path/to/repo (head <sha>)". Pass that repository, exactly as written, to every repo_* tool.
 
 PROCESS
-1. Call `repo_pr_read` with the repository and the pull request number. If the pull request is closed or merged, stop and reply "skipped: PR not open". Use the returned `headSha` as the `ref` for every later read (not the branch name).
+1. Call `repo_pr_read` with the repository and the pull request number. If the pull request is closed or merged, stop and reply "skipped: PR not open". Use the returned `headSha` as the `ref` for every later read (not the branch name). If this pull request is part of a multi-repository request, use `repo_pr_read`'s `relatedPullRequests` (current) rather than the description's Related pull requests section, which can be stale.
 2. Architecture knowledge: read `docs/knowledge/index.md` at the head with `repo_read_file`. If it exists, open the concepts (files in docs/knowledge/) whose `wardby.affects` globs or `wardby.citations[].path` match the changed files. Treat them as recalled context, not authority (AGENTS.md wins on conflict). Flag a change that violates a concept's invariant or walks into a recorded pitfall, citing the concept file. If the pull request edits a file under docs/knowledge/, check that each edited concept's citations still point at lines that support its claim at the head, and report unresolved or stale citations as a SUGGESTED finding only (never blocking, never MUST_FIX). If docs/knowledge/index.md does not exist, skip this step.
 3. If `lastReviewedSha` is set, you reviewed this pull request before: call `repo_pr_read` again with `sinceSha` = lastReviewedSha and review that delta (see RE-REVIEWS). Still check whether your earlier MUST_FIX items are resolved by reading the affected files at the head. Otherwise review the whole diff. If `openThreads` is non-empty, those are your own unresolved inline comments: put the `id` of each one this head fixes in `resolveThreadIds` when you publish, leave the others open, and do not post them again.
 4. If a patch is truncated or missing, read the file with `repo_read_file`. Where the diff alone is not enough to judge correctness, read the surrounding code, and use `repo_list_files` to find callers, related modules, existing helpers and tests. Before claiming a test is missing, find the test files and read the relevant one. Before claiming duplication, find the existing code it duplicates and name it.

package/help/brokered-secrets.md

@@ -0,0 +1,79 @@
+---
+id: brokered-secrets
+title: Brokered secrets and the secret broker
+summary: Let tools use a secret only by sending it to hosts you choose, without ever reading its value.
+audience: operator
+tags: [secrets, brokered, secret broker, security, tools, fetch, sigv4, set_secret_broker]
+appliesTo: ">=0.6.0"
+---
+
+# Brokered secrets and the secret broker
+
+A readable secret hands its value to any tool that is granted it, so a tool with
+untrusted code, or a prompt-injected agent, can send the value anywhere the tool
+may fetch. A **brokered** secret never reaches tool code: you fix the hosts it
+may be sent to and how it is placed, and the Wardby host adds it to the request.
+
+## When to use it
+
+Broker any secret that a tool only needs to send to an API, such as a bearer
+token, an API key, or AWS credentials. Keep a secret readable only when the tool
+must compute with the value itself.
+
+## Set it up
+
+1. Create the secret with a broker config, in one call or in the browser form's
+   "Brokered" checkbox: `create_secret { name, broker }`. For an existing secret
+   use `set_secret_broker { name, broker }`.
+2. Attach it to the agent (`attach_secret`) and list its name in the tool
+   attachment's `allowedSecrets` (`attach_tool`).
+3. Include the host in the attachment's `allowedHosts` too. The normal fetch
+   policy still applies on top of the broker.
+
+The config is `{ hosts, pathPrefixes?, placement }`. Hosts are exact hostnames
+such as `api.example.com`, and the request must use https on the default port.
+
+## The four placements
+
+- **header**: `{ "kind": "header", "name": "Authorization", "format": "Bearer {value}" }`
+- **query**: `{ "kind": "query", "name": "api_key" }`
+- **body**: `{ "kind": "body", "field": "token" }`, for a JSON-object or form body
+- **aws-sigv4**: `{ "kind": "aws-sigv4", "region": "us-east-1", "service": "s3" }`,
+  where the value is JSON `{ "accessKeyId", "secretAccessKey", "sessionToken?" }`
+
+## Use it in a tool
+
+```js
+const response = await fetch("https://api.example.com/v1/items", {
+  secrets: ["EXAMPLE_API_KEY"],
+});
+```
+
+`secrets.get("EXAMPLE_API_KEY")` on a brokered secret throws
+[`secret_brokered`](errors/secret-brokered.md). Redirects are not followed, and
+the value is scrubbed from responses and console output.
+
+## Change or remove brokering
+
+Changing the config (hosts, path prefixes, or placement) with
+`set_secret_broker` or `create_secret` takes effect immediately and is not
+confirmed in a browser. Anyone who can act as the owner over MCP can send the
+value to another host they also grant through `attach_tool` `allowedHosts`; the
+operator's fetch policy still applies.
+
+Only removal is confirmed: `set_secret_broker { name, broker: null }` returns a
+browser link, and a person confirms by typing the secret's name. The MCP call
+alone never removes it. Every change is audited.
+
+## Related
+
+- Full guide: [`docs/tool-secrets.md`](../docs/tool-secrets.md)
+- [Use native agents, tools, and data](native-capabilities.md)
+- Errors: [`secret_brokered`](errors/secret-brokered.md),
+  [`secret_not_brokered`](errors/secret-not-brokered.md),
+  [`secret_broker_destination_denied`](errors/secret-broker-destination-denied.md),
+  [`secret_broker_conflict`](errors/secret-broker-conflict.md),
+  [`secret_broker_body_invalid`](errors/secret-broker-body-invalid.md),
+  [`secret_broker_value_invalid`](errors/secret-broker-value-invalid.md),
+  [`secret_broker_changed`](errors/secret-broker-changed.md),
+  [`secret_broker_config_invalid`](errors/secret-broker-config-invalid.md)

package/help/build-claude-code-image.md

@@ -0,0 +1,131 @@
+---
+id: build-claude-code-image
+title: Build a tool runner image for a Claude Code agent
+summary: A procedure an MCP assistant follows to build a custom image for a Claude Code coding agent (Ruby, Go, Java or another language) FROM the release's tool runner image, check it, and set it with workerImageRef.
+audience: operator
+tags: [claude-code, custom-image, workerImageRef, tool-runner, worker-image, other-language, ruby, toolchain]
+appliesTo: ">=0.5.4"
+---
+
+# Build a tool runner image for a Claude Code agent
+
+A Claude Code agent uses two containers. One runs Claude Code and holds its API
+key; it always uses Wardby's standard image. The other, the **tool runner**,
+runs the agent's commands and has the repository. `codingProfile.workerImageRef`
+replaces the tool runner. The long-form guide is
+[`docs/coding-worker-byo-images.md`](../docs/coding-worker-byo-images.md).
+
+For a Codex agent, follow [Build a custom worker image](build-worker-image.md)
+instead.
+
+If you are an assistant connected to Wardby over MCP, follow these steps. Do
+them in order, ask the user instead of guessing, and stop at the first failed
+prerequisite. Never write into the user's repository; ask where to keep the
+Dockerfile (for example a folder outside the repository).
+
+## Step 1: find the toolchain
+
+Read the project's manifests and how it runs its tests, as in "Step 1: find the
+toolchain" of [Build a custom worker image](build-worker-image.md). Ask the user
+when the language or version is unclear.
+
+## Step 2: find the base image
+
+Ask the user for the value of `CODING_CLAUDE_TOOL_RUNNER_IMAGE` in the Wardby
+server's settings (on a quickstart install, `.wardby/.env` in the Wardby project
+directory). Use `CODING_CLAUDE_TOOL_RUNNER_IMAGE_NODE_PYTHON_3_12` instead when
+the project also needs Python. This image comes from the same Wardby release as
+the server, which the custom image must match.
+
+If the value is a bare local ID (`sha256:...`), tag it first, because Docker
+cannot build `FROM` an ID:
+
+```sh
+docker tag sha256:<id> wardby-tool-runner-base:local
+```
+
+## Step 3: write the Dockerfile
+
+Start from the base image, install as `root`, and end as the tool runner's user:
+
+```dockerfile
+FROM <base image from step 2>
+USER root
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends <packages> \
+    && rm -rf /var/lib/apt/lists/*
+USER 10001:10001
+```
+
+Rules:
+
+- **Keep the entrypoint.** Do not set `ENTRYPOINT` or `CMD`, and keep
+  `USER 10001:10001` as the last `USER` line.
+- **Install everything at build time.** A run can download only npm and PyPI
+  packages, so every other package must be in the image.
+- **Compile in an earlier stage.** The tool runner is Debian 12 (bookworm).
+  Compile native code in an earlier build stage that uses a bookworm image,
+  and copy only the results. The long-form guide has a Ruby example.
+- **Settings go in `/etc/profile.d/`.** Commands run as `sh -lc` with a fixed
+  environment, so `ENV` lines do not reach them. Put settings in a file under
+  `/etc/profile.d/`, and put programs in `/usr/local/bin`.
+- **Mind the run's filesystem.** The root filesystem is read-only. `/tmp` and
+  `/home/wardby` are empty scratch space; anything the image put there is
+  hidden. `/workspace` is the checkout; files you want to keep go there. Put
+  caches and temporary files under `/workspace/.cache/`.
+- **No root at run time.** Commands always run as user 10001 with
+  `no-new-privileges`, so setuid programs do not help.
+- Release images are `linux/amd64`. On an ARM machine, pass
+  `--platform linux/amd64` to `docker build` and `docker run`.
+
+## Step 4: build it and run the tests the way a run would
+
+```sh
+docker build --tag wardby-tool-runner-<language>:local <dockerfile folder>
+```
+
+Then run the project's test command against a **throwaway clone**, never the
+user's checkout. This command uses a run's restrictions and the same fixed
+environment a run gives commands, so `ENV` lines in the image do not apply:
+
+```sh
+git clone <repository> /tmp/wardby-image-check
+docker run --rm --read-only --tmpfs /tmp:rw,noexec,nosuid,size=64m --tmpfs /home/wardby:rw,noexec,nosuid,size=64m,uid=10001,gid=10001,mode=0700 --network none --user 10001:10001 --cap-drop ALL --security-opt no-new-privileges -v /tmp/wardby-image-check:/workspace -w /workspace --entrypoint env wardby-tool-runner-<language>:local -i HOME=/home/wardby LANG=C.UTF-8 PATH=/opt/wardby/bin:/usr/local/bin:/usr/bin:/bin sh -lc '<test command, e.g. bundle exec rake test>'
+```
+
+On Linux, make the clone writable for user 10001 first (it is a throwaway copy:
+`chmod -R a+rwX /tmp/wardby-image-check`). Fix the Dockerfile until the tests
+run. A "command not found" means a missing program or a missing
+`/etc/profile.d/` setting. Delete the clone afterwards.
+
+## Step 5: choose the image reference
+
+`workerImageRef` must be immutable; a tag is refused.
+
+- **Local quickstart** (Wardby runs coding jobs with Docker on this machine):
+  use the local image ID,
+  `docker image inspect --format '{{.Id}}' wardby-tool-runner-<language>:local`.
+  Wardby never pulls these images, so build on the same machine.
+- **Kubernetes**: push the image to a registry the cluster can pull from,
+  and use `<registry>/<name>@sha256:<digest>`.
+
+## Step 6: update the builder and try it
+
+1. Call `update_agent` with the coding agent's id and
+   `codingProfile: {workerImageRef: "<reference from step 5>"}`. This needs the
+   `agents:admin` scope and the admin role. On a hosted server, ask an
+   administrator if it is refused.
+2. Start a small run that exercises the toolchain:
+   `trigger_agent {agentId, task: "Run the project's tests and report the results. Change nothing."}`.
+3. Read the result with `get_run` and report to the user what ran, what passed
+   and what failed.
+
+If a run fails with `worker_tool_runner_unreachable`, the image was usually not
+built `FROM` this release's tool runner, or its `USER` or `ENTRYPOINT` was
+changed. Rebuild the image whenever Wardby is upgraded.
+
+To undo it, call `update_agent` with `codingProfile: {workerImageRef: null}`.
+
+Related: [Build a custom worker image](build-worker-image.md),
+[Approve packages for coding agents](coding-packages.md) and
+[Troubleshoot coding workers](troubleshooting/coding-workers.md).

package/help/build-worker-image.md

@@ -15,12 +15,9 @@ on top of Wardby's driver base image and set the coding agent's
 `codingProfile.workerImageRef` to it. The long-form guide is
 [`docs/coding-worker-byo-images.md`](../docs/coding-worker-byo-images.md).
 
-**Codex agents only.** A Claude Code agent runs its commands in Claude's tool
-runner, which `workerImageRef` does not change, so a custom image gives a Claude
-Code agent no new tools. If the agent's `codingProfile.provider` is
-`claude-code`, say so and stop; the user can switch the agent to Codex (the
-quickstart sets Codex up with `--coding-provider codex` and an
-`OPENAI_API_KEY`).
+These steps build on the driver image (`codingProfile.provider: codex`). For a
+`claude-code` agent, search help for a Claude Code image article for this
+version; if there is none, tell the user and stop.
 
 If you are an assistant connected to Wardby over MCP, follow these steps. Do
 them in order, ask the user instead of guessing, and stop at the first failed

package/help/code-review-agents.md

@@ -43,6 +43,17 @@ from bots and people without write access. Repository links require the
 agent owner's linked GitHub access, or an explicitly recorded administrator
 approval.
 
+## When a review starts
+
+A push normally starts a review right away, but its timing can be held back
+by two independent things: from Wardby 0.6.0, the pull request's own
+delegating request still running (see [Reviewing a pull request a delegated run
+opened](#reviewing-a-pull-request-a-delegated-run-opened) below), and, on a
+link set up for it, CI on the pushed head still running (see [Review after
+CI (`waitForCi`)](#review-after-ci-waitforci) below). Either can delay the
+check that reports the review's result; neither changes what the review
+itself reports once it runs.
+
 ## CI and sibling pull requests
 
 `repo_pr_read` also returns `ci`: the CI check runs and commit statuses on the
@@ -65,6 +76,54 @@ on the review check instead.
 Commit statuses need the App's **Commit statuses: Read** permission; without
 it only check runs are shown.
 
+With Wardby 0.6.0 or later, `repo_pr_read` also returns `relatedPullRequests`: this
+request's pull requests (`repository`, `number`, `state`, `mergeOrder`,
+`self`), computed fresh at call time; empty on a human pull request, one
+with no recognized Wardby marker, or a pull request on a local repository
+(no origin marker to look up there). The `self` entry (the pull request just
+read) always has a `state` (`draft`, `open`, `merged`, or `closed`) from that
+same read. Another entry has a `state` (`open`, `merged`, or `closed`) only
+when Wardby has it stored, as it does for pull requests linked to an issue,
+and omits it otherwise; call `repo_pr_read` on that pull request when you
+need its live state. The list is current; the PR body's **Related pull
+requests** section can be stale — see
+[Related pull requests across repositories](related-pull-requests.md).
+
+With Wardby 0.6.0 or later, once a set has more than one `mergeOrder`, each
+pull request in it also gets its own check run, named `wardby merge order`,
+independent of any reviewer link; search help for "merge order check" for
+its states and for requiring it in branch protection.
+
+## Reviewing a pull request a delegated run opened
+
+This requires Wardby 0.6.0 or later; earlier releases review such a pull
+request on its first push. When a lead agent delegates coding work and a sub-agent opens the pull
+request (see [Fanning out to several
+builders](../docs/agent-recipes.md#fanning-out-to-several-builders)), every
+reviewer linked with the `pull_request` trigger holds its review of that
+pull request until the delegating (lead) run finishes, however it ends
+(including failing, being cancelled or being lost), even if the link has no
+`waitForCi` set. This gives the request's other pull requests, if any, time
+to open before any of them is reviewed, so a reviewer does not report a
+field or route as missing only because a sibling pull request had not opened
+yet. When the lead run finishes normally, their **Related pull requests**
+sections have also been rewritten (see [Related pull requests across
+repositories](related-pull-requests.md)); when it is ended another way, such
+as being cancelled, held reviews start without that rewrite. Either way,
+reviewers should rely on `repo_pr_read`'s `relatedPullRequests`.
+
+A reviewer linked with `waitForCi` then waits for CI too, once the lead run
+finishes, with its own full 15-minute fallback counted from that point. A
+pull request opened directly, by a human, or on a local repository is never
+held this way. A later request that continues an already-open pull request
+is not held again: the request that opened it has already finished (a push
+inside the same, still-running request is held). If Wardby cannot tell
+whether the pull request's opening run was delegated, the review starts
+right away instead. A held review not released when its lead run finishes is
+reconsidered by Wardby's reconciliation sweep once it has been held for 15
+minutes and released when the lead run has finished, and dropped after 24
+hours like a review held for CI.
+
 ## Review after CI (`waitForCi`)
 
 A `pull_request` link can set `waitForCi: true` so this reviewer reviews a
@@ -105,12 +164,15 @@ Add this to a reviewer's system prompt:
     Reviewer step (CI and related pull requests). Read `ci` from repo_pr_read.
     When `ci` and the description's Tests disagree, follow CI and say so; never
     ask for a fix only because a sandbox test failed while CI passed. Report
-    pending checks as pending. If the description has a "Related pull requests"
-    section, a field, route or schema the change relies on may be added by one
-    of those pull requests: do not report it as missing; note the dependency
-    and the suggested merge order instead.
-
-Wardby also writes that section: see
+    pending checks as pending. If repo_pr_read's relatedPullRequests is
+    non-empty, a field, route or schema the change relies on may be added by
+    one of those pull requests: do not report it as missing; note the
+    dependency and the listed merge order instead. relatedPullRequests is
+    current; the PR body's "Related pull requests" section can be stale.
+
+On a release before 0.6.0, `repo_pr_read` has no `relatedPullRequests`:
+use the description's **Related pull requests** section in its place in that
+step. Wardby also writes that section: see
 [Related pull requests across repositories](related-pull-requests.md).
 
 For App permissions, webhook setup, trigger configuration, and security

package/help/deploy-gke.md

@@ -29,8 +29,12 @@ The deployment process is:
 3. Put first-time values in an untracked `.env.local`; `deploy/gke/up.sh`
    seeds Secret Manager without overwriting existing production values.
    Jira settings are optional there, all or none; see [Jira](jira.md).
-4. Run `HOSTNAME=wardby.example.com deploy/gke/up.sh`, then verify DNS,
+4. Run `WARDBY_HOSTNAME=wardby.example.com deploy/gke/up.sh`, then verify DNS,
    certificate issuance, database IAM bootstrap, and service health.
+   Use `WARDBY_HOSTNAME`, not `HOSTNAME` (shells set that to the machine name);
+   the script refuses local names such as `*.lan` or `*.local`, and asks you
+   to confirm (or set `WARDBY_HOSTNAME_CHANGE=<new hostname>`) before moving
+   a deployment to a different hostname.
 
 When a release changes `deploy/gke/database-grants.sql`, re-run the database
 grants bootstrap **before** deploying that release, so the proxy role can
@@ -42,6 +46,9 @@ The Kubernetes launcher runs Codex and Claude Code coding workers; a Claude
 Code pod adds a tool-runner sidecar with its own image. Configure an identity
 provider and GitHub App before allowing people to use the public endpoint.
 
+To lower the idle cost of a lightly used deployment, see
+[Low-power mode](../docs/getting-started-gke.md#low-power-mode) (Wardby 0.6.0 and later).
+
 ## Plan it with your assistant
 
 If you are an assistant connected to Wardby over MCP and the user asked to plan

package/help/deployment-targets.md

@@ -1,7 +1,7 @@
 ---
 id: deployment-targets
 title: Choose a deployment target
-summary: Pick the supported Wardby deployment path and understand its operational boundary.
+summary: Compare local, self-hosted, and GKE deployment paths and their operational boundaries.
 audience: operator
 tags: [deployment, docker, gke, aws, production]
 appliesTo: >=0.2.1
@@ -9,31 +9,42 @@ appliesTo: >=0.2.1
 
 # Choose a deployment target
 
-Wardby has one local path and two production-ready deployment shapes:
+Wardby has a local development path, a self-hosted container deployment
+reference, and a supported GKE reference deployment. The references provide
+different parts of a production environment; operators must complete the
+remaining controls and verification before accepting production work.
 
 - **Local development:** `wardby quickstart` runs the control plane locally
   with its portable PostgreSQL container. It is the best place to evaluate,
   develop agents, and connect a local Codex or Claude Code client.
-- **Production container baseline:** run the published production image with
-  PostgreSQL, HTTPS ingress, durable storage, backups, and an operator-owned
-  identity provider. The Compose and Caddy configuration is a reference
-  baseline, not a managed platform.
+  `deploy/kind-coding` is a local Kubernetes proof harness, not a production
+  deployment.
+- **Self-hosted container deployment** (e.g., Docker Compose on a VM or
+  on-premises host): Wardby supplies runtime and migration images plus a
+  Compose/Caddy edge reference. The operator supplies PostgreSQL, secrets,
+  network and egress controls, backups and restore testing, monitoring, and a
+  separate coding-controller host. Configure authentication for the deployment.
 - **Google Kubernetes Engine Autopilot:** the supported Google Cloud path. It
-  provisions GKE, private-IP Cloud SQL, Artifact Registry, isolated Codex and
-  Claude Code workers, HTTPS Gateway, and GCP-native secret and network
-  controls. See [Deploy on GKE](deploy-gke.md).
+  provisions GKE, private-IP Cloud SQL with backups and point-in-time recovery,
+  Artifact Registry, isolated Codex and Claude Code workers, HTTPS Gateway, and
+  GCP-native secret and network controls. Operators still need to choose
+  availability, test recovery, and configure alerts and retention. See
+  [Deploy on GKE](deploy-gke.md).
 
-AWS is supported as a portable runtime target and has a Bedrock Claude adapter,
-but Wardby does not ship a native AWS deployment module. Other cloud providers
+AWS can run the portable runtime and has a Bedrock Claude adapter, but a native
+AWS deployment module is planned and has not shipped. Other cloud providers
 can run the production container image with equivalent database, ingress,
 identity, secret, isolation, and observability controls; that infrastructure is
-operator-owned.
+operator-owned. On Amazon EKS, set `KUBERNETES_PLATFORM=eks` (gVisor node group
+required) and, for RDS, `DATABASE_AUTH=rds-iam`; see "Database
+authentication" in
+[`docs/security-deployment.md`](../docs/security-deployment.md).
 
 The older `deploy/gcp` Cloud Run module is deprecated. Do not choose it for a
 new installation.
 
-Before going live, complete the deployment security checklist and make a
-backup, upgrades, alerting, and incident-response plan. Read
+Before going live, complete the release verification and security deployment
+checks, and make plans for backups, upgrades, alerts, and incident response. Read
 [`docs/getting-started.md`](../docs/getting-started.md) for the local and
 container setup, and [`docs/security-deployment.md`](../docs/security-deployment.md)
 for the production controls.

package/help/errors/coding-provider-not-configured.md

@@ -26,8 +26,8 @@ runs recorded it) when `CODING_WORKER_IMAGE` has since been unset.
   a toolchain with its own image (such as `CODING_WORKER_IMAGE_NODE_PYTHON_3_12`),
   still runs without `CODING_WORKER_IMAGE`.
 - **`coding_provider_not_configured:claude-code`**: `CODING_CLAUDE_WORKER_IMAGE`
-  or `CODING_CLAUDE_TOOL_RUNNER_IMAGE` isn't set. Claude Code needs both, and
-  even an agent's own `workerImageRef` doesn't replace the tool runner.
+  or `CODING_CLAUDE_TOOL_RUNNER_IMAGE` isn't set. Claude Code needs both, even
+  for an agent with its own `workerImageRef`.
 
 This error is about images, not API keys. A missing or invalid model API key
 fails later, when the run calls the model.

package/help/errors/database-auth-invalid.md

@@ -0,0 +1,28 @@
+---
+id: errors/database-auth-invalid
+title: Database authentication is misconfigured
+summary: DATABASE_AUTH or the database URL does not meet the rules for the chosen authentication mode, so the process refused to start.
+audience: operator
+tags: [error, database, rds, iam, deploy, database_auth_invalid, rds-iam]
+appliesTo: ">=0.5.4"
+---
+
+# Database authentication is misconfigured
+
+`database_auth_invalid` means `DATABASE_AUTH` is not valid, or `DATABASE_AUTH=rds-iam` is set and `DATABASE_URL` (or `DBOS_SYSTEM_DATABASE_URL`) does not meet its rules. Wardby checks this when the process starts, so every `wardby` command fails with it, not only the server. The message names the problem; it never includes the URL, credentials, or parameter values.
+
+`DATABASE_AUTH` is `password` (the default; the password is in `DATABASE_URL`) or `rds-iam` (Amazon RDS IAM database authentication, where the password is a short-lived token signed with the workload's AWS credentials). Any other value is refused.
+
+Under `rds-iam` check each of these:
+
+1. `DATABASE_URL` starts with `postgresql://` or `postgres://`, has a user, and has no password.
+2. `AWS_REGION` or `DATABASE_AWS_REGION` is set (`DATABASE_AWS_REGION` wins).
+3. The URL has `sslmode=verify-full` and `sslrootcert=<path to the RDS CA bundle>`, and that file exists and is readable in the container. An unreadable file is reported with its error code, such as `ENOENT` for a missing file or `EACCES` for one the process cannot read.
+4. Only supported parameters are present: `sslmode`, `sslrootcert`, `application_name`, `fallback_application_name`, `options`, `client_encoding`, `statement_timeout`, `lock_timeout`, `idle_in_transaction_session_timeout`, `query_timeout`, `connection_limit`, `pool_timeout`, `connect_timeout`, `schema`. Anything else (`sslcert`, `sslkey`, `ssl`, `host`, `pgbouncer`, ...) is refused by name; remove it.
+5. User and database names in the URL are correctly percent-encoded.
+
+If the code is not raised but connections are rejected, the configuration is valid and the problem is on the AWS side: the workload's IAM role needs `rds-db:connect` for the database user, and that user needs the `rds_iam` role in the database.
+
+`prisma migrate deploy` and `dbos schema` take a URL and do not follow `DATABASE_AUTH`. Mint a short-lived URL with the migration image's helper: `DATABASE_URL="$(node scripts/rds-iam-url.mjs)" && export DATABASE_URL && npm run prisma:migrate && npm run dbos:migrate`. It reports the same `database_auth_invalid` errors for the checks it shares. `wardby quickstart` does not support `rds-iam`.
+
+See [Database authentication](../../docs/security-deployment.md#database-authentication).

package/help/errors/github-account-not-allowed.md

@@ -0,0 +1,25 @@
+---
+id: errors/github-account-not-allowed
+title: The repository's GitHub account is not served by this server
+summary: The repository belongs to a GitHub user or organization that is neither the GitHub App's owner nor listed in WARDBY_GITHUB_ALLOWED_ACCOUNTS, so wardby refuses to link or use it.
+audience: operator
+tags: [error, github, repositories, configuration, WARDBY_GITHUB_ALLOWED_ACCOUNTS, link_repository]
+appliesTo: ">=0.6.0"
+---
+
+# The repository's GitHub account is not served by this server
+
+`github_account_not_allowed` means the repository's owner is not one of the
+accounts this server serves through its GitHub App: the App's owner and the
+accounts in `WARDBY_GITHUB_ALLOWED_ACCOUNTS`. `link_repository` and coding
+profiles refuse such a repository, even with `adminOverride`, and runs on an
+existing link to it are refused.
+
+## What to do
+
+- **The repository should be served:** an operator adds its owner's login to
+  `WARDBY_GITHUB_ALLOWED_ACCOUNTS` and restarts the server, then links it again.
+- **It should not:** use a repository owned by a served account, or another
+  wardby server with its own GitHub App.
+
+Related: [Connect GitHub repositories](../github.md).

package/help/errors/low-power-disabled.md

@@ -0,0 +1,29 @@
+---
+id: errors/low-power-disabled
+title: Scale-down refused, mode not enabled
+summary: A request to put the coding proxy or native gateway to sleep was refused because WARDBY_LOW_POWER is not 1 on this deployment.
+audience: operator
+tags: [error, gke, kubernetes, low_power_disabled]
+appliesTo: ">=0.6.0"
+---
+
+# Sleep refused: low-power mode not enabled
+
+`low_power_disabled` (HTTP 409) means `power_sleep` was called, but low-power
+mode is not on for this deployment: `WARDBY_LOW_POWER` is not `1` on the
+control plane, or the control plane does not use `JOB_LAUNCHER=kubernetes` (it
+then logs `low_power_ignored` at start-up). Nothing was scaled.
+
+With the mode off, the coding proxy and native gateway always run, so there is
+nothing to put to sleep. `power_status` returns `{ "enabled": false }` in the
+same case.
+
+To turn the mode on:
+
+1. Deploy with the flag: `WARDBY_HOSTNAME=wardby.example.com WARDBY_LOW_POWER=1 deploy/gke/up.sh`.
+   On a local kind cluster, use `WARDBY_LOW_POWER=1 deploy/kind-coding/up.sh` and
+   also set `WARDBY_LOW_POWER=1` in the environment of `wardby serve`.
+2. Check that the control plane runs with `JOB_LAUNCHER=kubernetes`.
+3. Call `power_status`; it reports `"enabled": true` once the mode is on.
+
+See [Low-power mode on GKE](../low-power-mode.md).

package/help/errors/low-power-scale-forbidden.md

@@ -0,0 +1,35 @@
+---
+id: errors/low-power-scale-forbidden
+title: Scaling forbidden by RBAC
+summary: In low-power mode, the control plane is not allowed to read or scale the coding proxy or native gateway Deployment, or read its Endpoints, because the wardby-power Role is missing or out of date.
+audience: operator
+tags: [error, low-power, gke, kubernetes, rbac, low_power_scale_forbidden]
+appliesTo: ">=0.6.0"
+---
+
+# Low-power scale forbidden
+
+`low_power_scale_forbidden` means the Kubernetes API refused the control plane
+something low-power mode needs: reading or scaling the coding proxy or native
+gateway Deployment, or reading its Endpoints to see whether a woken target is
+ready. The message names the action and the object, for example
+`may not get Endpoints "wardby-native-gateway"`. It can come from a run waking a
+target, from `power_status`, or from `power_sleep`.
+
+Low-power mode needs the Role `wardby-power` (and its RoleBinding) in the
+namespace. It grants `get` and `patch` on the two Deployments and `get` on
+their Endpoints, by name. At start-up the control plane warns
+`low_power_scale_forbidden: missing ...` naming each missing permission (for
+example `get endpoints/wardby-native-gateway`); if the check itself fails it
+logs `low_power_access_check_failed`.
+
+1. Re-run the deploy with the mode on: `WARDBY_LOW_POWER=1 deploy/gke/up.sh`
+   (on kind, `WARDBY_LOW_POWER=1 deploy/kind-coding/up.sh`). It applies the
+   current Role, including the Endpoints rule an older Role may lack.
+2. Confirm: `kubectl -n wardby-coding describe role wardby-power` lists both
+   rules, and `kubectl -n wardby-coding get rolebinding wardby-power` exists.
+3. If you meant to turn the mode off, unset `WARDBY_LOW_POWER` on the control
+   plane too, then re-run `up.sh` without it.
+4. Trigger the run again.
+
+See [Low-power mode on GKE](../low-power-mode.md).