@wardby/cli 0.4.1 → 0.5.1

package/help/code-review-agents.md

@@ -3,7 +3,7 @@ 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]
+tags: [github, code-review, pull-requests, webhooks, ci, checks, waitForCi]
 appliesTo: >=0.2.1
 ---
 
@@ -26,12 +26,92 @@ A mention on a pull request that a wardby coding run opened continues that
 run's branch. If this deployment has no record of the run that opened it (for
 example, another wardby deployment sharing the same GitHub App opened it), the
 App replies that it cannot continue the pull request instead of starting a
-run. Ask the deployment that opened it, or change the branch by hand.
+run. Ask the deployment that opened it, or change the branch by hand. A
+continuation also never pushes to a pull request that has since been merged
+or closed — see
+[Continuation's pull request is no longer open](errors/continuation-closed.md).
+
+To review a branch of a git repository on the wardby host, without GitHub, see
+[Use local git repositories](local-repositories.md).
+
+A repository can also be linked so wardby fixes its own review's findings on
+such a pull request automatically, up to a round cap — see
+[Automatic review fix rounds](review-fix-rounds.md).
 
 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.
 
+## CI and sibling pull requests
+
+`repo_pr_read` also returns `ci`: the CI check runs and commit statuses on the
+pull request's head commit (Wardby's own checks left out), an overall state,
+and a note. CI is the authority on whether the head builds and passes its
+tests. The **Tests** list in a Wardby pull request's description was run in
+Wardby's coding sandbox, which may have had an incomplete install (see the
+**Dependency install incomplete** warning). Checks still running are reported
+as pending.
+
+If a review publishes only a comment while CI on the head is still running (or
+has not reported yet), Wardby runs that review again once CI on the same head
+has finished, so it can approve or request changes against the real result.
+This happens at most once per head commit for each reviewer, only while the pull request is open
+and still at that commit, and needs the App's **Check suite** event. CI that
+reports only commit statuses (no check suites) does not trigger it, nor does a
+commit status still pending when the last check suite finishes; use **Re-run**
+on the review check instead.
+
+Commit statuses need the App's **Commit statuses: Read** permission; without
+it only check runs are shown.
+
+## Review after CI (`waitForCi`)
+
+A `pull_request` link can set `waitForCi: true` so this reviewer reviews a
+pushed head only after that head's own CI has finished, instead of racing
+it. The gate below keeps it from approving while CI on that head is known
+to be failing or still running; see the gate's own exceptions for when CI
+can't be read or this run doesn't own the check.
+
+On a push, Wardby reads CI on the new head before starting a `waitForCi`
+reviewer. If CI is still pending, or nothing has reported yet, the review is
+held rather than started; it starts once CI finishes (the same **Check
+suite** event used for the re-review above), or — if CI never finishes —
+after 15 minutes anyway. CI that reports only commit statuses (no check
+suites), or a status still pending when the last check suite finishes,
+never releases a held review early; it starts only at that 15-minute
+fallback. The 15-minute fallback, and the 24-hour drop below, only run
+where Wardby's scheduler process runs (`wardby scheduler`, or `wardby
+serve` with the scheduler enabled); on an instance running only `wardby
+mcp`, a held review starts only once a **Check suite** event arrives, so
+with status-only CI it can wait indefinitely. A review still held after 24
+hours is dropped. This is decided per pull request, never across a set of
+related pull requests.
+
+While CI on the head is failing or still running, `repo_publish_review`
+refuses an approve verdict on a `waitForCi` reviewer's own check, returning
+a tool error instead of publishing anything:
+
+- `ci_failing` — CI is failing; request changes (or comment) instead.
+- `ci_pending` — CI is still running; comment instead. The re-review above
+  then runs the review again once a CI check suite finishes.
+
+Requesting changes or commenting is never affected by this gate. When CI
+cannot be read at all, the gate is skipped and the review proceeds as it
+would without `waitForCi`.
+
+Add this to a reviewer's system prompt:
+
+    Reviewer step (CI and related pull requests). Read `ci` from repo_pr_read.
+    When `ci` and the description's Tests disagree, follow CI and say so; never
+    ask for a fix only because a sandbox test failed while CI passed. Report
+    pending checks as pending. If the description has a "Related pull requests"
+    section, a field, route or schema the change relies on may be added by one
+    of those pull requests: do not report it as missing; note the dependency
+    and the suggested merge order instead.
+
+Wardby also writes that section: see
+[Related pull requests across repositories](related-pull-requests.md).
+
 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

@@ -3,7 +3,7 @@ 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]
+tags: [coding-agents, packages, npm, pypi, supply-chain, refusals, lockfile]
 appliesTo: >=0.2.1
 ---
 
@@ -27,5 +27,16 @@ 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.
 
+When the registry refuses a package, the pull request opens with a
+**Dependency install incomplete** warning naming each refused package and
+any lock file the run changed. A changed lock file may then fail a clean
+install in CI until it is regenerated, and the run's status comment shows ⚠️
+if its own checks failed. A package reachable only through a refused one is
+refused too, so a high-severity advisory deep in a toolchain blocks every run
+that installs it.
+
+Review agents see the pull request's CI results in `repo_pr_read` and are
+told to trust CI over the sandbox's **Tests**.
+
 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

@@ -58,6 +58,10 @@ 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).
 
+For a repository on the wardby host (`local:/absolute/path`), the declaration is
+read from the committed file at the run's base ref, never the working tree; see
+[Use local git repositories](local-repositories.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)

package/help/cost-attribution.md

@@ -16,7 +16,9 @@ A run is attributed to an issue when:
 
 - a Jira event on that issue started it;
 - it reviews, or answers an `@wardby` mention on, a pull request Wardby opened
-  for the issue;
+  for the issue — including a review that starts while the agent that asked
+  for the pull request is still running, before the pull request is linked to
+  the issue (Wardby then uses the issue of the coding run that opened it);
 - `trigger_agent` named an `issue`, or a webhook call's JSON body named a
   `wardbyIssue`, as `{ "provider": "jira", "key": "PROJ-123" }`, in a project
   the agent is linked to. Keys are matched without regard to case

package/help/creating-agents.md

@@ -85,6 +85,9 @@ A coding agent can also keep a repository's architecture knowledge current; see
 For an `@mention` builder with a router, see [Agent recipes](help://agent-recipes) and
 [Builder and router prompts](help://builder-agent).
 
+A coding or review agent can also use a git folder on the wardby host instead of a
+GitHub repository; see [Use local git repositories](local-repositories.md).
+
 Read [Connect GitHub repositories](github.md) and
 [Troubleshoot coding workers](troubleshooting/coding-workers.md) before
 enabling repository-changing work.

package/help/deploy-gke.md

@@ -3,7 +3,7 @@ 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]
+tags: [deployment, gke, gcp, kubernetes, production, secrets, jira]
 appliesTo: >=0.2.1
 ---
 
@@ -27,6 +27,7 @@ The deployment process is:
    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.
+   Jira settings are optional there, all or none; see [Jira](jira.md).
 4. Run `HOSTNAME=wardby.example.com deploy/gke/up.sh`, then verify DNS,
    certificate issuance, database IAM bootstrap, and service health.
 

package/help/errors/coding-provider-not-configured.md

@@ -0,0 +1,60 @@
+---
+id: errors/coding-provider-not-configured
+title: Coding provider not configured
+summary: A coding run was refused because this server has no worker images for the agent's coding provider (Codex or Claude Code).
+audience: operator
+tags: [error, coding-agents, configuration, coding_provider_not_configured, CODING_WORKER_IMAGE, codex, claude-code]
+appliesTo: ">=0.5.0"
+---
+
+# Coding provider not configured
+
+`coding_provider_not_configured:<provider>` means a coding agent's provider has
+no worker images on this wardby server. Each provider's images are optional, so
+a server can run Codex agents only, Claude Code agents only, or both. Starting
+the run (a trigger, schedule, or webhook) fails at dispatch with this error,
+before any worker starts and before anything is spent. A run records its worker
+image at dispatch, so removing an image later doesn't affect most runs already
+dispatched. The exceptions fail at launch with category
+`preflight`: a Claude Code run when `CODING_CLAUDE_TOOL_RUNNER_IMAGE` has since
+been unset, and a Codex run with no recorded worker image (one dispatched before
+runs recorded it) when `CODING_WORKER_IMAGE` has since been unset.
+
+- **`coding_provider_not_configured:codex`**: `CODING_WORKER_IMAGE` (the Codex
+  worker) isn't set, and the agent names no worker image of its own
+  (`codingProfile.workerImageRef`). An agent that sets `workerImageRef`, or uses
+  a toolchain with its own image (such as `CODING_WORKER_IMAGE_NODE_PYTHON_3_12`),
+  still runs without `CODING_WORKER_IMAGE`.
+- **`coding_provider_not_configured:claude-code`**: `CODING_CLAUDE_WORKER_IMAGE`
+  or `CODING_CLAUDE_TOOL_RUNNER_IMAGE` isn't set. Claude Code needs both, and
+  even an agent's own `workerImageRef` doesn't replace the tool runner.
+
+This error is about images, not API keys. A missing or invalid model API key
+fails later, when the run calls the model.
+
+## What to do
+
+Choose one:
+
+1. **Configure the provider.** Set its images on the wardby server and restart
+   it:
+   - Codex: `CODING_WORKER_IMAGE`.
+   - Claude Code: `CODING_CLAUDE_WORKER_IMAGE` and
+     `CODING_CLAUDE_TOOL_RUNNER_IMAGE`.
+
+   Each image must be immutable: a local `sha256:` image ID or a
+   `repo@sha256:` digest for Docker, and a registry digest for Kubernetes. With
+   the quickstart, re-run it and choose the provider you want; it pulls or builds
+   only that provider's images and keeps the ones already set. Then run
+   `wardby coding preflight`. See
+   [Local coding-agent setup](../../docs/coding-agent-setup.md).
+
+2. **Switch the agent to a configured provider.** Use `update_agent` to change
+   its `codingProfile.provider` and pick a model for that provider.
+
+The server refuses to start with a coding launcher (`JOB_LAUNCHER=docker` or
+`kubernetes`) when neither provider has images. That startup error names both
+options.
+
+Related: [Local git repositories](../local-repositories.md),
+[Model not available](model-unavailable.md).

package/help/errors/coding-turn-limit.md

@@ -0,0 +1,25 @@
+---
+id: errors/coding-turn-limit
+title: Coding run reached its turn limit
+summary: A Claude Code coding run stopped because it used every agent turn its codingProfile.maxTurns allows (200 by default), before it finished the task.
+audience: operator
+tags: [error, coding-agents, claude-code, turns, maxTurns]
+appliesTo: ">=0.4.2"
+---
+
+# Coding run reached its turn limit
+
+`coding_turn_limit` (failure category `turn_limit`) means a Claude Code run used
+all of its agent turns before it finished. Every file read, command and edit is
+a turn. The limit is the agent's `codingProfile.maxTurns`, or 200 when it is
+unset. Codex runs have no turn limit.
+
+1. Read the run's summary, and its debug trace if one was on
+   (`codingProfile.debugTraceMinutes`), to see whether the task was large or the
+   agent was repeating itself.
+2. For a large task, raise the limit (1 to 1000) with `update_agent`:
+   `{ "id": "<agent id>", "codingProfile": { "maxTurns": 400 } }`.
+3. For a loop, narrow the task or fix what it was retrying, then run it again.
+
+The run's `budgetUsd` and `timeoutSec` still apply. See
+[Troubleshoot coding workers](../troubleshooting/coding-workers.md).

package/help/errors/continuation-closed.md

@@ -0,0 +1,75 @@
+---
+id: errors/continuation-closed
+title: Continuation's pull request is no longer open
+summary: A run asked to continue a pull request that was already merged or closed, so nothing was pushed.
+audience: operator
+tags: [error, coding-agents, vcs, pull-requests, continuation, continuePriorRun]
+appliesTo: ">=0.4.2"
+---
+
+# Continuation's pull request is no longer open
+
+A coding run started with `continuePriorRun` (a mention follow-up, a Jira
+issue-event task, or a review fix round) reuses the branch and pull request
+the named run originally opened. Before cloning, and again right before it
+pushes, wardby asks GitHub whether that pull request is still open. A run
+that stopped with category `continuation_closed` got a definite answer that
+it is not: the pull request was merged or closed, or GitHub no longer lists
+an open pull request carrying that run's marker for the branch. Nothing from
+the run was pushed either way, so the pull request (and anyone who merged or
+closed it) is unaffected.
+
+Two things besides an actual merge or close can also make the check come back
+"no longer found," since it looks for an **open** pull request with that
+exact base branch and the run's hidden marker still in its description:
+
+- the pull request's base branch was retargeted to something other than the
+  one the run recorded;
+- the hidden `<!-- wardby:<run-id> -->` marker was removed or edited out of
+  the pull request's description (wardby relies on it to find its own PR;
+  nothing else identifies it).
+
+When the pull request was merged or closed **before the run started**, the
+check before cloning catches it: the run's status is `refused`, and nothing
+was spent beyond setup. When it was merged or closed **while the run was
+working**, the check right before the push catches it instead: that run ends
+`failed`, having already done its work, and that work is not pushed. Either
+way the category (`get_run`'s `codingRun.failureCategory`) is
+`continuation_closed`.
+
+This is a safety check, not a flaky one: a transient GitHub failure while
+checking (a timeout, a rate limit, a 5xx) is retried once, after a short
+wait, and if it still fails, wardby proceeds as though the pull request were
+still open rather than stopping the run on an unconfirmed answer — it only
+ever refuses on a definite "merged", "closed", or "no longer found" answer.
+
+## What the requester sees
+
+**(a) A parent agent that delegated the continuation** (a router that called
+`continuePriorRun`, a Jira or mention follow-up) gets this back as its
+sub-run's `refusal`, never the raw error code:
+
+> The pull request this run was asked to continue is no longer open (merged
+> or closed), so nothing was pushed. If the change is still needed, delegate
+> again without continuePriorRun: it becomes a new pull request from the
+> default branch.
+
+**(b) A person watching the request** — the @-mention's status comment, or
+the Jira issue comment for an issue-event task — sees a line about the
+sub-run instead, without the error code:
+
+> A sub-run was asked to continue a pull request that is no longer open
+> (merged or closed); nothing was pushed.
+
+## What to do
+
+If the change is still needed, ask again without `continuePriorRun` (or
+without naming the closed pull request). The new run opens a fresh pull
+request from the repository's default branch. If the check is wrongly
+finding nothing when the pull request is in fact open, check that its base
+branch still matches what wardby recorded and that the `<!-- wardby:... -->`
+marker is still in its description, unedited.
+
+Related: [Run GitHub code-review agents](../code-review-agents.md),
+[Automatic review fix rounds](../review-fix-rounds.md),
+[Related pull requests across repositories](../related-pull-requests.md).

package/help/errors/local-branch-conflict.md

@@ -0,0 +1,37 @@
+---
+id: errors/local-branch-conflict
+title: Run's branch was modified or is checked out
+summary: The branch wardby/run-<id> moved since the run started, or it is checked out in the local repository, so wardby did not push to it.
+audience: operator
+tags: [error, local-repositories, coding-agents, vcs]
+appliesTo: ">=0.5.0"
+---
+
+# Run's branch was modified or is checked out
+
+`local_branch_conflict` means wardby would not push a run's commit into the
+local repository because the target branch `wardby/run-<run id>` is not in the
+state the run expects. Either:
+
+- the branch moved after the run cloned it, for example you or another run
+  committed to it, so the push would not be a fast-forward; or
+- the branch is checked out in the repository, and wardby never changes the
+  branch you have checked out.
+
+The run fails and nothing is pushed. Your repository, working tree and checked-out
+branch are unchanged.
+
+## What to do
+
+1. Check what is checked out: `git -C /path/to/repo branch --show-current`. If
+   it is a `wardby/run-*` branch, switch to another one, such as `main`.
+2. If the branch moved, decide which work to keep. To build on the moved branch,
+   start a new run with `baseRef: wardby/run-<run id>` so it starts from the
+   branch's current tip.
+3. Start the run again.
+
+To avoid this, treat `wardby/run-*` branches as wardby's while a run is active:
+do not commit to them or check them out. To inspect a result, use
+`git show wardby/run-<run id>` or create your own branch from it.
+
+Related: [Local git repositories](../local-repositories.md).

package/help/errors/local-path-invalid.md

@@ -0,0 +1,30 @@
+---
+id: errors/local-path-invalid
+title: Invalid file path in local repository read
+summary: A file path given to a repository read was absolute or contained empty, dot or dot-dot segments.
+audience: operator
+tags: [error, local-repositories, coding-agents, vcs]
+appliesTo: ">=0.5.0"
+---
+
+# Invalid file path in local repository read
+
+`local_path_invalid` means a read of a file in a local repository (for example
+`repo_read_file` in a review, or wardby reading `.wardby/services.yaml`) used a
+path wardby will not pass to git. Paths must be relative to the repository root.
+A path is rejected when it:
+
+- starts with `/`;
+- contains an empty segment (`src//main.ts`), a `.` segment or a `..` segment; or
+- is empty or contains a NUL.
+
+Wardby reads files from the committed tree at a ref, so only regular files are
+readable. A symlink, directory or submodule at that path is not.
+
+## What to do
+
+Use a clean repository-relative path, such as `src/main.ts` or `docs/README.md`,
+not `/home/you/repo/src/main.ts`, `./src/main.ts` or `src/../src/main.ts`. Use
+`repo_list_files` to see what exists at the ref.
+
+Related: [Local git repositories](../local-repositories.md).

