@wardby/cli 0.5.3 → 0.6.0

package/help/errors/low-power-wake-timeout.md

@@ -0,0 +1,30 @@
+---
+id: errors/low-power-wake-timeout
+title: Wake timed out (scale to zero)
+summary: When scaling from zero, the coding proxy or native gateway did not become ready after being scaled up, or its Deployment does not exist.
+audience: operator
+tags: [error, low-power, gke, kubernetes, scale-to-zero, low_power_wake_timeout]
+appliesTo: ">=0.6.0"
+---
+
+# Low-power wake timed out
+
+`low_power_wake_timeout` means a run needed the coding proxy (or, for a sandbox
+run, the native gateway), Wardby scaled it from 0 to 1, and no ready endpoint
+appeared within the bound. The bound is 5 minutes, or
+`KUBERNETES_READY_TIMEOUT_MS` for the proxy and
+`NATIVE_SANDBOX_READY_TIMEOUT_MS` for the gateway when that is higher. It is
+also raised when the target Deployment does not exist.
+
+1. Check the Deployment exists: `kubectl -n wardby-coding get deploy wardby-coding-proxy wardby-native-gateway`
+   (names follow `KUBERNETES_PROXY_SERVICE` and `NATIVE_GATEWAY_SERVICE`). If
+   one is missing, re-run `deploy/gke/up.sh`.
+2. If it exists, look at why its Pod is not ready: `kubectl -n wardby-coding describe pod -l app.kubernetes.io/name=wardby-coding-proxy`.
+   A cold Autopilot node can take 1 to 2 minutes; unschedulable Pods, image
+   pull errors or a failing sidecar are the usual causes.
+3. If the node is simply slow, raise the timeout for that target above 5
+   minutes (300000): set `KUBERNETES_READY_TIMEOUT_MS` (proxy) or
+   `NATIVE_SANDBOX_READY_TIMEOUT_MS` (gateway) on the control-plane Deployment.
+4. Trigger the run again.
+
+See [Low-power mode on GKE](../low-power-mode.md).

package/help/errors/mobile-disabled.md

@@ -0,0 +1,31 @@
+---
+id: errors/mobile-disabled
+title: Mobile sign-in is not enabled
+summary: The server refused the mobile app's sign-in or registration because WARDBY_MOBILE_ENABLED is not true.
+audience: operator
+tags: [error, mobile, sign-in, oauth, mobile_disabled, WARDBY_MOBILE_ENABLED]
+appliesTo: ">=0.6.0"
+---
+
+# Mobile sign-in is not enabled
+
+Mobile sign-in is switched off. An operator turns it on with
+`WARDBY_MOBILE_ENABLED`.
+
+Only client registration returns the reason: `400 invalid_redirect_uri` with the
+description `mobile_disabled: mobile sign-in is not enabled on this server
+(WARDBY_MOBILE_ENABLED)`. Sign-in (authorize) and token refresh return the
+generic `invalid_request` or `invalid_grant` with an `id`. The `mobile_disabled`
+reason appears only in the control-plane log line "self-hosted OAuth request
+rejected" for that `id`, so look the `id` up in the control-plane logs.
+
+1. Set `WARDBY_MOBILE_ENABLED=true` on the control plane and restart it. On GKE,
+   redeploy with `WARDBY_MOBILE_ENABLED=true` passed to `deploy/gke/up.sh`; a
+   run without it turns mobile sign-in off again.
+2. If you use a white-label build, check that `WARDBY_MOBILE_REDIRECT_URI`
+   matches the redirect URI the app uses.
+3. Sign in again from the app.
+
+With an external identity provider this error does not come from Wardby; check
+that the IdP client lists the mobile redirect URI. See
+[Use the wardby mobile app](../mobile-app.md).

package/help/errors/native-sandbox-capacity.md

