@wardby/cli 0.5.0 → 0.5.1

package/dist/help-index.json

@@ -54,8 +54,8 @@
       ],
       "appliesTo": ">=0.4.0",
       "sourcePath": "agent-recipes.md",
-      "markdown": "\n# Agent recipes\n\nTwo complete setups: an **architecture keeper** (a scheduled architect coding\nagent, a merge watcher with the `push` trigger, and a reviewer step that uses\n`docs/knowledge/`) and a **builder** (a native router linked with `mention` that\ndelegates to a coding builder, for Node/TypeScript, Python, or a\nbring-your-own-image toolchain).\n\nThey go beyond the quickstart, which runs native agents only. They require\nWardby 0.4.0 or later, plus the GitHub App, worker image, and job launcher from\ncoding-agent setup. The full recipes, with every configuration and prompt, are\nin [`docs/agent-recipes.md`](../docs/agent-recipes.md).\n\nIf you are an assistant connected to Wardby over MCP, follow these steps. Do\nthem in order, ask the user instead of guessing, and stop at the first failed\nprerequisite.\n\n## Step 0: choose\n\nAsk the user:\n\n1. Which recipe: \"architecture keeper\" or \"builder\"?\n2. Which repository, as `owner/name`?\n3. The coding provider, `codex` or `claude-code`, for both recipes (the\n   architect is a coding agent too). Never guess it.\n4. For the builder only: the language or stack, which decides `toolchain`\n   (`node` for Node/TypeScript, `node-python` with `toolchainVersion: \"3.12\"`\n   for Python, or a bring-your-own worker image for anything else).\n\nAgent names are unique across the whole instance, so the recipes use\nrepo-scoped names: `<repo>-architect`, `<repo>-merge-watcher`, `<repo>-builder`,\nand `<repo>-router`, where `<repo>` is the repository name from `owner/name`.\nCall `list_agents` first; if a name is taken, ask the user for another. Keep the\n`boundName` values `architect` and `builder` unchanged, so the delegate tools\nstay `delegate_to_architect` and `delegate_to_builder`.\n\n## Step 1: check prerequisites\n\nCheck these before creating anything.\n\n1. **Local install.** Over the local stdio connection `link_host_account` is\n   not available (it needs Wardby's HTTP transport), and a quickstart-only\n   install has no GitHub App or coding workers. If that is your situation,\n   explain it to the user and point them to\n   [`docs/coding-agent-setup.md`](../docs/coding-agent-setup.md) instead of\n   trying.\n2. **GitHub account link.** Call `get_host_account`. If `accounts` is empty,\n   call `link_host_account` with no arguments, give the user the `authorizeUrl`,\n   and when they return the one-time code, call `link_host_account` again with\n   `confirmationCode`.\n3. **Repository access.** No tool lists the repositories the GitHub App can\n   see. The linked account needs write access to the repository, and both\n   `create_agent` (with a `codingProfile`) and `link_repository` check this and\n   refuse with a clear error if it is missing. Ask the user to confirm the GitHub\n   App is installed on the repository. Do not use `adminOverride` or\n   `repositoryAdminOverride` unless the user is an admin and asks for it.\n4. **Models.** Call `list_models` and pick ids whose `routable` is true: a\n   capable coding model that the chosen provider supports, and a small fast model\n   for the native agent.\n5. **Coding-agent setup.** If coding agents are not set up yet, tell the user to\n   run `wardby coding preflight` (CLI) and finish coding-agent setup first. See\n   [`docs/coding-agent-setup.md`](../docs/coding-agent-setup.md).\n6. **Webhooks.** Event triggers need GitHub to reach the instance at a public\n   HTTPS URL, with the App's events ticked: **Push** for the merge watcher;\n   **Issue comment**, **Pull request review comment**, and **Issues** for\n   mentions. Scheduled and manual runs need no webhook.\n\nIf a prerequisite fails, stop and tell the user what to do. Do not create agents.\n\n## Step 2A: architecture keeper\n\n1. Call `get_help_article` with `id: \"architecture-agent\"`. It holds the\n   architect system prompt (\"System prompt\"), the watcher prompt, and the\n   reviewer step. Use them unchanged.\n2. Call `create_agent` for the architect: `name: \"<repo>-architect\"`, `kind: \"coding\"`,\n   `model` a capable coding model, `budgetUsd: 3`, `systemPrompt` the architect\n   prompt, and `codingProfile` with `provider`, `repository`, `baseRef` (the\n   default branch), and `defaultTask`: `Weekly knowledge review. Run the full\ncycle described in your instructions for this repository. Your file changes\nare collected into a pull request for review; don't try to commit or open one\nyourself.`\n3. Tell the user the run is billed up to the agent's budget ($3) and get their\n   confirmation. Then call `trigger_agent` once with the architect's `agentId`\n   and show them the run (`get_run`). If the run failed or produced no pull\n   request, stop and show the error or summary; never call `set_schedule` after a\n   failed run. Otherwise **stop** and ask them to review and merge the first\n   draft pull request before continuing.\n4. When they say to continue, call `set_schedule` with the architect's\n   `agentId`, `schedule: \"0 6 * * 1\"`, and the user's `timezone`.\n5. Call `create_agent` for the watcher: `name: \"<repo>-merge-watcher\"`,\n   `kind: \"native\"`, a small fast `model`, the watcher prompt as `systemPrompt`,\n   and a `budgetUsd` of at least 3 plus a little (the run tree shares one\n   budget).\n6. Call `attach_subagent` with `parentAgentId` the watcher, `childAgentId` the\n   architect, and `boundName: \"architect\"`.\n7. Ask the user to tick **Push** in the GitHub App's event settings (and keep\n   Contents: read). Wait for their confirmation.\n8. Call `link_repository` with `agentId` the watcher, `repository`,\n   `access: \"write\"`, and `triggers: [\"push\"]`. Send no `checkName`.\n9. Offer the reviewer step: if the user has a code-review agent, offer to append\n   the \"Reviewer step\" from the same article to its prompt with `update_agent`\n   (read it first with `get_agent`, and keep its existing prompt).\n\n## Step 2B: builder\n\n1. **Check for a mention conflict first**, before creating anything. Call\n   `list_agents`, then `list_repositories` for each native agent you can see, to\n   find one linked to the repository with the `mention` trigger (only one agent\n   per repository may handle mentions). If one exists, reuse it as the router\n   only if the user owns it and agrees; then attach the builder to it and skip\n   creating a router. Never unlink or relink another agent.\n2. Ask the user to confirm the GitHub App subscribes to **Issue comment**,\n   **Pull request review comment**, and **Issues** events.\n3. Call `create_agent` for the builder: `name: \"<repo>-builder\"`,\n   `kind: \"coding\"`, a `model` the chosen provider supports, `budgetUsd` such as\n   `5`, `systemPrompt` the prompt from `get_help_article` with\n   `id: \"builder-agent\"` (section \"Builder prompt\"), and a `codingProfile` with\n   `provider`, `repository`, `baseRef`, and `timeoutSec` (for example `1800`),\n   plus the stack settings:\n   - Node/TypeScript: `toolchain: \"node\"`, with `packageAllowlist` such as\n     `{ \"npm\": [\"react@^19\", \"vitest\"] }`.\n   - Python: `toolchain: \"node-python\"`, `toolchainVersion: \"3.12\"`, with\n     `packageAllowlist` such as `{ \"pypi\": [\"flask>=3\"] }` (wheels only; list a\n     wheel package's own name, not an extra). Add `services: [\"postgres\"]` if\n     tests need a database: the repository must commit `.wardby/services.yaml`\n     declaring it, and the name must be in the catalog (`list_services`), or\n     `create_agent` returns 400.\n   - Other: `toolchain: \"node\"` plus a digest-pinned `workerImageRef`. Ask the\n     user for the image reference; never invent one. It needs the `agents:admin`\n     scope; if the user lacks it, stop and say so.\n\n   A `packageAllowlist` needs `packages:approve` or `agents:admin`.\n\n4. If you are not reusing a router, call `create_agent` with\n   `name: \"<repo>-router\"`, `kind: \"native\"`, a small fast `model`, a `budgetUsd`\n   of the builder's budget plus a little, and the router prompt from\n   `get_help_article` with `id: \"builder-agent\"` (section \"Router prompt\").\n5. Call `attach_subagent` with `parentAgentId` the router, `childAgentId` the\n   builder, and `boundName: \"builder\"`.\n6. Call `link_repository` with `agentId` the router, `repository`,\n   `access: \"write\"`, and `triggers: [\"mention\"]`. If it returns the 409\n   \"Another agent already handles @-mentions\", **stop** and tell the user, and\n   list the agents you created. Never unlink or relink another agent. If linking\n   fails for any reason after you created agents, tell the user what was created.\n7. Ask the user to try one `@<app-slug>` request on an issue, where\n   `<app-slug>` is the GitHub App's name. A test run is billed up to the\n   builder's budget; say so first.\n\n## Step 2C (optional): a lead that fans out\n\nA router delegates once per run by default. For one native agent that splits a\nrequest across several repositories, attach one builder per repository and set\nthe lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or\n`update_agent`. Each `delegate_to_<name>` call must go to a different\nsub-agent; the calls run one after another unless you also set\n`parallelDelegations: true`, which starts only the **consecutive**\n`delegate_to_*` calls of one turn together — a non-delegation call between\ntwo delegations splits them, nothing is reordered, and results return to the\nlead in call order (tell the lead to make its independent delegations\nconsecutively, in one turn; coding builders beyond `CODING_MAX_CONCURRENT`\nqueue); the run tree shares the lead's budget, so size `budgetUsd` for every\nbuilder it may start. Builders started together each reserve their budget up\nfront, so size the lead's `budgetUsd` for all of them, with headroom since\nthe lead's own unspent budget isn't reserved against them; a builder refused\nfor budget while a sibling still runs waits for it and retries (otherwise the\nrefusal is immediate). Cancelling the lead stops a running coding sub-agent\nbut not a running native one. Put the full cross-repository contract in each\nbuilder's task, since each builder sees only its own repository. Each\nbuilder's result includes `pullRequest` (`outcome`,\n`repository`, `number`, `url`) from Wardby's own record when it opened or\npushed to one, so the lead can report the links.\n\n## Step 3: confirm\n\nSummarize what you created: each agent's name and id, the sub-agent bindings,\nthe repository links and their triggers, and the schedule. Then state the next\nmanual step for the user: merge the first knowledge pull request, tick any App\nevents still missing, or try the first `@` mention. Remind them that Wardby never\nmerges pull requests for them.\n\nRelated: [Builder and router prompts](help://builder-agent),\n[Set up an architecture agent](help://architecture-agent),\n[Architecture knowledge bundles](help://knowledge),\n[Choose a native or coding agent](help://creating-agents),\n[Connect GitHub repositories](help://github-integration),\n[Run GitHub code-review agents](help://code-review-agents),\n[Approve packages for coding agents](help://coding-packages), and\n[Services for coding runs](help://coding-services).\n",
-      "plainText": "Agent recipes Two complete setups: an architecture keeper (a scheduled architect coding agent, a merge watcher with the push trigger, and a reviewer step that uses docs/knowledge/) and a builder (a native router linked with mention that delegates to a coding builder, for Node/TypeScript, Python, or a bring-your-own-image toolchain). They go beyond the quickstart, which runs native agents only. They require Wardby 0.4.0 or later, plus the GitHub App, worker image, and job launcher from coding-agent setup. The full recipes, with every configuration and prompt, are in docs/agent-recipes.md. If you are an assistant connected to Wardby over MCP, follow these steps. Do them in order, ask the user instead of guessing, and stop at the first failed prerequisite. Step 0: choose Ask the user: Which recipe: \"architecture keeper\" or \"builder\"? Which repository, as owner/name? The coding provider, codex or claude-code, for both recipes (the architect is a coding agent too). Never guess it. For the builder only: the language or stack, which decides toolchain (node for Node/TypeScript, node-python with toolchainVersion: \"3.12\" for Python, or a bring-your-own worker image for anything else). Agent names are unique across the whole instance, so the recipes use repo-scoped names: <repo-architect, <repo-merge-watcher, <repo-builder, and <repo-router, where <repo is the repository name from owner/name. Call listagents first; if a name is taken, ask the user for another. Keep the boundName values architect and builder unchanged, so the delegate tools stay delegatetoarchitect and delegatetobuilder. Step 1: check prerequisites Check these before creating anything. Local install. Over the local stdio connection linkhostaccount is not available (it needs Wardby's HTTP transport), and a quickstart-only install has no GitHub App or coding workers. If that is your situation, explain it to the user and point them to docs/coding-agent-setup.md instead of trying. GitHub account link. Call gethostaccount. If accounts is empty, call linkhostaccount with no arguments, give the user the authorizeUrl, and when they return the one-time code, call linkhostaccount again with confirmationCode. Repository access. No tool lists the repositories the GitHub App can see. The linked account needs write access to the repository, and both createagent (with a codingProfile) and linkrepository check this and refuse with a clear error if it is missing. Ask the user to confirm the GitHub App is installed on the repository. Do not use adminOverride or repositoryAdminOverride unless the user is an admin and asks for it. Models. Call listmodels and pick ids whose routable is true: a capable coding model that the chosen provider supports, and a small fast model for the native agent. Coding-agent setup. If coding agents are not set up yet, tell the user to run wardby coding preflight (CLI) and finish coding-agent setup first. See docs/coding-agent-setup.md. Webhooks. Event triggers need GitHub to reach the instance at a public HTTPS URL, with the App's events ticked: Push for the merge watcher; Issue comment, Pull request review comment, and Issues for mentions. Scheduled and manual runs need no webhook. If a prerequisite fails, stop and tell the user what to do. Do not create agents. Step 2A: architecture keeper Call gethelparticle with id: \"architecture-agent\". It holds the architect system prompt (\"System prompt\"), the watcher prompt, and the reviewer step. Use them unchanged. Call createagent for the architect: name: \"<repo-architect\", kind: \"coding\", model a capable coding model, budgetUsd: 3, systemPrompt the architect prompt, and codingProfile with provider, repository, baseRef (the default branch), and defaultTask: Weekly knowledge review. Run the full cycle described in your instructions for this repository. Your file changes are collected into a pull request for review; don't try to commit or open one yourself. Tell the user the run is billed up to the agent's budget ($3) and get their confirmation. Then call triggeragent once with the architect's agentId and show them the run (getrun). If the run failed or produced no pull request, stop and show the error or summary; never call setschedule after a failed run. Otherwise stop and ask them to review and merge the first draft pull request before continuing. When they say to continue, call setschedule with the architect's agentId, schedule: \"0 6 1\", and the user's timezone. Call createagent for the watcher: name: \"<repo-merge-watcher\", kind: \"native\", a small fast model, the watcher prompt as systemPrompt, and a budgetUsd of at least 3 plus a little (the run tree shares one budget). Call attachsubagent with parentAgentId the watcher, childAgentId the architect, and boundName: \"architect\". Ask the user to tick Push in the GitHub App's event settings (and keep Contents: read). Wait for their confirmation. Call linkrepository with agentId the watcher, repository, access: \"write\", and triggers: [\"push\"]. Send no checkName. Offer the reviewer step: if the user has a code-review agent, offer to append the \"Reviewer step\" from the same article to its prompt with updateagent (read it first with getagent, and keep its existing prompt). Step 2B: builder Check for a mention conflict first, before creating anything. Call listagents, then listrepositories for each native agent you can see, to find one linked to the repository with the mention trigger (only one agent per repository may handle mentions). If one exists, reuse it as the router only if the user owns it and agrees; then attach the builder to it and skip creating a router. Never unlink or relink another agent. Ask the user to confirm the GitHub App subscribes to Issue comment, Pull request review comment, and Issues events. Call createagent for the builder: name: \"<repo-builder\", kind: \"coding\", a model the chosen provider supports, budgetUsd such as 5, systemPrompt the prompt from gethelparticle with id: \"builder-agent\" (section \"Builder prompt\"), and a codingProfile with provider, repository, baseRef, and timeoutSec (for example 1800), plus the stack settings: Node/TypeScript: toolchain: \"node\", with packageAllowlist such as { \"npm\": [\"react@^19\", \"vitest\"] }. Python: toolchain: \"node-python\", toolchainVersion: \"3.12\", with packageAllowlist such as { \"pypi\": [\"flask=3\"] } (wheels only; list a wheel package's own name, not an extra). Add services: [\"postgres\"] if tests need a database: the repository must commit .wardby/services.yaml declaring it, and the name must be in the catalog (listservices), or createagent returns 400. Other: toolchain: \"node\" plus a digest-pinned workerImageRef. Ask the user for the image reference; never invent one. It needs the agents:admin scope; if the user lacks it, stop and say so. A packageAllowlist needs packages:approve or agents:admin. If you are not reusing a router, call createagent with name: \"<repo-router\", kind: \"native\", a small fast model, a budgetUsd of the builder's budget plus a little, and the router prompt from gethelparticle with id: \"builder-agent\" (section \"Router prompt\"). Call attachsubagent with parentAgentId the router, childAgentId the builder, and boundName: \"builder\". Call linkrepository with agentId the router, repository, access: \"write\", and triggers: [\"mention\"]. If it returns the 409 \"Another agent already handles @-mentions\", stop and tell the user, and list the agents you created. Never unlink or relink another agent. If linking fails for any reason after you created agents, tell the user what was created. Ask the user to try one @<app-slug request on an issue, where <app-slug is the GitHub App's name. A test run is billed up to the builder's budget; say so first. Step 2C (optional): a lead that fans out A router delegates once per run by default. For one native agent that splits a request across several repositories, attach one builder per repository and set the lead's maxDelegationsPerRun (1 to 20) with createagent or updateagent. Each delegateto<name call must go to a different sub-agent; the calls run one after another unless you also set parallelDelegations: true, which starts only the consecutive delegateto calls of one turn together — a non-delegation call between two delegations splits them, nothing is reordered, and results return to the lead in call order (tell the lead to make its independent delegations consecutively, in one turn; coding builders beyond CODINGMAXCONCURRENT queue); the run tree shares the lead's budget, so size budgetUsd for every builder it may start. Builders started together each reserve their budget up front, so size the lead's budgetUsd for all of them, with headroom since the lead's own unspent budget isn't reserved against them; a builder refused for budget while a sibling still runs waits for it and retries (otherwise the refusal is immediate). Cancelling the lead stops a running coding sub-agent but not a running native one. Put the full cross-repository contract in each builder's task, since each builder sees only its own repository. Each builder's result includes pullRequest (outcome, repository, number, url) from Wardby's own record when it opened or pushed to one, so the lead can report the links. Step 3: confirm Summarize what you created: each agent's name and id, the sub-agent bindings, the repository links and their triggers, and the schedule. Then state the next manual step for the user: merge the first knowledge pull request, tick any App events still missing, or try the first @ mention. Remind them that Wardby never merges pull requests for them. Related: Builder and router prompts, Set up an architecture agent, Architecture knowledge bundles, Choose a native or coding agent, Connect GitHub repositories, Run GitHub code-review agents, Approve packages for coding agents, and Services for coding runs.",
+      "markdown": "\n# Agent recipes\n\nTwo complete setups: an **architecture keeper** (a scheduled architect coding\nagent, a merge watcher with the `push` trigger, and a reviewer step that uses\n`docs/knowledge/`) and a **builder** (a native router linked with `mention` that\ndelegates to a coding builder, for Node/TypeScript, Python, or a\nbring-your-own-image toolchain).\n\nThey go beyond the quickstart. Its optional coding step sets up a builder and a\nreviewer on a local git repository, with no GitHub App (see the\n`local-repositories` article). These recipes react to GitHub events (`push`,\n`mention`, pull requests), so they require Wardby 0.4.0 or later, plus the\nGitHub App, worker image, and job launcher from coding-agent setup. The full recipes, with every configuration and prompt, are\nin [`docs/agent-recipes.md`](../docs/agent-recipes.md).\n\nIf you are an assistant connected to Wardby over MCP, follow these steps. Do\nthem in order, ask the user instead of guessing, and stop at the first failed\nprerequisite.\n\n## Step 0: choose\n\nAsk the user:\n\n1. Which recipe: \"architecture keeper\" or \"builder\"?\n2. Which repository, as `owner/name`?\n3. The coding provider, `codex` or `claude-code`, for both recipes (the\n   architect is a coding agent too). Never guess it.\n4. For the builder only: the language or stack, which decides `toolchain`\n   (`node` for Node/TypeScript, `node-python` with `toolchainVersion: \"3.12\"`\n   for Python, or a bring-your-own worker image for anything else).\n\nAgent names are unique across the whole instance, so the recipes use\nrepo-scoped names: `<repo>-architect`, `<repo>-merge-watcher`, `<repo>-builder`,\nand `<repo>-router`, where `<repo>` is the repository name from `owner/name`.\nCall `list_agents` first; if a name is taken, ask the user for another. Keep the\n`boundName` values `architect` and `builder` unchanged, so the delegate tools\nstay `delegate_to_architect` and `delegate_to_builder`.\n\n## Step 1: check prerequisites\n\nCheck these before creating anything.\n\n1. **Local install.** Over the local stdio connection `link_host_account` is\n   not available (it needs Wardby's HTTP transport), and a quickstart-only\n   install has no GitHub App or coding workers. If that is your situation,\n   explain it to the user and point them to\n   [`docs/coding-agent-setup.md`](../docs/coding-agent-setup.md) instead of\n   trying.\n2. **GitHub account link.** Call `get_host_account`. If `accounts` is empty,\n   call `link_host_account` with no arguments, give the user the `authorizeUrl`,\n   and when they return the one-time code, call `link_host_account` again with\n   `confirmationCode`.\n3. **Repository access.** No tool lists the repositories the GitHub App can\n   see. The linked account needs write access to the repository, and both\n   `create_agent` (with a `codingProfile`) and `link_repository` check this and\n   refuse with a clear error if it is missing. Ask the user to confirm the GitHub\n   App is installed on the repository. Do not use `adminOverride` or\n   `repositoryAdminOverride` unless the user is an admin and asks for it.\n4. **Models.** Call `list_models` and pick ids whose `routable` is true: a\n   capable coding model that the chosen provider supports, and a small fast model\n   for the native agent.\n5. **Coding-agent setup.** If coding agents are not set up yet, tell the user to\n   run `wardby coding preflight` (CLI) and finish coding-agent setup first. See\n   [`docs/coding-agent-setup.md`](../docs/coding-agent-setup.md).\n6. **Webhooks.** Event triggers need GitHub to reach the instance at a public\n   HTTPS URL, with the App's events ticked: **Push** for the merge watcher;\n   **Issue comment**, **Pull request review comment**, and **Issues** for\n   mentions. Scheduled and manual runs need no webhook.\n\nIf a prerequisite fails, stop and tell the user what to do. Do not create agents.\n\n## Step 2A: architecture keeper\n\n1. Call `get_help_article` with `id: \"architecture-agent\"`. It holds the\n   architect system prompt (\"System prompt\"), the watcher prompt, and the\n   reviewer step. Use them unchanged.\n2. Call `create_agent` for the architect: `name: \"<repo>-architect\"`, `kind: \"coding\"`,\n   `model` a capable coding model, `budgetUsd: 3`, `systemPrompt` the architect\n   prompt, and `codingProfile` with `provider`, `repository`, `baseRef` (the\n   default branch), and `defaultTask`: `Weekly knowledge review. Run the full\ncycle described in your instructions for this repository. Your file changes\nare collected into a pull request for review; don't try to commit or open one\nyourself.`\n3. Tell the user the run is billed up to the agent's budget ($3) and get their\n   confirmation. Then call `trigger_agent` once with the architect's `agentId`\n   and show them the run (`get_run`). If the run failed or produced no pull\n   request, stop and show the error or summary; never call `set_schedule` after a\n   failed run. Otherwise **stop** and ask them to review and merge the first\n   draft pull request before continuing.\n4. When they say to continue, call `set_schedule` with the architect's\n   `agentId`, `schedule: \"0 6 * * 1\"`, and the user's `timezone`.\n5. Call `create_agent` for the watcher: `name: \"<repo>-merge-watcher\"`,\n   `kind: \"native\"`, a small fast `model`, the watcher prompt as `systemPrompt`,\n   and a `budgetUsd` of at least 3 plus a little (the run tree shares one\n   budget).\n6. Call `attach_subagent` with `parentAgentId` the watcher, `childAgentId` the\n   architect, and `boundName: \"architect\"`.\n7. Ask the user to tick **Push** in the GitHub App's event settings (and keep\n   Contents: read). Wait for their confirmation.\n8. Call `link_repository` with `agentId` the watcher, `repository`,\n   `access: \"write\"`, and `triggers: [\"push\"]`. Send no `checkName`.\n9. Offer the reviewer step: if the user has a code-review agent, offer to append\n   the \"Reviewer step\" from the same article to its prompt with `update_agent`\n   (read it first with `get_agent`, and keep its existing prompt).\n\n## Step 2B: builder\n\n1. **Check for a mention conflict first**, before creating anything. Call\n   `list_agents`, then `list_repositories` for each native agent you can see, to\n   find one linked to the repository with the `mention` trigger (only one agent\n   per repository may handle mentions). If one exists, reuse it as the router\n   only if the user owns it and agrees; then attach the builder to it and skip\n   creating a router. Never unlink or relink another agent.\n2. Ask the user to confirm the GitHub App subscribes to **Issue comment**,\n   **Pull request review comment**, and **Issues** events.\n3. Call `create_agent` for the builder: `name: \"<repo>-builder\"`,\n   `kind: \"coding\"`, a `model` the chosen provider supports, `budgetUsd` such as\n   `5`, `systemPrompt` the prompt from `get_help_article` with\n   `id: \"builder-agent\"` (section \"Builder prompt\"), and a `codingProfile` with\n   `provider`, `repository`, `baseRef`, and `timeoutSec` (for example `1800`),\n   plus the stack settings:\n   - Node/TypeScript: `toolchain: \"node\"`, with `packageAllowlist` such as\n     `{ \"npm\": [\"react@^19\", \"vitest\"] }`.\n   - Python: `toolchain: \"node-python\"`, `toolchainVersion: \"3.12\"`, with\n     `packageAllowlist` such as `{ \"pypi\": [\"flask>=3\"] }` (wheels only; list a\n     wheel package's own name, not an extra). Add `services: [\"postgres\"]` if\n     tests need a database: the repository must commit `.wardby/services.yaml`\n     declaring it, and the name must be in the catalog (`list_services`), or\n     `create_agent` returns 400.\n   - Other: `toolchain: \"node\"` plus a digest-pinned `workerImageRef`. Ask the\n     user for the image reference; never invent one. It needs the `agents:admin`\n     scope; if the user lacks it, stop and say so.\n\n   A `packageAllowlist` needs `packages:approve` or `agents:admin`.\n\n4. If you are not reusing a router, call `create_agent` with\n   `name: \"<repo>-router\"`, `kind: \"native\"`, a small fast `model`, a `budgetUsd`\n   of the builder's budget plus a little, and the router prompt from\n   `get_help_article` with `id: \"builder-agent\"` (section \"Router prompt\").\n5. Call `attach_subagent` with `parentAgentId` the router, `childAgentId` the\n   builder, and `boundName: \"builder\"`.\n6. Call `link_repository` with `agentId` the router, `repository`,\n   `access: \"write\"`, and `triggers: [\"mention\"]`. If it returns the 409\n   \"Another agent already handles @-mentions\", **stop** and tell the user, and\n   list the agents you created. Never unlink or relink another agent. If linking\n   fails for any reason after you created agents, tell the user what was created.\n7. Ask the user to try one `@<app-slug>` request on an issue, where\n   `<app-slug>` is the GitHub App's name. A test run is billed up to the\n   builder's budget; say so first.\n\n## Step 2C (optional): a lead that fans out\n\nA router delegates once per run by default. For one native agent that splits a\nrequest across several repositories, attach one builder per repository and set\nthe lead's `maxDelegationsPerRun` (1 to 20) with `create_agent` or\n`update_agent`. Each `delegate_to_<name>` call must go to a different\nsub-agent; the calls run one after another unless you also set\n`parallelDelegations: true`, which starts only the **consecutive**\n`delegate_to_*` calls of one turn together — a non-delegation call between\ntwo delegations splits them, nothing is reordered, and results return to the\nlead in call order (tell the lead to make its independent delegations\nconsecutively, in one turn; coding builders beyond `CODING_MAX_CONCURRENT`\nqueue); the run tree shares the lead's budget, so size `budgetUsd` for every\nbuilder it may start. Builders started together each reserve their budget up\nfront, so size the lead's `budgetUsd` for all of them, with headroom since\nthe lead's own unspent budget isn't reserved against them; a builder refused\nfor budget while a sibling still runs waits for it and retries (otherwise the\nrefusal is immediate). Cancelling the lead stops a running coding sub-agent\nbut not a running native one. Put the full cross-repository contract in each\nbuilder's task, since each builder sees only its own repository. Each\nbuilder's result includes `pullRequest` (`outcome`,\n`repository`, `number`, `url`) from Wardby's own record when it opened or\npushed to one, so the lead can report the links.\n\n## Step 3: confirm\n\nSummarize what you created: each agent's name and id, the sub-agent bindings,\nthe repository links and their triggers, and the schedule. Then state the next\nmanual step for the user: merge the first knowledge pull request, tick any App\nevents still missing, or try the first `@` mention. Remind them that Wardby never\nmerges pull requests for them.\n\nRelated: [Builder and router prompts](help://builder-agent),\n[Set up an architecture agent](help://architecture-agent),\n[Architecture knowledge bundles](help://knowledge),\n[Choose a native or coding agent](help://creating-agents),\n[Connect GitHub repositories](help://github-integration),\n[Run GitHub code-review agents](help://code-review-agents),\n[Approve packages for coding agents](help://coding-packages), and\n[Services for coding runs](help://coding-services).\n",
+      "plainText": "Agent recipes Two complete setups: an architecture keeper (a scheduled architect coding agent, a merge watcher with the push trigger, and a reviewer step that uses docs/knowledge/) and a builder (a native router linked with mention that delegates to a coding builder, for Node/TypeScript, Python, or a bring-your-own-image toolchain). They go beyond the quickstart. Its optional coding step sets up a builder and a reviewer on a local git repository, with no GitHub App (see the local-repositories article). These recipes react to GitHub events (push, mention, pull requests), so they require Wardby 0.4.0 or later, plus the GitHub App, worker image, and job launcher from coding-agent setup. The full recipes, with every configuration and prompt, are in docs/agent-recipes.md. If you are an assistant connected to Wardby over MCP, follow these steps. Do them in order, ask the user instead of guessing, and stop at the first failed prerequisite. Step 0: choose Ask the user: Which recipe: \"architecture keeper\" or \"builder\"? Which repository, as owner/name? The coding provider, codex or claude-code, for both recipes (the architect is a coding agent too). Never guess it. For the builder only: the language or stack, which decides toolchain (node for Node/TypeScript, node-python with toolchainVersion: \"3.12\" for Python, or a bring-your-own worker image for anything else). Agent names are unique across the whole instance, so the recipes use repo-scoped names: <repo-architect, <repo-merge-watcher, <repo-builder, and <repo-router, where <repo is the repository name from owner/name. Call listagents first; if a name is taken, ask the user for another. Keep the boundName values architect and builder unchanged, so the delegate tools stay delegatetoarchitect and delegatetobuilder. Step 1: check prerequisites Check these before creating anything. Local install. Over the local stdio connection linkhostaccount is not available (it needs Wardby's HTTP transport), and a quickstart-only install has no GitHub App or coding workers. If that is your situation, explain it to the user and point them to docs/coding-agent-setup.md instead of trying. GitHub account link. Call gethostaccount. If accounts is empty, call linkhostaccount with no arguments, give the user the authorizeUrl, and when they return the one-time code, call linkhostaccount again with confirmationCode. Repository access. No tool lists the repositories the GitHub App can see. The linked account needs write access to the repository, and both createagent (with a codingProfile) and linkrepository check this and refuse with a clear error if it is missing. Ask the user to confirm the GitHub App is installed on the repository. Do not use adminOverride or repositoryAdminOverride unless the user is an admin and asks for it. Models. Call listmodels and pick ids whose routable is true: a capable coding model that the chosen provider supports, and a small fast model for the native agent. Coding-agent setup. If coding agents are not set up yet, tell the user to run wardby coding preflight (CLI) and finish coding-agent setup first. See docs/coding-agent-setup.md. Webhooks. Event triggers need GitHub to reach the instance at a public HTTPS URL, with the App's events ticked: Push for the merge watcher; Issue comment, Pull request review comment, and Issues for mentions. Scheduled and manual runs need no webhook. If a prerequisite fails, stop and tell the user what to do. Do not create agents. Step 2A: architecture keeper Call gethelparticle with id: \"architecture-agent\". It holds the architect system prompt (\"System prompt\"), the watcher prompt, and the reviewer step. Use them unchanged. Call createagent for the architect: name: \"<repo-architect\", kind: \"coding\", model a capable coding model, budgetUsd: 3, systemPrompt the architect prompt, and codingProfile with provider, repository, baseRef (the default branch), and defaultTask: Weekly knowledge review. Run the full cycle described in your instructions for this repository. Your file changes are collected into a pull request for review; don't try to commit or open one yourself. Tell the user the run is billed up to the agent's budget ($3) and get their confirmation. Then call triggeragent once with the architect's agentId and show them the run (getrun). If the run failed or produced no pull request, stop and show the error or summary; never call setschedule after a failed run. Otherwise stop and ask them to review and merge the first draft pull request before continuing. When they say to continue, call setschedule with the architect's agentId, schedule: \"0 6 1\", and the user's timezone. Call createagent for the watcher: name: \"<repo-merge-watcher\", kind: \"native\", a small fast model, the watcher prompt as systemPrompt, and a budgetUsd of at least 3 plus a little (the run tree shares one budget). Call attachsubagent with parentAgentId the watcher, childAgentId the architect, and boundName: \"architect\". Ask the user to tick Push in the GitHub App's event settings (and keep Contents: read). Wait for their confirmation. Call linkrepository with agentId the watcher, repository, access: \"write\", and triggers: [\"push\"]. Send no checkName. Offer the reviewer step: if the user has a code-review agent, offer to append the \"Reviewer step\" from the same article to its prompt with updateagent (read it first with getagent, and keep its existing prompt). Step 2B: builder Check for a mention conflict first, before creating anything. Call listagents, then listrepositories for each native agent you can see, to find one linked to the repository with the mention trigger (only one agent per repository may handle mentions). If one exists, reuse it as the router only if the user owns it and agrees; then attach the builder to it and skip creating a router. Never unlink or relink another agent. Ask the user to confirm the GitHub App subscribes to Issue comment, Pull request review comment, and Issues events. Call createagent for the builder: name: \"<repo-builder\", kind: \"coding\", a model the chosen provider supports, budgetUsd such as 5, systemPrompt the prompt from gethelparticle with id: \"builder-agent\" (section \"Builder prompt\"), and a codingProfile with provider, repository, baseRef, and timeoutSec (for example 1800), plus the stack settings: Node/TypeScript: toolchain: \"node\", with packageAllowlist such as { \"npm\": [\"react@^19\", \"vitest\"] }. Python: toolchain: \"node-python\", toolchainVersion: \"3.12\", with packageAllowlist such as { \"pypi\": [\"flask=3\"] } (wheels only; list a wheel package's own name, not an extra). Add services: [\"postgres\"] if tests need a database: the repository must commit .wardby/services.yaml declaring it, and the name must be in the catalog (listservices), or createagent returns 400. Other: toolchain: \"node\" plus a digest-pinned workerImageRef. Ask the user for the image reference; never invent one. It needs the agents:admin scope; if the user lacks it, stop and say so. A packageAllowlist needs packages:approve or agents:admin. If you are not reusing a router, call createagent with name: \"<repo-router\", kind: \"native\", a small fast model, a budgetUsd of the builder's budget plus a little, and the router prompt from gethelparticle with id: \"builder-agent\" (section \"Router prompt\"). Call attachsubagent with parentAgentId the router, childAgentId the builder, and boundName: \"builder\". Call linkrepository with agentId the router, repository, access: \"write\", and triggers: [\"mention\"]. If it returns the 409 \"Another agent already handles @-mentions\", stop and tell the user, and list the agents you created. Never unlink or relink another agent. If linking fails for any reason after you created agents, tell the user what was created. Ask the user to try one @<app-slug request on an issue, where <app-slug is the GitHub App's name. A test run is billed up to the builder's budget; say so first. Step 2C (optional): a lead that fans out A router delegates once per run by default. For one native agent that splits a request across several repositories, attach one builder per repository and set the lead's maxDelegationsPerRun (1 to 20) with createagent or updateagent. Each delegateto<name call must go to a different sub-agent; the calls run one after another unless you also set parallelDelegations: true, which starts only the consecutive delegateto calls of one turn together — a non-delegation call between two delegations splits them, nothing is reordered, and results return to the lead in call order (tell the lead to make its independent delegations consecutively, in one turn; coding builders beyond CODINGMAXCONCURRENT queue); the run tree shares the lead's budget, so size budgetUsd for every builder it may start. Builders started together each reserve their budget up front, so size the lead's budgetUsd for all of them, with headroom since the lead's own unspent budget isn't reserved against them; a builder refused for budget while a sibling still runs waits for it and retries (otherwise the refusal is immediate). Cancelling the lead stops a running coding sub-agent but not a running native one. Put the full cross-repository contract in each builder's task, since each builder sees only its own repository. Each builder's result includes pullRequest (outcome, repository, number, url) from Wardby's own record when it opened or pushed to one, so the lead can report the links. Step 3: confirm Summarize what you created: each agent's name and id, the sub-agent bindings, the repository links and their triggers, and the schedule. Then state the next manual step for the user: merge the first knowledge pull request, tick any App events still missing, or try the first @ mention. Remind them that Wardby never merges pull requests for them. Related: Builder and router prompts, Set up an architecture agent, Architecture knowledge bundles, Choose a native or coding agent, Connect GitHub repositories, Run GitHub code-review agents, Approve packages for coding agents, and Services for coding runs.",
       "headings": [
         {
           "level": 1,
@@ -946,13 +946,23 @@
       ],
       "appliesTo": ">=0.2.1",
       "sourcePath": "getting-started.md",
-      "markdown": "\n# Get started with Wardby\n\nFrom the project you want Wardby to manage, run:\n\n```sh\nnpx --yes @wardby/cli@latest quickstart\n```\n\nThe quickstart creates local state under `.wardby/`, starts the local services,\napplies the required database migrations, and can register Wardby with Codex or\nClaude Code. Run `wardby doctor` afterwards to verify the local installation.\n\nTo try a coding agent and a review agent without a GitHub App, answer yes to the\nquickstart's coding step (or pass `--coding --trust <dir>`, a repository or a folder of repositories); it points them at a\ngit folder on your machine. See [Use local git repositories](local-repositories.md).\n\nUse [Operate agents](operating-agents.md) to create and supervise managed work.\nRead [Choose a native or coding agent](creating-agents.md) before creating your\nfirst agent.\nUse [MCP access](mcp.md) when connecting an MCP client. Before enabling coding\nagents against a repository, complete [GitHub integration](github.md).\nFor two complete example setups, see [Agent recipes](agent-recipes.md).\nFor a self-hosted installation, start with [Choose a deployment target](deployment-targets.md)\nand [Configure identity and privileged access](identity-and-access.md).\n\nFor complete local setup and deployment prerequisites, read\n[`docs/getting-started.md`](../docs/getting-started.md).\n",
-      "plainText": "Get started with Wardby From the project you want Wardby to manage, run: npx --yes @wardby/cli@latest quickstart The quickstart creates local state under .wardby/, starts the local services, applies the required database migrations, and can register Wardby with Codex or Claude Code. Run wardby doctor afterwards to verify the local installation. 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. Use Operate agents to create and supervise managed work. Read Choose a native or coding agent before creating your first agent. Use MCP access when connecting an MCP client. Before enabling coding agents against a repository, complete GitHub integration. For two complete example setups, see Agent recipes. For a self-hosted installation, start with Choose a deployment target and Configure identity and privileged access. For complete local setup and deployment prerequisites, read docs/getting-started.md.",
+      "markdown": "\n# Get started with Wardby\n\nFrom the project you want Wardby to manage, run:\n\n```sh\nnpx --yes @wardby/cli@latest quickstart\n```\n\nThe quickstart creates local state under `.wardby/`, starts the local services,\napplies the required database migrations, and can register Wardby with Codex or\nClaude Code. Run `wardby doctor` afterwards to verify the local installation.\n\n## Coding and review agents: pick a path\n\n- **A. Try them locally, no GitHub App.** Run\n  `npx --yes @wardby/cli@latest quickstart --coding --trust <repo-or-folder>`\n  (or answer yes to the coding step). It creates `local-builder` and\n  `local-reviewer` for a git repository on your machine. Run the builder with\n  `trigger_agent {\"agentId\": \"<id>\", \"task\": \"...\"}`. It pushes a branch\n  `wardby/run-<run id>` into your repository and leaves your checkout alone.\n  Review that branch with\n  `trigger_agent {\"agentId\": \"<reviewer id>\", \"review\": {\"branch\": \"wardby/run-<run id>\"}}`.\n  You need Docker and an OpenAI key (Codex) or an Anthropic key (Claude Code).\n  See [Use local git repositories](local-repositories.md).\n- **B. A coding agent that opens GitHub pull requests.** Do A first. Then\n  install a GitHub App on the repository (Contents and Pull requests: read and\n  write), add `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` to `.wardby/.env`,\n  and create a coding agent for `owner/name`. You trigger it yourself, so\n  GitHub doesn't need to reach your machine. See\n  [GitHub integration](github.md).\n- **C. A review agent on GitHub pull requests.** Reviews start from GitHub\n  webhooks, so Wardby must be reachable over public HTTPS. Register the App\n  with webhooks, link a native agent to the repository with the `pull_request`\n  trigger, and open a pull request. See [Code review agents](code-review-agents.md).\n\nThe full step-by-step guide is \"Choose what to set up next\" in\n[`docs/getting-started.md`](../docs/getting-started.md).\n\n## Next\n\nUse [Operate agents](operating-agents.md) to create and supervise managed work.\nRead [Choose a native or coding agent](creating-agents.md) before creating your\nfirst agent.\nUse [MCP access](mcp.md) when connecting an MCP client. Before enabling coding\nagents against a repository, complete [GitHub integration](github.md).\nFor two complete example setups, see [Agent recipes](agent-recipes.md).\nFor a self-hosted installation, start with [Choose a deployment target](deployment-targets.md)\nand [Configure identity and privileged access](identity-and-access.md).\n\nFor complete local setup and deployment prerequisites, read\n[`docs/getting-started.md`](../docs/getting-started.md).\n",
+      "plainText": "Get started with Wardby From the project you want Wardby to manage, run: npx --yes @wardby/cli@latest quickstart The quickstart creates local state under .wardby/, starts the local services, applies the required database migrations, and can register Wardby with Codex or Claude Code. Run wardby doctor afterwards to verify the local installation. Coding and review agents: pick a path A. Try them locally, no GitHub App. Run npx --yes @wardby/cli@latest quickstart --coding --trust <repo-or-folder (or answer yes to the coding step). It creates local-builder and local-reviewer for a git repository on your machine. Run the builder with triggeragent {\"agentId\": \"<id\", \"task\": \"...\"}. It pushes a branch wardby/run-<run id into your repository and leaves your checkout alone. Review that branch with triggeragent {\"agentId\": \"<reviewer id\", \"review\": {\"branch\": \"wardby/run-<run id\"}}. You need Docker and an OpenAI key (Codex) or an Anthropic key (Claude Code). See Use local git repositories. B. A coding agent that opens GitHub pull requests. Do A first. Then install a GitHub App on the repository (Contents and Pull requests: read and write), add GITHUBAPPID and GITHUBAPPPRIVATEKEY to .wardby/.env, and create a coding agent for owner/name. You trigger it yourself, so GitHub doesn't need to reach your machine. See GitHub integration. C. A review agent on GitHub pull requests. Reviews start from GitHub webhooks, so Wardby must be reachable over public HTTPS. Register the App with webhooks, link a native agent to the repository with the pullrequest trigger, and open a pull request. See Code review agents. The full step-by-step guide is \"Choose what to set up next\" in docs/getting-started.md. Next Use Operate agents to create and supervise managed work. Read Choose a native or coding agent before creating your first agent. Use MCP access when connecting an MCP client. Before enabling coding agents against a repository, complete GitHub integration. For two complete example setups, see Agent recipes. For a self-hosted installation, start with Choose a deployment target and Configure identity and privileged access. For complete local setup and deployment prerequisites, read docs/getting-started.md.",
       "headings": [
         {
           "level": 1,
           "text": "Get started with Wardby",
           "slug": "get-started-with-wardby"
+        },
+        {
+          "level": 2,
+          "text": "Coding and review agents: pick a path",
+          "slug": "coding-and-review-agents-pick-a-path"
+        },
+        {
+          "level": 2,
+          "text": "Next",
+          "slug": "next"
         }
       ]
     },