package/help/errors/local-ref-invalid.md

@@ -0,0 +1,36 @@
+---
+id: errors/local-ref-invalid
+title: Invalid git branch or ref name
+summary: A branch or ref name was rejected because it does not follow git's naming rules.
+audience: operator
+tags: [error, local-repositories, coding-agents, vcs]
+appliesTo: ">=0.5.0"
+---
+
+# Invalid git branch or ref name
+
+`local_ref_invalid` means wardby refused a branch or ref name before passing it
+to git. A name is rejected when it:
+
+- is empty, starts with `-`, or contains `@{`, a NUL, a space or other
+  non-printable or non-ASCII character;
+- is too long; or
+- is not accepted by `git check-ref-format --branch` (for example it contains
+  `..`, a trailing `.lock`, or characters such as `~`, `^`, `:` or `\`).
+
+It can also appear when a review is requested without `base` while the
+repository's HEAD is detached, because there is no checked-out branch to use.
+
+## What to do
+
+Use a plain branch name that git accepts. You can check one with:
+
+```
+git check-ref-format --branch my-branch-name
+```
+
+Valid examples: `feature/add-login`, `fix-123`, `release-1.0`. Invalid examples:
+`-feature`, `feature branch`, `feature..fix`. For the detached HEAD case, pass
+`review.base` explicitly or check out a branch.
+
+Related: [Local git repositories](../local-repositories.md).

package/help/errors/local-ref-not-found.md

@@ -0,0 +1,41 @@
+---
+id: errors/local-ref-not-found
+title: Git branch or ref does not exist in the local repository
+summary: A branch or base ref the run asked for was not found in the repository history.
+audience: operator
+tags: [error, local-repositories, coding-agents, vcs]
+appliesTo: ">=0.5.0"
+---
+
+# Git branch or ref does not exist in the local repository
+
+`local_ref_not_found` means a branch, base or other ref named in a request does
+not resolve to a commit in the local repository. It comes from:
+
+- a coding run whose `baseRef` (on the agent's profile or in `trigger_agent`)
+  is not a branch of the repository;
+- a continuation or a `baseRef: wardby/run-<run id>` whose result branch was
+  deleted, for example with `git branch -D`; or
+- a review (`trigger_agent` with `review`) whose `branch` or `base` is not a
+  branch of the repository, or a file read at a ref that does not exist.
+
+Only committed history counts. Uncommitted changes are not part of any branch.
+
+## What to do
+
+1. List the branches the repository really has:
+   ```
+   git -C /path/to/repo branch --all
+   ```
+2. Fix the name, or commit your work to a branch first:
+   ```
+   git switch -c my-branch
+   git commit -am "Work in progress"
+   ```
+3. If a result branch was deleted and you still have its commit, recreate it
+   with `git branch wardby/run-<run id> <commit>`. Otherwise start from another
+   branch.
+4. For a review, check both `branch` and `base`; `base` defaults to the branch
+   checked out in the repository.
+
+Related: [Local git repositories](../local-repositories.md).

package/help/errors/local-repo-not-allowed.md

@@ -0,0 +1,46 @@
+---
+id: errors/local-repo-not-allowed
+title: Local repository is not in a trusted folder
+summary: The repository path is outside every folder listed in LOCAL_REPO_ROOTS, so the run was refused.
+audience: operator
+tags: [error, local-repositories, coding-agents, vcs]
+appliesTo: ">=0.5.0"
+---
+
+# Local repository is not in a trusted folder
+
+`local_repo_not_allowed` means wardby refused a local repository (a repository
+written `local:/absolute/path`) because its real path, after resolving symlinks,
+is not at or below any folder listed in the `LOCAL_REPO_ROOTS` environment
+variable. If `LOCAL_REPO_ROOTS` is unset, no local repository is allowed.
+
+A trusted folder that does not exist where the wardby server runs is ignored.
+This is the usual cause when the server runs in a container, a pod or on
+another machine: it cannot see the folder, so every repository under it is
+refused with this error. `doctor` lists each trusted folder and reports a
+missing one.
+
+Wardby checks the folders when you create or update an agent, link a
+repository, trigger a run, and again while a run uses the repository, so a
+narrowed list also refuses agents that were saved earlier.
+
+## What to do
+
+1. Add the repository's folder (or a parent folder) to `LOCAL_REPO_ROOTS` on the
+   wardby server. Separate folders with the platform's path delimiter: `:` on
+   macOS and Linux, `;` on Windows. For example:
+   ```
+   LOCAL_REPO_ROOTS=/home/you/projects:/srv/repos
+   ```
+2. Restart the wardby server so it reads the new value.
+3. If you set up wardby with `quickstart`, run it again with
+   `--coding --trust /path/to/folder` (repeat `--trust` for more folders). It
+   keeps the folders already trusted and writes the new list to `.wardby/.env`.
+
+4. Run the wardby server directly on the machine that holds the folders, not
+   in a container.
+
+If the repository path goes through a symlink, the symlink's target must be
+inside a trusted folder; the link's own location does not count.
+
+Related: [Local git repositories](../local-repositories.md), [Get started](../getting-started.md).

package/help/errors/local-repo-not-found.md

@@ -0,0 +1,39 @@
+---
+id: errors/local-repo-not-found
+title: Local repository path not found or not a git repository
+summary: The repository path does not exist, is not the top level of a git work tree, or is not readable by the wardby server.
+audience: operator
+tags: [error, local-repositories, coding-agents, vcs]
+appliesTo: ">=0.5.0"
+---
+
+# Local repository path not found or not a git repository
+
+`local_repo_not_found` means wardby could not use a local repository (written
+`local:/absolute/path`) even though the path is inside a trusted folder. One of
+these is true:
+
+- the path does not exist (it was moved or deleted);
+- the path is not the top level of a git work tree (it is a subfolder of a
+  repository, a bare repository, or not a repository at all); or
+- the wardby server's user cannot read the folder.
+
+Local repositories need the wardby server to run on the same machine as the
+folders, outside a container. A server in a container, a pod or on another
+machine usually cannot see the trusted folder at all; it ignores that folder,
+so the repository fails with
+[`local_repo_not_allowed`](local-repo-not-allowed.md) instead.
+
+## What to do
+
+1. Check the path from the machine that runs the wardby server:
+   ```
+   git -C /path/to/repo rev-parse --show-toplevel
+   ```
+   The output must be the path you gave wardby (after symlinks). If it is a
+   parent folder, use that folder instead.
+2. Make sure the server's user can read the folder.
+3. Make sure the path you gave is the folder that holds `.git`, not a
+   subfolder.
+
+Related: [Local git repositories](../local-repositories.md).

package/help/errors/model-unavailable.md

@@ -45,12 +45,13 @@ A coding agent's model is checked against the catalog only
 never look up a provider adapter at all, so a model can pass this check and
 still fail later for reasons `model_unavailable` never reports.
 
-One such failure has a specific name: dispatching a Claude Code run throws
-`coding_provider_not_configured:claude-code` when this deployment's
-`CODING_CLAUDE_WORKER_IMAGE` or `CODING_CLAUDE_TOOL_RUNNER_IMAGE` isn't set —
-it means the Claude Code worker or tool-runner image itself isn't configured,
-not a missing credential, and there is no equivalent error or string for
-Codex. See [Local coding-agent setup](../../docs/coding-agent-setup.md).
+One such failure has a specific name: dispatching a coding run throws
+`coding_provider_not_configured:codex` or
+`coding_provider_not_configured:claude-code` when this deployment has no
+worker images for that provider (`CODING_WORKER_IMAGE` for Codex;
+`CODING_CLAUDE_WORKER_IMAGE` and `CODING_CLAUDE_TOOL_RUNNER_IMAGE` for Claude
+Code). It means the images themselves aren't configured, not a missing
+credential. See [Coding provider not configured](coding-provider-not-configured.md).
 
 A missing or invalid API key behind a coding run's model-provider credential
 (`CODING_OPENAI_CREDENTIAL_REF` for Codex, `CODING_ANTHROPIC_CREDENTIAL_REF`

package/help/errors/vcs-github-not-configured.md

@@ -0,0 +1,34 @@
+---
+id: errors/vcs-github-not-configured
+title: GitHub is not configured for coding agents
+summary: A coding run used a GitHub repository, but the wardby server has no GitHub App credentials (GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY).
+audience: operator
+tags: [error, coding-agents, github, vcs, configuration, GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY]
+appliesTo: ">=0.5.0"
+---
+
+# GitHub is not configured for coding agents
+
+`vcs_github_not_configured` means a coding run's repository is a GitHub
+repository, but the wardby server was started without GitHub App credentials,
+so it cannot clone the repository or push the result. The run's failure
+category is `preflight`. Nothing is pushed.
+
+The server starts without the credentials so that it can serve local git
+repositories (`local:/absolute/path`) on its own. When neither GitHub App
+credentials nor `LOCAL_REPO_ROOTS` are set, the server logs a warning at
+startup that names both options.
+
+## What to do
+
+Choose one:
+
+1. **Use GitHub.** Install a GitHub App on the repository, then set
+   `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` on the wardby server and restart
+   it. See [Connect GitHub repositories](../github.md).
+2. **Use a local repository.** If the code is in a git folder on the machine
+   that runs the wardby server, set `LOCAL_REPO_ROOTS` and point the agent's
+   `codingProfile.repository` at `local:/absolute/path`. See
+   [Local git repositories](../local-repositories.md).
+
+Related: [Get started](../getting-started.md).