@@ -0,0 +1,22 @@
+---
+id: errors/native-sandbox-capacity
+title: Native sandbox is at capacity
+summary: A sandbox run could not start because the concurrent sandbox run limit or the namespace ResourceQuota has no room; the run failed at start and was not queued.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, capacity, quota, native_sandbox_capacity]
+appliesTo: ">=0.5.4"
+---
+
+# Native sandbox is at capacity
+
+`native_sandbox_capacity` means a sandbox-mode run could not start because there was no room for it. The run failed at start; it is not queued. The message gives one of two reasons:
+
+- **"N sandbox runs are already active (NATIVE_SANDBOX_MAX_CONCURRENT)"**: the cap on concurrent sandbox runs, counted across all server replicas as active gateway sessions, has been reached.
+- **"the namespace's ResourceQuota has no room for another native worker pod"**: with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, the run namespace's quota on pods, CPU, or memory is full.
+
+1. Wait for running sandbox runs to finish, then trigger the run again.
+2. To allow more at once, raise `NATIVE_SANDBOX_MAX_CONCURRENT` (unset means no cap) and raise the namespace ResourceQuota with it. Each worker pod needs its CPU and memory limits (`NATIVE_SANDBOX_CPUS`, `NATIVE_SANDBOX_MEMORY_MB`) from the quota, which coding runs and the gateway share. Idle warm-pool workers (`NATIVE_SANDBOX_WARM_POOL_SIZE`) take quota too, so leave room for `NATIVE_SANDBOX_MAX_CONCURRENT` plus the pool size.
+3. Check current usage with `kubectl describe resourcequota -n <namespace>` and `kubectl get pods -n <namespace> -l wardby.io/component=native-run`.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-deadline-exceeded.md

@@ -0,0 +1,19 @@
+---
+id: errors/native-sandbox-deadline-exceeded
+title: Native run deadline exceeded
+summary: A sandbox run passed its 60-minute maximum lifetime and its worker was stopped.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_deadline_exceeded]
+appliesTo: ">=0.5.4"
+---
+
+# Native run deadline exceeded
+
+`native_sandbox_deadline_exceeded` means the run was still going when it reached the sandbox's maximum lifetime of 60 minutes, so the worker was stopped and the run failed. The limit protects against stuck runs and is not configurable.
+
+1. Look for a tool that waits forever or a loop that does not converge.
+2. Split long work into smaller runs, or delegate parts to sub-agents (each is its own run).
+3. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-docker-failed.md

@@ -0,0 +1,20 @@
+---
+id: errors/native-sandbox-docker-failed
+title: Native worker Docker command failed
+summary: A Docker command Wardby ran to start or clean up a sandbox worker failed.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_docker_failed]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker Docker command failed
+
+`native_sandbox_docker_failed` means a Docker command needed to launch a worker (pull the image, create the run network, join the gateway to it, or start the container) failed. The message names the step and includes Docker's error output.
+
+1. Confirm the server can reach the Docker daemon (`docker info` as the server's user).
+2. For an image step, confirm the image exists on the host (a local id must already be present; a digest must be pullable without registry credentials, or pull it beforehand).
+3. For a network step, confirm `NATIVE_GATEWAY_CONTAINER` names a running gateway container on this Docker host.
+4. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-gateway-unavailable.md

@@ -0,0 +1,21 @@
+---
+id: errors/native-sandbox-gateway-unavailable
+title: Native gateway Service unavailable
+summary: On Kubernetes, Wardby could not find a usable native gateway Service, so a sandbox run could not start.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, native_sandbox_gateway_unavailable]
+appliesTo: ">=0.5.4"
+---
+
+# Native gateway Service unavailable
+
+`native_sandbox_gateway_unavailable` means that with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, the Service named by `NATIVE_GATEWAY_SERVICE` (default `wardby-native-gateway`) does not exist in the sandbox namespace or has no ClusterIP. Workers dial the Service's ClusterIP, so Wardby needs one.
+
+1. Confirm the namespace: `NATIVE_SANDBOX_NAMESPACE`, else `KUBERNETES_NAMESPACE`, else `wardby-coding`.
+2. Create the Service there as a regular ClusterIP Service (not headless) that selects the gateway pods (`app.kubernetes.io/name: wardby-native-gateway`) and exposes both 8790 and the deny port 8791.
+3. Confirm the server's Role allows `get` on `services` in that namespace.
+4. Alternatively set `NATIVE_GATEWAY_URL` to an address workers can dial, and keep the gateway's NetworkPolicy and the workers' egress consistent with it.
+5. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-image-not-pinned.md

