@wardby/cli 0.2.1 → 0.4.0

package/help/errors/service-unknown.md

@@ -0,0 +1,23 @@
+---
+id: errors/service-unknown
+title: Service not in the catalog
+summary: Wardby refused the coding run because the repository declares a service name and version the service catalog does not have.
+audience: operator
+tags: [error, coding-agents, services, refusal]
+appliesTo: >=0.2.1
+---
+
+# Service not in the catalog
+
+`service_unknown` means `.wardby/services.yaml` on the base branch asks for a
+name and version, such as `postgres 14`, that has no entry in Wardby's service
+catalog. Wardby refuses the run before a coding worker starts.
+
+1. Run `list_services` (needs `agents:read`) to see the names and versions
+   available.
+2. Either change the declaration on the base branch to an available version,
+   or ask someone with `services:manage` and the `admin` or `service-manager`
+   role to add the entry with `create_service`, pinned by digest.
+3. Trigger a new run once the catalog or the declaration matches.
+
+See [Coding services](../coding-services.md).

package/help/errors/service-unready.md

@@ -0,0 +1,49 @@
+---
+id: errors/service-unready
+title: Service did not become ready
+summary: A coding run failed at launch because one of its services never passed its readiness check.
+audience: operator
+tags: [error, coding-agents, services, kubernetes, docker]
+appliesTo: >=0.2.1
+---
+
+# Service did not become ready
+
+A run that failed with category `service_unready` (launcher error
+`coding_service_unready:<name>`) started, but the named service never became
+ready, so the coding agent never started. A service is not ready when its
+readiness command keeps failing past its failure threshold, its image cannot
+be pulled or started, or it is still not ready when the launcher's start-up
+limit runs out.
+
+1. On Kubernetes, inspect the run pod's init-container status and events for
+   the `service-<name>` container: image pull errors, crash loops, or probe
+   failures. On Docker the service's container is removed with the failed run,
+   so reproduce it on the Docker host: pull the entry's image and run it with
+   `--read-only`, `--user 10001:10001`, a `--tmpfs` at its `dataPath` and at
+   each `writablePaths` entry, and its `serviceEnv`; then run its readiness
+   command with `docker exec`.
+2. For a custom catalog entry, confirm the image runs as a non-root user with a
+   read-only root filesystem: every directory it writes to must be its
+   `dataPath` or one of its `writablePaths`. Probe over TCP on `127.0.0.1`
+   rather than a Unix socket.
+3. Each entry's readiness settings (`periodSeconds`, `timeoutSeconds`,
+   `failureThreshold`) apply within an overall start-up limit, whatever the
+   entry's own threshold would otherwise allow. On Kubernetes that limit is
+   the pod-start timeout (`KUBERNETES_READY_TIMEOUT_MS`, default 120000, an
+   operator setting) and includes image pulls; if first pulls on new nodes
+   are slow, raise it or mirror the image into a nearby registry. On Docker
+   the limit is a fixed 120 seconds covering every service of the run
+   together (they start one at a time), never runs past the run's own
+   timeout, and has no setting to raise it; image pulls are not counted in it
+   but may take up to 5 minutes each. The Docker launcher pulls without
+   registry credentials, so pull a private or rate-limited image on the
+   Docker host beforehand.
+4. Trigger a new run once the cause is fixed.
+
+When this run is a sub-run another agent dispatched (for example a router
+handing work to a coding agent), the parent sees a failed sub-run on its own
+status comment, with a line naming the service: "A sub-run could not start:
+The `<name>` service didn't become ready, so the run couldn't start."
+
+See [Coding services](../coding-services.md).

package/help/getting-started.md

