@wardby/cli 0.3.0 → 0.4.1

package/help/cost-attribution.md

@@ -0,0 +1,67 @@
+---
+id: cost-attribution
+title: Attribute agent spend to issues
+summary: See what agent work on a Jira card, epic, or project cost, by model and token kind, with the cost_report MCP tool.
+audience: operator
+tags: [cost, spend, attribution, jira, epic, reporting, cost_report, tokens]
+appliesTo: >=0.2.1
+---
+
+# Attribute agent spend to issues
+
+Wardby records which issue each run's cost belongs to, so you can see what agent
+work on a card, an epic, or a whole project cost.
+
+A run is attributed to an issue when:
+
+- a Jira event on that issue started it;
+- it reviews, or answers an `@wardby` mention on, a pull request Wardby opened
+  for the issue;
+- `trigger_agent` named an `issue`, or a webhook call's JSON body named a
+  `wardbyIssue`, as `{ "provider": "jira", "key": "PROJ-123" }`, in a project
+  the agent is linked to. Keys are matched without regard to case
+  (`proj-123` is read as `PROJ-123`). An unlinked project or a malformed key is
+  refused; a webhook answers `400 invalid_issue`. A webhook ignores a
+  top-level `issue` field, so forwarded GitHub or Jira payloads still run;
+- its parent run is attributed. Sub-agents and coding runs inherit the issue
+  and cannot change it.
+
+When a run starts, Wardby records the issue's parent (its epic) as it is at that
+moment. Moving an issue to another epic later leaves earlier runs under the
+earlier epic. Reports always show the latest known titles.
+
+## Read the report
+
+Call the `cost_report` MCP tool. `groupBy` is `issue` (default), `parent`,
+`scope` (project), `agent`, `model`, or `run`; filter with `scopeKey`,
+`parentKey`, `issueKey`, `agentId`, `provider`, and an ISO `from`/`to` window
+(default: the last 30 days). Drill down by combining them: `groupBy: "parent",
+scopeKey: "PROJ"` lists epics, then `groupBy: "issue", parentKey: "PROJ-10"`
+lists that epic's cards, and `groupBy: "run", issueKey: "PROJ-123"` gives run
+ids for `get_run`.
+
+- Amounts are USD. Tokens are reported by kind — fresh input, cached input,
+  cache write, output — because each kind is priced differently; they are never
+  added into one total.
+- `bySource` splits each row's cost by how its runs were attributed, which
+  shows how much was pull-request review (`linked_pr`).
+- `unattributed` is spend in the window with no issue. Only `agentId` narrows
+  it; the project, epic, and issue filters cannot.
+- `totals` sum each run's full cost. With `groupBy: "model"`, rows add up to
+  less when some runs have no per-model record.
+- You see the same runs as `list_runs`: runs of agents you own, plus runs you
+  triggered.
+
+The Jira status comment for a run also ends with its spend: the whole run tree,
+the issue's total so far (every attributed run, whichever agent ran it), and the
+cost per model.
+
+## Setup notes
+
+If a company-managed Jira site still uses the legacy Epic Link field, set
+`WARDBY_JIRA_EPIC_LINK_FIELD` (for example `customfield_10014`) so runs are
+grouped under their epic. On GKE, re-run the database grants bootstrap after
+upgrading so coding runs record their per-model usage; until then they still
+run and a warning is logged.
+
+For the full guide, follow [`docs/jira-agents.md`](../docs/jira-agents.md).

package/help/creating-agents.md

@@ -44,6 +44,21 @@ the trusted coding proxy, and a narrowly installed GitHub App. The agent owner
 must have the required repository access, or an administrator must explicitly
 approve the repository.
 
+## Choosing a model
+
+Both agent types take a `model` field naming an entry in wardby's model
+catalog. Run `list_models` to see which ids this deployment knows about and
+what each costs; `get_model` shows one entry in full. `create_agent` and
+`update_agent` always refuse a `model` that isn't in the catalog or that an
+admin has disabled. For a native agent, they also refuse a model whose
+provider has no credentials configured for native runs here (such a model
+shows `routable: false` in `list_models`). A coding agent's model isn't checked against
+`routable` at all — a coding run uses the coding proxy's own credentials
+instead, so confirm those are configured for Codex or Claude Code
+separately; a missing one fails the run itself at dispatch, not
+`create_agent`/`update_agent`. See [Models and pricing](models.md) and
+[Model not available](errors/model-unavailable.md).
+
 ## Decision checklist
 
 Choose a native agent when all of these are true:
@@ -63,6 +78,13 @@ Choose a coding agent when any of these are true:
 
 Do not use a coding agent merely because a task is complex. Start with the
 least powerful execution model that can safely produce the required outcome.
