@wardby/cli 0.6.0 → 0.8.0

package/help/fix-merge-conflicts.md

@@ -0,0 +1,73 @@
+---
+id: fix-merge-conflicts
+title: Fix merge conflicts on a wardby pull request
+summary: Follow-up runs merge the PR's current target branch first and resolve its conflicts; ask to update a PR that fell behind.
+audience: operator
+tags: [github, pull-requests, merge-conflict, update-pr, target-branch, continuation, review_fix]
+appliesTo: ">=0.7.0"
+---
+
+# Fix merge conflicts on a wardby pull request
+
+Every follow-up run on a pull request a wardby coding run opened (a mention on
+the PR, a delegated `continuePriorRun`, a review fix round) first brings the
+branch up to date with the branch the pull request **currently** targets:
+
+1. Before the agent starts, wardby asks GitHub for the pull request's base
+   branch. A pull request retargeted since it opened (a stacked PR whose
+   parent merged, a release branch) merges its new base, not the one the
+   first run used.
+2. wardby fetches that branch from the same repository (never a fork) and
+   merges it into the workspace, in trusted code, before the agent sees it.
+   A branch that already contains its target is left exactly as it was.
+3. **No conflicts:** the agent works on the updated branch as usual.
+   **Conflicts:** the agent's task lists the conflicted files and which side
+   is which (this pull request's branch, then the target). It is asked to
+   resolve every conflict keeping both sides' intent, fix the tests the
+   combination broke, and run the repository's checks.
+4. The push is one merge commit authored by Wardby, with the pull request's
+   head and the target as its parents. It is pushed even when the agent
+   changed nothing else, so asking a wardby agent on the pull request to
+   "update this PR" or "fix the merge conflicts" is enough.
+5. The run's status comment on the pull request says what was merged, for
+   example "Merged `main` @ `1a2b3c4` into this branch; resolved conflicts
+   in 2 files."
+
+## Ask to update this PR
+
+Mention the wardby agent on the pull request with "please update this PR" or
+"please fix the merge conflicts". The follow-up merges the target branch,
+resolves any conflicts, and pushes the merge commit.
+
+## What is checked
+
+- **Conflict markers.** A file the merge left conflicted that still holds
+  conflict markers when the run finishes stops the push: the run fails with
+  category `merge_conflict` and nothing is pushed — see
+  [Conflict markers remain](errors/merge-conflict.md).
+- **Protected paths and size limits** apply to the agent's own changes,
+  measured against the automatic merge: a change the target branch made to a
+  protected path is merged as it is, while resolving a conflict in a protected
+  path, or reverting the target's change to one, is an edit by the agent and
+  is refused as usual (see [Protected path](errors/protected-path.md)).
+- **Someone else pushed meanwhile.** The push is still a fast-forward of the
+  head the run started from, so a push by anyone else in the meantime fails
+  the run the same way it did before, with nothing pushed.
+- **No merge base.** A target branch that cannot be fetched, or shares no
+  history with the pull request, fails the run before the agent starts — see
+  [Target branch could not be merged](errors/target-merge.md).
+
+## Limits
+
+- Local repositories (`local:`) have no pull requests, so a continuation there
+  is not merged with anything.
+- A conflicted file with no markers (a binary file, or one deleted on one side
+  and changed on the other) holds one side's version, or the changed version.
+  The agent is told to check it, but nothing stops it from leaving that version
+  as it is.
+- A conflict in a protected path cannot be resolved by the agent: resolving it
+  is an edit to that path, which is refused. Resolve that file by hand and push.
+
+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/github-app-setup.md

@@ -0,0 +1,132 @@
+---
+id: github-app-setup
+title: Set up the GitHub App
+summary: Step by step, create Wardby's GitHub App, choose its events and permissions, install it on your repositories, and give the server its credentials.
+audience: operator
+tags: [github, github-app, setup, permissions, webhooks, GITHUB_APP_ID, GITHUB_APP_WEBHOOK_SECRET, link_host_account]
+appliesTo: ">=0.2.1"
+---
+
+# Set up the GitHub App
+
+Wardby reaches GitHub through a GitHub App that you create and own. Each Wardby
+server needs its own App, because an App has exactly one webhook URL. For an
+overview of how Wardby uses the App, see
+[Connect GitHub repositories](github.md).
+
+Decide first what the App is for:
+
+- **Coding agents only**, triggered with `trigger_agent` or on a schedule:
+  GitHub never calls your server, so you can skip the webhook (step 2) and the
+  events (step 4).
+- **Review agents, `@`-mentions, review fix rounds, merge watchers, or
+  marking pull requests ready**: these start from GitHub webhooks, so your
+  server must be reachable over public HTTPS at the host of
+  `MCP_CANONICAL_URI`.
+
+## 1. Create the App
+
+In the GitHub settings of the user or organization that will own it, open
+**Developer settings**, then **GitHub Apps**, then **New GitHub App**. Give
+it a name and a homepage URL. The owner matters: Wardby always serves the
+App's owner, and other accounts only when you list them (step 7).
+
+## 2. Webhook
+
+- **Webhook URL**: `https://<your-host>/hosts/github/events`, where
+  `<your-host>` is the host of `MCP_CANONICAL_URI`. Requests naming any other
+  host are rejected.
+- **Webhook secret**: a random value, for example from `openssl rand -hex 32`.
+  The same value goes into `GITHUB_APP_WEBHOOK_SECRET` (step 7). Until that
+  variable is set, the endpoint answers 404.
+
+For coding agents only, untick **Active** under Webhook instead.
+
+## 3. Repository permissions
+
+| Permission      | Access                                             |
+| --------------- | -------------------------------------------------- |
+| Contents        | Read and write (Read for an App that only reviews) |
+| Pull requests   | Read and write                                     |
+| Checks          | Read and write                                     |
+| Issues          | Read and write                                     |
+| Commit statuses | Read (optional)                                    |
+
+- **Contents: Read and write** lets coding agents push a branch for each pull
+  request. A review-only App can have Read, but its reviewers then can't
+  resolve their own fixed review threads.
+- **Checks** carries the `wardby review` and `wardby merge order` checks.
+- **Issues** covers mentions in issues and the labels used by
+  [automatic review fix rounds](review-fix-rounds.md).
+- **Commit statuses** lets reviewers see CI that reports commit statuses
+  rather than check runs.
+
+If you change permissions later, every installation must accept the new set
+before its webhooks resume.
+
+## 4. Events
+
+Tick each one; every event is its own checkbox.
+
+| Event                       | Needed for                                                                                                  |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Pull request                | `pull_request` reviewers and `review_fix`                                                                   |
+| Check run                   | Re-running the review check                                                                                 |
+| Check suite                 | Reviews that wait for CI (`waitForCi`), and `markReadyWhenPassing` marking a draft ready once CI goes green |
+| Issue comment               | `@`-mentions in issue and pull request comments                                                             |
+| Issues                      | `@`-mentions in a newly opened or edited issue                                                              |
+| Pull request review comment | `@`-mentions in inline review threads                                                                       |
+| Push                        | The `push` trigger (merge-watcher agents)                                                                   |
+
+Missing an event fails quietly: the matching trigger never starts. A common
+case is leaving out Check suite, so drafts that should be marked ready stay
+drafts.
+
+## 5. Account linking
+
+`link_host_account` lets a Wardby user prove which GitHub account they are, so
+Wardby can check their repository access. In the App's **General** settings:
+
+- **Callback URL**: `https://<your-host>/hosts/github/user-callback`.
+- Leave **Request user authorization (OAuth) during installation** unticked.
+- Note the **Client ID** (not the numeric App ID) and generate a **client
+  secret**.
+
+## 6. Private key and installation
+
+1. Save the App, note its numeric **App ID**, and generate a **private key**
+   (a `.pem` file).
+2. Under **Install App**, install it on your account or organization and
+   choose **Only select repositories**: pick only the repositories your agents
+   may use.
+
+## 7. Configure Wardby
+
+| Variable                         | Value                                                                       |
+| -------------------------------- | --------------------------------------------------------------------------- |
+| `GITHUB_APP_ID`                  | The numeric App ID                                                          |
+| `GITHUB_APP_PRIVATE_KEY`         | The contents of the `.pem` file                                             |
+| `GITHUB_APP_WEBHOOK_SECRET`      | The webhook secret from step 2                                              |
+| `GITHUB_APP_CLIENT_ID`           | The Client ID from step 5 (set together with the client secret, or neither) |
+| `GITHUB_APP_CLIENT_SECRET`       | The client secret from step 5                                               |
+| `WARDBY_GITHUB_ALLOWED_ACCOUNTS` | Optional: accounts other than the App's owner to serve, comma-separated     |
+| `WARDBY_MENTION_EXPLANATIONS`    | Optional: `false` = no reply saying why a mention started nothing           |
+
+Restart the server after setting them. Without `GITHUB_APP_ID` and
+`GITHUB_APP_PRIVATE_KEY`, coding runs on GitHub repositories fail with
+[`vcs_github_not_configured`](errors/vcs-github-not-configured.md).
+Repositories of accounts that aren't served are refused with
+[`github_account_not_allowed`](errors/github-account-not-allowed.md).
+
+## 8. Check it
+
+- Run `link_host_account` and finish the GitHub sign-in it opens.
+- Link an agent with `link_repository`, or create a coding agent on the
+  repository (see [builder agents](builder-agent.md) and
+  [Run GitHub code-review agents](code-review-agents.md)).
+- In the App's **Advanced** settings, **Recent Deliveries** should show your
+  server answering webhooks with a 2xx status. A signature failure there means
+  the webhook secret and `GITHUB_APP_WEBHOOK_SECRET` differ.
+
+The full reference, including rollout order on Kubernetes deployments, is
+[Registering the GitHub App](../docs/code-review-agents.md#registering-the-github-app).

package/help/github.md

@@ -23,6 +23,8 @@ 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.
 
+To create and install the App, follow [Set up the GitHub App](github-app-setup.md).
+
 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).
@@ -69,6 +71,19 @@ 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).
 