@@ -0,0 +1,32 @@
+---
+id: getting-started
+title: Get started with Wardby
+summary: Set up a local Wardby control plane, verify it, and choose the next guide.
+audience: operator
+tags: [setup, quickstart, operator]
+appliesTo: >=0.2.1
+---
+
+# Get started with Wardby
+
+From the project you want Wardby to manage, run:
+
+```sh
+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.
+
+Use [Operate agents](operating-agents.md) to create and supervise managed work.
+Read [Choose a native or coding agent](creating-agents.md) before creating your
+first agent.
+Use [MCP access](mcp.md) when connecting an MCP client. Before enabling coding
+agents against a repository, complete [GitHub integration](github.md).
+For two complete example setups, see [Agent recipes](agent-recipes.md).
+For a self-hosted installation, start with [Choose a deployment target](deployment-targets.md)
+and [Configure identity and privileged access](identity-and-access.md).
+
+For complete local setup and deployment prerequisites, read
+[`docs/getting-started.md`](../docs/getting-started.md).

package/help/github.md

@@ -0,0 +1,48 @@
+---
+id: github-integration
+title: Connect GitHub repositories
+summary: Authorize repository access and configure Wardby coding or review agents through a scoped GitHub App.
+audience: operator
+tags: [github, repositories, coding-agents, code-review]
+appliesTo: >=0.2.1
+---
+
+# Connect GitHub repositories
+
+Wardby uses a GitHub App installed only on the repositories an agent may use.
+Repository access is checked against the agent owner's linked GitHub account,
+or an explicitly recorded administrator approval. Coding agents need write
+access because they can push a branch and open a draft pull request.
+
+Wardby rechecks access before preparing a coding workspace and again before
+pushing. Losing access, unlinking the account, or a failed access check stops
+the run without publishing changes. See [Repository-access troubleshooting](troubleshooting/repository-access.md)
+for the resulting refusal states.
+
+Workers do not receive the GitHub App private key. A trusted component validates
+the changes, pushes a controlled branch, and opens at most one draft pull
+request. Wardby does not auto-merge coding-agent output.
+
+Read [`docs/coding-agent-setup.md`](../docs/coding-agent-setup.md) for coding
+agent setup and [`docs/code-review-agents.md`](../docs/code-review-agents.md)
+for pull-request review agents and webhook configuration.
+Use [Run GitHub code-review agents](code-review-agents.md) for the operator
+overview of checks, mentions, and fork limitations.
+
+## Events and triggers
+
+Link a native agent to a repository with `link_repository`. Each trigger needs
+its GitHub App event ticked in the App's event settings; every event is a
+separate checkbox.
+
+| Trigger        | Starts a run when                                                   | App event to subscribe                                                                 |
+| -------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `pull_request` | A pull request is opened or pushed to; a re-run of the review check | Pull request, Check run (re-runs of the review check)                                  |
+| `mention`      | Someone with write access `@`-mentions the App                      | Issue comment, Issues, Pull request review comment (mentions in inline review threads) |
+| `push`         | A commit lands on the repository's default branch                   | Push                                                                                   |
+
+The `push` trigger starts a merge-watcher agent; only default-branch pushes
+count (tags, other branches, and deletions are ignored). See
+[Keep the knowledge bundle current on merge](help://architecture-agent).
+
+For Jira Cloud instead of GitHub, see [Run Jira agents](jira.md).

package/help/identity-and-access.md

@@ -0,0 +1,44 @@
+---
+id: identity-and-access
+title: Configure identity and privileged access
+summary: Protect remote MCP access with an OAuth/OIDC provider and restrict sensitive operations with scopes and roles.
+audience: operator
+tags: [identity, oauth, oidc, access-control, mcp]
+appliesTo: >=0.2.1
+---
+
+# Configure identity and privileged access
+
+Local stdio MCP created by `wardby quickstart` trusts the local operator. A
+shared HTTPS deployment needs an OAuth/OIDC identity provider. In delegating
+mode, that provider authenticates the caller and issues a signed JWT access
+token; Wardby verifies the token and enforces its scopes without administering
+the provider's users or exchanging authorization codes.
+
+Set the provider's resource audience, `MCP_CANONICAL_URI`, and `AUTH_AUDIENCE`
+to the exact same public MCP URL. Tokens need a stable subject, expiry, issuer,
+audience, and the granted Wardby scopes in `scope` or `scp`.
+
+Scopes authorize normal operations such as managing agents, runs, tools,
+datastores, secrets, webhooks, budgets, packages, services, memory, and
+models. Five sensitive permissions have an additional role requirement:
+
+- `agents:admin` requires the Wardby `admin` role.
+- `packages:approve` requires the `admin` or `package-approver` role.
+- `services:manage` requires the `admin` or `service-manager` role.
+- `admin:view` requires the `admin` role. It opens the read-only, deployment-wide
+  admin viewer API; see [Watch live runs with the admin viewer API](admin-viewer.md).
+- `models:admin` requires the `admin` or `model-manager` role. It adds,
+  overrides, disables, and resets model catalog entries; see
+  [Models and pricing](models.md).
+
+Map roles only from an IdP claim that users cannot self-assign. Removing a
+role affects the next token the caller receives.
+
+When you upgrade a delegating-mode deployment, define any newly advertised
+scope, such as `admin:view`, in the provider before deploying. Clients
+that request every advertised scope otherwise fail with `invalid_scope`.
+
+Read [`docs/getting-started-identity-provider.md`](../docs/getting-started-identity-provider.md)
+for the required claims, scope list, role mapping, provider examples, and
+client registration.

package/help/jira.md

@@ -0,0 +1,135 @@
+---
+id: jira
+title: Run Jira agents
+summary: Connect Wardby to Jira Cloud with a service account, add the webhook, and link agents to projects.
+audience: operator
+tags: [jira, issue-tracker, webhooks, service-account]
+appliesTo: >=0.2.1
+---
+
+# Run Jira agents
+
+A native agent linked to a Jira Cloud project can be started by issue events
+and can read, search and comment on issues in that project. Everything it does
+is attributed to one Atlassian service account whose API token Wardby holds.
+Use only a service-account token (the email-plus-token setup is refused at
+startup); a personal token would attribute agent actions to that person. Check
+the `Jira acting as` startup line to confirm the account.
+
+## Setup checklist
+
+1. In Atlassian Administration, create a service account (Directory, then
+   Service accounts). Give it a project role with Browse Projects, Add
+   Comments and Edit Own Comments in each project agents will use, and only
+   there. To let agents change issues also add Transition issues, Edit issues
+   Link issues and Create issues. Its permissions are the outer boundary of what any linked
+   agent can read or change.
+2. Create an API token for it, with an expiry, and the scopes
+   `read:jira-work` (read issues and comments, JQL search), `write:jira-work`
+   (add and edit comments, transition issues, edit fields, link issues, write
+   issue properties) and `read:jira-user` (read its own identity).
+3. Find your site's cloudId at `https://your-site.atlassian.net/_edge/tenant_info`.
+4. In Jira, Settings, System, WebHooks: add
+   `https://<your-wardby-host>/hosts/jira/events` with a secret of 20 or more
+   characters and the events Issue created, Issue updated, Comment created and
+   Comment updated.
+   Editing a comment that mentions the service account can trigger the agent
+   again when the editor is a trusted account; leave out Comment updated if you
+   don't want that.
+5. Set `WARDBY_JIRA_SITE_URL`, `WARDBY_JIRA_API_BASE_URL`
+   (`https://api.atlassian.com/ex/jira/<cloudId>`), `WARDBY_JIRA_API_TOKEN` and
+   `WARDBY_JIRA_WEBHOOK_SECRET`, then restart. The startup log line
+   `Jira acting as` shows which account Wardby uses; confirm it is the service
+   account. Optionally set `WARDBY_JIRA_API_TOKEN_EXPIRES_AT` to get a warning
+   14 days before expiry.
+6. A Wardby administrator links the agent with `link_issue_project`, for
+   example `projectKey: "PROJ"`, `access: "write"`,
+   `triggers: ["transitioned", "mention"]`,
+   `triggerStatuses: ["Ready for agent"]` and
+   `trustedAccountIds: ["<accountId>"]`. To let the agent change issues, add
+   `allowedTransitions` (target status names), `writableFields` (`labels`,
+   `components`, `priority`, `customfield_N`) and `allowedLinkTypes` (issue
+   link type names such as `Duplicate`); all need `write` access and an empty
+   list means the tool refuses. Linking two issues also needs a `write` link to
+   both issues' projects, each allowlisting the type. Existing links get these
+   only once you set the lists. Status and link type names are matched in the
+   service account's Jira language (its profile language setting, which Jira
+   reports as its locale), so set that language to the one your team uses for
+   status names.
+
+## What agents can do
+
+Beyond reading, searching and commenting, linked agents get
+`jira_list_transitions`, `jira_transition`, `jira_update_fields`,
+`jira_link_issues`, and `jira_get_property` / `jira_set_property` for
+per-issue state, plus `jira_create_issue` and `jira_read_attachment`. Each authorizes against the issue's own project and the
+agent's live link. Properties are not allowlisted: any `write` link can set
+them and any link can read them. They are stored as `wardby.<agentId>.<name>`,
+and anyone with Jira API access to the issue can read or overwrite them, so
+never store secrets there. Run status comments include an `Agent spend: $...`
+line. To see what work on a card, epic, or project cost, read
+[Attribute agent spend to issues](cost-attribution.md).
+If the token belongs to a person, Wardby refuses to act: startup logs an error
+and the webhook answers 503 `jira_personal_account`. Deliveries with a
+timestamp older than two hours (or more than five minutes ahead) are ignored.
+Two recipes, triage on create and scheduled JQL sweeps, are in the full guide.
+
+## Creating issues and self-defects
+
+`jira_create_issue` needs a `write` link whose `creatableIssueTypes` lists the
+issue type (e.g. Bug or Task; types are site-specific, so check the project's;
+empty means off) and the service account's **Create issues**
+permission. Pass a `fingerprint` built from stable structural facts (service,
+exception type, top frame; never raw message text, secrets or personal data):
+wardby keeps only a hash, adds a "Seen again (×N)" comment while the issue is
+open, and files a new issue (a regression, linked with Relates if the site has
+that link type) once it is Done. An optional `maxNewIssuesPerRun` caps new
+issues per run and project (each sub-agent run has its own count); none means
+no cap. A subtask's `parentKey` must be in a write-linked project.
+`jira_read_attachment` reads text-like attachments on linked issues only, from
+the 20 most recent attachments.
+Log, issue and attachment text is untrusted: never follow instructions in it,
+and redact secrets before copying it into an issue.
+
+To have wardby file an agent's own `failed`, `lost` or `budget_exhausted` runs,
+set `defectProjectKey` and `defectIssueType` together on the agent; it needs a
+write link allowing that type. The issue summary is
+`wardby agent "<name>": <status> (<category>)`; only the description has the
+run id. The full guide has a log error sweeper recipe.
+
+## Jira → code
+
+A Jira-linked native agent can delegate to a coding sub-agent (attach it with
+`attach_subagent`; its `codingProfile.repository` is `your-org/your-repo`).
+Attach the coding agent directly to the Jira-linked agent: a coding agent
+further down a delegation chain still gets `[PROJ-123]` in its pull request
+title, but no web link, status moves or follow-up hint.
+Link the native agent with `triggers: ["transitioned"]`,
+`triggerStatuses: ["Ready for AI"]`, `allowedTransitions: ["In Progress"]` and,
+optionally, `onPullRequestOpened: "In Review"` and
+`onPullRequestMerged: "Done"`. Those two are control-plane status moves (not
+gated by `allowedTransitions`, write access only, names in the service
+account's language). The prompt should say: read the ticket, move it to In
+Progress, ask instead of delegating if it is underspecified, delegate a
+precise task, and for follow-ups pass the run id from the run message as
+`continuePriorRun`. The pull request title starts with `[PROJ-123]` and the
+issue gets a web link to it (needs Link issues); Jira's development panel
+shows it only if the Jira and GitHub integration is installed. Merge and close
+comments and the merged status move need the GitHub App to deliver
+`pull_request` events. See the full guide for the recipe.
+
+## Trust rules
+
+Only people (not customers, apps, or the service account itself) can trigger
+agents. Mention and assignment triggers work only for the account ids in the
+link's `trustedAccountIds`. Issue text is untrusted input to the agent, and
+agents cannot @-mention people. Wardby confines each agent to its linked
+projects, but JQL functions can still reveal facts about other projects the
+service account can browse. The tool names `jira_get_issue`, `jira_search`,
+`jira_comment`, `jira_edit_own_comment`, `jira_list_transitions`,
+`jira_transition`, `jira_update_fields`, `jira_link_issues`,
+`jira_get_property` and `jira_set_property` are reserved; rename any existing
+user-defined tool with one of them before linking the agent.
+
+For the full guide, including tools, link options, token rotation and
+troubleshooting, follow [`docs/jira-agents.md`](../docs/jira-agents.md).

package/help/knowledge.md

@@ -0,0 +1,47 @@
+---
+id: knowledge
+title: Architecture knowledge bundles
+summary: Keep cited, non-obvious architecture knowledge in docs/knowledge/ so coding runs, reviewers, and live sessions (through the AGENTS.md pointer) use it; validate it with wardby knowledge check.
+audience: operator
+tags: [knowledge, architecture, coding-agents, okf, cli, drift, push]
+appliesTo: >=0.4.0
+---
+
+# Architecture knowledge bundles
+
+A knowledge bundle is a set of markdown files in `docs/knowledge/` that records
+architecture knowledge people tend to miss: pitfalls, invariants, decisions and
+their reasons, and cross-module contracts. It uses the Open Knowledge Format
+(OKF) v0.2 plus a `wardby:` front-matter block that lists the roles a concept is
+for, the paths it affects, and citations to the code it describes. Each citation
+carries a commit `sha` and a `spanHash` so staleness can be detected.
+
+- `docs/knowledge/index.md` lists every concept in one line; `log.md` records
+  changes to the bundle.
+- When `docs/knowledge/index.md` exists on a coding run's base branch, the run's
+  task includes the index automatically (up to 8 KiB). It never fails a
+  dispatch; an unreadable index just means no note.
+- When the run's commit is known (it always is for a normal clone) and the
+  request leaves room, the task ends with a `Base commit: <sha>` line. The workspace
+  has no git metadata, so use that value for citation `sha` fields.
+- Validate the bundle with `wardby knowledge check` (add `--strict` to fail on
+  warnings, `--json` for machine output, `--root` to point at the repository).
+  Errors are `concept_invalid`, `concept_secret`, `index_missing`, and
+  `index_link_broken`; warnings are `concept_not_indexed`,
+  `citation_unverifiable`, and `citation_stale`.
+- Builders may edit concept prose. Citations can go stale afterward; the
+  architecture agent re-anchors them.
+
+To keep the bundle current on a schedule, set up the scheduled agent described
+in [Set up an architecture agent](help://architecture-agent). Code-review agents can read the bundle too.
+
+To re-verify only the concepts a merge touched, link a small watcher agent with
+the `push` trigger; it starts the architecture agent when a merge to the default
+branch affects a concept. See
+[Keep the knowledge bundle current on merge](help://architecture-agent) and
+[Connect GitHub repositories](help://github-integration) (the GitHub App must
+subscribe to the Push event).
+
+Read [`docs/knowledge.md`](../docs/knowledge.md) for the concept format, the
+span-hash definition, a full example, the issue-code table, and the reviewer
+prompt section.

package/help/mcp.md

@@ -0,0 +1,30 @@
+---
+id: mcp-access
+title: Connect an MCP client
+summary: Use Wardby's local stdio or protected HTTP MCP transport safely.
+audience: developer
+tags: [mcp, oauth, codex, claude-code]
+appliesTo: >=0.2.1
+---
+
+# Connect an MCP client
+
+For local use, `wardby quickstart` can register the local stdio MCP server with
+Codex or Claude Code. Local stdio trusts the local operator.
+
+For remote access, Wardby exposes an OAuth 2.1-protected HTTP resource server.
+Run the service with `MCP_TRANSPORT=http`, set a canonical public URI, and use
+the instance's configured identity-provider mode. Keep the MCP endpoint behind
+your intended ingress and authentication boundary.
+
+MCP clients use Wardby to manage agents, budgets, tools, schedules, secrets,
+datastores, and runs. They do not receive the provider or GitHub App
+credentials held by Wardby's trusted components.
+
+With the existing `agents:read` scope, clients can also use `search_help` to
+find bundled self-hosted guidance with fuzzy matching and `get_help_article`
+to read a complete article by id. These tools use the same release-bundled,
+offline catalog as `wardby help`; they expose no instance data or credentials.
+
+See [`docs/getting-started-identity-provider.md`](../docs/getting-started-identity-provider.md)
+for the supported self-hosted and delegated identity-provider setup.

package/help/models.md

@@ -0,0 +1,90 @@
+---
+id: models
+title: Models and pricing
+summary: Which models this deployment can run, what they cost, and how admins add, reprice, disable or reset them.
+audience: all
+tags: [models, pricing, list_models, set_model, disable_model, reset_model, get_model, models:admin, model-manager]
+appliesTo: ">=0.4.0"
+---
+
+# Models and pricing
+
+Wardby prices and routes every model call from one catalog: the models this
+release ships, overlaid with this deployment's own additions and overrides.
+An agent can use a model only when it's in the catalog and its provider has
+credentials configured here.
+
+## The five tools
+
+| Tool            | Scope          | What it does                                                                              |
+| --------------- | -------------- | ----------------------------------------------------------------------------------------- |
+| `list_models`   | `agents:read`  | Every active catalog entry (or, with `includeDisabled: true`, disabled ones too).         |
+| `get_model`     | `agents:read`  | One entry by `modelId`; for an override, also the shipped entry it shadows.               |
+| `set_model`     | `models:admin` | Adds or completely replaces one entry. Every field is required.                           |
+| `disable_model` | `models:admin` | Removes a model from routing without deleting its pricing history.                        |
+| `reset_model`   | `models:admin` | Removes every row for a model id, reverting to the shipped entry (if any) or removing it. |
+
+Reading the catalog needs only `agents:read` — no secrets live in an entry.
+Changing it needs `models:admin`, honored only for a caller whose Wardby role
+grants it: `admin`, or the narrower `model-manager` role.
+
+An entry's `origin` is `shipped` or `override`; `routable` says whether this
+deployment can actually route to it right now; `shippedDiffers` (overrides of
+a shipped model only) says whether your override has drifted from the
+current shipped values. See [`docs/models.md`](../docs/models.md) for the
+full field reference.
+
+## Adding or overriding a model
+
+```json
+{
+  "provider": "anthropic",
+  "modelId": "claude-example-model",
+  "encoding": "o200k_base",
+  "inputPerMTok": 0.0,
+  "outputPerMTok": 0.0,
+  "cachedInputPerMTok": 0.0,
+  "cacheWritePerMTok": 0.0,
+  "efforts": ["low", "medium", "high"],
+  "thinkingMode": "adaptive",
+  "sourceUrl": "https://example.com/replace-with-the-providers-own-pricing-page"
+}
+```
+
+The rates above are placeholders. Copy the provider's own published rates for
+that exact model — including its cache read and cache write rates — from its
+pricing page, and point `sourceUrl` at that page; never compute cache rates
+from `inputPerMTok` with a multiplier.
+
+`set_model` refuses (409) a `modelId` another provider already owns. A
+shipped id always belongs to its shipped provider — permanently; no other
+provider can ever claim it, not even by disabling or resetting the override.
+A non-shipped id already claimed by another provider (its row active or
+disabled) is freed only by `reset_model` — it takes only the `modelId` and
+clears every row for it, whichever provider owns it; `disable_model` alone
+never frees it, since the disabled row still reserves the id.
+
+`thinkingMode` (`adaptive`, `manual`, or `none`) must match what the exact
+model accepts. Getting it wrong doesn't fail at `set_model` — it fails later,
+when a run calls the model, with `unsupported_anthropic_feature`.
+For Claude Code coding runs, `efforts` is also the exact set of levels a run
+may send, so always include the model's default effort level.
+
+A newly released Claude model may also need a newer Claude Code than your
+Claude Code worker image has: coding runs on it then fail as
+`provider_rejected` (no cost) while native runs work. Upgrade wardby and
+rebuild the worker images before using the model in Claude Code agents.
+
+Catalog changes take effect on the writing process immediately, and on every
+other wardby process within `WARDBY_MODEL_CATALOG_REFRESH_SECONDS` (default
+45). A run already in progress keeps the catalog entry it started with, so
+disabling or repricing a model never changes a run already under way — only
+new runs.
+
+If this deployment delegates to an identity provider, define `models:admin`
+there before relying on it, and map the `model-manager` role (or `admin`) to
+the people who maintain pricing — see
+[Configure identity and privileged access](identity-and-access.md).
+
+If a run can't use a model, see
+[Model not available](errors/model-unavailable.md).

package/help/native-capabilities.md

@@ -0,0 +1,30 @@
+---
+id: native-capabilities
+title: Use native agents, tools, and data
+summary: Attach scoped tools, secrets, datastores, memory, schedules, and sub-agents to a native Wardby agent.
+audience: developer
+tags: [agents, tools, secrets, datastores, memory, schedules, subagents]
+appliesTo: >=0.2.1
+---
+
+# Use native agents, tools, and data
+
+Native agents work through the Wardby control plane rather than a repository
+checkout. Give each agent only the capabilities its job needs:
+
+- **Tools** for approved external actions or APIs.
+- **Secrets** as bindings to tools or agents; values remain in Wardby's trusted
+  components rather than being returned through MCP.
+- **Datastores** for scoped application data and queries.
+- **Memory** for agent-owned durable context.
+- **Schedules and webhooks** to start event-driven work.
+- **Sub-agents** for delegated, bounded work with their own capability set.
+
+Use a budget or shared budget group on every agent, and inspect runs before
+expanding its access. An access grant is intentional delegation: use it only
+when an owner permits one agent to use another resource. Creating or changing
+tools, secrets, datastores, schedules, webhooks, memory, and budget groups
+requires the matching MCP scope.
+
+See [Operate agents](operating-agents.md) for run and budget management, and
+[`README.md`](../README.md) for the feature overview and MCP operations.

package/help/observability.md

@@ -0,0 +1,41 @@
+---
+id: observability
+title: Monitor Wardby
+summary: Scrape private Prometheus metrics and build production alerting around the coding proxy and run lifecycle.
+audience: operator
+tags: [observability, prometheus, grafana, metrics, operations]
+appliesTo: >=0.2.1
+---
+
+# Monitor Wardby
+
+When `METRICS_BIND` is configured, Wardby's coding proxy exposes Prometheus
+metrics at `/metrics`. Keep that endpoint on a private network and permit only
+your collector to scrape it. Metrics cover proxy requests, errors, latency,
+audit events, model cost, reserved and actual budget spend, coding outcomes,
+and Node.js process health; they intentionally exclude prompts, repository
+content, credentials, diffs, raw worker output, and run identifiers.
+
+For a local dashboard stack, run:
+
+```sh
+npm run observability:up
+npm run observability:smoke
+```
+
+This starts Prometheus and Grafana locally. Use `npm run observability:down`
+when finished.
+
+In production, configure your own Prometheus-compatible collector, retention,
+private connectivity, alerts, and SLOs. GCP operators can use the Ops Agent or
+Managed Service for Prometheus; AWS operators can use the CloudWatch Agent
+Prometheus collector. Wardby's reference cloud deployments do not provision
+them, and application/MCP metrics are currently narrower than coding-proxy
+metrics.
+
+Alert on proxy failures, budget cutoffs, cleanup failures, stalled runs, and
+sustained latency or memory growth. Wardby's database remains the source of
+truth for runs, budgets, and accounting.
+
+Read [`docs/observability.md`](../docs/observability.md) for configuration and
+the full production checklist.

package/help/operating-agents.md

@@ -0,0 +1,36 @@
+---
+id: operating-agents
+title: Operate managed agents
+summary: Understand the identity, budget, capabilities, triggers, and result of a Wardby-managed agent.
+audience: operator
+tags: [agents, budgets, schedules, runs]
+appliesTo: >=0.2.1
+---
+
+# Operate managed agents
+
+Every Wardby-managed agent has an owner, system prompt, model, per-run budget,
+and explicitly attached capabilities. A run starts only when its identity,
+policy, and available budget agree.
+
+Create, update, pause, trigger, and inspect agents through Wardby's MCP tools.
+The CLI is the bootstrap and operations fallback. Scheduled work requires a
+running scheduler: `wardby serve` runs MCP, scheduler, and reconciliation in
+one process; `wardby mcp` alone does not execute schedules.
+
+Use [Choose a native or coding agent](creating-agents.md) to select the least
+powerful execution model that can safely produce the desired outcome.
+
+Before a run starts, Wardby reserves its allowed spend. The reservation is
+constrained by the agent's own budget, any shared budget group, and any
+sub-agent run tree. See [Budget troubleshooting](troubleshooting/budgets.md)
+when a run is refused for lack of budget, and
+[Attribute agent spend to issues](cost-attribution.md) to see what runs cost
+per issue, epic, project, agent, or model.
+
+A running run's cost, token counts, and turn count update after each model
+call, so `get_run` and `list_runs` show spend so far rather than zero until the
+run finishes.
+
+For the full lifecycle and the controls applied to every managed run, read
+[`README.md`](../README.md).

package/help/security.md

@@ -0,0 +1,27 @@
+---
+id: security-boundaries
+title: Understand Wardby security boundaries
+summary: Review the isolation, credential, budget, and action-authority controls that apply to managed work.
+audience: operator
+tags: [security, isolation, credentials, budgets]
+appliesTo: >=0.2.1
+---
+
+# Understand Wardby security boundaries
+
+Wardby is designed to make agent work bounded and reviewable. It applies hard
+per-agent and shared-budget limits, grants only explicitly attached tools,
+secrets, datastores, and sub-agents, and records a durable result.
+
+Native tools run in a constrained QuickJS environment. Coding agents use
+isolated workers with bounded resources and a trusted proxy. Workers do not
+receive provider credentials or the GitHub App private key. Coding finalization
+creates a draft pull request; it does not grant the worker merge authority.
+
+Treat the deployment boundary as part of the security model. Restrict Docker or
+Kubernetes administrator access, protect secrets, constrain network egress,
+and read the deployment guide before enabling a production repository.
+
+See [`docs/security-deployment.md`](../docs/security-deployment.md) and
+[`docs/coding-worker-isolation.md`](../docs/coding-worker-isolation.md) for
+the detailed operational model.