@@ -0,0 +1,19 @@
+---
+id: errors/native-sandbox-image-not-pinned
+title: Native worker image not pinned
+summary: NATIVE_SANDBOX_WORKER_IMAGE is a mutable tag, so Wardby refused to launch a sandbox worker.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_image_not_pinned]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker image not pinned
+
+`native_sandbox_image_not_pinned` means `NATIVE_SANDBOX_WORKER_IMAGE` is not immutable. Wardby only launches a worker from a digest (`repo@sha256:...`) or a local image id, so the code it isolates cannot change underneath it.
+
+1. Use the digest-pinned reference listed as `nativeWorker` in `dist/quickstart-images.json` for your version, or build locally with `npm run native-worker:image:local` and use the image id from `docker image inspect --format '{{.Id}}' wardby-native-worker:local`.
+2. On Kubernetes (`NATIVE_SANDBOX_LAUNCHER=kubernetes`) a local image id is not accepted: the image must be a registry digest, `repo@sha256:...`, that the cluster can pull. Push your build to a registry and use its digest.
+3. Set it as `NATIVE_SANDBOX_WORKER_IMAGE`, restart the server, and trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-isolation-mismatch.md

@@ -0,0 +1,20 @@
+---
+id: errors/native-sandbox-isolation-mismatch
+title: Native worker pod differs from what Wardby built
+summary: On Kubernetes, the sandbox pod or its NetworkPolicy as stored by the cluster differs from what Wardby created, so the run failed before starting.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, native_sandbox_isolation_mismatch]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker pod differs from what Wardby built
+
+`native_sandbox_isolation_mismatch` means that with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, Wardby read back the worker pod and NetworkPolicy it had just created and found a security-relevant difference: a service-account token, host networking, a different runtime class, priority class, image, container resources, or container security context or environment, an extra init container, or a changed NetworkPolicy. Something in the cluster modified the objects after creation, typically a mutating admission webhook, policy engine, or service mesh injector. The run is failed and the pod removed.
+
+1. Inspect an equivalent pod while a run is starting: `kubectl get pods -n <namespace> -l wardby.io/component=native-run -o yaml`.
+2. Find the admission controller that changes it (`kubectl get mutatingwebhookconfigurations`) and exempt pods labeled `wardby.io/component: native-run` and the run namespace's NetworkPolicies, for example by namespace or label selector. Do not disable sidecar-style injection by editing the pod after the fact.
+3. If `NATIVE_SANDBOX_RUNTIME_CLASS` or `NATIVE_SANDBOX_PRIORITY_CLASS` is set, confirm no policy overrides it. On GKE Autopilot set `KUBERNETES_PLATFORM=gke-autopilot` so pod resources are already in the form Autopilot admits and are not rewritten.
+4. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-network-unenforced.md