+When a mention run finishes without opening a pull request or failing a
+sub-run and its reply is longer than about 2,000 characters (for example a
+plan), the status comment does not cut the reply short. It says "✅ Finished
+without opening a pull request. The full reply follows in the next
+comment(s)." (in a review thread: "...follows in this pull request's
+conversation."), and the reply is posted in up to four numbered comments
+("Reply, part i of n") of about 60,000 characters each, split at headings,
+paragraphs or lines. Anything beyond four parts is cut with a note; the full
+text stays on the run (`get_run`, `finalText`). `@`-mentions in the reply are
+defused. Each part is posted once; if one cannot be posted, the rest are
+skipped. Shorter replies, and runs that opened a pull request or had a failed
+sub-run, keep the status comment that quotes up to 2,000 characters.
+
 `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).
@@ -79,4 +94,11 @@ opening coding run was delegated by a lead agent. See [Reviewing a pull
 request a delegated run
 opened](code-review-agents.md#reviewing-a-pull-request-a-delegated-run-opened).
 
+With Wardby 0.7.0 or later, `markReadyWhenPassing` on the write link of the
+agent the event triggers (a builder, or a lead that delegates to a coding
+builder) has Wardby mark the draft pull requests it opens here ready for review
+on its own, once every Wardby reviewer check and CI on the head are green
+and, for a merge-ordered set, the steps it depends on have merged. See [Mark
+ready when passing](code-review-agents.md#mark-ready-when-passing).
+
 For Jira Cloud instead of GitHub, see [Run Jira agents](jira.md).

package/help/host-providers.md

@@ -0,0 +1,40 @@
+---
+id: host-providers
+title: Add a code host with your own tools (host providers)
+summary: Register a code host implemented by custom tools, approve changes to them, and test them with read-only calls. Agents can't use a provider yet.
+audience: operator
+tags: [host provider, register_host_provider, approve_host_provider_tools, hosts:admin, host-manager]
+appliesTo: >=0.8.0
+---
+
+# Host providers
+
+A host provider adds a code host using your own custom tools. This release lets you register
+a provider, approve its tools and test them. Agents can't use a registered provider yet.
+
+You need the `hosts:admin` scope and a role that grants it (`admin` or `host-manager`). See
+[Identity and access](identity-and-access.md).
+
+1. Write one tool per operation with `create_tool`.
+2. Broker each credential with `set_secret_broker`, allowing the API hosts and the git host. The
+   permission credential needs only the API hosts ([Brokered secrets](brokered-secrets.md)).
+3. Call `register_host_provider`. No restart is needed today, because agents can't use a provider
+   yet; a new provider will need one once they can. A refusal has a
+   [`host_provider_*` code](errors/host-provider-error.md).
+4. Call `test_host_provider` to check each read-only tool. Failures have
+   [fixed codes](errors/host-tool-failed.md).
+
+`update_tool` changes nothing until you call `approve_host_provider_tools`, a new `timeoutMs`
+included. See which tools have changes with `get_host_provider`.
+
+A bound tool reaches only the provider's API hosts, inside one repository's path, and Wardby
+follows no redirects; the tool must fetch the `Location` itself. Any host manager can read and re-register any
+provider.
+
+Replacing a secret a provider uses, or changing its broker config, needs `hosts:admin` as well as
+`secrets:write`. A webhook secret stays at 16 characters or more.
+
+Keep provider credentials unattached: an agent's own tools can use an attached one without the
+provider's path guard.
+
+See [docs/host-providers.md](../docs/host-providers.md) for the full guide.

package/help/identity-and-access.md

@@ -21,7 +21,7 @@ audience, and the granted Wardby scopes in `scope` or `scp`.
 
 Scopes authorize normal operations such as managing agents, runs, tools,
 datastores, secrets, webhooks, budgets, packages, services, memory, and
-models. Six sensitive permissions have an additional role requirement:
+models. Seven sensitive permissions have an additional role requirement:
 
 - `agents:admin` requires the Wardby `admin` role.
 - `packages:approve` requires the `admin` or `package-approver` role.
@@ -31,6 +31,9 @@ models. Six sensitive permissions have an additional role requirement:
 - `models:admin` requires the `admin` or `model-manager` role. It adds,
   overrides, disables, and resets model catalog entries; see
   [Models and pricing](models.md).
+- `hosts:admin` requires the `admin` or `host-manager` role. It registers host
+  providers, approves their tools and, with `secrets:write`, replaces their secrets; see
+  [Host providers](../docs/host-providers.md).
 - `power:manage` requires the `admin` role. It reads low-power state and
   sleeps the coding proxy and native gateway now (`power_status`,
   `power_sleep`); see
@@ -46,3 +49,5 @@ that request every advertised scope otherwise fail with `invalid_scope`.
 Read [`docs/getting-started-identity-provider.md`](../docs/getting-started-identity-provider.md)
 for the required claims, scope list, role mapping, provider examples, and
 client registration.
+
+From Wardby 0.7.0, to share an agent with one person or with everyone signed in, see the help article `sharing-agents`.

package/help/jira.md

@@ -65,13 +65,24 @@ the `Jira acting as` startup line to confirm the account.
 Beyond reading, searching and commenting, linked agents get
 `jira_list_transitions`, `jira_transition`, `jira_update_fields`,
 `jira_link_issues`, and `jira_get_property` / `jira_set_property` for
-per-issue state, plus `jira_create_issue` and `jira_read_attachment`. Each authorizes against the issue's own project and the
-agent's live link. Properties are not allowlisted: any `write` link can set
-them and any link can read them. They are stored as `wardby.<agentId>.<name>`,
-and anyone with Jira API access to the issue can read or overwrite them, so
-never store secrets there. Run status comments include an `Agent spend: $...`
-line. To see what work on a card, epic, or project cost, read
+per-issue state, plus `jira_create_issue` and `jira_read_attachment`. Each
+authorizes against the issue's own project and the agent's live link.
+Properties are not allowlisted: any `write` link can set them and any link can
+read them. They are stored as `wardby.<agentId>.<name>`, and anyone with Jira
+API access to the issue can read or overwrite them, so never store secrets
+there. Run status comments include an `Agent spend: $...` line. To see what
+work on a card, epic, or project cost, read
 [Attribute agent spend to issues](cost-attribution.md).
+
+When a run succeeds, opens no pull request, has no failed sub-run, and its
+reply is longer than about 2,000 characters (for example a plan), the status
+comment says "✅ The full reply follows in the next comment(s)." and the reply
+follows in up to four numbered comments ("Reply, part i of n") of about 15,000
+characters each, split at headings, paragraphs or lines. Anything beyond is
+cut with a note, and the full text stays on the run (`get_run`, `finalText`).
+`@`-mentions are defused. Each part is posted once; if one cannot be posted,
+the rest are skipped. Shorter replies stay in the status comment.
+
 If the token belongs to a person, Wardby refuses to act: startup logs an error
 and the webhook answers 503 `jira_personal_account`. Deliveries with a
 timestamp older than two hours (or more than five minutes ahead) are ignored.
@@ -125,6 +136,12 @@ agent how to continue each open one; see
 [Related pull requests across repositories](related-pull-requests.md). See
 the full guide for the recipe.
 
+To have a code reviewer check such a pull request against the ticket's own
+acceptance criteria, link the reviewer to the Jira project too (read access
+is enough): it then reads the ticket with `jira_get_issue`. Without that link
+it can only judge the criteria from the pull request's description; see
+[Run GitHub code-review agents](code-review-agents.md#reading-the-issue-a-pull-request-resolves).
+
 ## Trust rules
 
 Only people (not customers, apps, or the service account itself) can trigger

package/help/knowledge.md

@@ -1,9 +1,9 @@
 ---
 id: knowledge
 title: Architecture knowledge bundles
-summary: Keep cited, non-obvious architecture knowledge in docs/knowledge/ so coding runs, reviewers, and live sessions (through the AGENTS.md pointer) use it; validate it with wardby knowledge check.
+summary: Keep cited, non-obvious architecture knowledge in docs/knowledge/ (or a folder you pick in .wardby/knowledge.yaml) so coding runs, reviewers, and live sessions (through the AGENTS.md pointer) use it; validate it with wardby knowledge check.
 audience: operator
-tags: [knowledge, architecture, coding-agents, okf, cli, drift, push]
+tags: [knowledge, architecture, coding-agents, okf, cli, drift, push, knowledge.yaml, bundle-path]
 appliesTo: >=0.4.0
 ---
 
@@ -16,9 +16,18 @@ their reasons, and cross-module contracts. It uses the Open Knowledge Format
 for, the paths it affects, and citations to the code it describes. Each citation
 carries a commit `sha` and a `spanHash` so staleness can be detected.
 
-- `docs/knowledge/index.md` lists every concept in one line; `log.md` records
-  changes to the bundle.
-- When `docs/knowledge/index.md` exists on a coding run's base branch, the run's
+- `index.md` lists every concept in one line; `log.md` records changes to the
+  bundle.
+- **Pick your own folder:** add `.wardby/knowledge.yaml` with one line,
+  `path: .okf` (any repo-relative folder outside `.wardby/` and `.git/`). Wardby
+  then reads the bundle there for the coding-run note, merge-watcher drift runs,
+  and `wardby knowledge check`. Without the file it uses `docs/knowledge/`; an
+  invalid file is ignored with a warning (`knowledge_config_invalid` from the
+  check). Or skip wardby's reading entirely: tell your agents where knowledge
+  lives in their prompts or `AGENTS.md`, and they use that folder; you lose
+  only the automatic note and drift scoping on merge. Update any prompt that
+  names `docs/knowledge/` to your folder.
+- When the bundle's `index.md` exists on a coding run's base branch, the run's
   task includes the index automatically (up to 8 KiB). It never fails a
   dispatch; an unreadable index just means no note.
 - When the run's commit is known (it always is for a normal clone) and the
@@ -26,8 +35,8 @@ carries a commit `sha` and a `spanHash` so staleness can be detected.
   has no git metadata, so use that value for citation `sha` fields.
 - Validate the bundle with `wardby knowledge check` (add `--strict` to fail on
   warnings, `--json` for machine output, `--root` to point at the repository).
-  Errors are `concept_invalid`, `concept_secret`, `index_missing`, and
-  `index_link_broken`; warnings are `concept_not_indexed`,
+  Errors are `concept_invalid`, `concept_secret`, `index_missing`,
+  `index_link_broken`, and `knowledge_config_invalid`; warnings are `concept_not_indexed`,
   `citation_unverifiable`, and `citation_stale`.
 - Builders may edit concept prose. Citations can go stale afterward; the
   architecture agent re-anchors them.

package/help/local-repositories.md

@@ -50,7 +50,7 @@ The easiest way to try it is the optional coding step of
   machine cannot see the folder: it ignores a trusted folder that does not
   exist, so the repository fails with `local_repo_not_allowed`, and `doctor`
   reports the folder as missing.
-- **git 2.24 or newer** on the machine that runs the wardby server.
+- **git 2.38 or newer** on the machine that runs the wardby server.
 - **Worker images from this release or later.** An older worker image rejects
   a `local:` repository and the run fails with `worker_input_failed`. That
   includes a bring-your-own `workerImageRef` image: rebuild it on a current

package/help/low-power-mode.md

@@ -46,7 +46,11 @@ only when `WARDBY_LOW_POWER=1`.
   a sandbox run does the same for the gateway. The wait is at least 5 minutes.
   A `KUBERNETES_READY_TIMEOUT_MS` (proxy) or `NATIVE_SANDBOX_READY_TIMEOUT_MS`
   (gateway) above that, set on the control-plane Deployment, raises it. Expect
-  about 1 to 2 minutes extra on a cold node. Log: `power: proxy woke`.
+  about 1 to 2 minutes extra on a cold node. Log: `power: proxy woke`. A
+  sandbox run woken this way may then wait for a gVisor node for its worker
+  pod, so its first model call can come several minutes after it started. From
+  0.7.0 it shows as running the whole time and is not reaped as orphaned; only
+  the wake and pod-start limits above can fail it.
 - **Preflight.** The first coding run after a control-plane restart also runs
   the cluster preflight canary, because start-up preflight is deferred while the
   proxy sleeps (`kubernetes_preflight_deferred`).
@@ -107,6 +111,8 @@ full table.
 
 - [`low_power_wake_timeout`](errors/low-power-wake-timeout.md): the target did
   not become ready in time, or its Deployment does not exist.
+- `native_sandbox_launch_abandoned` (0.7.0 and later): a sandbox run was
+  stopped while the gateway woke, so no worker pod was made.
 - [`low_power_disabled`](errors/low-power-disabled.md): `power_sleep` was
   called while the mode is off.
 - [`low_power_scale_forbidden`](errors/low-power-scale-forbidden.md): the

package/help/mcp-servers.md

@@ -0,0 +1,73 @@
+---
+id: mcp-servers
+title: Remote MCP server tools for native and coding agents
+summary: Register a remote MCP server, then attach an allowlist of its tools to a native, Claude Code or Codex agent; credentials stay in brokered secrets.
+audience: operator
+tags: [mcp, mcp server, coding-agent, codex, register_mcp_server, attach_mcp_server, readOnlyHint, WARDBY_MCP_SERVERS]
+appliesTo: ">=0.8.0"
+---
+
+# Remote MCP server tools for native and coding agents
+
+A native, Claude Code or Codex agent can call tools from a remote MCP server (Streamable HTTP, HTTPS only).
+
+1. Create a [brokered secret](brokered-secrets.md) for the server's host, for example
+   `Authorization: Bearer {value}`.
+2. `register_mcp_server` with a `name`, the `url` (`https://mcp.example.com/mcp`) and
+   `secretNames`. Wardby saves the server's tool list.
+3. `attach_mcp_server` with the agent, the server and `allowedTools` (exact names, at least one).
+   The agent sees each as `<server name>__<tool name>`.
+4. After the server changes its tools, `refresh_mcp_server` applies the new list at once. Allowed
+   tools the server dropped show as `missingTools` in `get_agent`.
+
+Each call has `callTimeoutMs` (default `30000`, at most `WARDBY_TOOL_MAX_TIMEOUT_MS`, and never
+past the run's deadline). Results are untrusted input; the allowlist is the control. stdio servers
+and OAuth are not supported.
+
+`WARDBY_MCP_SERVERS` is `owners` (default), `admins` (registering needs `hosts:admin`) or `off`
+(only `detach_mcp_server` and `delete_mcp_server` still work, for cleanup).
+
+Each call opens a fresh MCP session, so a server that keeps state between calls in one session
+won't see it. Arguments that aren't a JSON object return `invalid_arguments`.
+
+## Coding agents
+
+`attach_mcp_server` also takes a Claude Code or Codex agent. Its run reaches the tools only through
+the coding proxy and the native gateway; the worker never sees the server's URL or secrets.
+
+- Claude Code agents see each tool as `mcp__wardby_mcp__<server name>__<tool name>` and may use any
+  allowed tool.
+- Codex agents may use only tools the server marks `readOnlyHint: true`. Wardby checks this when
+  you attach, when a run loads and on every call. Repository code in a Codex run can read the run's
+  MCP token, so a Codex agent must not be given tools that change things. `readOnlyHint` is the
+  server's claim, which Wardby can't verify, so the allowlist stays your control.
+- A run may make `WARDBY_MCP_MAX_CALLS_PER_RUN` calls (default `100`, failed calls count); more are
+  refused with [`mcp_call_limit`](errors/mcp-call-limit.md).
+- The proxy needs `WARDBY_MCP_GATEWAY_URL`. Without it coding agents get no MCP tools
+  ([`mcp_unavailable`](errors/mcp-unavailable.md)).
+- MCP for coding agents needs this release's Claude worker image and a new Codex driver image.
+  Older images get no MCP tools, and runs don't fail.
+- A repository's MCP configuration is still never loaded.
+- Codex models that use tool search load MCP tools on demand. They need this release's coding
+  proxy; an older one refuses their requests with `openai_tool_not_allowed:tool_search`.
+- Switching an agent to Codex with `update_agent` keeps its attachments, but tools not marked
+  read-only won't reach Codex runs; the result's `warnings` names them.
+- The proxy gives up on a coding run's MCP call after 5 minutes, whatever
+  `WARDBY_TOOL_MAX_TIMEOUT_MS` says ([`mcp_unavailable`](errors/mcp-unavailable.md)).
+
+Share a server with `grant_access` (`resourceType: "mcp_server"`; needs the `agents:write` scope,
+registering needs `tools:write`). `use` lets the grantee attach it, and its tools then run with your
+secrets. Revoking the grant, or lowering it to `read`, detaches the server from the grantee's agents
+at once, and their runs' next call is refused with `mcp_tool_not_allowed`.
+
+Errors a call can return: [`mcp_server_unreachable`](errors/mcp-server-unreachable.md),
+[`mcp_server_auth_failed`](errors/mcp-server-auth-failed.md),
+[`mcp_server_credentials_unavailable`](errors/mcp-server-credentials-unavailable.md),
+[`mcp_server_error`](errors/mcp-server-error.md),
+[`mcp_tool_not_allowed`](errors/mcp-tool-not-allowed.md),
+[`mcp_tool_removed`](errors/mcp-tool-removed.md),
+[`mcp_call_timeout`](errors/mcp-call-timeout.md),
+[`mcp_servers_off`](errors/mcp-servers-off.md), and for coding agents
+[`mcp_call_limit`](errors/mcp-call-limit.md) and [`mcp_unavailable`](errors/mcp-unavailable.md).
+
+Full guide: [Remote MCP servers](../docs/mcp-servers.md).

package/help/mcp.md

@@ -1,13 +1,13 @@
 ---
 id: mcp-access
-title: Connect an MCP client
+title: Connect a client to Wardby
 summary: Use Wardby's local stdio or protected HTTP MCP transport safely.
 audience: developer
 tags: [mcp, oauth, codex, claude-code]
 appliesTo: >=0.2.1
 ---
 
-# Connect an MCP client
+# Connect a client to Wardby
 
 For local use, `wardby quickstart` can register the local stdio MCP server with
 Codex or Claude Code. Local stdio trusts the local operator.
@@ -28,3 +28,8 @@ offline catalog as `wardby help`; they expose no instance data or credentials.
 
 See [`docs/getting-started-identity-provider.md`](../docs/getting-started-identity-provider.md)
 for the supported self-hosted and delegated identity-provider setup.
+
+From Wardby 0.8.0, Claude Code can show your runs in a pane beside the chat
+through the `wardby-runs` plugin: run `wardby claude-plugin install`, then
+`/wardby-runs`. Search help for "claude code plugin" (article
+`claude-code-run-pane`, Wardby 0.8.0 and later).

package/help/merge-order-check.md

@@ -51,6 +51,11 @@ merge order set by the delegating agent," counted over the whole set
 (merged and closed pull requests included), so a pull request's step
 number doesn't change as earlier steps merge.
 
+With Wardby 0.7.0 or later, when the delegating lead is linked with
+`markReadyWhenPassing`, later steps become ready for review only once this
+check is `success`. See
+[Mark ready when passing](code-review-agents.md#mark-ready-when-passing).
+
 ### Waiting for the delegating run to finish
 
 While the delegating (lead) agent's run that produced this set is still

package/help/native-capabilities.md

@@ -3,7 +3,7 @@ id: native-capabilities
 title: Use native agents, tools, and data
 summary: Attach scoped tools, secrets, datastores, memory, schedules, and sub-agents to a native Wardby agent.
 audience: developer
-tags: [agents, tools, secrets, datastores, memory, schedules, subagents]
+tags: [agents, tools, secrets, datastores, memory, schedules, subagents, zod, create_tool, dry_run_tool, timeoutMs, mcp]
 appliesTo: >=0.2.1
 ---
 
@@ -20,11 +20,65 @@ checkout. Give each agent only the capabilities its job needs:
 - **Schedules and webhooks** to start event-driven work.
 - **Sub-agents** for delegated, bounded work with their own capability set.
 
+A tool's parameters are a Zod schema written as source text (`paramsZod` on
+`create_tool` and `update_tool`). Wardby compiles it inside the sandbox, both to
+derive the JSON Schema the model sees and to validate each call's arguments.
+
+Wardby itself now uses Zod 4. For this release only, a tool's `paramsZod` is
+still compiled with Zod 3 (Zod 4's built-in `zod/v3` API), so existing tools keep
+working unchanged; a schema Zod 3 can't compile, such as one using `z.email()`,
+is compiled with Zod 4. **Zod 3 schemas stop working in the next release**,
+which compiles `paramsZod` with Zod 4 only. A schema that calls something Zod 4
+removed, such as `.nonstrict()`, `.deepPartial()`, `z.ostring()` or
+`z.string().ip()`, will then fail every call's validation.
+
+Wardby warns about each such tool now:
+
+- `create_tool`, `update_tool` and `dry_run_tool` results include a `warnings`
+  list naming the tool and the removed methods;
+- in `list_tools` and in `get_agent`'s attached tools, each tool you own that is
+  affected carries the same `warnings` list;
+- `wardby tool create` and bundle imports print the same warning;
+- the server logs one warning per affected tool at startup.
+
+To check a schema before the next release, call `dry_run_tool` with the tool's
+`paramsZod` and sample arguments. With no `warnings` in the result, the schema
+compiles with Zod 4 and Zod 4 treats those arguments the same way. Otherwise,
+rewrite the schema with the Zod 4 API (for example `z.looseObject()` for
+`.nonstrict()`, `z.string().optional()` for `z.ostring()`, and `z.ipv4()` or
+`z.ipv6()` for `.ip()`), dry-run it again, and save it with `update_tool`.
+
+## Tool time limits
+
+Wardby 0.8.0 and later. Each call of a tool has 10 seconds by default. A tool that calls a slow API can
+ask for more with `timeoutMs` (milliseconds, at least `1000`) on `create_tool`,
+`update_tool` or `dry_run_tool`, or `--timeout-ms` on `wardby tool create` and
+`wardby tool update`. Pass `timeoutMs: null` to `update_tool` (or
+`--timeout-ms default` to `wardby tool update`) to go back to the default.
+
+- The limit covers the whole call. Each `fetch` may run until the limit, and a
+  timer (`setTimeout`) can't be set for longer than it.
+- The server's `WARDBY_TOOL_MAX_TIMEOUT_MS` (default `300000`, five minutes)
+  caps it. A larger `timeoutMs` is refused with an error naming the ceiling. If
+  the operator lowers the ceiling later, existing tools run with the ceiling.
+- A run keeps the value it loaded, as it does the tool's code.
+- A call never outlasts its run: stopping the run aborts it, and a sandboxed
+  run's deadline cuts it off.
+- `list_tools` and `get_agent` show each tool's `timeoutMs` (`null` means the
+  default).
+
+Test a slow tool with `dry_run_tool` and the same `timeoutMs` before you attach
+it. A call that runs out of time fails with a `timeout` error; the help article
+`errors/tool-timeout` explains what to do.
+
 Use a budget or shared budget group on every agent, and inspect runs before
 expanding its access. An access grant is intentional delegation: use it only
 when an owner permits one agent to use another resource. Creating or changing
 tools, secrets, datastores, schedules, webhooks, memory, and budget groups
 requires the matching MCP scope.
 
+Native agents can also call tools from remote MCP servers; see
+[Remote MCP servers](../docs/mcp-servers.md) (0.8.0+).
+
 See [Operate agents](operating-agents.md) for run and budget management, and
 [`README.md`](../README.md) for the feature overview and MCP operations.