package/dist/quickstart-images.json

@@ -1 +1 @@
-{"runtime":"ghcr.io/wardby/wardby/wardby-runtime@sha256:b6d6403338725abc9fc109c5a026e654c88e72ae8db43788db0cfa86f18c1635","worker":"ghcr.io/wardby/wardby/wardby-coding-worker@sha256:45acf6f2ac4b43b46dd3b9e1a89cd3e3369fd4898f0ce177cf063806f98f65d1","claudeWorker":"ghcr.io/wardby/wardby/wardby-claude-coding-worker@sha256:701abc30b689aed61b8d2028523d53847cbc33dea23ce16ddd22b302a5d964e2","claudeToolRunner":"ghcr.io/wardby/wardby/wardby-claude-tool-runner@sha256:7c4574fffc1adba27d3c86949b62d8f8a95f8198fbbca0710ed68e812ad2f357"}
+{"runtime":"ghcr.io/wardby/wardby/wardby-runtime@sha256:1b6646eccf13dbe534257f641b757cd11a127ef54741cf7b7a0a56fc53de60da","worker":"ghcr.io/wardby/wardby/wardby-coding-worker@sha256:0a9d4a8f737b4b2badde4dfad5646db3cb26ead4f3783ee0c13819daf0f44b1a","claudeWorker":"ghcr.io/wardby/wardby/wardby-claude-coding-worker@sha256:36fdf3b28d60a332b170ec5bd52d7158d11cab70562d7cadffe2fa286ccff974","claudeToolRunner":"ghcr.io/wardby/wardby/wardby-claude-tool-runner@sha256:68c276dce5341bf5e8dd3723ae8ad45ae01c81065a99ee2c5ca9847ce1afe0d7"}