@@ -0,0 +1,22 @@
+---
+id: errors/native-sandbox-network-unenforced
+title: Native worker network isolation not proven
+summary: On Kubernetes, Wardby could not prove a sandbox pod's network isolation in time, so it removed the pod and failed the run.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, native_sandbox_network_unenforced]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker network isolation not proven
+
+`native_sandbox_network_unenforced` means that with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, Wardby ran a check inside the worker pod and it did not pass before the time limit. The check requires the gateway to be reachable on port 8790 while the gateway's deny port (8791 by default), an outside address, and the cloud metadata endpoints (`169.254.169.254:80`, the EKS Pod Identity agent `169.254.170.23:80` and `[fd00:ec2::23]:80`, and EC2's IPv6 metadata address `[fd00:ec2::254]:80`) are not. The message says which part failed. The pod is removed and the run never started.
+
+- **"the gateway was unreachable"**: confirm the gateway Deployment has ready pods, the `wardby-native-gateway` Service (or `NATIVE_GATEWAY_SERVICE`) exposes 8790 and 8791, and the gateway's own NetworkPolicy admits `wardby.io/component: native-run` pods on port 8790.
+- **"the gateway's deny port was reachable"** or **"an outside address was reachable"** (or a metadata endpoint): the cluster is not enforcing the per-run NetworkPolicy. Confirm your CNI enforces `NetworkPolicy` (some local clusters need a policy-capable CNI such as Calico), and that no other policy or mesh adds egress for these pods.
+- If the Service lacks port 8791, or the gateway's policy does not admit 8791, unprogrammed pods would look isolated. Keep both in place; the check depends on them.
+- On a slow node the policy can take longer to program. Retrigger the run once, or raise `NATIVE_SANDBOX_ENFORCEMENT_TIMEOUT_MS` (default 30000), before changing anything.
+
+A cluster that does not enforce NetworkPolicy fails every sandbox run this way, by design. Switch the agent back to `control-plane` if you cannot enable enforcement.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-requires-catalog.md

@@ -0,0 +1,31 @@
+---
+id: errors/native-sandbox-requires-catalog
+title: Sandbox run has no model catalog entry
+summary: A sandbox-mode run could not start because no model catalog entry was recorded for it.
+audience: operator
+tags: [error, native-agents, sandbox, model-catalog, native_sandbox_requires_catalog]
+appliesTo: ">=0.5.4"
+---
+
+# Sandbox run has no model catalog entry
+
+`native_sandbox_requires_catalog` means a sandbox-mode run reached its worker
+launch without a model catalog entry. The worker prices every model call and
+enforces the run's budget from that entry, so Wardby fails the run before
+starting a worker or spending anything.
+
+Every run records its model's catalog entry when it first starts. A model
+that is unknown, disabled, or has no configured provider fails earlier with
+its own model error, not this one. This error only appears when the process
+executing the run does not use Wardby's catalog-backed model router, for
+example a modified build or an embedding that supplies its own LLM provider.
+
+1. Run sandbox-mode agents on a standard `wardby serve` (or `wardby
+scheduler` / `wardby mcp`) process, which always uses the catalog.
+2. If you supply your own LLM provider, route it through the model catalog,
+   or keep the agent on `control-plane` with `update_agent` or
+   `wardby agent mode <name> control-plane`.
+3. Trigger the run again. A failed run is not retried on its own.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and
+[Models and the model catalog](../models.md).

package/help/errors/native-sandbox-unavailable.md

@@ -0,0 +1,19 @@
+---
+id: errors/native-sandbox-unavailable
+title: Native execution mode unavailable
+summary: A run failed with native_sandbox_unavailable because its agent is in sandbox mode but the server has no native sandbox configured.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_unavailable]
+appliesTo: ">=0.5.4"
+---
+
+# Native execution mode unavailable
+
+`native_sandbox_unavailable` means the agent's `nativeExecutionMode` is `sandbox` but this deployment has no native sandbox configured. Wardby fails the run before any spend rather than running it unisolated.
+
+1. To use the sandbox, set `NATIVE_SANDBOX_LAUNCHER=docker`, `NATIVE_SANDBOX_WORKER_IMAGE`, and `NATIVE_GATEWAY_CONTAINER` on the server that executes runs (`wardby serve` or `wardby scheduler`), start the native gateway, and restart the server.
+2. Otherwise set the agent back to `control-plane` with `update_agent`.
+3. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-warm-delivery-failed.md

