@wardby/cli 0.2.1 → 0.4.0

package/help/coding-packages.md

@@ -0,0 +1,31 @@
+---
+id: coding-packages
+title: Approve packages for coding agents
+summary: Let Codex coding workers install vetted npm and PyPI dependencies through Wardby's registry proxy.
+audience: operator
+tags: [coding-agents, packages, npm, pypi, supply-chain]
+appliesTo: >=0.2.1
+---
+
+# Approve packages for coding agents
+
+Coding workers have no direct registry network access. For **Codex** workers,
+Wardby's registry proxy can allow `npm install` and `pip install` from a
+per-agent npm or PyPI allowlist. The proxy records what was fetched and applies
+supply-chain checks, including package graph validation, release-age policy,
+and vulnerability filtering.
+
+An empty allowlist keeps registry mode off. Approve only top-level packages;
+Wardby validates and permits the required transitive dependency graph for the
+run. Changing a package allowlist or policy needs `packages:approve` (or
+`agents:admin`) and a Wardby `admin` or `package-approver` role.
+
+Registry mode works for Codex and Claude Code runs alike, on the `node`
+toolchain (npm) and the `node-python` toolchain (npm and pip). Claude Code runs
+its shell commands in a separate, credential-free tool-runner container that
+reaches the registry through the run's proxy network. Use a pinned custom
+worker image when an agent needs system packages, another runtime, or
+dependencies that should be baked into the image.
+
+Read [`docs/coding-packages.md`](../docs/coding-packages.md) for allowlist
+syntax, package-policy controls, lockfile behavior, and refusal errors.

package/help/coding-services.md