package/docs/agent-recipes.md

@@ -24,9 +24,10 @@ These recipes go beyond the quickstart. Check each item.
 1. **Version.** The recipes require Wardby 0.4.0 or later. The knowledge note in
    coding runs, `wardby knowledge check`, and the `push` trigger are not in
    earlier releases.
-2. **Coding-agent setup.** The quickstart runs native agents only: it does not
-   install a GitHub App or build worker images. Both recipes use coding agents,
-   so complete [Coding-agent setup](coding-agent-setup.md) first: a GitHub App
+2. **Coding-agent setup.** The quickstart's optional coding step sets up coding
+   agents on a local git repository only; it does not install a GitHub App.
+   Both recipes use coding agents triggered by GitHub events, so complete
+   [Coding-agent setup](coding-agent-setup.md) first: a GitHub App
    installed on the repository, a worker image, the coding proxy, and a Docker or
    Kubernetes job launcher. Run `wardby coding preflight` to check it. For a
    hosted deployment, [Getting started on GKE](getting-started-gke.md) covers

package/docs/getting-started.md

@@ -43,6 +43,116 @@ Provider credentials and `SECRET_APP_KEY` are written with owner-only file
 permissions. They are not printed, passed as command-line arguments, or added
 to the application's own `.env` files.
 