@@ -0,0 +1,21 @@
+---
+id: errors/native-sandbox-warm-delivery-failed
+title: Native sandbox warm worker could not take the run
+summary: A run claimed an idle warm-pool worker, delivering its input failed, and the worker could not be confirmed stopped within 30 seconds, so the run failed instead of cold-launching.
+audience: operator
+tags: [error, native-agents, sandbox, warm-pool, kubernetes, docker, native_sandbox_warm_delivery_failed]
+appliesTo: ">=0.5.4"
+---
+
+# Native sandbox warm worker could not take the run
+
+`native_sandbox_warm_delivery_failed` means a sandbox run claimed an idle worker from the warm pool (`NATIVE_SANDBOX_WARM_POOL_SIZE`), but writing the run's input into that worker failed. The worker may already hold the run's one-time gateway capability, so Wardby removes it and waits up to 30 seconds for it to be confirmed gone before starting a cold worker. This error means it could not be confirmed gone in that time, so the run failed rather than risk two workers holding the same capability. If the worker is confirmed gone, the run cold-launches and you see no error (the log has a `fallback` event).
+
+1. Trigger the run again. Most failures are transient.
+2. Check that the worker is gone: `kubectl get pods -n <namespace> -l wardby.io/pool=warm` (Kubernetes) or `docker ps --all --filter label=io.wardby.pool=warm` (Docker). Pool upkeep removes leftovers, but a stuck pod usually means the node or Docker host is unhealthy.
+3. Look for `native-warm-pool` log entries with `event` `fallback`, and check that the server may exec into pods in the run namespace.
+4. To bypass the pool while you investigate, set `NATIVE_SANDBOX_WARM_POOL_SIZE=0`; every run then cold-starts.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md#warm-pool). A related error is
+[native_sandbox_capacity](native-sandbox-capacity.md).

package/help/errors/native-sandbox-worker-exited.md

@@ -0,0 +1,20 @@
+---
+id: errors/native-sandbox-worker-exited
+title: Native worker exited without a result
+summary: The sandbox worker container ended without producing a result.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_worker_exited]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker exited without a result
+
+`native_sandbox_worker_exited` means the worker container stopped without reporting a result; the message includes its exit code. Common causes are a tool that exhausted the worker's memory or process limit, or a crash in tool code.
+
+1. Read the exit code in the run's error (`get_run`). Code 137 usually means the memory limit was hit.
+2. If limits are the cause, raise `NATIVE_SANDBOX_MEMORY_MB`, `NATIVE_SANDBOX_PIDS`, or `NATIVE_SANDBOX_CPUS` on the server and restart it.
+3. Otherwise test the agent's tools with `dry_run_tool` and fix the failing code.
+4. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-worker-lost.md

@@ -0,0 +1,20 @@
+---
+id: errors/native-sandbox-worker-lost
+title: Native worker lost
+summary: The sandbox worker container disappeared and was not relaunched.
+audience: operator
+tags: [error, native-agents, sandbox, native_sandbox_worker_lost]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker lost
+
+`native_sandbox_worker_lost` means the run's worker container (or Kubernetes pod) is gone and left no result, for example because the Docker host restarted or an operator removed the container. Wardby never relaunches a worker, because a relaunch could repeat tool side effects.
+
+1. Check whether the Docker host or daemon restarted around the run's time.
+2. List workers with `docker ps --all --filter label=io.wardby.component=native-worker`; do not remove workers of running runs by hand.
+3. On Kubernetes, check whether the node was drained or preempted, and list pods with `kubectl get pods -n <namespace> -l wardby.io/component=native-run`.
+4. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/native-sandbox-worker-unready.md