+A coding agent can also keep a repository's architecture knowledge current; see
+[Set up an architecture agent](help://architecture-agent) and
+[Architecture knowledge bundles](help://knowledge).
+
+For an `@mention` builder with a router, see [Agent recipes](help://agent-recipes) and
+[Builder and router prompts](help://builder-agent).
+
 Read [Connect GitHub repositories](github.md) and
 [Troubleshoot coding workers](troubleshooting/coding-workers.md) before
 enabling repository-changing work.

package/help/deploy-gke.md

@@ -30,6 +30,12 @@ The deployment process is:
 4. Run `HOSTNAME=wardby.example.com deploy/gke/up.sh`, then verify DNS,
    certificate issuance, database IAM bootstrap, and service health.
 
+When a release changes `deploy/gke/database-grants.sql`, re-run the database
+grants bootstrap **before** deploying that release, so the proxy role can
+already write the tables and columns it adds (such as per-model usage for
+[cost attribution](cost-attribution.md), or a run's live turn count). Until the
+grants are applied, the coding proxy's writes are refused and coding runs fail.
+
 Claude Code's two-container executor is currently Docker-only; Kubernetes
 coding workers use the Codex path. Configure an identity provider and GitHub
 App before allowing people to use the public endpoint.

package/help/errors/model-unavailable.md

@@ -0,0 +1,63 @@
+---
+id: errors/model-unavailable
+title: Model not available
+summary: Wardby refused to start or configure a run because its model is not usable in this deployment right now.
+audience: all
+tags: [error, models, pricing, model_unavailable, refusal]
+appliesTo: ">=0.4.0"
+---
+
+# Model not available
+
+`model_unavailable` means the model an agent names cannot be routed to in
+this deployment right now. Wardby checks this before a run starts spending —
+and whenever `create_agent` or `update_agent` sets or changes an agent's
+model — never mid-run. A native agent's error carries one of three reasons;
+a coding agent's only ever carries the first two, since a coding run uses the
+coding proxy's own credentials rather than looking up a provider adapter:
+
+- **`not_in_catalog`** — the model id is not in the catalog at all: not
+  shipped with this release, and no admin has added it. Run `list_models` to
+  see the exact ids this deployment knows about, and pick one of those, or
+  ask someone with `models:admin` to add it with `set_model`.
+- **`disabled`** — the model is in the catalog, but an admin has disabled it
+  with `disable_model`. Pick a different model, or ask someone with
+  `models:admin` to bring it back with `reset_model` (reverts to the shipped
+  entry, if any) or `set_model` (re-adds it with current values).
+- **`provider_not_configured`** (native agents only) — the model's provider
+  (`openai`, `anthropic`, or `bedrock-claude`) has no credentials configured
+  for native runs in this deployment, even though the model itself is in the
+  catalog. An operator needs to configure that provider's credentials before
+  any native agent can use a model under it; see
+  [Getting started](../getting-started.md).
+
+Whatever the reason, the run is not lost: it ends with status `failed`, zero spend, and
+the `model_unavailable` message as its error, so `list_runs` and `get_run`
+show why. A coding agent's run fails at dispatch, before any worker starts,
+and a scheduled agent moves on to its next window instead of retrying the
+same one. A coding agent whose model now belongs to a different provider than
+its coding provider drives (for example a Claude model on a Codex agent)
+fails the same way, with `Model "<id>" is not supported by coding provider
+"<provider>"` as its error.
+
+A coding agent's model is checked against the catalog only
+(`not_in_catalog`/`disabled`), never `provider_not_configured`: coding runs
+never look up a provider adapter at all, so a model can pass this check and
+still fail later for reasons `model_unavailable` never reports.
+
+One such failure has a specific name: dispatching a Claude Code run throws
+`coding_provider_not_configured:claude-code` when this deployment's
+`CODING_CLAUDE_WORKER_IMAGE` or `CODING_CLAUDE_TOOL_RUNNER_IMAGE` isn't set —
+it means the Claude Code worker or tool-runner image itself isn't configured,
+not a missing credential, and there is no equivalent error or string for
+Codex. See [Local coding-agent setup](../../docs/coding-agent-setup.md).
+
+A missing or invalid API key behind a coding run's model-provider credential
+(`CODING_OPENAI_CREDENTIAL_REF` for Codex, `CODING_ANTHROPIC_CREDENTIAL_REF`
+for Claude Code) is a different problem with no dedicated error code
+documented here: the run starts, then fails when it actually calls the
+model — not as `model_unavailable`, and not at dispatch. Check the coding
+proxy's own logs for that run.
+
+See [Models and pricing](../models.md) for how the catalog works and who can
+change it.

package/help/getting-started.md

@@ -24,6 +24,7 @@ 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).
 

package/help/github.md

@@ -28,3 +28,21 @@ 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

@@ -20,18 +20,23 @@ 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, and memory. Three
-sensitive permissions have an additional role requirement:
+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 `services:manage`, in the provider before deploying. Clients
+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)

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/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/operating-agents.md

@@ -24,7 +24,13 @@ 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.
+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/troubleshooting/budgets.md

@@ -23,4 +23,10 @@ In-progress runs retain their unspent reservation, so overlapping scheduled,
 webhook, and manual runs share one cap rather than each assuming the full
 remaining balance.
 
+A run's spend is recorded as it goes, not only when it finishes. A sub-agent
+dispatched partway through a run therefore gets the run tree's capacity minus
+what the parent (and any earlier sub-agents) have already spent, so a parent
+that spends heavily before delegating can leave a sub-agent refused with
+`run_tree_exhausted`.
+
 For a shared-group refusal, read [Budget group exhausted](../errors/budget-group-exhausted.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wardby/cli",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Self-hosted control plane for budget-guarded AI agents.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/wardby/wardby#readme",
@@ -55,10 +55,12 @@
     "format:check": "prettier --check .",
     "build:vendor": "node scripts/build-sandbox-vendor.mjs",
     "build:help": "tsx src/help/build.ts",
+    "build:viewer-schemas": "tsx src/viewer/build-schemas.ts",
     "build": "npm run build:vendor && PRISMA_HIDE_UPDATE_MESSAGE=1 prisma generate && tsc -p tsconfig.build.json && npm run build:help",
     "prepare": "npm run build:vendor && PRISMA_HIDE_UPDATE_MESSAGE=1 prisma generate",
     "prepack": "npm run build",
     "cli": "tsx --conditions=wardby-source src/cli.ts",
+    "codex:rerecord": "tsx --conditions=wardby-source src/tools/codex-rerecord.ts",
     "capture:autopilot": "tsx --conditions=wardby-source src/tools/capture-autopilot-dry-run.ts",
     "test": "npm run build:vendor && vitest run",
     "test:package": "node scripts/npm-package-acceptance.mjs",
@@ -115,12 +117,13 @@
     "semver": "^7.8.5",
     "tar-stream": "^3.2.1",
     "undici": "^8.7.0",
+    "yaml": "^2.9.1",
     "zod": "^3.25.76",
     "zod-to-json-schema": "^3.25.2"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@openai/codex-sdk": "0.153.4",
+    "@openai/codex-sdk": "0.159.2",
     "@types/node": "^24.0.0",
     "@types/papaparse": "^5.5.2",
     "@types/pg": "8.23.1",

package/prisma/migrations/20260930000000_jira_issue_projects/migration.sql

@@ -0,0 +1,34 @@
+-- Jira issue-tracker links and per-run status comments (phase 1).
+CREATE TABLE "AgentIssueProject" (
+    "id" TEXT NOT NULL,
+    "agentId" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "projectKey" TEXT NOT NULL,
+    "access" TEXT NOT NULL,
+    "triggers" TEXT[] DEFAULT ARRAY[]::TEXT[],
+    "triggerStatuses" TEXT[] DEFAULT ARRAY[]::TEXT[],
+    "triggerLabels" TEXT[] DEFAULT ARRAY[]::TEXT[],
+    "jqlFilter" TEXT,
+    "trustedAccountIds" TEXT[] DEFAULT ARRAY[]::TEXT[],
+    "commentVisibilityRole" TEXT,
+    "authorizedById" TEXT NOT NULL,
+    "authorizedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    CONSTRAINT "AgentIssueProject_pkey" PRIMARY KEY ("id")
+);
+CREATE UNIQUE INDEX "AgentIssueProject_agentId_provider_projectKey_key" ON "AgentIssueProject"("agentId", "provider", "projectKey");
+CREATE INDEX "AgentIssueProject_provider_projectKey_idx" ON "AgentIssueProject"("provider", "projectKey");
+ALTER TABLE "AgentIssueProject" ADD CONSTRAINT "AgentIssueProject_agentId_fkey" FOREIGN KEY ("agentId") REFERENCES "Agent"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+CREATE TABLE "RunIssueStatus" (
+    "runId" TEXT NOT NULL,
+    "provider" TEXT NOT NULL,
+    "issueKey" TEXT NOT NULL,
+    "commentId" TEXT,
+    "visibilityRole" TEXT,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "completedAt" TIMESTAMP(3),
+    CONSTRAINT "RunIssueStatus_pkey" PRIMARY KEY ("runId")
+);
+CREATE INDEX "RunIssueStatus_completedAt_idx" ON "RunIssueStatus"("completedAt");
+ALTER TABLE "RunIssueStatus" ADD CONSTRAINT "RunIssueStatus_runId_fkey" FOREIGN KEY ("runId") REFERENCES "Run"("id") ON DELETE CASCADE ON UPDATE CASCADE;

package/prisma/migrations/20261001000000_jira_phase2_allowlists/migration.sql

@@ -0,0 +1,3 @@
+-- Jira phase 2: per-link allowlists for transitions and field edits.
+ALTER TABLE "AgentIssueProject" ADD COLUMN "allowedTransitions" TEXT[] DEFAULT ARRAY[]::TEXT[];
+ALTER TABLE "AgentIssueProject" ADD COLUMN "writableFields" TEXT[] DEFAULT ARRAY[]::TEXT[];

package/prisma/migrations/20261001010000_jira_link_types_allowlist/migration.sql

@@ -0,0 +1,2 @@
+-- Jira phase 2: per-link allowlist of issue link types jira_link_issues may create.
+ALTER TABLE "AgentIssueProject" ADD COLUMN "allowedLinkTypes" TEXT[] DEFAULT ARRAY[]::TEXT[];