@@ -0,0 +1,71 @@
+---
+id: coding-services
+title: Give coding runs the services their tests need
+summary: Let coding runs on the Kubernetes or Docker launcher start fresh PostgreSQL, Redis or MySQL instances declared in the repository's .wardby/services.yaml.
+audience: operator
+tags: [coding-agents, services, postgres, redis, mysql, kubernetes, docker]
+appliesTo: >=0.2.1
+---
+
+# Give coding runs the services their tests need
+
+A coding run can have a PostgreSQL, Redis or MySQL instance next to it for the
+length of the run. Three parties agree before a service starts:
+
+- **The repository** declares it in `.wardby/services.yaml` on its base branch,
+  for example `services: { postgres: "16" }`. Wardby reads the file from the
+  run's base branch (the agent's `baseRef`, or a `baseRef` given to
+  `trigger_agent` for that run), never from the run's own branch, so a change
+  to the declaration takes effect only once it is merged into that base.
+- **The service catalog** says what each name and version is: a digest-pinned
+  image, its readiness check, resources, and the variables the agent's shells
+  receive (`testEnv`, such as `DATABASE_URL`). `list_services` and
+  `get_service` need `agents:read`. `create_service`, `update_service` and
+  `delete_service` need `services:manage` and the `admin` or
+  `service-manager` role. Built-in entries (`postgres` 15, 16 and 17, `redis`
+  7, `mysql` 8) cannot be changed over MCP.
+- **The agent's owner** lists the catalog names its runs may use in
+  `codingProfile.services`. An empty list, the default, allows none.
+
+An agent with an empty list never reads the repository's declaration at all —
+wardby only looks at `.wardby/services.yaml` for an agent that allows at least
+one service. Such an agent's runs simply start without services, whatever a
+repository declares, and none of the errors below can apply to them.
+
+Services need the Kubernetes job launcher with Kubernetes 1.29 or later (each
+service runs as a native sidecar in the run's pod) or the Docker job launcher
+(each service runs as its own container sharing the run's network namespace);
+both start them for Codex and Claude Code agents. Each run gets its own empty
+instance, reachable on `127.0.0.1`; the run's sandbox and network policy do
+not change, and the instance is deleted with the run. Each service's CPU,
+memory and disk count toward the run: on Kubernetes toward its pod, namespace
+quota and what a managed cluster bills; on Docker toward the host's memory,
+because its data is kept in memory.
+
+A bring-your-own worker image
+([`docs/coding-worker-byo-images.md`](../docs/coding-worker-byo-images.md))
+needs driver v11 or later to run with services.
+
+Catalog values are visible to anyone with `agents:read`. Use throwaway test
+credentials only; never put a real secret in `serviceEnv` or `testEnv`.
+
+Every run protects `.wardby/**` except `.wardby/services.yaml`, so a coding
+agent may propose a declaration change in its pull request but cannot change
+other `.wardby/` files. An agent's own `protectedPaths` exceptions (entries
+starting with `!`) must be literal file paths and cannot unprotect `.wardby/`.
+
+When upgrading a deployment that delegates to an identity provider, define the
+`services:manage` scope in the provider first; see
+[Configure identity and privileged access](identity-and-access.md).
+
+If a run is refused or fails over its services, read the page for its code:
+
+- [`service_declaration_invalid`](errors/service-declaration-invalid.md)
+- [`service_declaration_unavailable`](errors/service-declaration-unavailable.md)
+- [`service_unknown`](errors/service-unknown.md)
+- [`service_not_allowed`](errors/service-not-allowed.md)
+- [`service_launcher_unsupported`](errors/service-launcher-unsupported.md)
+- [`service_unready`](errors/service-unready.md)
+
+Read [`docs/coding-services.md`](../docs/coding-services.md) for the file
+format, catalog fields, built-in variables, custom entries, and capacity.

package/help/cost-attribution.md

@@ -0,0 +1,67 @@
+---
+id: cost-attribution
+title: Attribute agent spend to issues
+summary: See what agent work on a Jira card, epic, or project cost, by model and token kind, with the cost_report MCP tool.
+audience: operator
+tags: [cost, spend, attribution, jira, epic, reporting, cost_report, tokens]
+appliesTo: >=0.2.1
+---
+
+# Attribute agent spend to issues
+
+Wardby records which issue each run's cost belongs to, so you can see what agent
+work on a card, an epic, or a whole project cost.
+
+A run is attributed to an issue when:
+
+- a Jira event on that issue started it;
+- it reviews, or answers an `@wardby` mention on, a pull request Wardby opened
+  for the issue;
+- `trigger_agent` named an `issue`, or a webhook call's JSON body named a
+  `wardbyIssue`, as `{ "provider": "jira", "key": "PROJ-123" }`, in a project
+  the agent is linked to. Keys are matched without regard to case
+  (`proj-123` is read as `PROJ-123`). An unlinked project or a malformed key is
+  refused; a webhook answers `400 invalid_issue`. A webhook ignores a
+  top-level `issue` field, so forwarded GitHub or Jira payloads still run;
+- its parent run is attributed. Sub-agents and coding runs inherit the issue
+  and cannot change it.
+
+When a run starts, Wardby records the issue's parent (its epic) as it is at that
+moment. Moving an issue to another epic later leaves earlier runs under the
+earlier epic. Reports always show the latest known titles.
+
+## Read the report
+
+Call the `cost_report` MCP tool. `groupBy` is `issue` (default), `parent`,
+`scope` (project), `agent`, `model`, or `run`; filter with `scopeKey`,
+`parentKey`, `issueKey`, `agentId`, `provider`, and an ISO `from`/`to` window
+(default: the last 30 days). Drill down by combining them: `groupBy: "parent",
+scopeKey: "PROJ"` lists epics, then `groupBy: "issue", parentKey: "PROJ-10"`
+lists that epic's cards, and `groupBy: "run", issueKey: "PROJ-123"` gives run
+ids for `get_run`.
+
+- Amounts are USD. Tokens are reported by kind — fresh input, cached input,
+  cache write, output — because each kind is priced differently; they are never
+  added into one total.
+- `bySource` splits each row's cost by how its runs were attributed, which
+  shows how much was pull-request review (`linked_pr`).
+- `unattributed` is spend in the window with no issue. Only `agentId` narrows
+  it; the project, epic, and issue filters cannot.
+- `totals` sum each run's full cost. With `groupBy: "model"`, rows add up to
+  less when some runs have no per-model record.
+- You see the same runs as `list_runs`: runs of agents you own, plus runs you
+  triggered.
+
+The Jira status comment for a run also ends with its spend: the whole run tree,
+the issue's total so far (every attributed run, whichever agent ran it), and the
+cost per model.
+
+## Setup notes
+
+If a company-managed Jira site still uses the legacy Epic Link field, set
+`WARDBY_JIRA_EPIC_LINK_FIELD` (for example `customfield_10014`) so runs are
+grouped under their epic. On GKE, re-run the database grants bootstrap after
+upgrading so coding runs record their per-model usage; until then they still
+run and a warning is logged.
+
+For the full guide, follow [`docs/jira-agents.md`](../docs/jira-agents.md).

package/help/creating-agents.md

@@ -0,0 +1,90 @@
+---
+id: creating-agents
+title: Choose a native or coding agent
+summary: Decide whether a task should run as a native Wardby agent or an isolated Codex or Claude Code coding agent.
+audience: developer
+tags: [agents, native-agents, coding-agents, codex, claude-code]
+appliesTo: >=0.2.1
+---
+
+# Choose a native or coding agent
+
+Create a **native agent** when Wardby should run a model with explicit,
+attached capabilities to produce a bounded operational result. Create a
+**coding agent** when the task must inspect and change a Git repository, run
+project checks, and optionally open a draft pull request.
+
+| Choose       | Best for                                                                             | Execution model                                                                                    | Typical result                                                     |
+| ------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| Native agent | Review, triage, analysis, reporting, workflow coordination, and API-backed tasks     | Wardby's managed native run loop with only its attached tools, secrets, datastores, and sub-agents | A structured result, report, decision, or bounded follow-up action |
+| Coding agent | Repository changes, tests, dependency updates, implementation work, and PR revisions | An isolated Codex or Claude Code worker with a trusted proxy and Git finalization                  | No changes, a bounded result, or one controlled draft pull request |
+
+## Start with a native agent
+
+Native agents are the default when a task does not need a full repository
+workspace. Give the agent a narrow purpose, model, per-run budget, and only the
+tools or data it needs. Attach schedules or webhooks when the work should run
+without a person starting it manually.
+
+Examples include an architecture reviewer that writes findings to a datastore,
+a release monitor that investigates an alert, or a triage agent that turns
+incoming information into a report for a person to act on.
+
+## Use a coding agent for repository work
+
+Coding agents use a `codingProfile` that selects Codex or Claude Code and names
+the authorized repository. They run in isolated workers; Wardby keeps provider
+credentials and the GitHub App private key in trusted components. A coding run
+can change a checkout and run approved checks, but trusted finalization is what
+validates the result, pushes a controlled branch, and opens a draft pull
+request. It never auto-merges.
+
+Before creating one, configure immutable worker images, the selected launcher,
+the trusted coding proxy, and a narrowly installed GitHub App. The agent owner
+must have the required repository access, or an administrator must explicitly
+approve the repository.
+
+## Choosing a model
+
+Both agent types take a `model` field naming an entry in wardby's model
+catalog. Run `list_models` to see which ids this deployment knows about and
+what each costs; `get_model` shows one entry in full. `create_agent` and
+`update_agent` always refuse a `model` that isn't in the catalog or that an
+admin has disabled. For a native agent, they also refuse a model whose
+provider has no credentials configured for native runs here (such a model
+shows `routable: false` in `list_models`). A coding agent's model isn't checked against
+`routable` at all — a coding run uses the coding proxy's own credentials
+instead, so confirm those are configured for Codex or Claude Code
+separately; a missing one fails the run itself at dispatch, not
+`create_agent`/`update_agent`. See [Models and pricing](models.md) and
+[Model not available](errors/model-unavailable.md).
+
+## Decision checklist
+
+Choose a native agent when all of these are true:
+
+- The task can be completed with a narrow set of attached tools or data.
+- A repository checkout, shell-based project setup, and code changes are not
+  required.
+- The intended output is an analysis, report, decision, or controlled API
+  action.
+
+Choose a coding agent when any of these are true:
+
+- The agent must edit a repository or execute the project's test suite.
+- The reviewable outcome should be a branch or draft pull request.
+- The task needs a coding-agent builder such as Codex or Claude Code inside an
+  isolated workspace.
+
+Do not use a coding agent merely because a task is complex. Start with the
+least powerful execution model that can safely produce the required outcome.
+A coding agent can also keep a repository's architecture knowledge current; see
+[Set up an architecture agent](help://architecture-agent) and
+[Architecture knowledge bundles](help://knowledge).
+
+For an `@mention` builder with a router, see [Agent recipes](help://agent-recipes) and
+[Builder and router prompts](help://builder-agent).
+
+Read [Connect GitHub repositories](github.md) and
+[Troubleshoot coding workers](troubleshooting/coding-workers.md) before
+enabling repository-changing work.

package/help/deploy-gke.md

@@ -0,0 +1,45 @@
+---
+id: deploy-gke
+title: Deploy Wardby on GKE Autopilot
+summary: Use the supported Google Cloud path for a private database, isolated coding workers, and HTTPS ingress.
+audience: operator
+tags: [deployment, gke, gcp, kubernetes, production]
+appliesTo: >=0.2.1
+---
+
+# Deploy Wardby on GKE Autopilot
+
+The supported Google Cloud deployment creates a GKE Autopilot cluster, private
+Cloud SQL for PostgreSQL, Artifact Registry, HTTPS Gateway, Google Secret
+Manager synchronization, and isolated gVisor-backed **Codex** coding-worker
+pods. It also applies namespace RBAC and default-deny network policies.
+
+Use a dedicated billed project, a hostname you control, remote Terraform state,
+and a GitHub App installed only on repositories that agents need. Review
+Terraform's plan and set cloud budgets before applying it: the deployment
+creates billable resources.
+
+The deployment process is:
+
+1. Install `gcloud`, Terraform, Docker with `linux/amd64` support, `kubectl`,
+   Helm, Node.js 24, and authenticate to the target project.
+2. Configure `deploy/gke/terraform.tfvars`, apply Terraform, and prepare the
+   Gateway's address, certificate map, Cloud Armor policy, and DNS record.
+3. Put first-time values in an untracked `.env.local`; `deploy/gke/up.sh`
+   seeds Secret Manager without overwriting existing production values.
+4. Run `HOSTNAME=wardby.example.com deploy/gke/up.sh`, then verify DNS,
+   certificate issuance, database IAM bootstrap, and service health.
+
+When a release changes `deploy/gke/database-grants.sql`, re-run the database
+grants bootstrap **before** deploying that release, so the proxy role can
+already write the tables and columns it adds (such as per-model usage for
+[cost attribution](cost-attribution.md), or a run's live turn count). Until the
+grants are applied, the coding proxy's writes are refused and coding runs fail.
+
+Claude Code's two-container executor is currently Docker-only; Kubernetes
+coding workers use the Codex path. Configure an identity provider and GitHub
+App before allowing people to use the public endpoint.
+
+Follow the complete, ordered guide at
+[`docs/getting-started-gke.md`](../docs/getting-started-gke.md). It includes
+the precise IAM, DNS, bootstrap, upgrades, and teardown steps.

package/help/deployment-targets.md

@@ -0,0 +1,39 @@
+---
+id: deployment-targets
+title: Choose a deployment target
+summary: Pick the supported Wardby deployment path and understand its operational boundary.
+audience: operator
+tags: [deployment, docker, gke, aws, production]
+appliesTo: >=0.2.1
+---
+
+# Choose a deployment target
+
+Wardby has one local path and two production-ready deployment shapes:
+
+- **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.
+- **Google Kubernetes Engine Autopilot:** the supported Google Cloud path. It
+  provisions GKE, private-IP Cloud SQL, Artifact Registry, isolated Codex
+  workers, HTTPS Gateway, and GCP-native secret and network controls. 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
+can run the production container image with equivalent database, ingress,
+identity, secret, isolation, and observability controls; that infrastructure is
+operator-owned.
+
+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
+[`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/budget-group-exhausted.md

@@ -0,0 +1,25 @@
+---
+id: errors/budget-group-exhausted
+title: Budget group exhausted
+summary: Wardby refused the run because the shared budget group has no remaining capacity for the period.
+audience: operator
+tags: [error, budget, refusal]
+appliesTo: >=0.2.1
+---
+
+# Budget group exhausted
+
+An error such as `budget_group_exhausted:week` means the agent's budget group
+has no capacity left for that period after accounting for actual spending and
+active reservations. Wardby refuses the run before model work or a coding
+worker begins.
+
+1. Inspect the budget group's `spentUsd` and `reservedUsd` values.
+2. Inspect active and recent runs that use the group.
+3. Wait for the period to reset, cancel unneeded active work, or deliberately
+   adjust the agent or group budget.
+4. Trigger a new run after capacity is available; a refused run is not resumed
+   automatically.
+
+Do not raise a limit merely to clear a refusal without confirming the intended
+owner, schedule, and overlapping work. See [Budget troubleshooting](../troubleshooting/budgets.md).

package/help/errors/docker-isolation-unsupported.md

@@ -0,0 +1,26 @@
+---
+id: errors/docker-isolation-unsupported
+title: Coding-worker isolation unavailable
+summary: Wardby refused to launch a coding worker because it could not verify the required isolation controls.
+audience: operator
+tags: [error, coding-agents, docker, isolation]
+appliesTo: >=0.2.1
+---
+
+# Coding-worker isolation unavailable
+
+`docker_isolation_unsupported` means a required worker-isolation guarantee was
+missing, unexpected, or could not be inspected. Wardby fails closed rather than
+running a worker with a weaker profile.
+
+1. Run `wardby coding preflight` and correct the reported launcher, image,
+   proxy-network, or host-support issue.
+2. Confirm worker images are immutable image IDs or digests, not mutable tags.
+3. Confirm the trusted proxy and worker use the intended isolated network and
+   that no unapproved host mount, Docker socket, environment, or network path
+   is present.
+4. Re-run preflight before triggering another coding run.
+
+If the deployment target does not support the selected coding provider, choose
+a supported launcher/provider combination instead of disabling the controls.
+See [Coding-worker troubleshooting](../troubleshooting/coding-workers.md).

package/help/errors/model-unavailable.md

@@ -0,0 +1,63 @@
+---
+id: errors/model-unavailable
+title: Model not available
+summary: Wardby refused to start or configure a run because its model is not usable in this deployment right now.
+audience: all
+tags: [error, models, pricing, model_unavailable, refusal]
+appliesTo: ">=0.4.0"
+---
+
+# Model not available
+
+`model_unavailable` means the model an agent names cannot be routed to in
+this deployment right now. Wardby checks this before a run starts spending —
+and whenever `create_agent` or `update_agent` sets or changes an agent's
+model — never mid-run. A native agent's error carries one of three reasons;
+a coding agent's only ever carries the first two, since a coding run uses the
+coding proxy's own credentials rather than looking up a provider adapter:
+
+- **`not_in_catalog`** — the model id is not in the catalog at all: not
+  shipped with this release, and no admin has added it. Run `list_models` to
+  see the exact ids this deployment knows about, and pick one of those, or
+  ask someone with `models:admin` to add it with `set_model`.
+- **`disabled`** — the model is in the catalog, but an admin has disabled it
+  with `disable_model`. Pick a different model, or ask someone with
+  `models:admin` to bring it back with `reset_model` (reverts to the shipped
+  entry, if any) or `set_model` (re-adds it with current values).
+- **`provider_not_configured`** (native agents only) — the model's provider
+  (`openai`, `anthropic`, or `bedrock-claude`) has no credentials configured
+  for native runs in this deployment, even though the model itself is in the
+  catalog. An operator needs to configure that provider's credentials before
+  any native agent can use a model under it; see
+  [Getting started](../getting-started.md).
+
+Whatever the reason, the run is not lost: it ends with status `failed`, zero spend, and
+the `model_unavailable` message as its error, so `list_runs` and `get_run`
+show why. A coding agent's run fails at dispatch, before any worker starts,
+and a scheduled agent moves on to its next window instead of retrying the
+same one. A coding agent whose model now belongs to a different provider than
+its coding provider drives (for example a Claude model on a Codex agent)
+fails the same way, with `Model "<id>" is not supported by coding provider
+"<provider>"` as its error.
+
+A coding agent's model is checked against the catalog only
+(`not_in_catalog`/`disabled`), never `provider_not_configured`: coding runs
+never look up a provider adapter at all, so a model can pass this check and
+still fail later for reasons `model_unavailable` never reports.
+
+One such failure has a specific name: dispatching a Claude Code run throws
+`coding_provider_not_configured:claude-code` when this deployment's
+`CODING_CLAUDE_WORKER_IMAGE` or `CODING_CLAUDE_TOOL_RUNNER_IMAGE` isn't set —
+it means the Claude Code worker or tool-runner image itself isn't configured,
+not a missing credential, and there is no equivalent error or string for
+Codex. See [Local coding-agent setup](../../docs/coding-agent-setup.md).
+
+A missing or invalid API key behind a coding run's model-provider credential
+(`CODING_OPENAI_CREDENTIAL_REF` for Codex, `CODING_ANTHROPIC_CREDENTIAL_REF`
+for Claude Code) is a different problem with no dedicated error code
+documented here: the run starts, then fails when it actually calls the
+model — not as `model_unavailable`, and not at dispatch. Check the coding
+proxy's own logs for that run.
+
+See [Models and pricing](../models.md) for how the catalog works and who can
+change it.

package/help/errors/protected-path.md

@@ -0,0 +1,45 @@
+---
+id: errors/protected-path
+title: Run changed a protected path
+summary: A coding run's changes touched a path this agent may not edit, so none of its changes were kept.
+audience: operator
+tags: [error, coding-agents, vcs]
+appliesTo: >=0.2.1
+---
+
+# Run changed a protected path
+
+A run that failed with category `protected_path` finished its work, but the
+changes it collected included a file its agent is not allowed to edit. Wardby
+discards the run's changes entirely rather than dropping just that file:
+nothing from the run reaches a pull request.
+
+Wardby protects two kinds of paths on every coding run:
+
+- **The agent's own `protectedPaths`**, a list of glob patterns set on the
+  agent (`codingProfile.protectedPaths`, via `create_agent`/`update_agent`).
+  An entry may start with `!` to carve out one literal file as an exception
+  to the agent's own patterns; a whole tree can never be carved out this way.
+- **The `.wardby/` baseline**, which every coding run gets regardless of the
+  agent's own settings. It protects everything under `.wardby/` except the one
+  literal file `.wardby/services.yaml`, which any coding agent may propose a
+  change to (see [Coding services](../coding-services.md)) — the baseline
+  cannot be widened to cover that file, and no exception can narrow it further
+  than that.
+
+What to do:
+
+1. Ask again without changing the named file. If the change is small, doing it
+   yourself and letting the agent build on top is often fastest.
+2. If the agent genuinely needs to change that file, its owner (or an admin)
+   can widen `codingProfile.protectedPaths` with `update_agent` — for example
+   adding a `!`-prefixed exception for one file. This can never remove the
+   `.wardby/` baseline itself.
+3. Otherwise, the repository owner makes the change directly and the agent
+   works around it on the next run.
+
+When this run is a sub-run another agent dispatched (for example a router
+handing work to a coding agent), the parent sees a failed sub-run on its own
+status comment: "A sub-run could not open its changes: it changed a file its
+agent may not edit, so none of its changes were kept." That line never names
+the file; check the sub-run's own PR comment or `get_run` for it.

package/help/errors/repo-access.md

@@ -0,0 +1,27 @@
+---
+id: errors/repo-access
+title: Repository access refused
+summary: Wardby refused repository work because it could not confirm the managed agent owner's required GitHub access.
+audience: operator
+tags: [error, github, authorization, refusal]
+appliesTo: >=0.2.1
+---
+
+# Repository access refused
+
+`repo_access` means Wardby cannot authorize the agent owner's current access to
+the selected repository. Nothing is cloned or pushed for a refusal at run
+preparation. The check also happens immediately before a coding run pushes, so
+access lost during a run prevents publication.
+
+1. Confirm the agent has an owner and the intended repository is attached.
+2. Confirm that owner has linked their GitHub account to Wardby.
+3. Confirm the GitHub App is installed on the repository and the owner has the
+   required permission: write for coding work, read for a read-only link.
+4. If no individual owner can hold the access, ask a Wardby administrator to
+   record an explicit repository approval.
+5. Trigger a fresh run after the correction.
+
+`repo_access_unavailable` is different: GitHub could not be queried reliably.
+Resolve the availability condition and retry later rather than treating it as
+an authorization success. See [Repository-access troubleshooting](../troubleshooting/repository-access.md).

package/help/errors/service-declaration-invalid.md

@@ -0,0 +1,27 @@
+---
+id: errors/service-declaration-invalid
+title: Service declaration invalid
+summary: Wardby refused the coding run because the repository's .wardby/services.yaml on the base branch is not a valid declaration.
+audience: operator
+tags: [error, coding-agents, services, refusal]
+appliesTo: >=0.2.1
+---
+
+# Service declaration invalid
+
+`service_declaration_invalid` means the repository's `.wardby/services.yaml`,
+read from the run's base branch, could not be used. The run's `error` names the
+line and reason. Wardby refuses the run before a coding worker starts.
+
+1. Check the file on the base branch. Its only key is `services`, mapping
+   catalog names (lowercase letters, digits and hyphens) to quoted version
+   strings, for example `postgres: "16"`.
+2. Keep it to at most five services and under 8 KiB. Images, ports, commands
+   and environment belong in the catalog, not in the repository.
+3. Merge the fix to the base branch; a fix on the run's own branch has no
+   effect.
+4. Trigger a new run; a refused run is not resumed automatically.
+
+The same code is used when the declared services' instructions would push the
+coding task over its size limit; declare fewer services in that case. See
+[Coding services](../coding-services.md).

package/help/errors/service-declaration-unavailable.md

@@ -0,0 +1,25 @@
+---
+id: errors/service-declaration-unavailable
+title: Service declaration unavailable
+summary: Wardby refused the coding run because it could not read .wardby/services.yaml from the base branch.
+audience: operator
+tags: [error, coding-agents, services, github, refusal]
+appliesTo: >=0.2.1
+---
+
+# Service declaration unavailable
+
+`service_declaration_unavailable` means Wardby could not read
+`.wardby/services.yaml` from the run's base branch through the GitHub App, so
+it could not tell which services the run needs. A missing file is not this
+error (no file means no services); this is a failed read. Wardby refuses the
+run rather than start it without services the repository may require.
+
+1. Trigger the run again; the cause is often a transient GitHub error.
+2. If it repeats, confirm the GitHub App installation still covers the
+   repository and has contents read access, and that the agent's base branch
+   exists.
+3. Check the control-plane logs around the refusal for the GitHub response.
+
+See [Repository access troubleshooting](../troubleshooting/repository-access.md)
+and [Coding services](../coding-services.md).

package/help/errors/service-launcher-unsupported.md

@@ -0,0 +1,30 @@
+---
+id: errors/service-launcher-unsupported
+title: Services are not available to this run
+summary: Wardby refused the coding run because the repository declares services and this deployment cannot start them.
+audience: operator
+tags: [error, coding-agents, services, kubernetes, docker, refusal]
+appliesTo: >=0.2.1
+---
+
+# Services are not available to this run
+
+`service_launcher_unsupported` means the repository declares services, but this
+deployment cannot start them. Services need a job launcher that starts them:
+
+- `JOB_LAUNCHER=kubernetes` and `JOB_LAUNCHER=docker` start them for Codex and
+  Claude Code agents;
+- a deployment with `JOB_LAUNCHER=local` cannot start them at all.
+
+1. Run the coding agent on a deployment that uses the Kubernetes or Docker job
+   launcher, or
+2. remove `.wardby/services.yaml` from the base branch if the repository's
+   tests do not need the services.
+
+This error only applies to an agent that already allows at least one service
+(`codingProfile.services` is non-empty): wardby reads a repository's
+declaration only for such an agent, and refuses rather than silently starting
+the run without the services it names. An agent that allows no services never
+reads the declaration at all, so its runs are unaffected and start normally on
+any launcher. See [Coding-worker troubleshooting](../troubleshooting/coding-workers.md)
+and [Coding services](../coding-services.md).

package/help/errors/service-not-allowed.md

@@ -0,0 +1,27 @@
+---
+id: errors/service-not-allowed
+title: Service not allowed for this agent
+summary: Wardby refused the coding run because the repository declares a service the agent's codingProfile.services does not allow.
+audience: operator
+tags: [error, coding-agents, services, refusal]
+appliesTo: >=0.2.1
+---
+
+# Service not allowed for this agent
+
+`service_not_allowed` means the repository declares a service that exists in
+the catalog, but the agent's `codingProfile.services` does not list its name.
+Wardby refuses the run before a coding worker starts.
+
+1. Confirm the repository should have the service; the declaration is on the
+   base branch in `.wardby/services.yaml`.
+2. If it should, the agent's owner (or an admin) adds the name, for example
+   `postgres`, to `codingProfile.services` with `update_agent`. Allowing a name
+   allows every version the catalog has for it.
+3. Trigger a new run.
+
+Each allowed service reserves CPU, memory and disk for the whole run, so allow
+only what the agent's repositories need. This error implies the agent already
+allows at least one service — an agent whose `codingProfile.services` is empty
+never reads the declaration at all, so it never reaches this check. See
+[Coding services](../coding-services.md).