@@ -0,0 +1,22 @@
+---
+id: errors/native-sandbox-worker-unready
+title: Native worker pod did not start
+summary: On Kubernetes, the sandbox worker pod did not reach the Running state in time, so the run failed before starting.
+audience: operator
+tags: [error, native-agents, sandbox, kubernetes, native_sandbox_worker_unready]
+appliesTo: ">=0.5.4"
+---
+
+# Native worker pod did not start
+
+`native_sandbox_worker_unready` means that with `NATIVE_SANDBOX_LAUNCHER=kubernetes`, the worker pod stayed pending past the start-up limit (`NATIVE_SANDBOX_READY_TIMEOUT_MS`, default two minutes). Nothing ran.
+
+1. Describe the pod while it waits: `kubectl describe pod -n <namespace> -l wardby.io/component=native-run`. Look at the events for image pull errors, unschedulable reasons, or an unknown runtime class.
+2. Image pull: the cluster must be able to pull `NATIVE_SANDBOX_WORKER_IMAGE` (a registry digest) without interactive credentials; add a pull secret to the namespace's default service account if the registry is private.
+3. Scheduling: raise node capacity or lower `NATIVE_SANDBOX_CPUS` and `NATIVE_SANDBOX_MEMORY_MB`, and check namespace ResourceQuotas.
+4. Runtime class: confirm `NATIVE_SANDBOX_RUNTIME_CLASS` (or `KUBERNETES_RUNTIME_CLASS`) exists on the cluster. On Amazon EKS (`KUBERNETES_PLATFORM=eks`) the `gvisor` RuntimeClass must use handler `runsc` and its scheduling block must match your sandbox nodes (label `wardby.dev/sandbox=gvisor`, taint `sandbox=gvisor:NoSchedule`); a mismatch leaves the pod pending.
+5. On a cold node, such as a first gVisor pod on GKE Autopilot (about two minutes), raise `NATIVE_SANDBOX_READY_TIMEOUT_MS` (1000 to 1800000; about 600000 on Autopilot).
+6. Trigger the run again.
+
+See [Run native agents in a sandbox](../native-sandbox.md) and the
+[native sandbox guide](../../docs/native-sandbox.md).

package/help/errors/secret-broker-body-invalid.md

@@ -0,0 +1,26 @@
+---
+id: errors/secret-broker-body-invalid
+title: Secret broker body invalid
+summary: Body placement needs a JSON-object or form-encoded request body with a matching content-type.
+audience: operator
+tags: [error, secrets, secret_broker_body_invalid]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker body invalid
+
+`secret_broker_body_invalid` means a secret placed in the request body could not
+be added to the body the tool sent. Body placement needs one of:
+
+- a JSON object body with `content-type: application/json` (or a `+json` type);
+- a form body with `content-type: application/x-www-form-urlencoded`.
+
+The request must have a body, valid JSON that is an object (not an array or a
+scalar), and a matching `content-type` header.
+
+1. Send a body of a supported type and set the `content-type` header to match.
+2. If the API expects the credential elsewhere, change the placement with
+   `set_secret_broker` to `header` or `query`.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-changed.md

@@ -0,0 +1,20 @@
+---
+id: errors/secret-broker-changed
+title: Brokering changed since the link was created
+summary: A browser link to remove brokering was created before the secret's broker config changed, so it no longer applies.
+audience: operator
+tags: [error, secrets, secret_broker_changed]
+appliesTo: ">=0.6.0"
+---
+
+# Brokering changed since the link was created
+
+`secret_broker_changed` means the browser link for removing brokering was minted
+for a broker config that has since changed or been removed. A link only ever
+removes the exact config it was created for.
+
+1. Call `set_secret_broker` with `broker: null` again to get a new link.
+2. Check the config shown on the new page before confirming removal.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-config-invalid.md

@@ -0,0 +1,30 @@
+---
+id: errors/secret-broker-config-invalid
+title: Secret broker config invalid
+summary: A broker config failed validation: hosts, path prefixes, or placement are malformed.
+audience: operator
+tags: [error, secrets, secret_broker_config_invalid]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker config invalid
+
+`secret_broker_config_invalid` means the broker config passed to `create_secret`,
+`set_secret_broker`, or the browser form did not validate. The message lists
+each problem. Common causes:
+
+- `hosts` is empty, has more than 20 entries, or contains a scheme, port,
+  wildcard, or IP address (including short forms such as `127.1`), or a label
+  ending in `-`; use exact hostnames such as `api.example.com`;
+- a `pathPrefixes` entry does not start with `/`, or contains `?`, `#`, a
+  backslash, a control character, `%2F`, or `%5C`;
+- a header `format` does not contain `{value}` exactly once or contains a line
+  break, or the header name is not allowed (`Host`, `Content-Length` and similar);
+- an AWS `region` or `service` is malformed;
+- the config or its placement has fields it does not define.
+
+1. Fix the fields named in the message and retry.
+2. The config shape is `{ hosts, pathPrefixes?, placement }`.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-conflict.md

