@wardby/cli 0.2.0 → 0.3.0

package/help/code-review-agents.md

@@ -0,0 +1,31 @@
+---
+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
+---
+
+# 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`](../docs/code-review-agents.md).

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/creating-agents.md

@@ -0,0 +1,68 @@
+---
+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.
+
+## 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](github.md) and
+[Troubleshoot coding workers](troubleshooting/coding-workers.md) before
+enabling repository-changing work.

package/help/deploy-gke.md

@@ -0,0 +1,39 @@
+---
+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.
+
+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/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).

package/help/errors/service-unknown.md

@@ -0,0 +1,23 @@
+---
+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
+---
+
+# Service not in the catalog
+
+`service_unknown` 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.
+
+1. Run `list_services` (needs `agents:read`) to see the names and versions
+   available.
+2. 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 `create_service`, pinned by digest.
+3. Trigger a new run once the catalog or the declaration matches.
+
+See [Coding services](../coding-services.md).

package/help/errors/service-unready.md

@@ -0,0 +1,49 @@
+---
+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
+---
+
+# Service did not become ready
+
+A run that failed with category `service_unready` (launcher error
+`coding_service_unready:<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.
+
+1. 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`.
+2. 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.
+3. 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 (`KUBERNETES_READY_TIMEOUT_MS`, 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.
+4. 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](../coding-services.md).

package/help/getting-started.md

@@ -0,0 +1,31 @@
+---
+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
+---
+
+# Get started with Wardby
+
+From the project you want Wardby to manage, run:
+
+```sh
+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](operating-agents.md) to create and supervise managed work.
+Read [Choose a native or coding agent](creating-agents.md) before creating your
+first agent.
+Use [MCP access](mcp.md) when connecting an MCP client. Before enabling coding
+agents against a repository, complete [GitHub integration](github.md).
+For a self-hosted installation, start with [Choose a deployment target](deployment-targets.md)
+and [Configure identity and privileged access](identity-and-access.md).
+
+For complete local setup and deployment prerequisites, read
+[`docs/getting-started.md`](../docs/getting-started.md).