@wardby/cli 0.2.1 → 0.3.0

package/dist/help-index.json

@@ -0,0 +1,660 @@
+{
+  "schemaVersion": 1,
+  "pages": [
+    {
+      "id": "code-review-agents",
+      "title": "Run GitHub code-review agents",
+      "summary": "Link a read-only review agent to a repository for pull-request checks and trusted mention workflows.",
+      "audience": "operator",
+      "tags": [
+        "github",
+        "code-review",
+        "pull-requests",
+        "webhooks"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "code-review-agents.md",
+      "markdown": "\n# Run GitHub code-review agents\n\nA native agent linked through Wardby's GitHub App can review pull requests\nwithout receiving repository credentials. On pull-request pushes it creates an\nin-progress check, reads the diff, then posts inline findings, one updated\nsummary comment, and a final approve, changes-requested, or comment result.\nBudget exhaustion or another failed review makes the check fail rather than\nsilently pass branch protection.\n\nPeople with write access to the repository may request another review with\n`@<app-slug> review`. Other mentions can be routed to a dedicated mention\nagent, which acknowledges the request and posts its final outcome. Do not give\na mention agent instructions that could echo secrets or internal details: its\nreply is visible wherever the mention was posted.\n\nWardby skips pull requests whose head is in a fork. It also ignores mentions\nfrom bots and people without write access. Repository links require the\nagent owner's linked GitHub access, or an explicitly recorded administrator\napproval.\n\nFor App permissions, webhook setup, trigger configuration, and security\ndetails, follow [`docs/code-review-agents.md`](../docs/code-review-agents.md).\n",
+      "plainText": "Run GitHub code-review agents A native agent linked through Wardby's GitHub App can review pull requests without receiving repository credentials. On pull-request pushes it creates an in-progress check, reads the diff, then posts inline findings, one updated summary comment, and a final approve, changes-requested, or comment result. Budget exhaustion or another failed review makes the check fail rather than silently pass branch protection. People with write access to the repository may request another review with @<app-slug review. Other mentions can be routed to a dedicated mention agent, which acknowledges the request and posts its final outcome. Do not give a mention agent instructions that could echo secrets or internal details: its reply is visible wherever the mention was posted. Wardby skips pull requests whose head is in a fork. It also ignores mentions from bots and people without write access. Repository links require the agent owner's linked GitHub access, or an explicitly recorded administrator approval. For App permissions, webhook setup, trigger configuration, and security details, follow docs/code-review-agents.md.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Run GitHub code-review agents",
+          "slug": "run-github-code-review-agents"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "coding-packages.md",
+      "markdown": "\n# Approve packages for coding agents\n\nCoding workers have no direct registry network access. For **Codex** workers,\nWardby's registry proxy can allow `npm install` and `pip install` from a\nper-agent npm or PyPI allowlist. The proxy records what was fetched and applies\nsupply-chain checks, including package graph validation, release-age policy,\nand vulnerability filtering.\n\nAn empty allowlist keeps registry mode off. Approve only top-level packages;\nWardby validates and permits the required transitive dependency graph for the\nrun. Changing a package allowlist or policy needs `packages:approve` (or\n`agents:admin`) and a Wardby `admin` or `package-approver` role.\n\nRegistry mode works for Codex and Claude Code runs alike, on the `node`\ntoolchain (npm) and the `node-python` toolchain (npm and pip). Claude Code runs\nits shell commands in a separate, credential-free tool-runner container that\nreaches the registry through the run's proxy network. Use a pinned custom\nworker image when an agent needs system packages, another runtime, or\ndependencies that should be baked into the image.\n\nRead [`docs/coding-packages.md`](../docs/coding-packages.md) for allowlist\nsyntax, package-policy controls, lockfile behavior, and refusal errors.\n",
+      "plainText": "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 for allowlist syntax, package-policy controls, lockfile behavior, and refusal errors.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Approve packages for coding agents",
+          "slug": "approve-packages-for-coding-agents"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "coding-services.md",
+      "markdown": "\n# Give coding runs the services their tests need\n\nA coding run can have a PostgreSQL, Redis or MySQL instance next to it for the\nlength of the run. Three parties agree before a service starts:\n\n- **The repository** declares it in `.wardby/services.yaml` on its base branch,\n  for example `services: { postgres: \"16\" }`. Wardby reads the file from the\n  run's base branch (the agent's `baseRef`, or a `baseRef` given to\n  `trigger_agent` for that run), never from the run's own branch, so a change\n  to the declaration takes effect only once it is merged into that base.\n- **The service catalog** says what each name and version is: a digest-pinned\n  image, its readiness check, resources, and the variables the agent's shells\n  receive (`testEnv`, such as `DATABASE_URL`). `list_services` and\n  `get_service` need `agents:read`. `create_service`, `update_service` and\n  `delete_service` need `services:manage` and the `admin` or\n  `service-manager` role. Built-in entries (`postgres` 15, 16 and 17, `redis`\n  7, `mysql` 8) cannot be changed over MCP.\n- **The agent's owner** lists the catalog names its runs may use in\n  `codingProfile.services`. An empty list, the default, allows none.\n\nAn agent with an empty list never reads the repository's declaration at all —\nwardby only looks at `.wardby/services.yaml` for an agent that allows at least\none service. Such an agent's runs simply start without services, whatever a\nrepository declares, and none of the errors below can apply to them.\n\nServices need the Kubernetes job launcher with Kubernetes 1.29 or later (each\nservice runs as a native sidecar in the run's pod) or the Docker job launcher\n(each service runs as its own container sharing the run's network namespace);\nboth start them for Codex and Claude Code agents. Each run gets its own empty\ninstance, reachable on `127.0.0.1`; the run's sandbox and network policy do\nnot change, and the instance is deleted with the run. Each service's CPU,\nmemory and disk count toward the run: on Kubernetes toward its pod, namespace\nquota and what a managed cluster bills; on Docker toward the host's memory,\nbecause its data is kept in memory.\n\nA bring-your-own worker image\n([`docs/coding-worker-byo-images.md`](../docs/coding-worker-byo-images.md))\nneeds driver v11 or later to run with services.\n\nCatalog values are visible to anyone with `agents:read`. Use throwaway test\ncredentials only; never put a real secret in `serviceEnv` or `testEnv`.\n\nEvery run protects `.wardby/**` except `.wardby/services.yaml`, so a coding\nagent may propose a declaration change in its pull request but cannot change\nother `.wardby/` files. An agent's own `protectedPaths` exceptions (entries\nstarting with `!`) must be literal file paths and cannot unprotect `.wardby/`.\n\nWhen upgrading a deployment that delegates to an identity provider, define the\n`services:manage` scope in the provider first; see\n[Configure identity and privileged access](identity-and-access.md).\n\nIf a run is refused or fails over its services, read the page for its code:\n\n- [`service_declaration_invalid`](errors/service-declaration-invalid.md)\n- [`service_declaration_unavailable`](errors/service-declaration-unavailable.md)\n- [`service_unknown`](errors/service-unknown.md)\n- [`service_not_allowed`](errors/service-not-allowed.md)\n- [`service_launcher_unsupported`](errors/service-launcher-unsupported.md)\n- [`service_unready`](errors/service-unready.md)\n\nRead [`docs/coding-services.md`](../docs/coding-services.md) for the file\nformat, catalog fields, built-in variables, custom entries, and capacity.\n",
+      "plainText": "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 triggeragent 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 DATABASEURL). listservices and getservice need agents:read. createservice, updateservice and deleteservice 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) 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. If a run is refused or fails over its services, read the page for its code: servicedeclarationinvalid servicedeclarationunavailable serviceunknown servicenotallowed servicelauncherunsupported serviceunready Read docs/coding-services.md for the file format, catalog fields, built-in variables, custom entries, and capacity.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Give coding runs the services their tests need",
+          "slug": "give-coding-runs-the-services-their-tests-need"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "creating-agents.md",
+      "markdown": "\n# Choose a native or coding agent\n\nCreate a **native agent** when Wardby should run a model with explicit,\nattached capabilities to produce a bounded operational result. Create a\n**coding agent** when the task must inspect and change a Git repository, run\nproject checks, and optionally open a draft pull request.\n\n| Choose       | Best for                                                                             | Execution model                                                                                    | Typical result                                                     |\n| ------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |\n| 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 |\n| 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 |\n\n## Start with a native agent\n\nNative agents are the default when a task does not need a full repository\nworkspace. Give the agent a narrow purpose, model, per-run budget, and only the\ntools or data it needs. Attach schedules or webhooks when the work should run\nwithout a person starting it manually.\n\nExamples include an architecture reviewer that writes findings to a datastore,\na release monitor that investigates an alert, or a triage agent that turns\nincoming information into a report for a person to act on.\n\n## Use a coding agent for repository work\n\nCoding agents use a `codingProfile` that selects Codex or Claude Code and names\nthe authorized repository. They run in isolated workers; Wardby keeps provider\ncredentials and the GitHub App private key in trusted components. A coding run\ncan change a checkout and run approved checks, but trusted finalization is what\nvalidates the result, pushes a controlled branch, and opens a draft pull\nrequest. It never auto-merges.\n\nBefore creating one, configure immutable worker images, the selected launcher,\nthe trusted coding proxy, and a narrowly installed GitHub App. The agent owner\nmust have the required repository access, or an administrator must explicitly\napprove the repository.\n\n## Decision checklist\n\nChoose a native agent when all of these are true:\n\n- The task can be completed with a narrow set of attached tools or data.\n- A repository checkout, shell-based project setup, and code changes are not\n  required.\n- The intended output is an analysis, report, decision, or controlled API\n  action.\n\nChoose a coding agent when any of these are true:\n\n- The agent must edit a repository or execute the project's test suite.\n- The reviewable outcome should be a branch or draft pull request.\n- The task needs a coding-agent builder such as Codex or Claude Code inside an\n  isolated workspace.\n\nDo not use a coding agent merely because a task is complex. Start with the\nleast powerful execution model that can safely produce the required outcome.\nRead [Connect GitHub repositories](github.md) and\n[Troubleshoot coding workers](troubleshooting/coding-workers.md) before\nenabling repository-changing work.\n",
+      "plainText": "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. 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. Read Connect GitHub repositories and Troubleshoot coding workers before enabling repository-changing work.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Choose a native or coding agent",
+          "slug": "choose-a-native-or-coding-agent"
+        },
+        {
+          "level": 2,
+          "text": "Start with a native agent",
+          "slug": "start-with-a-native-agent"
+        },
+        {
+          "level": 2,
+          "text": "Use a coding agent for repository work",
+          "slug": "use-a-coding-agent-for-repository-work"
+        },
+        {
+          "level": 2,
+          "text": "Decision checklist",
+          "slug": "decision-checklist"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "deploy-gke.md",
+      "markdown": "\n# Deploy Wardby on GKE Autopilot\n\nThe supported Google Cloud deployment creates a GKE Autopilot cluster, private\nCloud SQL for PostgreSQL, Artifact Registry, HTTPS Gateway, Google Secret\nManager synchronization, and isolated gVisor-backed **Codex** coding-worker\npods. It also applies namespace RBAC and default-deny network policies.\n\nUse a dedicated billed project, a hostname you control, remote Terraform state,\nand a GitHub App installed only on repositories that agents need. Review\nTerraform's plan and set cloud budgets before applying it: the deployment\ncreates billable resources.\n\nThe deployment process is:\n\n1. Install `gcloud`, Terraform, Docker with `linux/amd64` support, `kubectl`,\n   Helm, Node.js 24, and authenticate to the target project.\n2. Configure `deploy/gke/terraform.tfvars`, apply Terraform, and prepare the\n   Gateway's address, certificate map, Cloud Armor policy, and DNS record.\n3. Put first-time values in an untracked `.env.local`; `deploy/gke/up.sh`\n   seeds Secret Manager without overwriting existing production values.\n4. Run `HOSTNAME=wardby.example.com deploy/gke/up.sh`, then verify DNS,\n   certificate issuance, database IAM bootstrap, and service health.\n\nClaude Code's two-container executor is currently Docker-only; Kubernetes\ncoding workers use the Codex path. Configure an identity provider and GitHub\nApp before allowing people to use the public endpoint.\n\nFollow the complete, ordered guide at\n[`docs/getting-started-gke.md`](../docs/getting-started-gke.md). It includes\nthe precise IAM, DNS, bootstrap, upgrades, and teardown steps.\n",
+      "plainText": "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: Install gcloud, Terraform, Docker with linux/amd64 support, kubectl, Helm, Node.js 24, and authenticate to the target project. Configure deploy/gke/terraform.tfvars, apply Terraform, and prepare the Gateway's address, certificate map, Cloud Armor policy, and DNS record. Put first-time values in an untracked .env.local; deploy/gke/up.sh seeds Secret Manager without overwriting existing production values. Run HOSTNAME=wardby.example.com deploy/gke/up.sh, then verify DNS, certificate issuance, database IAM bootstrap, and service health. 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. It includes the precise IAM, DNS, bootstrap, upgrades, and teardown steps.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Deploy Wardby on GKE Autopilot",
+          "slug": "deploy-wardby-on-gke-autopilot"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "deployment-targets.md",
+      "markdown": "\n# Choose a deployment target\n\nWardby has one local path and two production-ready deployment shapes:\n\n- **Local development:** `wardby quickstart` runs the control plane locally\n  with its portable PostgreSQL container. It is the best place to evaluate,\n  develop agents, and connect a local Codex or Claude Code client.\n- **Production container baseline:** run the published production image with\n  PostgreSQL, HTTPS ingress, durable storage, backups, and an operator-owned\n  identity provider. The Compose and Caddy configuration is a reference\n  baseline, not a managed platform.\n- **Google Kubernetes Engine Autopilot:** the supported Google Cloud path. It\n  provisions GKE, private-IP Cloud SQL, Artifact Registry, isolated Codex\n  workers, HTTPS Gateway, and GCP-native secret and network controls. See\n  [Deploy on GKE](deploy-gke.md).\n\nAWS is supported as a portable runtime target and has a Bedrock Claude adapter,\nbut Wardby does not ship a native AWS deployment module. Other cloud providers\ncan run the production container image with equivalent database, ingress,\nidentity, secret, isolation, and observability controls; that infrastructure is\noperator-owned.\n\nThe older `deploy/gcp` Cloud Run module is deprecated. Do not choose it for a\nnew installation.\n\nBefore going live, complete the deployment security checklist and make a\nbackup, upgrades, alerting, and incident-response plan. Read\n[`docs/getting-started.md`](../docs/getting-started.md) for the local and\ncontainer setup, and [`docs/security-deployment.md`](../docs/security-deployment.md)\nfor the production controls.\n",
+      "plainText": "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. 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 for the local and container setup, and docs/security-deployment.md for the production controls.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Choose a deployment target",
+          "slug": "choose-a-deployment-target"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "errors/budget-group-exhausted.md",
+      "markdown": "\n# Budget group exhausted\n\nAn error such as `budget_group_exhausted:week` means the agent's budget group\nhas no capacity left for that period after accounting for actual spending and\nactive reservations. Wardby refuses the run before model work or a coding\nworker begins.\n\n1. Inspect the budget group's `spentUsd` and `reservedUsd` values.\n2. Inspect active and recent runs that use the group.\n3. Wait for the period to reset, cancel unneeded active work, or deliberately\n   adjust the agent or group budget.\n4. Trigger a new run after capacity is available; a refused run is not resumed\n   automatically.\n\nDo not raise a limit merely to clear a refusal without confirming the intended\nowner, schedule, and overlapping work. See [Budget troubleshooting](../troubleshooting/budgets.md).\n",
+      "plainText": "Budget group exhausted An error such as budgetgroupexhausted: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. Inspect the budget group's spentUsd and reservedUsd values. Inspect active and recent runs that use the group. Wait for the period to reset, cancel unneeded active work, or deliberately adjust the agent or group budget. 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.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Budget group exhausted",
+          "slug": "budget-group-exhausted"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "errors/docker-isolation-unsupported.md",
+      "markdown": "\n# Coding-worker isolation unavailable\n\n`docker_isolation_unsupported` means a required worker-isolation guarantee was\nmissing, unexpected, or could not be inspected. Wardby fails closed rather than\nrunning a worker with a weaker profile.\n\n1. Run `wardby coding preflight` and correct the reported launcher, image,\n   proxy-network, or host-support issue.\n2. Confirm worker images are immutable image IDs or digests, not mutable tags.\n3. Confirm the trusted proxy and worker use the intended isolated network and\n   that no unapproved host mount, Docker socket, environment, or network path\n   is present.\n4. Re-run preflight before triggering another coding run.\n\nIf the deployment target does not support the selected coding provider, choose\na supported launcher/provider combination instead of disabling the controls.\nSee [Coding-worker troubleshooting](../troubleshooting/coding-workers.md).\n",
+      "plainText": "Coding-worker isolation unavailable dockerisolationunsupported 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. Run wardby coding preflight and correct the reported launcher, image, proxy-network, or host-support issue. Confirm worker images are immutable image IDs or digests, not mutable tags. 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. 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.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Coding-worker isolation unavailable",
+          "slug": "coding-worker-isolation-unavailable"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "errors/protected-path.md",
+      "markdown": "\n# Run changed a protected path\n\nA run that failed with category `protected_path` finished its work, but the\nchanges it collected included a file its agent is not allowed to edit. Wardby\ndiscards the run's changes entirely rather than dropping just that file:\nnothing from the run reaches a pull request.\n\nWardby protects two kinds of paths on every coding run:\n\n- **The agent's own `protectedPaths`**, a list of glob patterns set on the\n  agent (`codingProfile.protectedPaths`, via `create_agent`/`update_agent`).\n  An entry may start with `!` to carve out one literal file as an exception\n  to the agent's own patterns; a whole tree can never be carved out this way.\n- **The `.wardby/` baseline**, which every coding run gets regardless of the\n  agent's own settings. It protects everything under `.wardby/` except the one\n  literal file `.wardby/services.yaml`, which any coding agent may propose a\n  change to (see [Coding services](../coding-services.md)) — the baseline\n  cannot be widened to cover that file, and no exception can narrow it further\n  than that.\n\nWhat to do:\n\n1. Ask again without changing the named file. If the change is small, doing it\n   yourself and letting the agent build on top is often fastest.\n2. If the agent genuinely needs to change that file, its owner (or an admin)\n   can widen `codingProfile.protectedPaths` with `update_agent` — for example\n   adding a `!`-prefixed exception for one file. This can never remove the\n   `.wardby/` baseline itself.\n3. Otherwise, the repository owner makes the change directly and the agent\n   works around it on the next run.\n\nWhen this run is a sub-run another agent dispatched (for example a router\nhanding work to a coding agent), the parent sees a failed sub-run on its own\nstatus comment: \"A sub-run could not open its changes: it changed a file its\nagent may not edit, so none of its changes were kept.\" That line never names\nthe file; check the sub-run's own PR comment or `get_run` for it.\n",
+      "plainText": "Run changed a protected path A run that failed with category protectedpath 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 createagent/updateagent). 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) — the baseline cannot be widened to cover that file, and no exception can narrow it further than that. What to do: 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. If the agent genuinely needs to change that file, its owner (or an admin) can widen codingProfile.protectedPaths with updateagent — for example adding a !-prefixed exception for one file. This can never remove the .wardby/ baseline itself. 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 getrun for it.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Run changed a protected path",
+          "slug": "run-changed-a-protected-path"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "errors/repo-access.md",
+      "markdown": "\n# Repository access refused\n\n`repo_access` means Wardby cannot authorize the agent owner's current access to\nthe selected repository. Nothing is cloned or pushed for a refusal at run\npreparation. The check also happens immediately before a coding run pushes, so\naccess lost during a run prevents publication.\n\n1. Confirm the agent has an owner and the intended repository is attached.\n2. Confirm that owner has linked their GitHub account to Wardby.\n3. Confirm the GitHub App is installed on the repository and the owner has the\n   required permission: write for coding work, read for a read-only link.\n4. If no individual owner can hold the access, ask a Wardby administrator to\n   record an explicit repository approval.\n5. Trigger a fresh run after the correction.\n\n`repo_access_unavailable` is different: GitHub could not be queried reliably.\nResolve the availability condition and retry later rather than treating it as\nan authorization success. See [Repository-access troubleshooting](../troubleshooting/repository-access.md).\n",
+      "plainText": "Repository access refused repoaccess 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. Confirm the agent has an owner and the intended repository is attached. Confirm that owner has linked their GitHub account to Wardby. 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. If no individual owner can hold the access, ask a Wardby administrator to record an explicit repository approval. Trigger a fresh run after the correction. repoaccessunavailable 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.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Repository access refused",
+          "slug": "repository-access-refused"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "errors/service-declaration-invalid.md",
+      "markdown": "\n# Service declaration invalid\n\n`service_declaration_invalid` means the repository's `.wardby/services.yaml`,\nread from the run's base branch, could not be used. The run's `error` names the\nline and reason. Wardby refuses the run before a coding worker starts.\n\n1. Check the file on the base branch. Its only key is `services`, mapping\n   catalog names (lowercase letters, digits and hyphens) to quoted version\n   strings, for example `postgres: \"16\"`.\n2. Keep it to at most five services and under 8 KiB. Images, ports, commands\n   and environment belong in the catalog, not in the repository.\n3. Merge the fix to the base branch; a fix on the run's own branch has no\n   effect.\n4. Trigger a new run; a refused run is not resumed automatically.\n\nThe same code is used when the declared services' instructions would push the\ncoding task over its size limit; declare fewer services in that case. See\n[Coding services](../coding-services.md).\n",
+      "plainText": "Service declaration invalid servicedeclarationinvalid 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. 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\". Keep it to at most five services and under 8 KiB. Images, ports, commands and environment belong in the catalog, not in the repository. Merge the fix to the base branch; a fix on the run's own branch has no effect. 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.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Service declaration invalid",
+          "slug": "service-declaration-invalid"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "errors/service-declaration-unavailable.md",
+      "markdown": "\n# Service declaration unavailable\n\n`service_declaration_unavailable` means Wardby could not read\n`.wardby/services.yaml` from the run's base branch through the GitHub App, so\nit could not tell which services the run needs. A missing file is not this\nerror (no file means no services); this is a failed read. Wardby refuses the\nrun rather than start it without services the repository may require.\n\n1. Trigger the run again; the cause is often a transient GitHub error.\n2. If it repeats, confirm the GitHub App installation still covers the\n   repository and has contents read access, and that the agent's base branch\n   exists.\n3. Check the control-plane logs around the refusal for the GitHub response.\n\nSee [Repository access troubleshooting](../troubleshooting/repository-access.md)\nand [Coding services](../coding-services.md).\n",
+      "plainText": "Service declaration unavailable servicedeclarationunavailable 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. Trigger the run again; the cause is often a transient GitHub error. 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. Check the control-plane logs around the refusal for the GitHub response. See Repository access troubleshooting and Coding services.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Service declaration unavailable",
+          "slug": "service-declaration-unavailable"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "errors/service-launcher-unsupported.md",
+      "markdown": "\n# Services are not available to this run\n\n`service_launcher_unsupported` means the repository declares services, but this\ndeployment cannot start them. Services need a job launcher that starts them:\n\n- `JOB_LAUNCHER=kubernetes` and `JOB_LAUNCHER=docker` start them for Codex and\n  Claude Code agents;\n- a deployment with `JOB_LAUNCHER=local` cannot start them at all.\n\n1. Run the coding agent on a deployment that uses the Kubernetes or Docker job\n   launcher, or\n2. remove `.wardby/services.yaml` from the base branch if the repository's\n   tests do not need the services.\n\nThis error only applies to an agent that already allows at least one service\n(`codingProfile.services` is non-empty): wardby reads a repository's\ndeclaration only for such an agent, and refuses rather than silently starting\nthe run without the services it names. An agent that allows no services never\nreads the declaration at all, so its runs are unaffected and start normally on\nany launcher. See [Coding-worker troubleshooting](../troubleshooting/coding-workers.md)\nand [Coding services](../coding-services.md).\n",
+      "plainText": "Services are not available to this run servicelauncherunsupported means the repository declares services, but this deployment cannot start them. Services need a job launcher that starts them: JOBLAUNCHER=kubernetes and JOBLAUNCHER=docker start them for Codex and Claude Code agents; a deployment with JOBLAUNCHER=local cannot start them at all. Run the coding agent on a deployment that uses the Kubernetes or Docker job launcher, or 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 and Coding services.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Services are not available to this run",
+          "slug": "services-are-not-available-to-this-run"
+        }
+      ]
+    },
+    {
+      "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",
+      "sourcePath": "errors/service-not-allowed.md",
+      "markdown": "\n# Service not allowed for this agent\n\n`service_not_allowed` means the repository declares a service that exists in\nthe catalog, but the agent's `codingProfile.services` does not list its name.\nWardby refuses the run before a coding worker starts.\n\n1. Confirm the repository should have the service; the declaration is on the\n   base branch in `.wardby/services.yaml`.\n2. If it should, the agent's owner (or an admin) adds the name, for example\n   `postgres`, to `codingProfile.services` with `update_agent`. Allowing a name\n   allows every version the catalog has for it.\n3. Trigger a new run.\n\nEach allowed service reserves CPU, memory and disk for the whole run, so allow\nonly what the agent's repositories need. This error implies the agent already\nallows at least one service — an agent whose `codingProfile.services` is empty\nnever reads the declaration at all, so it never reaches this check. See\n[Coding services](../coding-services.md).\n",
+      "plainText": "Service not allowed for this agent servicenotallowed 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. Confirm the repository should have the service; the declaration is on the base branch in .wardby/services.yaml. If it should, the agent's owner (or an admin) adds the name, for example postgres, to codingProfile.services with updateagent. Allowing a name allows every version the catalog has for it. 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.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Service not allowed for this agent",
+          "slug": "service-not-allowed-for-this-agent"
+        }
+      ]
+    },
+    {
+      "id": "errors/service-unknown",
+      "title": "Service not in the catalog",
+      "summary": "Wardby refused the coding run because the repository declares a service name and version the service catalog does not have.",
+      "audience": "operator",
+      "tags": [
+        "error",
+        "coding-agents",
+        "services",
+        "refusal"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "errors/service-unknown.md",
+      "markdown": "\n# Service not in the catalog\n\n`service_unknown` means `.wardby/services.yaml` on the base branch asks for a\nname and version, such as `postgres 14`, that has no entry in Wardby's service\ncatalog. Wardby refuses the run before a coding worker starts.\n\n1. Run `list_services` (needs `agents:read`) to see the names and versions\n   available.\n2. Either change the declaration on the base branch to an available version,\n   or ask someone with `services:manage` and the `admin` or `service-manager`\n   role to add the entry with `create_service`, pinned by digest.\n3. Trigger a new run once the catalog or the declaration matches.\n\nSee [Coding services](../coding-services.md).\n",
+      "plainText": "Service not in the catalog serviceunknown means .wardby/services.yaml on the base branch asks for a name and version, such as postgres 14, that has no entry in Wardby's service catalog. Wardby refuses the run before a coding worker starts. Run listservices (needs agents:read) to see the names and versions available. Either change the declaration on the base branch to an available version, or ask someone with services:manage and the admin or service-manager role to add the entry with createservice, pinned by digest. Trigger a new run once the catalog or the declaration matches. See Coding services.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Service not in the catalog",
+          "slug": "service-not-in-the-catalog"
+        }
+      ]
+    },
+    {
+      "id": "errors/service-unready",
+      "title": "Service did not become ready",
+      "summary": "A coding run failed at launch because one of its services never passed its readiness check.",
+      "audience": "operator",
+      "tags": [
+        "error",
+        "coding-agents",
+        "services",
+        "kubernetes",
+        "docker"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "errors/service-unready.md",
+      "markdown": "\n# Service did not become ready\n\nA run that failed with category `service_unready` (launcher error\n`coding_service_unready:<name>`) started, but the named service never became\nready, so the coding agent never started. A service is not ready when its\nreadiness command keeps failing past its failure threshold, its image cannot\nbe pulled or started, or it is still not ready when the launcher's start-up\nlimit runs out.\n\n1. On Kubernetes, inspect the run pod's init-container status and events for\n   the `service-<name>` container: image pull errors, crash loops, or probe\n   failures. On Docker the service's container is removed with the failed run,\n   so reproduce it on the Docker host: pull the entry's image and run it with\n   `--read-only`, `--user 10001:10001`, a `--tmpfs` at its `dataPath` and at\n   each `writablePaths` entry, and its `serviceEnv`; then run its readiness\n   command with `docker exec`.\n2. For a custom catalog entry, confirm the image runs as a non-root user with a\n   read-only root filesystem: every directory it writes to must be its\n   `dataPath` or one of its `writablePaths`. Probe over TCP on `127.0.0.1`\n   rather than a Unix socket.\n3. Each entry's readiness settings (`periodSeconds`, `timeoutSeconds`,\n   `failureThreshold`) apply within an overall start-up limit, whatever the\n   entry's own threshold would otherwise allow. On Kubernetes that limit is\n   the pod-start timeout (`KUBERNETES_READY_TIMEOUT_MS`, default 120000, an\n   operator setting) and includes image pulls; if first pulls on new nodes\n   are slow, raise it or mirror the image into a nearby registry. On Docker\n   the limit is a fixed 120 seconds covering every service of the run\n   together (they start one at a time), never runs past the run's own\n   timeout, and has no setting to raise it; image pulls are not counted in it\n   but may take up to 5 minutes each. The Docker launcher pulls without\n   registry credentials, so pull a private or rate-limited image on the\n   Docker host beforehand.\n4. Trigger a new run once the cause is fixed.\n\nWhen this run is a sub-run another agent dispatched (for example a router\nhanding work to a coding agent), the parent sees a failed sub-run on its own\nstatus comment, with a line naming the service: \"A sub-run could not start:\nThe `<name>` service didn't become ready, so the run couldn't start.\"\n\nSee [Coding services](../coding-services.md).\n",
+      "plainText": "Service did not become ready A run that failed with category serviceunready (launcher error codingserviceunready:<name) started, but the named service never became ready, so the coding agent never started. A service is not ready when its readiness command keeps failing past its failure threshold, its image cannot be pulled or started, or it is still not ready when the launcher's start-up limit runs out. On Kubernetes, inspect the run pod's init-container status and events for the service-<name container: image pull errors, crash loops, or probe failures. On Docker the service's container is removed with the failed run, so reproduce it on the Docker host: pull the entry's image and run it with --read-only, --user 10001:10001, a --tmpfs at its dataPath and at each writablePaths entry, and its serviceEnv; then run its readiness command with docker exec. For a custom catalog entry, confirm the image runs as a non-root user with a read-only root filesystem: every directory it writes to must be its dataPath or one of its writablePaths. Probe over TCP on 127.0.0.1 rather than a Unix socket. Each entry's readiness settings (periodSeconds, timeoutSeconds, failureThreshold) apply within an overall start-up limit, whatever the entry's own threshold would otherwise allow. On Kubernetes that limit is the pod-start timeout (KUBERNETESREADYTIMEOUTMS, default 120000, an operator setting) and includes image pulls; if first pulls on new nodes are slow, raise it or mirror the image into a nearby registry. On Docker the limit is a fixed 120 seconds covering every service of the run together (they start one at a time), never runs past the run's own timeout, and has no setting to raise it; image pulls are not counted in it but may take up to 5 minutes each. The Docker launcher pulls without registry credentials, so pull a private or rate-limited image on the Docker host beforehand. Trigger a new run once the cause is fixed. 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, with a line naming the service: \"A sub-run could not start: The <name service didn't become ready, so the run couldn't start.\" See Coding services.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Service did not become ready",
+          "slug": "service-did-not-become-ready"
+        }
+      ]
+    },
+    {
+      "id": "getting-started",
+      "title": "Get started with Wardby",
+      "summary": "Set up a local Wardby control plane, verify it, and choose the next guide.",
+      "audience": "operator",
+      "tags": [
+        "setup",
+        "quickstart",
+        "operator"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "getting-started.md",
+      "markdown": "\n# Get started with Wardby\n\nFrom the project you want Wardby to manage, run:\n\n```sh\nnpx --yes @wardby/cli@latest quickstart\n```\n\nThe quickstart creates local state under `.wardby/`, starts the local services,\napplies the required database migrations, and can register Wardby with Codex or\nClaude Code. Run `wardby doctor` afterwards to verify the local installation.\n\nUse [Operate agents](operating-agents.md) to create and supervise managed work.\nRead [Choose a native or coding agent](creating-agents.md) before creating your\nfirst agent.\nUse [MCP access](mcp.md) when connecting an MCP client. Before enabling coding\nagents against a repository, complete [GitHub integration](github.md).\nFor a self-hosted installation, start with [Choose a deployment target](deployment-targets.md)\nand [Configure identity and privileged access](identity-and-access.md).\n\nFor complete local setup and deployment prerequisites, read\n[`docs/getting-started.md`](../docs/getting-started.md).\n",
+      "plainText": "Get started with Wardby From the project you want Wardby to manage, run: npx --yes @wardby/cli@latest quickstart The quickstart creates local state under .wardby/, starts the local services, applies the required database migrations, and can register Wardby with Codex or Claude Code. Run wardby doctor afterwards to verify the local installation. Use Operate agents to create and supervise managed work. Read Choose a native or coding agent before creating your first agent. Use MCP access when connecting an MCP client. Before enabling coding agents against a repository, complete GitHub integration. For a self-hosted installation, start with Choose a deployment target and Configure identity and privileged access. For complete local setup and deployment prerequisites, read docs/getting-started.md.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Get started with Wardby",
+          "slug": "get-started-with-wardby"
+        }
+      ]
+    },
+    {
+      "id": "github-integration",
+      "title": "Connect GitHub repositories",
+      "summary": "Authorize repository access and configure Wardby coding or review agents through a scoped GitHub App.",
+      "audience": "operator",
+      "tags": [
+        "github",
+        "repositories",
+        "coding-agents",
+        "code-review"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "github.md",
+      "markdown": "\n# Connect GitHub repositories\n\nWardby uses a GitHub App installed only on the repositories an agent may use.\nRepository access is checked against the agent owner's linked GitHub account,\nor an explicitly recorded administrator approval. Coding agents need write\naccess because they can push a branch and open a draft pull request.\n\nWardby rechecks access before preparing a coding workspace and again before\npushing. Losing access, unlinking the account, or a failed access check stops\nthe run without publishing changes. See [Repository-access troubleshooting](troubleshooting/repository-access.md)\nfor the resulting refusal states.\n\nWorkers do not receive the GitHub App private key. A trusted component validates\nthe changes, pushes a controlled branch, and opens at most one draft pull\nrequest. Wardby does not auto-merge coding-agent output.\n\nRead [`docs/coding-agent-setup.md`](../docs/coding-agent-setup.md) for coding\nagent setup and [`docs/code-review-agents.md`](../docs/code-review-agents.md)\nfor pull-request review agents and webhook configuration.\nUse [Run GitHub code-review agents](code-review-agents.md) for the operator\noverview of checks, mentions, and fork limitations.\n",
+      "plainText": "Connect GitHub repositories Wardby uses a GitHub App installed only on the repositories an agent may use. Repository access is checked against the agent owner's linked GitHub account, or an explicitly recorded administrator approval. Coding agents need write access because they can push a branch and open a draft pull request. Wardby rechecks access before preparing a coding workspace and again before pushing. Losing access, unlinking the account, or a failed access check stops the run without publishing changes. See Repository-access troubleshooting for the resulting refusal states. Workers do not receive the GitHub App private key. A trusted component validates the changes, pushes a controlled branch, and opens at most one draft pull request. Wardby does not auto-merge coding-agent output. Read docs/coding-agent-setup.md for coding agent setup and docs/code-review-agents.md for pull-request review agents and webhook configuration. Use Run GitHub code-review agents for the operator overview of checks, mentions, and fork limitations.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Connect GitHub repositories",
+          "slug": "connect-github-repositories"
+        }
+      ]
+    },
+    {
+      "id": "identity-and-access",
+      "title": "Configure identity and privileged access",
+      "summary": "Protect remote MCP access with an OAuth/OIDC provider and restrict sensitive operations with scopes and roles.",
+      "audience": "operator",
+      "tags": [
+        "identity",
+        "oauth",
+        "oidc",
+        "access-control",
+        "mcp"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "identity-and-access.md",
+      "markdown": "\n# Configure identity and privileged access\n\nLocal stdio MCP created by `wardby quickstart` trusts the local operator. A\nshared HTTPS deployment needs an OAuth/OIDC identity provider. In delegating\nmode, that provider authenticates the caller and issues a signed JWT access\ntoken; Wardby verifies the token and enforces its scopes without administering\nthe provider's users or exchanging authorization codes.\n\nSet the provider's resource audience, `MCP_CANONICAL_URI`, and `AUTH_AUDIENCE`\nto the exact same public MCP URL. Tokens need a stable subject, expiry, issuer,\naudience, and the granted Wardby scopes in `scope` or `scp`.\n\nScopes authorize normal operations such as managing agents, runs, tools,\ndatastores, secrets, webhooks, budgets, packages, services, and memory. Three\nsensitive permissions have an additional role requirement:\n\n- `agents:admin` requires the Wardby `admin` role.\n- `packages:approve` requires the `admin` or `package-approver` role.\n- `services:manage` requires the `admin` or `service-manager` role.\n\nMap roles only from an IdP claim that users cannot self-assign. Removing a\nrole affects the next token the caller receives.\n\nWhen you upgrade a delegating-mode deployment, define any newly advertised\nscope, such as `services:manage`, in the provider before deploying. Clients\nthat request every advertised scope otherwise fail with `invalid_scope`.\n\nRead [`docs/getting-started-identity-provider.md`](../docs/getting-started-identity-provider.md)\nfor the required claims, scope list, role mapping, provider examples, and\nclient registration.\n",
+      "plainText": "Configure identity and privileged access Local stdio MCP created by wardby quickstart trusts the local operator. A shared HTTPS deployment needs an OAuth/OIDC identity provider. In delegating mode, that provider authenticates the caller and issues a signed JWT access token; Wardby verifies the token and enforces its scopes without administering the provider's users or exchanging authorization codes. Set the provider's resource audience, MCPCANONICALURI, and AUTHAUDIENCE to the exact same public MCP URL. Tokens need a stable subject, expiry, issuer, audience, and the granted Wardby scopes in scope or scp. Scopes authorize normal operations such as managing agents, runs, tools, datastores, secrets, webhooks, budgets, packages, services, and memory. Three sensitive permissions have an additional role requirement: agents:admin requires the Wardby admin role. packages:approve requires the admin or package-approver role. services:manage requires the admin or service-manager role. Map roles only from an IdP claim that users cannot self-assign. Removing a role affects the next token the caller receives. When you upgrade a delegating-mode deployment, define any newly advertised scope, such as services:manage, in the provider before deploying. Clients that request every advertised scope otherwise fail with invalidscope. Read docs/getting-started-identity-provider.md for the required claims, scope list, role mapping, provider examples, and client registration.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Configure identity and privileged access",
+          "slug": "configure-identity-and-privileged-access"
+        }
+      ]
+    },
+    {
+      "id": "mcp-access",
+      "title": "Connect an MCP client",
+      "summary": "Use Wardby's local stdio or protected HTTP MCP transport safely.",
+      "audience": "developer",
+      "tags": [
+        "mcp",
+        "oauth",
+        "codex",
+        "claude-code"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "mcp.md",
+      "markdown": "\n# Connect an MCP client\n\nFor local use, `wardby quickstart` can register the local stdio MCP server with\nCodex or Claude Code. Local stdio trusts the local operator.\n\nFor remote access, Wardby exposes an OAuth 2.1-protected HTTP resource server.\nRun the service with `MCP_TRANSPORT=http`, set a canonical public URI, and use\nthe instance's configured identity-provider mode. Keep the MCP endpoint behind\nyour intended ingress and authentication boundary.\n\nMCP clients use Wardby to manage agents, budgets, tools, schedules, secrets,\ndatastores, and runs. They do not receive the provider or GitHub App\ncredentials held by Wardby's trusted components.\n\nWith the existing `agents:read` scope, clients can also use `search_help` to\nfind bundled self-hosted guidance with fuzzy matching and `get_help_article`\nto read a complete article by id. These tools use the same release-bundled,\noffline catalog as `wardby help`; they expose no instance data or credentials.\n\nSee [`docs/getting-started-identity-provider.md`](../docs/getting-started-identity-provider.md)\nfor the supported self-hosted and delegated identity-provider setup.\n",
+      "plainText": "Connect an MCP client For local use, wardby quickstart can register the local stdio MCP server with Codex or Claude Code. Local stdio trusts the local operator. For remote access, Wardby exposes an OAuth 2.1-protected HTTP resource server. Run the service with MCPTRANSPORT=http, set a canonical public URI, and use the instance's configured identity-provider mode. Keep the MCP endpoint behind your intended ingress and authentication boundary. MCP clients use Wardby to manage agents, budgets, tools, schedules, secrets, datastores, and runs. They do not receive the provider or GitHub App credentials held by Wardby's trusted components. With the existing agents:read scope, clients can also use searchhelp to find bundled self-hosted guidance with fuzzy matching and gethelparticle to read a complete article by id. These tools use the same release-bundled, offline catalog as wardby help; they expose no instance data or credentials. See docs/getting-started-identity-provider.md for the supported self-hosted and delegated identity-provider setup.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Connect an MCP client",
+          "slug": "connect-an-mcp-client"
+        }
+      ]
+    },
+    {
+      "id": "native-capabilities",
+      "title": "Use native agents, tools, and data",
+      "summary": "Attach scoped tools, secrets, datastores, memory, schedules, and sub-agents to a native Wardby agent.",
+      "audience": "developer",
+      "tags": [
+        "agents",
+        "tools",
+        "secrets",
+        "datastores",
+        "memory",
+        "schedules",
+        "subagents"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "native-capabilities.md",
+      "markdown": "\n# Use native agents, tools, and data\n\nNative agents work through the Wardby control plane rather than a repository\ncheckout. Give each agent only the capabilities its job needs:\n\n- **Tools** for approved external actions or APIs.\n- **Secrets** as bindings to tools or agents; values remain in Wardby's trusted\n  components rather than being returned through MCP.\n- **Datastores** for scoped application data and queries.\n- **Memory** for agent-owned durable context.\n- **Schedules and webhooks** to start event-driven work.\n- **Sub-agents** for delegated, bounded work with their own capability set.\n\nUse a budget or shared budget group on every agent, and inspect runs before\nexpanding its access. An access grant is intentional delegation: use it only\nwhen an owner permits one agent to use another resource. Creating or changing\ntools, secrets, datastores, schedules, webhooks, memory, and budget groups\nrequires the matching MCP scope.\n\nSee [Operate agents](operating-agents.md) for run and budget management, and\n[`README.md`](../README.md) for the feature overview and MCP operations.\n",
+      "plainText": "Use native agents, tools, and data Native agents work through the Wardby control plane rather than a repository checkout. Give each agent only the capabilities its job needs: Tools for approved external actions or APIs. Secrets as bindings to tools or agents; values remain in Wardby's trusted components rather than being returned through MCP. Datastores for scoped application data and queries. Memory for agent-owned durable context. Schedules and webhooks to start event-driven work. Sub-agents for delegated, bounded work with their own capability set. Use a budget or shared budget group on every agent, and inspect runs before expanding its access. An access grant is intentional delegation: use it only when an owner permits one agent to use another resource. Creating or changing tools, secrets, datastores, schedules, webhooks, memory, and budget groups requires the matching MCP scope. See Operate agents for run and budget management, and README.md for the feature overview and MCP operations.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Use native agents, tools, and data",
+          "slug": "use-native-agents-tools-and-data"
+        }
+      ]
+    },
+    {
+      "id": "observability",
+      "title": "Monitor Wardby",
+      "summary": "Scrape private Prometheus metrics and build production alerting around the coding proxy and run lifecycle.",
+      "audience": "operator",
+      "tags": [
+        "observability",
+        "prometheus",
+        "grafana",
+        "metrics",
+        "operations"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "observability.md",
+      "markdown": "\n# Monitor Wardby\n\nWhen `METRICS_BIND` is configured, Wardby's coding proxy exposes Prometheus\nmetrics at `/metrics`. Keep that endpoint on a private network and permit only\nyour collector to scrape it. Metrics cover proxy requests, errors, latency,\naudit events, model cost, reserved and actual budget spend, coding outcomes,\nand Node.js process health; they intentionally exclude prompts, repository\ncontent, credentials, diffs, raw worker output, and run identifiers.\n\nFor a local dashboard stack, run:\n\n```sh\nnpm run observability:up\nnpm run observability:smoke\n```\n\nThis starts Prometheus and Grafana locally. Use `npm run observability:down`\nwhen finished.\n\nIn production, configure your own Prometheus-compatible collector, retention,\nprivate connectivity, alerts, and SLOs. GCP operators can use the Ops Agent or\nManaged Service for Prometheus; AWS operators can use the CloudWatch Agent\nPrometheus collector. Wardby's reference cloud deployments do not provision\nthem, and application/MCP metrics are currently narrower than coding-proxy\nmetrics.\n\nAlert on proxy failures, budget cutoffs, cleanup failures, stalled runs, and\nsustained latency or memory growth. Wardby's database remains the source of\ntruth for runs, budgets, and accounting.\n\nRead [`docs/observability.md`](../docs/observability.md) for configuration and\nthe full production checklist.\n",
+      "plainText": "Monitor Wardby When METRICSBIND is configured, Wardby's coding proxy exposes Prometheus metrics at /metrics. Keep that endpoint on a private network and permit only your collector to scrape it. Metrics cover proxy requests, errors, latency, audit events, model cost, reserved and actual budget spend, coding outcomes, and Node.js process health; they intentionally exclude prompts, repository content, credentials, diffs, raw worker output, and run identifiers. For a local dashboard stack, run: npm run observability:up npm run observability:smoke This starts Prometheus and Grafana locally. Use npm run observability:down when finished. In production, configure your own Prometheus-compatible collector, retention, private connectivity, alerts, and SLOs. GCP operators can use the Ops Agent or Managed Service for Prometheus; AWS operators can use the CloudWatch Agent Prometheus collector. Wardby's reference cloud deployments do not provision them, and application/MCP metrics are currently narrower than coding-proxy metrics. Alert on proxy failures, budget cutoffs, cleanup failures, stalled runs, and sustained latency or memory growth. Wardby's database remains the source of truth for runs, budgets, and accounting. Read docs/observability.md for configuration and the full production checklist.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Monitor Wardby",
+          "slug": "monitor-wardby"
+        }
+      ]
+    },
+    {
+      "id": "operating-agents",
+      "title": "Operate managed agents",
+      "summary": "Understand the identity, budget, capabilities, triggers, and result of a Wardby-managed agent.",
+      "audience": "operator",
+      "tags": [
+        "agents",
+        "budgets",
+        "schedules",
+        "runs"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "operating-agents.md",
+      "markdown": "\n# Operate managed agents\n\nEvery Wardby-managed agent has an owner, system prompt, model, per-run budget,\nand explicitly attached capabilities. A run starts only when its identity,\npolicy, and available budget agree.\n\nCreate, update, pause, trigger, and inspect agents through Wardby's MCP tools.\nThe CLI is the bootstrap and operations fallback. Scheduled work requires a\nrunning scheduler: `wardby serve` runs MCP, scheduler, and reconciliation in\none process; `wardby mcp` alone does not execute schedules.\n\nUse [Choose a native or coding agent](creating-agents.md) to select the least\npowerful execution model that can safely produce the desired outcome.\n\nBefore a run starts, Wardby reserves its allowed spend. The reservation is\nconstrained by the agent's own budget, any shared budget group, and any\nsub-agent run tree. See [Budget troubleshooting](troubleshooting/budgets.md)\nwhen a run is refused for lack of budget.\n\nFor the full lifecycle and the controls applied to every managed run, read\n[`README.md`](../README.md).\n",
+      "plainText": "Operate managed agents Every Wardby-managed agent has an owner, system prompt, model, per-run budget, and explicitly attached capabilities. A run starts only when its identity, policy, and available budget agree. Create, update, pause, trigger, and inspect agents through Wardby's MCP tools. The CLI is the bootstrap and operations fallback. Scheduled work requires a running scheduler: wardby serve runs MCP, scheduler, and reconciliation in one process; wardby mcp alone does not execute schedules. Use Choose a native or coding agent to select the least powerful execution model that can safely produce the desired outcome. Before a run starts, Wardby reserves its allowed spend. The reservation is constrained by the agent's own budget, any shared budget group, and any sub-agent run tree. See Budget troubleshooting when a run is refused for lack of budget. For the full lifecycle and the controls applied to every managed run, read README.md.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Operate managed agents",
+          "slug": "operate-managed-agents"
+        }
+      ]
+    },
+    {
+      "id": "security-boundaries",
+      "title": "Understand Wardby security boundaries",
+      "summary": "Review the isolation, credential, budget, and action-authority controls that apply to managed work.",
+      "audience": "operator",
+      "tags": [
+        "security",
+        "isolation",
+        "credentials",
+        "budgets"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "security.md",
+      "markdown": "\n# Understand Wardby security boundaries\n\nWardby is designed to make agent work bounded and reviewable. It applies hard\nper-agent and shared-budget limits, grants only explicitly attached tools,\nsecrets, datastores, and sub-agents, and records a durable result.\n\nNative tools run in a constrained QuickJS environment. Coding agents use\nisolated workers with bounded resources and a trusted proxy. Workers do not\nreceive provider credentials or the GitHub App private key. Coding finalization\ncreates a draft pull request; it does not grant the worker merge authority.\n\nTreat the deployment boundary as part of the security model. Restrict Docker or\nKubernetes administrator access, protect secrets, constrain network egress,\nand read the deployment guide before enabling a production repository.\n\nSee [`docs/security-deployment.md`](../docs/security-deployment.md) and\n[`docs/coding-worker-isolation.md`](../docs/coding-worker-isolation.md) for\nthe detailed operational model.\n",
+      "plainText": "Understand Wardby security boundaries Wardby is designed to make agent work bounded and reviewable. It applies hard per-agent and shared-budget limits, grants only explicitly attached tools, secrets, datastores, and sub-agents, and records a durable result. Native tools run in a constrained QuickJS environment. Coding agents use isolated workers with bounded resources and a trusted proxy. Workers do not receive provider credentials or the GitHub App private key. Coding finalization creates a draft pull request; it does not grant the worker merge authority. Treat the deployment boundary as part of the security model. Restrict Docker or Kubernetes administrator access, protect secrets, constrain network egress, and read the deployment guide before enabling a production repository. See docs/security-deployment.md and docs/coding-worker-isolation.md for the detailed operational model.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Understand Wardby security boundaries",
+          "slug": "understand-wardby-security-boundaries"
+        }
+      ]
+    },
+    {
+      "id": "troubleshooting/budgets",
+      "title": "Troubleshoot budgets and reservations",
+      "summary": "Diagnose run refusals caused by an exhausted agent, shared budget group, or sub-agent run tree.",
+      "audience": "operator",
+      "tags": [
+        "budgets",
+        "reservations",
+        "refusals",
+        "scheduling"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "troubleshooting/budgets.md",
+      "markdown": "\n# Troubleshoot budgets and reservations\n\nWardby reserves budget when it dispatches a run. The reservation is limited by\nthe agent's `budgetUsd`, the remaining shared daily, weekly, or monthly budget\ngroup capacity, and the remaining parent run-tree capacity for a sub-agent.\n\nWhen no capacity remains, Wardby records the run as refused and does not start\na worker. Common errors include `budget_group_exhausted:day`,\n`budget_group_exhausted:week`, `budget_group_exhausted:month`, and\n`run_tree_exhausted`.\n\nInspect the agent, its budget group, and recent runs before increasing a limit.\nIn-progress runs retain their unspent reservation, so overlapping scheduled,\nwebhook, and manual runs share one cap rather than each assuming the full\nremaining balance.\n\nFor a shared-group refusal, read [Budget group exhausted](../errors/budget-group-exhausted.md).\n",
+      "plainText": "Troubleshoot budgets and reservations Wardby reserves budget when it dispatches a run. The reservation is limited by the agent's budgetUsd, the remaining shared daily, weekly, or monthly budget group capacity, and the remaining parent run-tree capacity for a sub-agent. When no capacity remains, Wardby records the run as refused and does not start a worker. Common errors include budgetgroupexhausted:day, budgetgroupexhausted:week, budgetgroupexhausted:month, and runtreeexhausted. Inspect the agent, its budget group, and recent runs before increasing a limit. In-progress runs retain their unspent reservation, so overlapping scheduled, webhook, and manual runs share one cap rather than each assuming the full remaining balance. For a shared-group refusal, read Budget group exhausted.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Troubleshoot budgets and reservations",
+          "slug": "troubleshoot-budgets-and-reservations"
+        }
+      ]
+    },
+    {
+      "id": "troubleshooting/coding-workers",
+      "title": "Troubleshoot coding workers",
+      "summary": "Investigate coding-worker setup, isolation preflight, and safe failure handling.",
+      "audience": "operator",
+      "tags": [
+        "coding-agents",
+        "docker",
+        "kubernetes",
+        "isolation",
+        "services"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "troubleshooting/coding-workers.md",
+      "markdown": "\n# Troubleshoot coding workers\n\nBefore enabling a coding agent, configure an immutable worker image, the\ntrusted coding proxy, a scoped GitHub App installation, and the selected job\nlauncher. Run `wardby coding preflight` after changing the Docker or Kubernetes\nconfiguration.\n\nWardby refuses to weaken an isolation profile when a required host feature,\nnetwork setting, mount, environment, or cleanup guarantee cannot be verified.\nInvestigate the host configuration instead of bypassing the refusal.\n\nCodex and Claude Code workers have different supported launcher combinations.\nReview the deployment guide for your target before assigning a coding profile.\n\nFor the specific isolation refusal, read [Coding-worker isolation unavailable](../errors/docker-isolation-unsupported.md).\n\n## Service refusals and failures\n\nA repository can declare services such as PostgreSQL in `.wardby/services.yaml`\non its base branch. Wardby checks the declaration, the service catalog, and the\nagent's `codingProfile.services` before a run starts, and refuses the run with a\n`service_*` code when they disagree. The run's `error` (from `get_run`) is the\ncode followed by a sentence the requester also sees on the run's status comment.\n\n- [`service_declaration_invalid`](../errors/service-declaration-invalid.md):\n  the file on the base branch is not a valid declaration.\n- [`service_declaration_unavailable`](../errors/service-declaration-unavailable.md):\n  Wardby could not read the file through the GitHub App.\n- [`service_unknown`](../errors/service-unknown.md): the catalog has no such\n  name and version.\n- [`service_not_allowed`](../errors/service-not-allowed.md): the agent does not\n  allow that service.\n- [`service_launcher_unsupported`](../errors/service-launcher-unsupported.md):\n  services need the Kubernetes or Docker job launcher.\n- [`service_unready`](../errors/service-unready.md): the run started but a\n  service never became ready (launcher error `coding_service_unready:<name>`).\n\nSee [Coding services](../coding-services.md).\n",
+      "plainText": "Troubleshoot coding workers Before enabling a coding agent, configure an immutable worker image, the trusted coding proxy, a scoped GitHub App installation, and the selected job launcher. Run wardby coding preflight after changing the Docker or Kubernetes configuration. Wardby refuses to weaken an isolation profile when a required host feature, network setting, mount, environment, or cleanup guarantee cannot be verified. Investigate the host configuration instead of bypassing the refusal. Codex and Claude Code workers have different supported launcher combinations. Review the deployment guide for your target before assigning a coding profile. For the specific isolation refusal, read Coding-worker isolation unavailable. Service refusals and failures A repository can declare services such as PostgreSQL in .wardby/services.yaml on its base branch. Wardby checks the declaration, the service catalog, and the agent's codingProfile.services before a run starts, and refuses the run with a service code when they disagree. The run's error (from getrun) is the code followed by a sentence the requester also sees on the run's status comment. servicedeclarationinvalid: the file on the base branch is not a valid declaration. servicedeclarationunavailable: Wardby could not read the file through the GitHub App. serviceunknown: the catalog has no such name and version. servicenotallowed: the agent does not allow that service. servicelauncherunsupported: services need the Kubernetes or Docker job launcher. serviceunready: the run started but a service never became ready (launcher error codingserviceunready:<name). See Coding services.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Troubleshoot coding workers",
+          "slug": "troubleshoot-coding-workers"
+        },
+        {
+          "level": 2,
+          "text": "Service refusals and failures",
+          "slug": "service-refusals-and-failures"
+        }
+      ]
+    },
+    {
+      "id": "troubleshooting/repository-access",
+      "title": "Troubleshoot repository access",
+      "summary": "Diagnose why Wardby refused repository work or could not verify the agent owner's GitHub access.",
+      "audience": "operator",
+      "tags": [
+        "github",
+        "repositories",
+        "authorization",
+        "refusals"
+      ],
+      "appliesTo": ">=0.2.1",
+      "sourcePath": "troubleshooting/repository-access.md",
+      "markdown": "\n# Troubleshoot repository access\n\nWardby checks that the owner of a coding or repository-linked agent has the\nrequired current GitHub permission. A coding repository requires write access;\na read-only repository link requires read access. An administrator can record a\nrepository approval when no individual's access is appropriate.\n\n`repo_access` means the current owner no longer has the required permission,\nhas unlinked their account, or the repository was not authorized. Restore the\nowner's GitHub link and permission, or have an administrator review and record\nthe appropriate repository authorization.\n\n`repo_access_unavailable` means Wardby could not verify GitHub access after its\nretry. Do not treat it as permission granted: resolve the GitHub/API condition\nand re-run the work later.\n\nRead [Repository access refused](../errors/repo-access.md) for the safe\nremediation sequence.\n",
+      "plainText": "Troubleshoot repository access Wardby checks that the owner of a coding or repository-linked agent has the required current GitHub permission. A coding repository requires write access; a read-only repository link requires read access. An administrator can record a repository approval when no individual's access is appropriate. repoaccess means the current owner no longer has the required permission, has unlinked their account, or the repository was not authorized. Restore the owner's GitHub link and permission, or have an administrator review and record the appropriate repository authorization. repoaccessunavailable means Wardby could not verify GitHub access after its retry. Do not treat it as permission granted: resolve the GitHub/API condition and re-run the work later. Read Repository access refused for the safe remediation sequence.",
+      "headings": [
+        {
+          "level": 1,
+          "text": "Troubleshoot repository access",
+          "slug": "troubleshoot-repository-access"
+        }
+      ]
+    }
+  ]
+}