@@ -0,0 +1,27 @@
+---
+id: errors/secret-broker-conflict
+title: Secret broker placement conflict
+summary: The request already sets the header, parameter, or field a broker places, two brokers collide, or more than one SigV4 secret was named.
+audience: operator
+tags: [error, secrets, secret_broker_conflict]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker placement conflict
+
+`secret_broker_conflict` means the request would set the same spot twice. A
+brokered value is never merged with or overridden by one from the tool. It
+occurs when:
+
+- the tool sets the header, query parameter, or body field that a brokered
+  secret places (for SigV4: `authorization`, `x-amz-date`,
+  `x-amz-security-token`, or `x-amz-content-sha256`);
+- two named secrets place the same header, parameter, or field;
+- more than one AWS SigV4 secret is named in one request.
+
+1. Remove the conflicting header, parameter, or field from the tool's request.
+2. Send secrets that place the same spot in separate requests.
+3. Name at most one SigV4 secret per request.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-destination-denied.md

@@ -0,0 +1,28 @@
+---
+id: errors/secret-broker-destination-denied
+title: Secret broker destination denied
+summary: A fetch with a brokered secret targeted a URL that is not https, uses a non-default port, or is outside the allowed hosts or path prefixes.
+audience: operator
+tags: [error, secrets, secret_broker_destination_denied]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker destination denied
+
+`secret_broker_destination_denied` means a brokered secret may not be sent to
+the requested URL. The message says which check failed:
+
+- the URL is not `https`, or names a port other than the default;
+- the host is not in the secret's `hosts` (exact match, no wildcards);
+- the path does not start with any of the secret's `pathPrefixes`, or, for a
+  secret with `pathPrefixes`, contains an encoded slash or backslash (`%2F`,
+  `%5C`).
+
+1. Correct the URL in the tool.
+2. If the destination is intended, the secret's owner updates the config with
+   `set_secret_broker`, adding the host or path prefix.
+3. Make sure the tool attachment's `allowedHosts` also lists the host; a host
+   missing there is refused by the normal fetch policy.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-broker-value-invalid.md

@@ -0,0 +1,28 @@
+---
+id: errors/secret-broker-value-invalid
+title: Secret broker value invalid
+summary: A brokered value is shorter than 6 characters, or an AWS SigV4 secret is not the expected JSON.
+audience: operator
+tags: [error, secrets, secret_broker_value_invalid]
+appliesTo: ">=0.6.0"
+---
+
+# Secret broker value invalid
+
+`secret_broker_value_invalid` means the stored value cannot be brokered under its
+config. It is returned when saving a config and when a tool uses the secret.
+
+- A brokered value must be at least 6 characters.
+- An AWS SigV4 secret's value must be JSON
+  `{"accessKeyId": "...", "secretAccessKey": "...", "sessionToken": "..."}` with
+  no other keys. `sessionToken` is optional; the secret access key and session
+  token must each be at least 6 characters.
+
+1. Re-enter the value with `create_secret` using the same name; it rotates the
+   value in place. Leave out `broker`: a rotation without one keeps the
+   existing broker config. In the browser form, correct the value and submit
+   the same link again.
+2. For SigV4, store the credentials as that JSON object.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-brokered.md