+## Choose what to set up next
+
+The quickstart's sample agent is a native agent: it calls a model and nothing
+else. To have agents write code or review it, pick the path that matches what
+you have:
+
+| You want                                          | You need                                                           | Path                                              |
+| ------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------- |
+| A coding agent and a review agent, tried locally  | Docker, an OpenAI **or** Anthropic key, a git repository on disk   | [A](#path-a-local-repository-no-github-app)       |
+| A coding agent that opens pull requests on GitHub | Path A's setup, plus a GitHub App installed on the repository      | [B](#path-b-coding-agent-on-a-github-repository)  |
+| A review agent that reviews GitHub pull requests  | A GitHub App with webhooks, and Wardby reachable over public HTTPS | [C](#path-c-review-agent-on-github-pull-requests) |
+
+Codex agents need only an OpenAI key and Claude Code agents only an Anthropic
+key; you don't need both.
+
+### Path A: local repository, no GitHub App
+
+1. Run the quickstart with its coding step, pointing it at your repository (or
+   at a folder of repositories):
+
+   ```sh
+   npx --yes @wardby/cli@latest quickstart --coding --trust ~/code/my-repo
+   ```
+
+   Or run plain `quickstart` and answer **yes** to "Set up coding + review
+   agents against a local git repo?". It asks for Codex or Claude Code, pulls
+   only that provider's images, starts the coding proxy, and creates two agents:
+   `local-builder` (writes code) and `local-reviewer` (reviews it).
+
+2. Ask your MCP client (the quickstart can register Wardby with Codex or Claude
+   Code) to run the builder. The quickstart prints the exact call, for example:
+
+   ```json
+   trigger_agent {"agentId": "<local-builder id>", "task": "Add a short CONTRIBUTING.md"}
+   ```
+
+3. Check the run with `get_run`. When it succeeds, its `resultBranch` is a new
+   branch `wardby/run-<run id>` **in your repository**. Inspect it with
+   `git diff main...wardby/run-<run id>`. Your working tree and checked-out
+   branch are not touched.
+4. Review that branch:
+
+   ```json
+   trigger_agent {"agentId": "<local-reviewer id>", "review": {"branch": "wardby/run-<run id>"}}
+   ```
+
+   `get_run` on the review run shows its verdict, summary, and line comments.
+
+5. Merge the branch if you like it, or delete it with
+   `git branch -D wardby/run-<run id>`.
+
+Details, options, and the trust model are in
+[Coding agents on a local repository](#coding-agents-on-a-local-repository)
+below.
+
+### Path B: coding agent on a GitHub repository
+
+A coding agent you trigger yourself can work on a GitHub repository from the
+same local setup. It pushes a branch and opens a **draft pull request**. GitHub
+doesn't need to reach your machine for this.
+
+1. Complete path A first, so that Docker, the coding proxy, and the worker
+   image are set up.
+2. Create a GitHub App and install it on **only** the repository the agent may
+   change, with `Contents: Read and write` and `Pull requests: Read and write`
+   ([details](coding-agent-setup.md#prerequisites)).
+3. Add `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` to the project's
+   `.wardby/.env`, then re-run `doctor`.
+4. Create a coding agent whose `codingProfile.repository` is `owner/name`. The
+   repository must be authorized for the agent's owner. Either link your GitHub
+   account with `link_host_account`, or, on a local installation (where you
+   hold the `admin` role), pass `repositoryAdminOverride: true`. See
+   [Repository authorization](coding-agent-setup.md#repository-authorization).
+5. Trigger it with `trigger_agent` and a `task`. `get_run` shows the draft
+   pull request it opened.
+
+### Path C: review agent on GitHub pull requests
+
+Automatic reviews start from GitHub webhooks, so GitHub must be able to reach
+your Wardby server over public HTTPS. A laptop-only installation can't receive
+them; use a deployment such as [Getting started on GKE](getting-started-gke.md),
+or another host with a public URL.
+
+1. Run Wardby where GitHub can reach it, with `MCP_CANONICAL_URI` set to its
+   public URL.
+2. Register the GitHub App with the webhook URL, secret, events, and
+   permissions in
+   [Registering the GitHub App](code-review-agents.md#registering-the-github-app).
+3. Link your GitHub account with `link_host_account`.
+4. Create a native review agent. The reviewer prompt in
+   [Agent recipes](agent-recipes.md) is a good start.
+5. Link it to the repository with the `pull_request` trigger (see
+   [Linking an agent to a repository](code-review-agents.md#linking-an-agent-to-a-repository)):
+
+   ```json
+   {
+     "agentId": "<agent-id>",
+     "repository": "owner/name",
+     "access": "write",
+     "triggers": ["pull_request"],
+     "checkName": "wardby review"
+   }
+   ```
+
+6. Open or update a pull request. A **wardby review** check starts, and the
+   agent posts inline comments and a summary.
+
+To try reviews before you have a public URL, use path A's `local-reviewer` on
+any local branch.
+
 ## Unattended setup
 
 Automation must explicitly accept the billed demo with `--yes`:
@@ -118,7 +228,8 @@ agents do not use it.
 ## Coding agents
 
 The first-run demo proves native model routing, budget admission, persistence,
-and accounting. It does not install a GitHub App or start any worker.
+and accounting. It does not install a GitHub App or start any worker. For the
+step-by-step paths, see [Choose what to set up next](#choose-what-to-set-up-next).
 
 Coding agents require the stronger boundary described in
 [Coding-agent setup](coding-agent-setup.md): an immutable worker image, a
@@ -200,8 +311,9 @@ folders) and its limits (no submodules or Git LFS).
 
 [Agent recipes](agent-recipes.md) gives two complete, copyable setups: an
 architecture keeper and a builder per language. They go beyond the quickstart,
-which runs native agents only. They require Wardby 0.4.0 or later. They need the
-GitHub App, worker image, and job launcher from
+whose optional coding step works on a local git repository without a GitHub
+App. The recipes react to GitHub events, so they require Wardby 0.4.0 or later
+and need the GitHub App, worker image, and job launcher from
 [Coding-agent setup](coding-agent-setup.md). Their event triggers need GitHub to
 reach your instance at a public HTTPS URL.
 

package/help/agent-recipes.md

@@ -15,9 +15,11 @@ agent, a merge watcher with the `push` trigger, and a reviewer step that uses
 delegates to a coding builder, for Node/TypeScript, Python, or a
 bring-your-own-image toolchain).
 
-They go beyond the quickstart, which runs native agents only. They require
-Wardby 0.4.0 or later, plus the GitHub App, worker image, and job launcher from
-coding-agent setup. The full recipes, with every configuration and prompt, are
+They go beyond the quickstart. Its optional coding step sets up a builder and a
+reviewer on a local git repository, with no GitHub App (see the
+`local-repositories` article). These recipes react to GitHub events (`push`,
+`mention`, pull requests), so they require Wardby 0.4.0 or later, plus the
+GitHub App, worker image, and job launcher from coding-agent setup. The full recipes, with every configuration and prompt, are
 in [`docs/agent-recipes.md`](../docs/agent-recipes.md).
 
 If you are an assistant connected to Wardby over MCP, follow these steps. Do

package/help/getting-started.md

@@ -19,9 +19,33 @@ 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).
+## Coding and review agents: pick a path
+
+- **A. Try them locally, no GitHub App.** Run
+  `npx --yes @wardby/cli@latest quickstart --coding --trust <repo-or-folder>`
+  (or answer yes to the coding step). It creates `local-builder` and
+  `local-reviewer` for a git repository on your machine. Run the builder with
+  `trigger_agent {"agentId": "<id>", "task": "..."}`. It pushes a branch
+  `wardby/run-<run id>` into your repository and leaves your checkout alone.
+  Review that branch with
+  `trigger_agent {"agentId": "<reviewer id>", "review": {"branch": "wardby/run-<run id>"}}`.
+  You need Docker and an OpenAI key (Codex) or an Anthropic key (Claude Code).
+  See [Use local git repositories](local-repositories.md).
+- **B. A coding agent that opens GitHub pull requests.** Do A first. Then
+  install a GitHub App on the repository (Contents and Pull requests: read and
+  write), add `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY` to `.wardby/.env`,
+  and create a coding agent for `owner/name`. You trigger it yourself, so
+  GitHub doesn't need to reach your machine. See
+  [GitHub integration](github.md).
+- **C. A review agent on GitHub pull requests.** Reviews start from GitHub
+  webhooks, so Wardby must be reachable over public HTTPS. Register the App
+  with webhooks, link a native agent to the repository with the `pull_request`
+  trigger, and open a pull request. See [Code review agents](code-review-agents.md).
+
+The full step-by-step guide is "Choose what to set up next" in
+[`docs/getting-started.md`](../docs/getting-started.md).
+
+## Next
 
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardby/cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Self-hosted control plane for budget-guarded AI agents.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/wardby/wardby#readme",