@wardby/cli 0.4.1 → 0.5.0

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).

package/help/getting-started.md

@@ -19,6 +19,10 @@ 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.
 
+To try a coding agent and a review agent without a GitHub App, answer yes to the
+quickstart's coding step (or pass `--coding --trust <dir>`, a repository or a folder of repositories); it points them at a
+git folder on your machine. See [Use local git repositories](local-repositories.md).
+
 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.

package/help/github.md

@@ -23,6 +23,13 @@ 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.
 
+Set the App's credentials as `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` on
+the wardby server. Without them, a coding run on a GitHub repository fails with
+[`vcs_github_not_configured`](errors/vcs-github-not-configured.md).
+
+No GitHub App is needed for a git repository on the wardby host. See
+[Use local git repositories](local-repositories.md).
+
 Read [`docs/coding-agent-setup.md`](../docs/coding-agent-setup.md) for coding
 agent setup and [`docs/code-review-agents.md`](../docs/code-review-agents.md)
 for pull-request review agents and webhook configuration.
@@ -35,14 +42,24 @@ Link a native agent to a repository with `link_repository`. Each trigger needs
 its GitHub App event ticked in the App's event settings; every event is a
 separate checkbox.
 
-| Trigger        | Starts a run when                                                   | App event to subscribe                                                                 |
-| -------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `pull_request` | A pull request is opened or pushed to; a re-run of the review check | Pull request, Check run (re-runs of the review check)                                  |
-| `mention`      | Someone with write access `@`-mentions the App                      | Issue comment, Issues, Pull request review comment (mentions in inline review threads) |
-| `push`         | A commit lands on the repository's default branch                   | Push                                                                                   |
+| Trigger                         | Starts a run when                                                                                                                                                            | App event to subscribe                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `pull_request`                  | A pull request is opened or pushed to; a re-run of the review check; CI finishing after a review that waited for it                                                          | Pull request, Check run (re-runs of the review check), Check suite (CI finishing)      |
+| `pull_request` with `waitForCi` | Same, but the review of a pushed head is held until that head's own CI finishes (or 15 minutes pass), and an approve verdict is refused while CI is failing or still running | Same events as `pull_request`                                                          |
+| `mention`                       | Someone with write access `@`-mentions the App                                                                                                                               | Issue comment, Issues, Pull request review comment (mentions in inline review threads) |
+| `push`                          | A commit lands on the repository's default branch                                                                                                                            | Push                                                                                   |
+| `review_fix`                    | Wardby's own review check requests changes on a PR it opened                                                                                                                 | Same events as `pull_request` (it reacts to that check's own verdict, no extra event)  |
 
 The `push` trigger starts a merge-watcher agent; only default-branch pushes
 count (tags, other branches, and deletions are ignored). See
 [Keep the knowledge bundle current on merge](help://architecture-agent).
 
+The `review_fix` trigger lets Wardby fix its own review's findings
+automatically, up to a round cap, on pull requests its own coding runs
+opened. See [Automatic review fix rounds](review-fix-rounds.md).
+
+`waitForCi` holds a reviewer's review until that pull request's own CI
+finishes, and gates its ability to approve on CI passing. See
+[Review after CI (`waitForCi`)](code-review-agents.md#review-after-ci-waitforci).
+
 For Jira Cloud instead of GitHub, see [Run Jira agents](jira.md).

package/help/jira.md

@@ -41,7 +41,10 @@ the `Jira acting as` startup line to confirm the account.
    `WARDBY_JIRA_WEBHOOK_SECRET`, then restart. The startup log line
    `Jira acting as` shows which account Wardby uses; confirm it is the service
    account. Optionally set `WARDBY_JIRA_API_TOKEN_EXPIRES_AT` to get a warning
-   14 days before expiry.
+   14 days before expiry. On the GKE reference deployment, put all five in
+   `.env.local` (all or none) and run `deploy/gke/up.sh`: it seeds them into
+   Secret Manager and syncs the optional `wardby-jira-env` Secret for the
+   control plane. See [Deploy on GKE](deploy-gke.md).
 6. A Wardby administrator links the agent with `link_issue_project`, for
    example `projectKey: "PROJ"`, `access: "write"`,
    `triggers: ["transitioned", "mention"]`,
@@ -116,7 +119,11 @@ precise task, and for follow-ups pass the run id from the run message as
 issue gets a web link to it (needs Link issues); Jira's development panel
 shows it only if the Jira and GitHub integration is installed. Merge and close
 comments and the merged status move need the GitHub App to deliver
-`pull_request` events. See the full guide for the recipe.
+`pull_request` events. When one issue leads to pull requests in several
+repositories, each lists the others, and a later event on the issue tells the
+agent how to continue each open one; see
+[Related pull requests across repositories](related-pull-requests.md). See
+the full guide for the recipe.
 
 ## Trust rules