@wardby/cli 0.5.2 → 0.6.0

package/docs/getting-started-gke.md

@@ -3,6 +3,9 @@
 This is the supported Google Cloud deployment path for Wardby. It creates a
 GKE Autopilot cluster, Artifact Registry, private-IP Cloud SQL for PostgreSQL,
 isolated coding workers, an HTTPS Gateway, and the Wardby control plane.
+Before accepting production work, complete the
+[release verification](release-verification.md) and
+[security deployment](security-deployment.md) checks.
 
 The older `deploy/gcp` Cloud Run module is deprecated. New deployments should
 use `deploy/gke` and the `gke-autopilot` Kubernetes overlay described here.
@@ -14,7 +17,10 @@ use `deploy/gke` and the `gke-autopilot` Kubernetes overlay described here.
 ## Architecture
 
 - The Wardby control plane and coding proxy run in GKE Autopilot.
-- Each Codex coding run uses an ephemeral gVisor-backed pod.
+- Each Codex or Claude Code coding run uses an ephemeral gVisor-backed pod;
+  Claude Code adds a tool-runner sidecar in that pod.
+- Native agents set to sandbox mode run in single-use gVisor pods behind the
+  native gateway (see "Native sandbox" below).
 - Cloud SQL PostgreSQL has no public IP and is reached through private services
   access on the cluster's VPC.
 - Runtime, migration, and worker images are stored in Artifact Registry and
@@ -176,6 +182,34 @@ seeded: add it to the control plane's `env` in
 `deploy/kind-coding/manifests/overlays/gke-autopilot/control-plane.yaml` if you
 need it.
 