@@ -0,0 +1,24 @@
+---
+id: errors/secret-brokered
+title: Secret is brokered and cannot be read
+summary: A tool called secrets.get on a brokered secret; brokered secrets are only sent with fetch(url, { secrets }).
+audience: operator
+tags: [error, secrets, secret_brokered]
+appliesTo: ">=0.6.0"
+---
+
+# Secret is brokered and cannot be read
+
+`secret_brokered` means a tool called `secrets.get(name)` on a secret that is
+brokered. A brokered secret never exposes its value to tool code.
+
+1. Update the tool to send the secret with
+   `fetch(url, { secrets: ["NAME"] })`; the host places the value in the request.
+2. Or, if the tool really must read the value, have the secret owner remove
+   brokering with `set_secret_broker` and `broker: null`, confirmed in the
+   browser. This makes the value readable by every tool granted it.
+3. `attach_tool` and `set_secret_broker` warn when a granted tool calls
+   `secrets.get`; that scan is best-effort.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/secret-not-brokered.md

@@ -0,0 +1,25 @@
+---
+id: errors/secret-not-brokered
+title: Secret is not brokered
+summary: A fetch named a secret that is readable, not attached to the agent, or not granted to the tool.
+audience: operator
+tags: [error, secrets, secret_not_brokered]
+appliesTo: ">=0.6.0"
+---
+
+# Secret is not brokered
+
+`secret_not_brokered` means `fetch(url, { secrets: [...] })` named a secret that
+is not a brokered secret available to this tool: it is readable, it is not
+attached to the agent, it is not listed in the attachment's `allowedSecrets`, or
+the request named more than 8 secrets.
+
+1. Check the name matches the alias the secret is attached under
+   (`attach_secret`) and appears in the tool attachment's `allowedSecrets`.
+2. To send the secret through `fetch`, make it brokered with
+   `set_secret_broker { name, broker }`.
+3. If the secret is meant to stay readable, read it with `secrets.get(name)`
+   instead of naming it in `fetch`.
+
+See [Brokered secrets](../brokered-secrets.md) and the
+[secrets guide](../../docs/tool-secrets.md).

package/help/errors/slack-auth-failed.md

@@ -0,0 +1,48 @@
+---
+id: errors/slack-auth-failed
+title: Bot authentication failed — invalid or revoked token
+summary: wardby's Slack bot token is invalid, revoked, disabled, or missing a required scope, so delivery to every linked channel is paused.
+audience: operator
+tags: [error, notifications, auth, authentication, invalid_auth, token_revoked, missing_scope]
+appliesTo: ">=0.6.0"
+---
+
+# Bot authentication failed — invalid or revoked token
+
+Slack returned `invalid_auth`, `token_revoked`, `account_inactive`,
+`missing_scope`, or `not_authed` for `WARDBY_SLACK_BOT_TOKEN`. This is
+different from a single channel being unreachable: it means the token
+itself no longer works, so wardby pauses delivery to **every** linked
+channel rather than attempting and failing each one. Deliveries already
+queued stay pending — nothing is lost — and wardby automatically re-checks
+the token every five minutes with Slack's `auth.test`, resuming delivery as
+soon as it succeeds.
+
+A **missing scope** (`missing_scope`) does not fix itself this way:
+`auth.test` needs no scope, so the re-check succeeds, the next delivery fails
+again, and delivery pauses again. Add the scope and reinstall the app (steps
+1–2 below).
+
+The same errors while linking a channel refuse the link, except
+`missing_scope` from a missing `channels:read`/`groups:read`, which only
+skips validating the channel id.
+
+wardby logs this once per pause, not on every retry.
+
+## What to do
+
+1. In Slack, check the app's **OAuth & Permissions** page: is the bot
+   installed, and does it still have `chat:write` at minimum?
+2. If the app's scopes changed (for example after editing
+   [`app-manifest.yaml`](../../deploy/slack/app-manifest.yaml)), reinstall
+   the app to the workspace to apply them.
+3. If the token was revoked or the app was uninstalled, reinstall it and
+   copy a fresh Bot User OAuth Token.
+4. If Slack issued a new token, set it as `WARDBY_SLACK_BOT_TOKEN` and
+   restart wardby; the startup log line `chat notifications acting as`
+   confirms it. If the token is unchanged (a scope added and the app
+   reinstalled), no restart is needed: pending deliveries go out after the
+   next check.
+
+See [Send workflow updates to Slack](../../docs/slack-notifications.md) for
+the full guide.