@wardby/cli 0.5.3 → 0.7.0

package/help/package-audit-mode.md

@@ -0,0 +1,91 @@
+---
+id: package-audit-mode
+title: Package audit mode
+summary: Let a coding agent install packages outside its allowlist for a limited time, recorded for approval afterwards; full mode also installs versions with high-severity advisories. Malware and the release-age limit are always enforced.
+audience: operator
+tags: [coding-agents, packages, allowlist, package audit, package audit mode, audit mode, packageAuditMode, packageAuditMinutes, approve_audited_packages, packages_audited, npm, pypi, supply-chain]
+appliesTo: >=0.7.0
+---
+
+# Package audit mode
+
+From Wardby 0.7.0, a coding agent's registry can run in package audit mode for
+a limited time. Instead of refusing a package that is not on the agent's
+allowlist, the registry installs it and records it. Use it to find out which
+packages a task needs, then approve them and turn the mode off.
+
+## Modes
+
+| Mode    | Packages outside the allowlist | High or critical advisories | Malware | Release age |
+| ------- | ------------------------------ | --------------------------- | ------- | ----------- |
+| off     | refused                        | withheld unless accepted    | refused | enforced    |
+| `audit` | installed and recorded         | withheld unless accepted    | refused | enforced    |
+| `full`  | installed and recorded         | installed and recorded      | refused | enforced    |
+
+Everything else still applies in every mode: integrity checks, source
+distributions, size and file limits, and a version outside an allowlist
+entry's own range (`foo@^1` never serves `foo@2`).
+
+## Turn it on and off
+
+The agent's owner sets it with `update_agent` (needs `packages:approve` or
+`agents:admin`):
+
+```json
+{ "id": "<agent id>", "codingProfile": { "packageAuditMode": "audit", "packageAuditMinutes": 1440 } }
+```
+
+- `packageAuditMinutes` defaults to 1440 (24 hours); the most is 10080 (7 days).
+- `packageAuditMinutes` alone re-arms the stored mode for that long.
+- `"packageAuditMode": null` turns it off.
+- `create_agent` does not accept it.
+
+`get_agent` shows `packageAuditActive` and a warning while the window is
+open. Each coding run takes the mode when it is dispatched and keeps it for
+its whole life, so a run that starts just before the window ends still runs
+with it.
+
+## Where audited packages show up
+
+- `get_run`: `packageAuditMode` and `packageAudit`, one entry per version
+  with its `relation` (`top-level`, `transitive` with `via`, `unknown`, or
+  `allowed`) and, in `full` mode, its `advisories` (the high and critical ones it was served despite).
+- The pull request body: a caution banner, **Packages outside the
+  allowlist**, and in `full` mode **Served despite advisories**.
+- The run's status comment on GitHub or Jira, and a `packages_audited` Slack
+  message on linked channels (see [Slack notifications](slack-notifications.md)).
+- The proxy log: one `registry.audited` line per version.
+
+A lockfile plan in audit mode approves what passes every other check, and the
+dependency cache never restores or saves a lockfile whose plan audited
+anything.
+
+## Keep the packages
+
+Approve the names a run recorded with `approve_audited_packages`
+(`{ "runId": "<run id>" }`), or add them to `codingProfile.packageAllowlist`
+with `update_agent`. Then turn the mode off.
+
+Without `names`, the tool adds only `top-level` packages. A package recorded
+as `unknown` (installed with no metadata or plan to show its parent) may be a
+dependency of an allowlisted package, so every report lists it apart as
+"Relation unknown — may be a dependency; approve only if needed directly".
+Add one only if the project uses it directly, by listing it in `names`.
+
+## Risks
+
+Audit mode weakens the supply-chain guard while it is on. `audit` keeps the
+malware, advisory and release-age checks; `full` keeps only malware and
+release age. A confused or prompt-injected agent could install a lookalike
+package that has no advisory yet. Install scripts stay off, but tests and
+builds still run what was installed. Keep the window short, review the
+caution banner on every affected pull request, and never leave it on.
+
+## Related
+
+- [Coding packages](coding-packages.md)
+- [Not allowed: `wardby_package_not_allowed`](errors/package-not-allowed.md)
+- [Package not reached: `wardby_package_not_allowed_pending`](errors/package-not-allowed-pending.md)
+- [Graph limit: `wardby_graph_limit`](errors/graph-limit.md)
+- [Still being checked: `wardby_graph_incomplete`](errors/graph-incomplete.md)
+- [Package audit mode guide](../docs/coding-packages.md#package-audit-mode)

package/help/related-pull-requests.md

@@ -1,7 +1,7 @@
 ---
 id: related-pull-requests
 title: Related pull requests across repositories
-summary: Wardby lists the other pull requests from the same request in each pull request's description, with a suggested merge order.
+summary: Wardby lists the other pull requests from the same request in each pull request's description, in the merge order the delegating agent set (mergeOrder) or else a suggested merge order.
 audience: operator
 tags: [github, pull-requests, multi-repo, merge-order, related, siblings, continuePriorRun, coding-agents, jira]
 appliesTo: ">=0.4.2"
@@ -11,16 +11,19 @@ appliesTo: ">=0.4.2"
 
 When one request produces pull requests in several repositories — a lead
 agent that delegates to one coding agent per repository, or several runs for
-the same Jira issue — Wardby adds a **Related pull requests** section to each
+the same Jira or GitHub issue — Wardby adds a **Related pull requests** section to each
 of those pull requests' descriptions. It lists the others with links and
 their state, names the originating issue when there is one, and gives a
-suggested merge order.
+merge order: the one the delegating agent set, or else a suggested one.
 
-Without a tracked Jira issue, the list covers the pull requests opened by
-runs in the same delegation tree (the same lead run and everything it
-started). With a tracked issue, the list covers every pull request Wardby
-has recorded for that issue across every run, merged and closed ones
-included, plus that run tree's own siblings.
+Without a tracked issue, the list covers the pull requests opened by runs in
+the same delegation tree (the same lead run and everything it started). With
+a tracked issue (a Jira issue, or a GitHub issue whose `@<app-slug>` mention
+started the request), the list covers every pull request Wardby has recorded
+for that issue across every run, merged and closed ones included, plus that
+run tree's own siblings. The section names the issue the same way for both,
+for example "for Jira issue PROJ-123" or "for GitHub issue owner/repo#7",
+linked to the issue.
 
 - **Written by Wardby, not the model.** The list comes from Wardby's own run
   records, never from the agent's text. Edits you make inside the section
@@ -30,13 +33,33 @@ included, plus that run tree's own siblings.
   section on every open pull request of the request with the full list and
   current states. A later run that pushes to any pull request in the set
   refreshes the section on all of them the same way, and never removes it.
-- **Suggested merge order (the order Wardby's agent opened them in)** numbers
-  the open (and draft) pull requests in delegation order. It is not a
-  dependency analysis — it is only reliable when the lead delegates
-  repositories that own shared data first (see
+  With Wardby 0.6.0 or later, a reviewer linked to one of these pull requests does
+  not review it until that same lead run finishes, however it ends. When the
+  lead finishes normally the section has already been rewritten by then;
+  when it is ended another way, such as being cancelled, reviews start
+  without that rewrite, so reviewers should rely on `repo_pr_read`'s
+  `relatedPullRequests` either way — see [Reviewing a pull request a
+  delegated run
+  opened](code-review-agents.md#reviewing-a-pull-request-a-delegated-run-opened).
+- **Merge order.** Without a `mergeOrder` (see below) on any pull request in
+  the set, open (and draft) pull requests are numbered as a **Suggested merge
+  order (the order Wardby's agent opened them in)** — delegation order, not a
+  dependency analysis, and only reliable when the lead delegates repositories
+  that own shared data first (see
   [Fanning out to several builders](../docs/agent-recipes.md#fanning-out-to-several-builders)).
-  Check it before merging. Merged and closed pull requests follow in a
-  separate "Already merged or closed" list, as context only.
+  When any pull request in the set has a `mergeOrder` (open, merged or
+  closed), the open ones that have one are numbered under **Merge order (set
+  by the delegating agent; equal steps can merge in either order)** and
+  labelled "step k of n" (equal values share a step and merge in either
+  order relative to each other), and any open pull request without one is
+  listed after under "Not ordered:". If only merged or closed pull requests
+  have a `mergeOrder`, every open one is listed under "Not ordered:" and the
+  "Merge order" heading is left out. Steps are counted over the whole set,
+  merged and closed pull requests included, so "step 2 of 3" keeps its label
+  after step 1 merges. Either way, check it before merging — neither is a
+  guarantee. Merged and closed pull requests follow in a separate "Already
+  merged or closed" list, as context only, with their step label when they
+  have one.
 - Only open pull requests that Wardby's own GitHub App opened are edited;
   merged or closed ones are listed but never changed, and a pull request
   from a different Wardby deployment sharing the same App is never touched.
@@ -45,13 +68,54 @@ included, plus that run tree's own siblings.
   name and number, so a request that spans repositories of different
   visibility can show a private repository's name in a public repository's
   pull request. If you mix public and private repositories, keep such work in
-  separate requests: separate Jira issues, or separate lead agents.
+  separate requests: separate issues, or separate lead agents.
 
 Reviewers see the section in the pull request description, so a reviewer
 agent can tell that a field, route, or schema a change relies on is added by
-a sibling pull request rather than missing. See the reviewer step in
+a sibling pull request rather than missing. Because the description is only
+rewritten at the points above, a sibling opened (or merged, or closed) since
+then can be missing from it or shown with an old state. With Wardby 0.6.0 or later,
+`repo_pr_read`'s `relatedPullRequests` field lists the request's pull
+requests fresh on every call instead, so a reviewer should prefer it over
+the description's section when they disagree. Its entry for the pull request
+just read always carries that pull request's live state; another entry
+carries a state only when Wardby has one stored (pull requests linked to an
+issue) and omits it otherwise, so call `repo_pr_read` on that pull request
+for its live state. `relatedPullRequests` is empty for a pull request on a
+local repository, which has no App-authored marker to resolve the request
+from. See the
+reviewer step in
 [Run GitHub code-review agents](code-review-agents.md#ci-and-sibling-pull-requests).
 
+## Setting a merge order
+
+A lead agent sets the order explicitly by passing `mergeOrder` on its
+`delegate_to_<name>` call to a coding sub-agent: an integer from 1 to 99,
+where 1 merges first. Give a repository that other repositories' changes
+depend on a lower number than the ones that use it — for example a shared
+service `1`, the API that calls it `2`, the client that calls the API `3`.
+Give two changes the same number when there is no order between them; they
+share a step and either can merge first. A bad value (not an integer, or
+outside 1-99) is refused as a tool error, not silently dropped or clamped.
+
+Set it whenever one request's change spans several repositories and the
+pull requests need to land in a specific sequence; leave it out and the set
+keeps the delegation-order suggestion above. `mergeOrder` applies only to
+coding sub-agents, since only a coding run's pull request can be ordered: a
+native sub-agent ignores it, and its tool result notes that it did.
+
+Each pull request shows the value most recently set for it, by the run that
+opened it or a later continuation of it. A `continuePriorRun` call that
+omits `mergeOrder` keeps that current value, so a follow-up does not need to
+repeat it to keep a pull request in its place; one that sets `mergeOrder`
+replaces it.
+
+With Wardby 0.6.0 or later, once a set has more than one `mergeOrder`, each
+open or draft pull request Wardby opened in it also gets a check run named
+`wardby merge order`, tracking whether the pull requests it depends on have
+merged yet. It's an informational check by default; search help for "merge
+order check" for its states and for requiring it in branch protection.
+
 ## Follow-up runs and sibling pull requests
 
 When someone asks for a follow-up on one of these pull requests (an

package/help/repo-instructions-and-skills.md

@@ -0,0 +1,91 @@
+---
+id: repo-instructions-and-skills
+title: Repository instructions and skills in coding runs
+summary: What AGENTS.md, CLAUDE.md, and repo skills a coding run loads, and how to turn repo skills off per agent with codingProfile.repoSkills.
+audience: all
+tags: [coding, skills, repoSkills, claudeBareMode, CLAUDE.md, AGENTS.md, SKILL.md, codex, claude-code]
+appliesTo: ">=0.5.4"
+---
+
+# Repository instructions and skills in coding runs
+
+Every coding run loads the repository's own instructions, and by default
+also loads whatever agent skills the repository ships. This is on for both
+builders and cannot be turned off for instructions; skills can be turned off
+per agent.
+
+## Repository instructions (always on)
+
+| Builder     | Gets                                                                              |
+| ----------- | --------------------------------------------------------------------------------- |
+| Codex       | `AGENTS.md`, read directly from the checkout                                      |
+| Claude Code | `CLAUDE.md`, `.claude/CLAUDE.md`, and their `@path` imports (up to 5 levels deep) |
+
+A repository that only has `AGENTS.md` still gets it in Claude Code, through
+a one-line `CLAUDE.md` wardby synthesizes for it. Subdirectory `CLAUDE.md`
+files (anything other than the repository root and `.claude/CLAUDE.md`) are
+not loaded unless an imported file pulls them in.
+
+Claude Code's instructions and skills are bounded: at most 64 KiB per file,
+200 files, and 256 KiB combined; symlinks and non-UTF-8 files are refused. A
+file that doesn't pass is left out of the run rather than failing it.
+Repository settings, hooks, `.mcp.json`, agents, and commands are never sent
+to Claude Code — only Markdown instruction files and
+`.claude/skills/<name>/SKILL.md` files are allowed through, whatever an
+instruction file imports.
+
+Repository instructions and skills are untrusted guidance: they can shape a
+run's work but never relax the worker's sandbox rules.
+
+## Repository skills
+
+`codingProfile.repoSkills` loads the repository's own agent skills into a
+run. It defaults to `true`, and the agent owner or an admin can set it with
+`create_agent`/`update_agent`:
+
+```json
+{ "id": "<agent-id>", "codingProfile": { "repoSkills": false } }
+```
+
+| Builder     | Reads skills from                   | `repoSkills: false`                |
+| ----------- | ----------------------------------- | ---------------------------------- |
+| Codex       | `.agents/skills/`, `.codex/skills/` | Every repository skill is disabled |
+| Claude Code | `.claude/skills/<name>/SKILL.md`    | No skill context is collected      |
+
+Codex's own four built-in skills (`imagegen`, `openai-docs`, `skill-creator`,
+`skill-installer`) are always disabled, whatever `repoSkills` is set to.
+
+A Claude Code skill ships to the worker as its `SKILL.md` only; its other
+files (scripts, references, data) stay in the repository checkout, read or
+run through the command runner at `/workspace/.claude/skills/<name>/`.
+
+## Claude Code loading mode
+
+`codingProfile.claudeBareMode` (Claude Code agents only, default `true`)
+decides how Claude Code uses its repository instructions and skills:
+
+- **`true` (default).** Claude Code's hardened bare mode stays on. Wardby
+  adds the repository's instruction files to the system prompt in full, and
+  lists each skill by name, description, and path; the model reads a
+  skill's full `SKILL.md` itself with `run_command`.
+- **`false`.** Bare mode is off and Claude Code loads `CLAUDE.md` and skills
+  itself, through its native Skill tool, instead of reading them from the
+  system prompt.
+
+Repository settings, hooks, MCP configuration, agents, and commands are
+never loaded in either mode.
+
+```json
+{ "id": "<agent-id>", "codingProfile": { "claudeBareMode": false } }
+```
+
+## See also
+
+- [Choose a native or coding agent](creating-agents.md) for `codingProfile`
+  basics and the other fields it accepts.
+- [Bring-Your-Own Coding-Worker Images](../docs/coding-worker-byo-images.md)
+  — a custom `workerImageRef` image must be rebuilt for the current release. A
+  Codex agent's image built on an older driver base rejects
+  `repoSkills: false` and keeps offering Codex's built-in skills.
+- [Build a tool runner image for a Claude Code agent](build-claude-code-image.md)
+  to give a Claude Code agent's commands the tools your project needs.

package/help/resume-runs-locally.md

@@ -0,0 +1,131 @@
+---
+id: resume-runs-locally
+title: Resume Claude Code runs locally (sessionResume, get_run_transcript, wardby resume)
+summary: Keep each Claude Code run's redacted conversation with sessionResume, then continue it on your machine with get_run_transcript and npx @wardby/cli@latest resume.
+audience: operator
+tags: [sessionResume, wardby resume, get_run_transcript, transcript, blob-store, WARDBY_SESSION_TRANSCRIPTS]
+appliesTo: ">=0.7.0"
+---
+
+# Resume Claude Code runs locally
+
+`sessionResume` makes a Claude Code agent keep a redacted copy of each run's
+conversation, so the session can be continued locally in Claude Code with
+`get_run_transcript` and `npx @wardby/cli@latest resume`. It is off by default and is not
+available for Codex agents. It needs Claude Code worker images from Wardby
+0.7.0 or later.
+
+## Turn it on
+
+```json
+{ "id": "<coding agent id>", "codingProfile": { "sessionResume": true } }
+```
+
+Use `update_agent` or `create_agent`. The server needs a blob store
+(`BLOB_STORE`, with `BLOB_STORE_LOCAL_DIR`, `BLOB_STORE_GCS_BUCKET`, or
+`BLOB_STORE_S3_BUCKET` and `BLOB_STORE_S3_REGION`, plus the optional
+`BLOB_STORE_S3_ENDPOINT` for an S3-compatible store) set on the **server
+process** that launches coding runs, not only on the coding proxy. Without a
+blob store nothing is stored, and `update_agent` warns you.
+
+## What is stored
+
+- The conversation as Claude Code recorded it: user and assistant messages,
+  tool calls and their results, compaction summaries, files and skills the
+  agent loaded, and a session title (`wardby run <id>: <task>` when Claude
+  Code made none).
+- Removed: thinking blocks, the system prompt, the worker's environment, date
+  and budget reminders, account and organisation details, and billing
+  records.
+- Redacted: the values of the agent's attached secrets, plus the run's
+  capability and registry token by their token shape. If the agent's secrets
+  cannot be loaded, nothing is stored.
+- Stored for runs that finish, stop at their budget, or fail. Not stored for
+  runs stopped with `stop_run` or ended by their timeout.
+- Stored gzip-compressed under the `run-transcripts/` prefix. When the run's
+  context was compacted, only what a resume loads is kept: the last
+  compaction's summary, the messages it kept, and everything after it.
+- At most `RUN_TRANSCRIPT_MAX_BYTES` per run, measured before compression
+  (default 10 MiB, at most 64 MiB). Each run records a status (`stored`,
+  `too_large`, `not_captured` or `failed`) with a reason code.
+
+## Who can read it
+
+Transcripts are stored from the first run with `sessionResume` on. Anyone
+who can read a run (its triggerer and the agent's owner, as for `get_run`)
+can download its transcript, which includes
+what the agent saw in the repository and in command output. Redaction removes secret
+values, not other sensitive text. Turn this on only for agents whose runs you
+are comfortable sharing with everyone who can read them.
+
+## Continue a run on your machine
+
+1. Ask your MCP client to call `get_run_transcript` with the run id (same
+   access as `get_run`). For a stored transcript it returns a download link
+   that works for 10 minutes and the command to run; otherwise the status
+   (`none`, `too_large`, `not_captured`, `failed`, `expired`, `unavailable`,
+   `unsupported`) and what it means.
+2. Run the command in a terminal, `npx @wardby/cli@latest resume -`, and paste the link
+   when it asks. (A link given as an argument stays in shell history and the
+   process list.) For a GitHub repository, run it inside a clone of that
+   repository. A `local:` repository is used only when the link comes from
+   this machine (a stdio MCP server); otherwise pass `--here` or `--dir`.
+
+It verifies the download's SHA-256, writes the session to
+`~/.wardby/sessions/<run id>/<session id>.jsonl` (mode 0600, never into
+Claude Code's own config directory), adds a detached git worktree of the
+run's branch next to the repository (the base commit, with a warning, when
+the branch is gone), and starts `claude --resume` there. A stand-in
+`wardby_tools` server shows the run's `run_command` calls but runs nothing,
+and a note tells the model `/workspace` is now the worktree.
+
+Options: `--dir <path>` (worktree location), `--here` (no checkout),
+`--force` (replace a different imported session file), `--print` (print the
+`claude` command instead of starting it). The command passes
+`--system-prompt-snapshot off` so the move note applies; remove it for a
+Claude Code older than 2.1.257 when the version could not be read. Under
+`npx`, the MCP config points into the npx cache: run `wardby resume` again if
+the cache was cleaned.
+
+The link is a credential until it expires: do not share it. Over stdio it
+points at a local port the MCP server opens, so keep your MCP client
+connected until the download finishes. The token is in the link's query
+string: keep `/run-transcripts/download` out of load-balancer and ingress
+access logs. Refusals:
+[Run transcript download refused](errors/run-transcript-download.md).
+
+## Retention
+
+`RUN_TRANSCRIPT_RETENTION_DAYS` is a whole number from 1 to 3650 (default 30).
+Expired transcripts are pruned when new ones are stored. On GCS or S3 also add
+a bucket lifecycle rule on the `run-transcripts/` prefix.
+
+## Set it up per deployment
+
+Give transcripts a bucket of their own, not the dependency cache bucket, that
+only the control plane can use.
+
+- GKE: `session_transcripts_enabled` and `session_transcripts_bucket_name` in
+  Terraform (optionally `session_transcripts_retention_days`), then
+  `WARDBY_SESSION_TRANSCRIPTS=true deploy/gke/up.sh`. Terraform adds the
+  lifecycle rule; `up.sh` passes the same retention to the control plane.
+- AWS: the same Terraform variables, then give the control plane `BLOB_STORE=s3`,
+  the `session_transcripts_bucket` output as `BLOB_STORE_S3_BUCKET`,
+  `BLOB_STORE_S3_REGION`, and the `session_transcripts_retention_days` output as
+  `RUN_TRANSCRIPT_RETENTION_DAYS`.
+- kind harness and Docker quickstart: the server runs on your host. Set
+  `BLOB_STORE=local` and `BLOB_STORE_LOCAL_DIR` in its environment (for the
+  quickstart, in `.wardby/.env`).
+
+## Startup and custom images
+
+With `JOB_LAUNCHER` set to `docker` or `kubernetes`, a half-set `BLOB_STORE`
+or an invalid `RUN_TRANSCRIPT_RETENTION_DAYS` or `RUN_TRANSCRIPT_MAX_BYTES` stops
+the server at startup,
+naming the variable. An agent with its own `workerImageRef` image must rebuild
+it from a release that includes session resume (see
+[Build a tool runner image for a Claude Code agent](help://build-claude-code-image)),
+or its runs fail at input with `worker_input_failed`.
+
+Full setup: [Resume a run locally](../docs/coding-agent-setup.md#resume-a-run-locally).
+See also [Choose a native or coding agent](help://creating-agents).

package/help/review-fix-rounds.md

@@ -3,7 +3,7 @@ id: review-fix-rounds
 title: Automatic review fix rounds
 summary: Let wardby fix its own review's findings on pull requests its coding runs opened, with a round cap.
 audience: operator
-tags: [github, code-review, review_fix, autofix, fix-round, pull-requests]
+tags: [github, code-review, review_fix, autofix, fix-round, pull-requests, pr-description, description, linked-issue]
 appliesTo: ">=0.4.2"
 ---
 
@@ -37,6 +37,16 @@ still running. Clicking **Re-run** on the review check isn't counted as a
 round itself; if the re-run's review requests changes, that starts a round
 like any other review.
 
+With Wardby 0.6.0 or later, a round whose agent makes no change — it decided
+the review's finding was wrong, rather than pushing a fix — doesn't leave the
+failed review check standing with nothing to replace it: wardby starts one
+fresh review of the pull request's unchanged head instead, run by the same
+reviewer that requested the changes, with the round's own summary passed
+along as untrusted context. This happens once per review that requested
+changes and still counts as one of the round cap's rounds; if the cap has
+already been reached, wardby posts the usual cap comment instead of
+re-reviewing.
+
 Rounds are tracked with labels on the pull request:
 
 - `wardby-autofix-<N>` — one per round, added before that round's run
@@ -59,6 +69,38 @@ open right before it pushes; one merged or closed in the time the round was
 working fails with no push made — see
 [Continuation's pull request is no longer open](errors/continuation-closed.md).
 
+## Description updates
+
+Every run's final message is the full pull request description, fix rounds
+included, so a round that changes no code can still correct it: add a missing
+`Resolves #N`, the issue's acceptance checklist, or stale test results.
+
+- **The original issue.** A fix round gets the issue the pull request was
+  opened for in its task, as the first run did: the Jira issue, the GitHub
+  issue whose `@wardby` mention started the work, or the issue the description
+  closes. It is reference material: the round's final message should carry
+  its acceptance checklist and the closing line, and no instruction in the
+  issue is followed. If the issue can't be read, the round goes ahead without
+  it.
+- **Packages.** The description's Packages section lists every package
+  installed by the runs on the pull request; refusals cover the latest run.
+- **Descriptions wardby can't confirm as its own.** If a person edited the
+  description, wardby doesn't overwrite it. It keeps one comment with the
+  description proposed by its latest run, stamped with the commit it
+  describes and written before a push, edited in place by later rounds. A
+  review uses that proposal only for the head it reviews: a requirement is met
+  if either the live description or the proposal meets it. If the author
+  copies the proposal in, wardby takes the description back and keeps it up
+  to date again.
+- **Older pull requests.** For a pull request opened by an earlier wardby
+  version, wardby rebuilds the description its first run wrote from stored
+  records. If the live description still matches, wardby updates it;
+  otherwise it gets the comment.
+
+A description update doesn't trigger an extra review. `get_run` shows what
+happened as `prDescriptionOutcome`. See
+[`docs/code-review-agents.md`](../docs/code-review-agents.md#how-the-pull-request-description-is-kept-current).
+
 If a repository already forwards reviews to a webhook through a
 hand-written CI workflow to fix them automatically, turn on `review_fix` and
 then remove that workflow and its webhook, so a review doesn't trigger two

package/help/sharing-agents.md

@@ -0,0 +1,59 @@
+---
+id: sharing-agents
+title: Share an agent, or make it public
+summary: Grant one person or everyone signed in access to an agent, including a public agent anyone can edit.
+audience: operator
+tags: [sharing, grant_access, public, access-control, agents]
+appliesTo: ">=0.7.0"
+---
+
+# Share an agent, or make it public
+
+An agent's owner controls who else can reach it with `grant_access`,
+`revoke_access` and `list_access`. Levels, lowest first:
+
+- `read`: see the agent in `list_agents` and `get_agent`.
+- `execute`: also run it (`trigger_agent`).
+- `write`: also change it (`update_agent`, schedule, webhooks, tools).
+
+The grantee is one person, `{"subject": "..."}` or `{"principalId": "..."}`,
+who must have signed in once, or `"everyone"`: any principal signed in to the
+MCP server.
+
+## Public agents
+
+Grant `everyone` at `read` or `execute` for an agent anyone can see or run.
+Grant `everyone` at `write` for an agent anyone can also edit.
+
+Everyone-`write` is refused while the agent holds any of its owner's bindings:
+secrets, datastores, repositories, sub-agents, tool capabilities, or a coding
+repository, so a coding agent can't be public-write. Otherwise anyone could
+rewrite its prompt and use them. Detach them first, or grant `execute` instead.
+The reverse holds too: `attach_secret`, `attach_datastore`, `link_repository`,
+`attach_subagent`, `attach_tool` with capabilities, and `update_agent` making
+it a coding agent are refused on an agent everyone can write. Revoke or lower
+the everyone grant first.
+
+### Cap what a public-write agent can spend
+
+Runs of a shared agent are charged to its owner. With `write`, anyone signed in
+can change the agent's model, per-run budget, turns and schedule, and create
+webhooks that trigger it. Before granting everyone `write`, put the agent in a
+budget group (`create_budget_group`, then `update_agent` with `budgetGroupId`).
+Only the owner can change
+budget-group membership, so the group's limit caps total spend whatever anyone
+else changes.
+
+### After you revoke or lower the grant
+
+- **Webhooks:** a webhook fires only while its creator can still run the
+  agent. Revoking the everyone grant stops webhooks other people created;
+  lowering it to `execute` keeps them firing. Use `list_webhooks` and
+  `delete_webhook` to remove them; the owner can delete any webhook on the
+  agent.
+- **Schedule:** a schedule someone else set stays on the agent. Check it with
+  `get_agent` and remove it with `disable_schedule`.
+- **Prompt and settings:** edits stay. Check the prompt, model and budget with
+  `get_agent`.
+
+See [Identity and access](identity-and-access.md) for sign-in and scopes.

package/help/slack-notifications.md

@@ -0,0 +1,76 @@
+---
+id: slack-notifications
+title: Send workflow updates to Slack
+summary: Link a Slack channel to a Jira project or an agent to follow cards from pickup to merge, one thread per card.
+audience: operator
+tags: [slack, notifications, channels, jira, pull-requests, link_notification_channel]
+appliesTo: >=0.6.0
+---
+
+# Send workflow updates to Slack
+
+Link a Slack channel to a Jira project or to an agent (native or coding) and wardby posts
+that project's or agent's workflow updates there — a card picked up, a pull
+request opened, a review verdict, fix rounds, and the merge — with one thread
+per card. This is outbound only: nothing in Slack starts or affects a run.
+
+## Setup checklist
+
+1. Create the Slack app from [`deploy/slack/app-manifest.yaml`](../deploy/slack/app-manifest.yaml)
+   and install it to your workspace.
+2. Copy the Bot User OAuth Token (`xoxb-…`).
+3. Set `WARDBY_SLACK_BOT_TOKEN` (store it like any other provider credential)
+   and restart wardby.
+4. Link a channel with `link_notification_channel` — to a Jira project
+   (`projectKey`) or to an agent (`agentId`).
+5. Call `test_notification_channel` and confirm "✅ wardby is connected to
+   this channel." posts there.
+
+## Events
+
+`issue_picked_up`, `run_failed` and `run_blocked` (top-level runs only),
+`pr_opened`, `review_posted` (approve / changes requested / comment),
+`review_fix` (round started, or stopped at the cap), `pr_closed` (merged or
+closed, with any Jira status move), and `packages_audited` (from Wardby 0.7.0,
+top-level runs only: what its coding runs installed under package audit mode,
+described in the `package-audit-mode` help article; it doesn't change the
+thread's status). `events` on a link narrows which of these post; omitted
+means all eight. `includeCost` appends the run's spend line.
+
+A pull request opened from a GitHub issue mention posts `pr_opened` and
+`pr_closed` too, the same as one opened for a Jira issue. Its thread is the
+issue's, one per GitHub issue, not one per pull request; once the pull request
+is recorded for the issue, its `review_posted` and `review_fix` events reply
+there as well. The run events of a run a GitHub issue mention started keep a
+thread of their own.
+
+A `run_blocked` event uses the same ⛔ package registry wording and fixes as
+[Run status comments](status-comments.md). See [Package refusal errors](errors/package-refusals.md)
+for allowlist, release-age, advisory, and malware guidance.
+
+wardby never posts code, diffs, review text, or run output to Slack.
+
+## If something isn't posting
+
+- The link's `lastError` (from `list_notification_channels`) names the
+  problem. A channel error means the bot can't write there — see
+  [`errors/slack-channel-unreachable`](errors/slack-channel-unreachable.md).
+- No deliveries at all, for every channel, usually means the bot token is
+  invalid, revoked, or missing a scope — see
+  [`errors/slack-auth-failed`](errors/slack-auth-failed.md).
+- A channel that recovers gets new events again right away; deliveries that
+  already failed are not resent.
+- Linking or testing refused outright means Slack isn't configured yet — see
+  [`errors/slack-not-configured`](errors/slack-not-configured.md).
+
+## Related
+
+- [Run Jira agents](jira.md) — link a channel to the same project a Jira
+  agent is linked to, to see its cards move end to end.
+- [Automatic review fix rounds](review-fix-rounds.md) — the `review_fix`
+  event covers these rounds.
+- [Connect GitHub repositories](github.md) — pull-request events come from
+  the same App your coding and review agents already use.
+
+For the full guide, including scopes, threads, and failure modes, see
+[`docs/slack-notifications.md`](../docs/slack-notifications.md).