+To post [workflow notifications to Slack](slack-notifications.md), also add the
+Slack app's bot token. This requires Wardby 0.6.0 or later. It is optional:
+
+```dotenv
+WARDBY_SLACK_BOT_TOKEN="xoxb-..."
+```
+
+When it is in Secret Manager, `up.sh` syncs it into a separate Secret,
+`wardby-slack-env`, that only the control plane reads; when it is not, it
+leaves that Secret out and Slack stays off. `WARDBY_SLACK_CUSTOMIZE` and
+`WARDBY_SLACK_API_BASE_URL` are not secrets and are not seeded: add them to the
+control plane's `env` in the same `control-plane.yaml` if you need them. If you
+later remove the bot token, remove these two entries too: the control plane
+refuses to start with either one set and no token.
+
+`WARDBY_GITHUB_ALLOWED_ACCOUNTS` (optional, not a secret) adds GitHub accounts
+the App serves besides its owner. Pass it to `up.sh` on every run, for example
+`WARDBY_GITHUB_ALLOWED_ACCOUNTS=acme-labs WARDBY_HOSTNAME=app.example.com deploy/gke/up.sh`;
+a run without it serves only the App's owner. See
+[Which accounts the App serves](code-review-agents.md#which-accounts-the-app-serves-wardby_github_allowed_accounts).
+
+`WARDBY_MOBILE_ENABLED=true` (optional, not a secret) lets the Wardby mobile app
+sign in to the self-hosted OAuth server. Pass it to `up.sh` on every run, the
+same way as `WARDBY_GITHUB_ALLOWED_ACCOUNTS`; a run without it turns mobile
+sign-in off. It works for normal and low-power deploys. White-label builds that
+use their own redirect URI add `WARDBY_MOBILE_REDIRECT_URI` to the control
+plane's `env` themselves. See the help article `mobile-app`.
+
 Generate `SECRET_APP_KEY` with:
 
 ```sh
@@ -189,6 +223,13 @@ on. A value already in Secret Manager is never overwritten, so after the first
 deployment Secret Manager is the source of truth. You can then remove the
 production values from `.env.local`.
 
+External Secrets Operator runs as three small pods in the `external-secrets`
+namespace. `deploy/gke/eso-values.yaml` requests 100m CPU and 256 MiB of
+memory for each (memory limited to the same), because Autopilot bills a pod
+that requests nothing at 500m CPU and 2 GiB. If one is ever restarted for
+exceeding its memory limit, raise the limit and request together in that file
+and re-run `up.sh`; the Secrets it already synced are unaffected.
+
 Redeploying onto a cluster that already runs Wardby carries its existing
 `SECRET_APP_KEY` and login signing keys over, so stored credentials still
 decrypt and nobody has to sign in again.
@@ -249,9 +290,20 @@ The deployment script is idempotent. It converges Terraform, builds and pushes
 renders the GKE overlay, and waits for the proxy and control plane:
 
 ```sh
-HOSTNAME=wardby.example.com deploy/gke/up.sh
+WARDBY_HOSTNAME=wardby.example.com deploy/gke/up.sh
 ```
 
+Set `WARDBY_HOSTNAME`, not `HOSTNAME`: shells set `HOSTNAME` to the machine's own
+name, so the script no longer reads it. It refuses a hostname with no dot, or a
+local name such as `*.lan`, `*.local`, or `*.internal`. If you deployed with an
+earlier version using `HOSTNAME=...`, pass the same value as `WARDBY_HOSTNAME`.
+
+If the cluster is already published on a different hostname, the script stops
+before building anything: moving the hostname breaks DNS, every client's
+configured endpoint, and every issued token. In a terminal it asks you to type
+the new hostname; elsewhere, set `WARDBY_HOSTNAME_CHANGE` to the new hostname to
+confirm the move.
+
 Point the hostname's public A record at the reserved address:
 
 ```sh
@@ -275,11 +327,12 @@ 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`/`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                                                                                  |
+| 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` |
+| Native gateway | `<name_prefix>-gateway`  | `wardby-native-gateway`    | Member of `wardby_app`: the same data access as the control plane, under its own login (see [Native sandbox](#native-sandbox))                                                                  |
+| 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
@@ -296,10 +349,16 @@ SQL Admin API, uses that password once to apply the grants, and resets it to
 a value nobody holds on every exit, including a failed grant. No password is
 ever stored, printed, or passed as a process argument.
 
+A deployment that already runs and then gains the native gateway identity from
+`terraform apply` runs `deploy/gke/bootstrap-database-iam.sh` once, so the
+gateway's user gets its `wardby_app` membership, and then `deploy/gke/up.sh`.
+`up.sh`'s database check also tests the native gateway and says so if the
+grant is missing.
+
 A brand-new project runs, in this order:
 
 1. `terraform -chdir=deploy/gke apply` — creates the cluster, the instance
-   and the three IAM database users. Run it yourself rather than through
+   and the four IAM database users. Run it yourself rather than through
    `up.sh`, which would go on to the migrations before the migrator has its
    grants.
 2. `deploy/gke/bootstrap-database-iam.sh` (default mode) — fetches the
@@ -568,6 +627,160 @@ it, set `replicas: 0` in
 A PriorityClass's value and preemption policy cannot be changed in place:
 delete the class and re-run `up.sh` to change them.
 
+### Native sandbox
+
+Native sandbox requires Wardby 0.5.4 or later.
+
+`up.sh` deploys everything the [native sandbox](native-sandbox.md) needs on
+this cluster. It builds and pushes the `native-worker` image, checks it (Node is
+present; `curl`, `wget`, `nc` and `ssh` are not), and pins it by digest as
+`NATIVE_SANDBOX_WORKER_IMAGE`. It syncs the gateway's ExternalSecret, rolls out
+`wardby-native-gateway`, waits for it, and checks its database round trip. The
+control plane is configured with `NATIVE_SANDBOX_LAUNCHER=kubernetes`,
+`NATIVE_SANDBOX_CPUS=0.5`, `NATIVE_SANDBOX_MEMORY_MB=512`,
+`NATIVE_SANDBOX_MAX_CONCURRENT=4`, `NATIVE_SANDBOX_READY_TIMEOUT_MS=600000`
+(a cold gVisor node takes about two minutes), and
+`NATIVE_SANDBOX_ENFORCEMENT_TIMEOUT_MS=60000`. Worker pods use the gVisor runtime
+class, `KUBERNETES_PLATFORM=gke-autopilot`, and the run priority class.
+
+- **One-time bootstrap.** The gateway has its own database login. After
+  `terraform apply` adds its identity to an existing deployment, run
+  `deploy/gke/bootstrap-database-iam.sh` once, then `deploy/gke/up.sh`; see
+  [Database login](#database-login).
+- **Enable per agent.** Nothing runs in the sandbox until you opt an agent in:
+  set its `nativeExecutionMode` to `sandbox` with the `update_agent` MCP tool
+  (native agents only).
+- **Capacity.** At most `NATIVE_SANDBOX_MAX_CONCURRENT` sandbox runs are active
+  at once; a start past that fails with `native_sandbox_capacity` rather than
+  queuing. The `wardby-coding` ResourceQuota (26 pods, 11 CPU, 20Gi memory)
+  already covers the gateway's two replicas and that many 500m / 512Mi worker
+  pods. Raise the quota together with `NATIVE_SANDBOX_MAX_CONCURRENT` or
+  `CODING_MAX_CONCURRENT`.
+- **Warm pool.** To keep idle, already-isolated workers ready so runs skip pod
+  scheduling and the isolation probe, set `NATIVE_SANDBOX_WARM_POOL_SIZE` (0 to
+  50, default 0) in the control-plane manifest and raise the `wardby-coding`
+  ResourceQuota by that many 500m / 512Mi pods. Each idle worker is billed
+  continuously. See [Warm pool](native-sandbox.md#warm-pool).
+- **Check isolation.** `npm run test:native-cluster` runs launcher-only
+  isolation checks against the deployed gateway; set `NATIVE_TEST_WORKER_IMAGE`
+  to the worker digest and `NATIVE_TEST_FORBIDDEN` to the database's private
+  `host:port` (for example `10.0.0.5:3307`).
+- **Roll back.** Set an agent back to `control-plane` with `update_agent`; this
+  affects only new runs, and runs already started in sandbox mode finish there.
+  To undo a bad gateway release, run
+  `kubectl -n wardby-coding rollout undo deploy/wardby-native-gateway`.
+
+### Low-power mode
+
+Low-power mode requires Wardby 0.6.0 or later.
+
+Low-power mode cuts the idle cost of a deployment that runs agents only now and
+then. The coding proxy and the native gateway scale to zero replicas when
+nothing needs them, and wake on demand; the headroom placeholder is turned off;
+and the control plane runs 1 copy, scaling to 2 under load. The database and
+edge are unchanged.
+
+Turn it on by deploying with the flag:
+
+```sh
+WARDBY_HOSTNAME=wardby.example.com WARDBY_LOW_POWER=1 deploy/gke/up.sh
+```
+
+To turn it off, re-run `up.sh` without the flag. That removes the autoscaler
+(HorizontalPodAutoscaler `wardby-control-plane`) and the Role and RoleBinding
+`wardby-power`, and restores the normal sizes: proxy 1, gateway 2, headroom 1,
+control plane 1.
+
+| Variable                 | Where it is set                    | Values                          | Meaning                                                                                                                                                  |
+| ------------------------ | ---------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `WARDBY_LOW_POWER`       | `up.sh` environment; control plane | unset, `0` (off) or `1` (on)    | Anything else fails `up.sh` and stops the control plane at start-up. Needs `JOB_LAUNCHER=kubernetes`, else it logs `low_power_ignored` and does nothing. |
+| `LOW_POWER_IDLE_MINUTES` | Control-plane Deployment           | integer 5 to 1440, default `30` | How long a target must be unused before it sleeps. Read only when `WARDBY_LOW_POWER=1`.                                                                  |
+
+**Sleeping.** Every minute the scheduler leader scales the coding proxy
+(`wardby-coding-proxy`) to 0 when no coding run is pending or running and none
+finished within the idle window. It scales the native gateway
+(`wardby-native-gateway`) to 0 when no sandbox native run is pending, running or
+recently finished and the gateway has no active session. Either target sleeps
+only once at least one idle window has passed since it was last woken (recorded
+in its `wardby.io/power-woke-at` annotation) and since the control plane
+started, whichever is later. The condition is checked again immediately before
+scaling. The control plane
+logs `power: proxy slept (idle 30m)`.
+
+**Waking.** Starting a coding run scales the proxy to 1 and waits for a ready
+endpoint. Starting a sandbox run does the same for the gateway. The wait is at
+least 5 minutes, because a cold Autopilot node can add 1 to 2 minutes of
+start-up; a `KUBERNETES_READY_TIMEOUT_MS` (proxy) or
+`NATIVE_SANDBOX_READY_TIMEOUT_MS` (gateway) above 5 minutes, set on the
+control-plane Deployment, raises it to that value. The first coding run after a
+control-plane restart also runs the cluster preflight canary, because start-up
+preflight is deferred while the proxy sleeps (`kubernetes_preflight_deferred`).
+
+**Deploys.** Every `up.sh` run marks the proxy and gateway as just woken before
+it applies the manifests, which bring them back up. That includes a run that
+turns low-power mode off: the control plane being replaced still runs in
+low-power mode until its rollout ends, and the mark stops it scaling them back
+down. With the mode on they stay up through the deploy (its database checks
+need them) and sleep one idle window later if nothing uses them.
+
+**Sleeping now.** To skip the idle window (for example right after a test), an
+admin calls the MCP tool `power_sleep`, optionally with `target` set to `proxy`
+or `gateway` (default both). It scales the target to 0 at once, but never stops
+a run: a target with a pending or running run, or for the gateway an active
+gateway session, is left up and its run ids are returned under `blocked`.
+Recently finished runs do not block it. The next run wakes the target as usual.
+`power_status` shows each target's replicas, readiness, last wake time and
+blocking run ids. Both tools need the `power:manage` scope, which only the
+`admin` role grants; with the mode off, `power_sleep` fails with
+`409 low_power_disabled` and `power_status` returns `{ "enabled": false }`.
+Each `power_sleep` is logged as `event: "power.sleep"` with the caller's
+principal.
+
+**Control-plane autoscaling.** The control plane scales between 1 and 2 copies
+on CPU (20% target, scale-down after 10 minutes). A run executes on
+the copy that started it, so scheduled runs stay on the scheduler leader, while
+runs started by a webhook or over MCP spread across copies. While the mode is on
+the autoscaler owns the replica count, so do not set it by hand.
+
+**Trade-offs.**
+
+- Headroom is off, so the control plane has less protection against being
+  preempted when the cluster is short of capacity (see
+  [Pod priority and headroom](#pod-priority-and-headroom)).
+- The gateway runs 1 replica instead of 2 while awake, so there is no
+  redundancy.
+- `NATIVE_SANDBOX_WARM_POOL_SIZE` must be 0; the control plane refuses to start
+  otherwise, because a warm pool needs the gateway running.
+- The gateway must be in the same namespace as `KUBERNETES_NAMESPACE`.
+- The control plane needs the `wardby-power` Role: `get` and `patch` on the
+  proxy and gateway Deployments, and `get` on their Endpoints (to tell when a
+  woken target is ready). If any of it is missing, start-up warns
+  `low_power_scale_forbidden: missing ...` naming each permission, and waking,
+  `power_status` and `power_sleep` fail with that error; re-run `up.sh` with
+  the flag.
+
+**Cost.** Autopilot bills Pod requests while a Pod exists. The table uses
+us-central1 list prices of $0.0445 per vCPU-hour and $0.0049225 per GiB-hour and
+730 hours a month; substitute your region's current rates. Requests include the
+Cloud SQL sidecar.
+
+| Workload                     | Requests per replica  | Per hour | Per month, always on | In low-power mode                       |
+| ---------------------------- | --------------------- | -------- | -------------------- | --------------------------------------- |
+| Control plane                | 1.1 vCPU / 2.125 GiB  | $0.0594  | $43.37               | 1 copy always; $0.0594/h per extra copy |
+| Coding proxy                 | 1.1 vCPU / 3.125 GiB  | $0.0643  | $46.96               | $0.0643/h only while awake              |
+| Native gateway (per replica) | 0.35 vCPU / 0.625 GiB | $0.0187  | $13.62 (x2 = $27.23) | 1 replica, $0.0187/h only while awake   |
+| Headroom placeholder         | 0.25 vCPU / 0.5 GiB   | $0.0136  | $9.92                | $0                                      |
+
+With the mode off, those four workloads cost about $127.48 a month at these
+rates. In low-power mode the control plane is still always on, and a fully
+awake moment costs about $0.142 an hour for one control-plane copy, the proxy
+and one gateway replica. Your total depends on how many hours the proxy and
+gateway stay awake. Cloud SQL, the static address, load balancer, Cloud Armor
+and any other always-on component are unchanged.
+
+For error codes and log lines, see the
+[low-power mode help article](../help/low-power-mode.md).
+
 ### Coding-run services
 
 A coding run whose agent allows [services](coding-services.md) waits for each
@@ -587,6 +800,7 @@ before. `up.sh` prints the previous digests at the end of every deploy.
 ```sh
 kubectl -n wardby-coding rollout undo deploy/wardby-control-plane
 kubectl -n wardby-coding rollout undo deploy/wardby-coding-proxy
+kubectl -n wardby-coding rollout undo deploy/wardby-native-gateway
 ```
 
 `rollout undo` restores only the Deployments' images and pod templates — there
@@ -623,7 +837,9 @@ kubectl -n wardby-coding rollout restart deploy/wardby-coding-proxy deploy/wardb
 
 For a Jira setting, add the version to its `wardby-jira-*` secret, wait on
 `wardby-jira-env` instead, and restart only `deploy/wardby-control-plane`.
-Rotate the token and its `jira-api-token-expires-at` together.
+Rotate the token and its `jira-api-token-expires-at` together. The Slack bot
+token works the same way: add the version to `wardby-slack-bot-token`, wait on
+`wardby-slack-env`, and restart only `deploy/wardby-control-plane`.
 
 Pods read their environment only at start, hence the restart. The LLM API
 keys and the database URL are read by both Deployments; the other secrets only

package/docs/getting-started-identity-provider.md

@@ -70,9 +70,10 @@ Create these scopes in the provider:
 | `memory:write`        | Set and delete agent memory entries.                               |
 | `admin:view`          | Read every owner's runs through the admin viewer API; admins only. |
 | `models:admin`        | Add, override, disable and reset model catalog entries.            |
+| `power:manage`        | Read low-power state and sleep the proxy/gateway now; admins only. |
 
 MCP clients discover this list from Wardby's protected-resource metadata and
-may request every advertised scope. Define all fourteen in the provider even when
+may request every advertised scope. Define all fifteen in the provider even when
 policy grants a particular client or user only a subset. Ensure granted scopes
 are emitted in the access token's `scope` or `scp` claim; defining them only in
 the provider UI is not sufficient.
@@ -92,17 +93,21 @@ otherwise clients that request every advertised scope fail with `invalid_scope`.
 deployment, define it in the provider too; otherwise clients that request
 every advertised scope fail with `invalid_scope`.
 
+`power:manage` was added after `models:admin`. When you upgrade an existing
+deployment, define it in the provider too and map it like `agents:admin`;
+otherwise clients that request every advertised scope fail with `invalid_scope`.
+
 ### Wardby roles
 
 A scope only delegates. `agents:admin`, `packages:approve`, `services:manage`,
-`admin:view` and `models:admin` take effect only for a caller who also holds a Wardby role that grants them:
+`admin:view`, `models:admin` and `power:manage` take effect only for a caller who also holds a Wardby role that grants them:
 
-| Wardby role        | Grants                                                                                                                                                                                                    |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve`, `services:manage`, `admin:view` (read every owner's runs, see [viewer-api.md](viewer-api.md)) and `models:admin` (model catalog) |
-| `package-approver` | `packages:approve` (package allowlist and policy approval)                                                                                                                                                |
-| `service-manager`  | `services:manage` (coding-run service catalog changes)                                                                                                                                                    |
-| `model-manager`    | `models:admin` (model catalog changes: `set_model`, `disable_model`, `reset_model`; see [models.md](models.md))                                                                                           |
+| Wardby role        | Grants                                                                                                                                                                                                                                                                                                                         |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `admin`            | `agents:admin` (`make_owner`, BYO `workerImageRef`), `packages:approve`, `services:manage`, `admin:view` (read every owner's runs, see [viewer-api.md](viewer-api.md)), `models:admin` (model catalog) and `power:manage` (`power_status`, `power_sleep`; see [getting-started-gke.md](getting-started-gke.md#low-power-mode)) |
+| `package-approver` | `packages:approve` (package allowlist and policy approval)                                                                                                                                                                                                                                                                     |
+| `service-manager`  | `services:manage` (coding-run service catalog changes)                                                                                                                                                                                                                                                                         |
+| `model-manager`    | `models:admin` (model catalog changes: `set_model`, `disable_model`, `reset_model`; see [models.md](models.md))                                                                                                                                                                                                                |
 
 The roles come from a claim in the caller's **access token**, which you map to
 Wardby roles:
@@ -162,7 +167,7 @@ Provider examples:
   to the access token, filtered to those groups. Set `AUTH_ROLE_CLAIM=groups` and
   `AUTH_ROLE_MAP=wardby-admin=admin,wardby-packages=package-approver,wardby-services=service-manager,wardby-models=model-manager`.
   Optionally, add access policy rules so only those groups can obtain
-  `agents:admin`, `packages:approve`, `services:manage`, `admin:view` and `models:admin`.
+  `agents:admin`, `packages:approve`, `services:manage`, `admin:view`, `models:admin` and `power:manage`.
 - **FusionAuth:** create four application roles, `admin`,
   `package-approver`, `service-manager` and `model-manager`. They appear in the
   access token's top-level `roles` claim. Set `AUTH_ROLE_CLAIM=roles` and
@@ -188,6 +193,11 @@ that case, register the MCP client manually as a **public/native application**:
 - register the client's exact loopback callback URI; and
 - allow it to request the Wardby audience and scopes.
 
+To let the Wardby mobile app sign in, also register its private-use redirect
+URI, `com.wardby.mobile:/oauth` (or your white-label build's redirect, such as
+`com.example.app:/oauth`), as an allowed redirect URI on the IdP client that
+requests `admin:view`. Wardby needs no setting for this in delegating mode.
+
 For Claude Code, a fixed callback port makes the redirect URI predictable:
 
 ```sh
@@ -253,7 +263,7 @@ Confirm that:
 
 - `resource` is the canonical MCP URI;
 - `authorization_servers` contains the external issuer; and
-- `scopes_supported` contains all fourteen Wardby scopes.
+- `scopes_supported` contains all fifteen Wardby scopes.
 
 An unauthenticated MCP request must return `401` with a `WWW-Authenticate`
 challenge pointing back to that metadata document.
@@ -310,6 +320,7 @@ test procedure and cleanup.
 | Wardby returns `403 insufficient_scope`       | The token is valid but `scope`/`scp` lacks the operation's required permission.      |
 | Client registration returns `403`             | Anonymous dynamic registration is disabled; pre-register a public client.            |
 | Browser flow rejects the redirect             | The provider's registered loopback callback does not exactly match the client.       |
+| Mobile sign-in fails with a redirect error    | The IdP client doesn't list the mobile redirect URI.                                 |
 | Wardby cannot validate any newly issued token | The control plane cannot reach the JWKS URI, or provider key rotation is incomplete. |
 | One person appears as multiple principals     | The provider is emitting different or pairwise `sub` values for different clients.   |
 

package/docs/getting-started.md

@@ -49,11 +49,12 @@ The quickstart's sample agent is a native agent: it calls a model and nothing
 else. To have agents write code or review it, pick the path that matches what
 you have:
 
-| You want                                          | You need                                                           | Path                                              |
-| ------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------- |
-| A coding agent and a review agent, tried locally  | Docker, an OpenAI **or** Anthropic key, a git repository on disk   | [A](#path-a-local-repository-no-github-app)       |
-| A coding agent that opens pull requests on GitHub | Path A's setup, plus a GitHub App installed on the repository      | [B](#path-b-coding-agent-on-a-github-repository)  |
-| A review agent that reviews GitHub pull requests  | A GitHub App with webhooks, and Wardby reachable over public HTTPS | [C](#path-c-review-agent-on-github-pull-requests) |
+| You want                                                | You need                                                           | Path                                               |
+| ------------------------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------- |
+| A coding agent and a review agent, tried locally        | Docker, an OpenAI **or** Anthropic key, a git repository on disk   | [A](#path-a-local-repository-no-github-app)        |
+| A coding agent that opens pull requests on GitHub       | Path A's setup, plus a GitHub App installed on the repository      | [B](#path-b-coding-agent-on-a-github-repository)   |
+| A review agent that reviews GitHub pull requests        | A GitHub App with webhooks, and Wardby reachable over public HTTPS | [C](#path-c-review-agent-on-github-pull-requests)  |
+| A coding agent for a language other than Node or Python | Path A's setup with Codex, and Docker to build an image            | [D](#path-d-another-language-build-your-own-image) |
 
 Codex agents need only an OpenAI key and Claude Code agents only an Anthropic
 key; you don't need both.
@@ -70,7 +71,10 @@ key; you don't need both.
    Or run plain `quickstart` and answer **yes** to "Set up coding + review
    agents against a local git repo?". It asks for Codex or Claude Code, pulls
    only that provider's images, starts the coding proxy, and creates two agents:
-   `local-builder` (writes code) and `local-reviewer` (reviews it).
+   `local-builder` (writes code) and `local-reviewer` (reviews it). If the
+   repository is a Python project, the builder gets a Node + Python 3.12
+   workspace so it can run the project's tests (see
+   [Python projects](#python-projects)).
 
 2. Ask your MCP client (the quickstart can register Wardby with Codex or Claude
    Code) to run the builder. The quickstart prints the exact call, for example:
@@ -153,6 +157,27 @@ or another host with a public URL.
 To try reviews before you have a public URL, use path A's `local-reviewer` on
 any local branch.
 
+### Path D: another language: build your own image
+
+Wardby's worker images have Node, or Node and Python 3.12. For a Go, Java, Rust
+or other project, build a worker image with that toolchain on Wardby's driver
+base image, and point the builder at it with `codingProfile.workerImageRef`.
+These steps are for a **Codex** builder. For a Claude Code builder, the image
+starts from Wardby's tool runner image instead; see
+[Codex and Claude Code](coding-worker-byo-images.md#codex-and-claude-code).
+
+1. Complete path A with Codex (`--coding-provider codex`).
+2. Run `npx @wardby/cli@latest doctor`. It prints the base image to build on:
+   "Base image for your own worker images: …@sha256:…".
+3. Write and build the Dockerfile as described in
+   [Bring-your-own worker images](coding-worker-byo-images.md), then set the
+   builder's `codingProfile.workerImageRef` with `update_agent` to the image's
+   local ID (`docker image inspect --format '{{.Id}}' <image>`).
+
+Your MCP assistant can do these steps for you: ask it "Help me build a Wardby
+worker image for Go" (or your language). It follows the `build-worker-image`
+help article, checks the image, and runs a test task with it.
+
 ## Unattended setup
 
 Automation must explicitly accept the billed demo with `--yes`:
@@ -261,7 +286,10 @@ This step needs Docker, and an `OPENAI_API_KEY` (Codex) or `ANTHROPIC_API_KEY`
    `CODING_CLAUDE_TOOL_RUNNER_IMAGE`, to use images of your own;
 3. starts the coding proxy and runs the coding preflight;
 4. creates `local-builder` (a coding agent, $2 budget) and `local-reviewer` (a
-   review agent, $1 budget) for a repository in the trusted folders (a trusted
+   review agent, $1.50 budget, on Claude Sonnet 5 or `gpt-5.6-terra` by default:
+   a step above the builder's model, so a review costs more per call but stays
+   within its budget; `--model` does not change it: change it with
+   `update_agent` — a quickstart re-run resets it) for a repository in the trusted folders (a trusted
    folder that is a git repository, or one directly inside it; with several,
    quickstart asks, or non-interactively uses the first in sorted order and
    prints it. Re-run with `--trust <repo>` to choose another: folders passed on
@@ -270,6 +298,14 @@ This step needs Docker, and an `OPENAI_API_KEY` (Codex) or `ANTHROPIC_API_KEY`
    other asks `local-reviewer` to review the branch `wardby/run-<run id>` the
    run pushed into your repository.
 
+`local-reviewer` uses a thorough, repository-agnostic review prompt: it checks
+correctness, security against the OWASP Top 10, performance, duplication,
+modularity, AI-generated slop, code quality, test coverage and process, cites
+your `docs/knowledge/` concepts when you have them, and ends with APPROVE or
+CHANGES_REQUESTED. The prompt is quoted in the `architecture-agent` help
+article. A re-run of quickstart moves a reviewer created by an earlier version
+onto it; a `local-reviewer` you changed yourself is left alone.
+
 **Trust model.** Wardby only touches repositories inside the folders you trust.
 Agents see committed history only: untracked files such as `.env.local` never
 leave your machine. A run never changes your working tree or the branch you have
@@ -284,6 +320,79 @@ branch" for these agents is the branch checked out when quickstart runs. If the
 repository already has a services file, quickstart prints what it declares, or
 why it is invalid.
 
+#### Python projects
+
+Quickstart reads the committed root of the repository (never your working tree)
+and treats it as a Python project when it holds `pyproject.toml`, `setup.py`,
+`setup.cfg`, `Pipfile` or a `requirements*.txt` file. For a Python project it
+prepares the Node + Python 3.12 workspace image for the provider you chose
+(`toolchain: node-python`, version `3.12`) and creates `local-builder` on it, for
+both Codex and Claude Code. The builder can then run the project's tests:
+`pytest` and `ruff` are installed. Quickstart prints
+"Python project detected: local-builder uses a Node + Python 3.12 workspace".
+
+The image is recorded in `.wardby/.env`. To use your own build of it, set the
+variable for your provider to an immutable digest (`repo@sha256:...`) or a local
+image id before running quickstart:
+
+| Provider    | Variable                                           |
+| ----------- | -------------------------------------------------- |
+| Codex       | `CODING_WORKER_IMAGE_NODE_PYTHON_3_12`             |
+| Claude Code | `CODING_CLAUDE_TOOL_RUNNER_IMAGE_NODE_PYTHON_3_12` |
+
+If your wardby version ships no Python workspace image, quickstart prints
+"Python project detected, but this version has no Python workspace image" and
+creates the builder on the default Node workspace: it can edit code but not run
+Python tests. Upgrade, or set the variable above.
+
+Other languages (Go, Rust, Java and so on) are not detected. Use a
+bring-your-own image through `workerImageRef`; see
+[Path D](#path-d-another-language-build-your-own-image) and
+[Bring-your-own worker images](coding-worker-byo-images.md), for Codex or
+Claude Code.
+
+#### Packages the repository declares
+
+Coding agents can install only the packages on their allowlist (see
+[Installing packages in coding runs](coding-packages.md)), and a new agent's
+allowlist is empty. So that `local-builder` can install the project's
+dependencies, quickstart reads the ones the repository declares at the root of
+the same commit (never your working tree):
+
+- `package.json`: `dependencies`, `devDependencies` and `optionalDependencies`
+  (not peer dependencies) for npm;
+- `pyproject.toml`: `[project] dependencies`, every
+  `[project.optional-dependencies]` group, `[tool.poetry.dependencies]`,
+  Poetry's dependency groups and the legacy `[tool.poetry.dev-dependencies]`
+  for PyPI, plus the packages pip needs to build the project:
+  `[build-system] requires` (such as `setuptools`, `hatchling` or
+  `poetry-core`), or `setuptools` and `wheel` when the file has no
+  `[build-system]` table (pip then uses the legacy setuptools backend);
+- every `requirements*.txt` for PyPI. Options such as `-r`, `-c` and `-e`,
+  URLs and local paths are skipped; an included file (`-r other.txt`) is not
+  followed.
+
+It keeps package names without versions (a Python requirement keeps the extras
+it names, such as `psycopg[binary]`, so the packages those extras add can be
+installed too), drops names that are not valid in their ecosystem, and skips non-registry sources (`file:`, `git`, URL and
+path dependencies). It prints the counts and up to a dozen names, then asks
+"Allow local-builder to install these packages through Wardby's registry?
+[Y/n]". The allowed names go on the builder's `codingProfile.packageAllowlist`.
+Versions still come from your lockfile or the package manager's resolver, and
+every registry safeguard (release age, advisories, the record of what was
+fetched) still applies.
+
+- More than 200 names in one ecosystem: quickstart adds none from it and says
+  why.
+- A manifest it cannot read (an unusual `pyproject.toml` layout, for example):
+  it prints a one-line note and skips that file.
+- Answering no, or a `--non-interactive` run without `--allow-repo-packages`,
+  leaves the allowlist empty. Add packages later with `update_agent` and
+  `codingProfile.packageAllowlist`.
+- A re-run sets an existing quickstart `local-builder`'s allowlist to what the
+  repository declares now (or empty if you decline), replacing entries you
+  added by hand.
+
 Options for unattended use:
 
 ```sh
@@ -291,7 +400,8 @@ OPENAI_API_KEY="..." npx --yes @wardby/cli@latest quickstart \
   --non-interactive --yes \
   --coding --trust ~/projects/my-repo \
   --coding-provider codex \
-  --starter-services postgres
+  --starter-services postgres \
+  --allow-repo-packages
 ```
 
 - `--coding` runs the step without asking and `--no-coding` skips it. With
@@ -301,6 +411,9 @@ OPENAI_API_KEY="..." npx --yes @wardby/cli@latest quickstart \
 - `--coding-provider codex|claude-code` picks the coding agent; by default it
   uses the provider whose key is available.
 - `--starter-services postgres,redis|none` answers the starter-file question.
+- `--allow-repo-packages` allows the repository's declared packages without
+  asking; `--no-allow-repo-packages` allows none. Non-interactive runs allow
+  none unless the flag is given.
 
 `doctor` and `status` then also report the trusted folders, the worker image,
 the coding proxy, and each local agent's repository, and `down` stops the proxy
@@ -319,9 +432,25 @@ and need the GitHub App, worker image, and job launcher from
 [Coding-agent setup](coding-agent-setup.md). Their event triggers need GitHub to
 reach your instance at a public HTTPS URL.
 
-The assistant the quickstart connected can walk you through either recipe. Ask it
-"Set up the Wardby architecture keeper for this repository" or "Set up a Wardby
-builder for this repository"; it follows the `agent-recipes` help article.
+The quickstart ends with a short menu of things to ask the assistant it
+connected, each with the help article the assistant follows:
+
+1. "Run local-builder with a task, then have local-reviewer review the branch"
+   (`local-repositories`; shown only when the coding step ran).
+2. "Let local-builder install more packages" (`coding-packages`).
+3. "Help me build a Wardby worker image for Go (or Java, Rust…)"
+   (`build-worker-image`).
+4. "Set up a scheduled Wardby agent" (`creating-agents`).
+5. "Set up a Wardby architecture reviewer and keeper for this repo"
+   (`architecture-agent`, which has a local-repository variant).
+6. "Help me plan out a GKE deployment" (`deploy-gke` and
+   `deployment-targets`).
+
+Without an MCP client, read an article with
+`npx @wardby/cli@latest help open <article>`. The GitHub setups above are not
+in the menu; ask for one directly, for example "Set up the Wardby architecture
+keeper for this repository", and the assistant follows the `agent-recipes`
+help article.
 
 ## Next steps
 

package/docs/jira-agents.md

@@ -24,7 +24,7 @@ Jira Cloud only. One Jira site per wardby deployment.
   properties are not allowlisted.
 - **Status comments.** When an event starts a run, wardby posts a short
   "working on it" comment on the issue and edits it with the outcome when the
-  run ends, including a line such as `Agent spend: $0.0123` for the run and
+  run ends, including a line such as `Agent spend: $0.012` for the run and
   its direct sub-runs. That one comment is the reply: when the run succeeds
   it shows the agent's final answer, so the agent is told not to post the
   answer again with `jira_comment` (it uses `jira_comment` only for other
@@ -478,6 +478,10 @@ What happens:
   [`code-review-agents.md`](code-review-agents.md)). Without them the pull
   request is still linked, but the issue is not updated on merge.
 
+To mirror this lifecycle in Slack — picked up, pull request open, review
+verdict, merge — link a channel to the project or agent; see
+[Send workflow updates to Slack](slack-notifications.md).
+
 ## Recipe: scheduled JQL sweeps
 
 An agent linked to a project can also run on a schedule with no issue event:

package/docs/knowledge.md

@@ -366,6 +366,17 @@ Reply with one line: what you started and why, or "No action: <reason>".
 If the delegate call returns a failure, reply with a line beginning FAILED:.
 ```
 
+## Architecture agents on a local repository
+
+For a `local:` repository (no GitHub App), such as the one the quickstart's
+coding step sets up, the `architecture-agent` help article has a "Local
+repository (no GitHub App)" section: the keeper is a scheduled coding agent
+whose runs push knowledge updates to `wardby/run-<run id>` branches, and the
+reviewer is a native agent linked with `link_repository` (`provider: "local"`)
+that you start with `trigger_agent` and `review: {branch}`. There is no merge
+watcher (the `push` trigger needs GitHub), and the schedule fires only while a
+Wardby scheduler (`wardby scheduler` or `wardby serve`) is running.
+
 ## Reviewer step
 
 Add this section to the system prompt of a code-review agent (see