@wardby/cli 0.1.0 → 0.2.1

package/README.md

@@ -1,79 +1,175 @@
 <div>
-  <img align="left" hspace="24" src="docs/assets/brand/wardby-mascot.png" alt="Wardby guardian robot protecting an agent budget" width="280">
+  <img align="left" hspace="24" src="https://raw.githubusercontent.com/wardby/wardby/main/docs/assets/brand/wardby-mascot.png" alt="Wardby guardian robot protecting an agent budget" width="280">
   <h3><big><big>Wardby</big></big> <small><em>(pronounced&nbsp;“WARD&#8209;bee”)</em></small></h3>
   <h3>Autonomous agents, bounded by design.</h3>
-  <p><strong>Most agent runners focus on helping a model complete a task. Wardby is the self-hosted control plane that decides whether the task should run, limits what it can access, and returns a reviewable outcome governed by explicit policy.</strong></p>
+  <p><strong>Agent runners help a model complete a task. Wardby is the self-hosted control plane that governs the work around it: whether it may run, what it may access, what it may spend, and what reviewable outcome it may produce.</strong></p>
   <br clear="left">
   <p><strong>Budgets are enforced before spend: every model request must fit within a hard run limit before it reaches the provider.</strong></p>
+  <p><strong>Bring your providers. Keep your infrastructure. Govern agents in one place.</strong></p>
   <p>
+    <a href="#get-started">Get started</a> ·
     <a href="#why-wardby">Why Wardby</a> ·
-    <a href="#why-wardby-instead-of-another-agent-runner">Why it is different</a> ·
+    <a href="#where-wardby-fits">Where it fits</a> ·
     <a href="#a-full-cycle-agent-from-one-conversation">Full-cycle example</a> ·
     <a href="#host-it-in-your-cloud">Deployments</a> ·
     <a href="#bring-your-own-observability">Observability</a> ·
-    <a href="#quickstart">Quickstart</a> ·
     <a href="#security-boundaries">Security</a>
   </p>
 </div>
 <br clear="left">
 
-<!-- GitHub does not expose live Actions badge images for private repositories. These capability badges link authenticated readers to the authoritative workflow. -->
-
-[![Security CI](https://img.shields.io/badge/security%20CI-GitHub%20Actions-2088FF?logo=githubactions&logoColor=white)](https://github.com/wardby/wardby/actions/workflows/security.yml?query=branch%3Amain)
+<!-- The first four badges are live: the npm version, Node floor and license are
+read from the published package, and the security badge shows the latest run of
+the security workflow on main. The last three are capability labels describing
+what that workflow enforces -- they are not status and never change colour.
+Every URL is absolute because npm renders this README too, and a relative path
+there resolves against npmjs.com instead of this repository. -->
+
+[![npm](https://img.shields.io/npm/v/@wardby/cli)](https://www.npmjs.com/package/@wardby/cli)
+[![Security checks](https://github.com/wardby/wardby/actions/workflows/security.yml/badge.svg?branch=main)](https://github.com/wardby/wardby/actions/workflows/security.yml?query=branch%3Amain)
+[![Node](https://img.shields.io/node/v/@wardby/cli)](https://www.npmjs.com/package/@wardby/cli)
+[![License](https://img.shields.io/npm/l/@wardby/cli)](https://github.com/wardby/wardby/blob/main/LICENSE)
 [![Dependency audit](https://img.shields.io/badge/dependencies-audit%20policy-0f766e.svg)](https://github.com/wardby/wardby/actions/workflows/security.yml?query=branch%3Amain)
 [![Container scan](https://img.shields.io/badge/container%20images-Trivy%20CRITICAL%20gate-0f766e.svg)](https://github.com/wardby/wardby/actions/workflows/security.yml?query=branch%3Amain)
 [![SBOM](https://img.shields.io/badge/SBOM-SPDX%20JSON-0f766e.svg)](https://github.com/wardby/wardby/actions/workflows/security.yml?query=branch%3Amain)
-[![License](https://img.shields.io/badge/license-Apache--2.0-0f766e.svg)](LICENSE)
 
 > **Project status:** the control plane, scheduler, budget groups, MCP server,
 > native agents, isolated Codex and Claude Code workers, GitHub draft-PR flow,
 > and local observability stack are implemented and tested. Production
 > readiness and cloud deployment coverage are still being expanded.
 
+## Get started
+
+### Run locally in five minutes
+
+Requirements: Node.js 24 or newer, Docker, and an OpenAI or Anthropic API key.
+You do not need to clone Wardby or install PostgreSQL.
+
+1. From the project where you want to use Wardby, run:
+
+   ```sh
+   npx --yes @wardby/cli@latest quickstart
+   ```
+
+2. Follow the prompts to choose a provider, start PostgreSQL, create a `$1`
+   demo agent, and optionally connect Codex or Claude Code through MCP.
+
+3. Verify the installation:
+
+   ```sh
+   npx --yes @wardby/cli@latest doctor
+   ```
+
+Quickstart keeps credentials and local state under `.wardby/` in the current
+project. Read the [local getting-started guide](https://github.com/wardby/wardby/blob/main/docs/getting-started.md)
+for unattended setup, lifecycle commands, MCP configuration, and cleanup.
+
+### Develop Wardby from source
+
+Clone the repository only when you want to contribute to Wardby, inspect its
+deployment assets, or build images yourself:
+
+```sh
+git clone https://github.com/wardby/wardby.git
+cd wardby
+npm ci
+npm run build
+npm test
+```
+
+Continue with [CONTRIBUTING.md](https://github.com/wardby/wardby/blob/main/CONTRIBUTING.md)
+for the development database, migrations, required checks, and contribution
+expectations.
+
+### Deploy for a team
+
+- Follow the [GKE guide](https://github.com/wardby/wardby/blob/main/docs/getting-started-gke.md)
+  for the supported Google Cloud reference deployment.
+- Start from the [portable production boundary](https://github.com/wardby/wardby/blob/main/deploy/production/README.md)
+  for another cloud, VM, or container platform.
+- Follow [Bring your own identity provider](https://github.com/wardby/wardby/blob/main/docs/getting-started-identity-provider.md)
+  to protect remote MCP with your existing OAuth/OIDC provider.
+
 ## Why Wardby
 
 AI agents are easy to demo and harder to operate. Once an agent can spend
 money, use credentials, change a repository, or run without a person watching,
 teams need more than a prompt and a cron job.
 
+### One control plane instead of scattered automation
+
+Teams often begin with Claude Code or Codex on developer machines,
+repository-specific automation, and separate provider dashboards. As adoption
+grows, agent definitions, ownership, credentials, budgets, schedules, and run
+history become fragmented across tools and repositories.
+
+Wardby gives every Wardby-managed agent one durable operational identity: who
+owns it, why it exists, what it may access, when it runs, what it may spend,
+and what outcome it produced.
+
 Wardby provides the control plane around the model:
 
-| For engineering leaders                                                     | For developers                                                                             |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| Put explicit cost, ownership, and approval boundaries around agent work.    | Create and manage agents from Claude or Codex through MCP.                                 |
-| Keep execution, data, and credentials in infrastructure your team controls. | Choose OpenAI, Anthropic, or Bedrock-backed models per agent.                              |
-| Turn one-off experiments into scheduled, observable operating processes.    | Attach scoped tools, secrets, schedules, memory, and sub-agents.                           |
-| Keep approval and action authority explicit for consequential outcomes.     | Run optional coding tasks in isolated Codex or Claude Code workers that produce draft PRs. |
+| For engineering leaders                                                      | For developers                                                                             |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Keep an inventory of owned agents, purposes, schedules, limits, and results. | Create and manage agents from Claude or Codex through MCP.                                 |
+| See reserved budget and actual usage across Wardby-managed agents.           | Choose OpenAI, Anthropic, or Bedrock-backed models per agent.                              |
+| Keep execution, data, and credentials in infrastructure your team controls.  | Switch approved models or builders without rewriting the governance contract.              |
+| Turn one-off experiments into scheduled, observable operating processes.     | Attach scoped tools, secrets, schedules, memory, and sub-agents.                           |
+| Keep approval and action authority explicit for consequential outcomes.      | Run optional coding tasks in isolated Codex or Claude Code workers that produce draft PRs. |
 
 The result is not another autonomous black box. It is a way to make agent work
 repeatable, bounded, inspectable, and reviewable.
 
-## Why Wardby instead of another agent runner?
+## Where Wardby fits
 
 Agent tools solve different layers of the problem. Wardby does not need to
 replace them: it provides the self-hosted operating boundary around agents and
 the work they perform.
 
-| Category                   | What it primarily helps you do                              | What Wardby adds                                                                           |
-| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| **Agent frameworks**       | Build reasoning loops, tool calls, and multi-agent logic.   | Persistent ownership, schedules, budgets, credentials, run history, and lifecycle control. |
-| **Coding agents**          | Plan, edit, and test code for an interactive task.          | Isolated managed workers, admission-time budgets, scoped access, and optional draft PRs.   |
-| **Hosted agent platforms** | Start quickly on infrastructure operated by another vendor. | A control plane, data, credentials, and execution boundary you can host in your own cloud. |
-| **Workflow orchestrators** | Make application jobs durable, retryable, and observable.   | Agent-specific policy, model usage, capabilities, budgets, and MCP-native operations.      |
-
-The distinction is control, not just execution. Wardby reserves spend before a
-run starts, grants only assigned capabilities, records what happened, and
-keeps downstream action authority separate from the worker that produced the
-result.
-
-## One control plane, the full lifecycle
-
-![Wardby workflow: ask in Claude or Codex, define an agent through MCP, govern it in Wardby, execute it in isolation, and apply review policy to its outcome](docs/assets/wardby-workflow.svg)
-
-Claude and Codex are the operator experience. Wardby is the durable system
-behind them: it stores agent definitions, triggers work, reserves budget,
-mediates tools and credentials, records outcomes, and exposes run state through
-MCP.
+| Category                    | What it primarily helps you do                              | What Wardby adds                                                                           |
+| --------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **Repository automation**   | Run jobs for one repository in response to delivery events. | One agent catalog, budget model, and policy boundary across repositories and triggers.     |
+| **Agent frameworks**        | Build reasoning loops, tool calls, and multi-agent logic.   | Persistent ownership, schedules, budgets, credentials, run history, and lifecycle control. |
+| **Coding agents**           | Plan, edit, and test code for an interactive task.          | Isolated managed workers, admission-time budgets, scoped access, and optional draft PRs.   |
+| **Provider dashboards**     | Report usage and cost within one model provider.            | Agent-owned budgets, capabilities, runs, and outcomes across approved providers.           |
+| **LLM gateways**            | Route model requests, manage keys, and enforce quotas.      | Budgets tied to named agents, owned runs, capabilities, schedules, and outcomes.           |
+| **Observability platforms** | Trace requests, evaluate quality, and explain cost.         | Admission and execution controls applied before work occurs, plus a durable agent catalog. |
+| **Vendor control planes**   | Govern agents inside one provider or cloud ecosystem.       | A self-hosted boundary spanning approved providers, builders, repositories, and clouds.    |
+| **Workflow orchestrators**  | Make application jobs durable, retryable, and observable.   | Agent-specific policy, model usage, capabilities, budgets, and MCP-native operations.      |
+
+The distinction is governed work, not just model calls or execution. Rather
+than assembling a gateway, scheduler, agent catalog, budget service,
+capability registry, and run database, Wardby provides one operating boundary.
+It reserves spend before a run starts, grants only assigned capabilities,
+records what happened, and keeps downstream action authority separate from the
+worker that produced the result.
+
+> **Scope:** Wardby's inventory and budget views cover work managed through
+> Wardby. Provider reconciliation and unmanaged-agent discovery are required
+> before those views can represent every AI agent or expense in an
+> organization.
+
+## One operational contract, the full lifecycle
+
+![Wardby workflow: ask in Claude or Codex, define an agent through MCP, govern it in Wardby, execute it in isolation, and apply review policy to its outcome](https://raw.githubusercontent.com/wardby/wardby/main/docs/assets/wardby-workflow.svg)
+
+Claude and Codex are the operator experience. Wardby is the durable operating
+boundary between intent and agent execution: it stores agent definitions,
+triggers work, reserves budget, mediates tools and credentials, records
+outcomes, and exposes run state through MCP. Nothing runs until identity,
+policy, and available budget agree.
+
+### Governed shared state for agent teams
+
+Named Wardby datastores let related agents exchange persistent structured data
+without sharing an unrestricted database credential. Datastores are owned and
+attached to agents explicitly; each sandboxed tool can reach only approved
+bound names and key prefixes.
+
+A planner can publish a feature plan, a builder can record implementation
+state, and a reviewer or QA agent can add findings to the same governed
+workspace. Datastores provide bounded coordination state, not a replacement
+for authoritative source systems or searchable agent memory.
 
 ## A full-cycle agent from one conversation
 
@@ -100,13 +196,17 @@ Claude or Codex can translate that request into Wardby MCP operations such as
 
 The same agent can be updated, paused, triggered, inspected, or deleted from an
 MCP conversation. The CLI remains available as the bootstrap and operations
-floor.
+floor. The result is autonomy with a receipt: an owned run with bounded spend,
+assigned capabilities, durable status, and a reviewable outcome.
 
 ## Agent ecosystems you can compose
 
 Wardby provides lifecycle primitives rather than prescribing one fixed catalog.
 These are example systems a team can build and manage through MCP:
 
+**Builders can vary. The controls do not.** Each system inherits the same
+budget, capability, identity, evidence, and review contract.
+
 | Agent system             | Typical cycle                                                      | Governed outcome                     |
 | ------------------------ | ------------------------------------------------------------------ | ------------------------------------ |
 | **Delivery pipeline**    | Work request → plan → implementation → tests → review              | Optional draft feature or bug-fix PR |
@@ -122,31 +222,33 @@ own model, tools, schedule, and run history.
 
 ## Host it in your cloud
 
+**Bring your providers. Keep your infrastructure. Govern agents in one place.**
+
 The core does not import a cloud SDK. Jobs, model access, email, secrets,
 authentication, and object storage sit behind provider interfaces so operators
-can choose the infrastructure boundary that fits their environment.
-
-| Target                               | Current support                                                                                                                                 |
-| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Local Docker, VM, or on-premises** | Portable PostgreSQL and container workflow for development and self-hosting.                                                                    |
-| **Production container baseline**    | Separate runtime and migration images plus a Compose/Caddy reference boundary.                                                                  |
-| **GCP**                              | Terraform reference for the control plane on Cloud Run and Cloud SQL. Cloud-native coding jobs and production observability are follow-on work. |
-| **AWS**                              | The portable runtime and Bedrock model adapter are available; a native AWS deployment module is planned.                                        |
-| **Other clouds**                     | Run the production image and provide equivalent PostgreSQL, secrets, ingress, egress, and monitoring controls.                                  |
-
-Start with [deployment targets](deploy/README.md), the
-[portable production boundary](deploy/production/README.md), or the
-[GCP setup guide](deploy/gcp/SETUP.md). Reference deployments are examples,
+can choose the infrastructure boundary that fits their environment. Models,
+coding executors, cloud platforms, and observability systems can change
+independently instead of defining the agent architecture. This reduces
+control-plane lock-in without pretending that source control, model providers,
+or monitoring systems disappear.
+
+| Target                               | Current support                                                                                                  |
+| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| **Local Docker, VM, or on-premises** | Portable PostgreSQL and container workflow for development and self-hosting.                                     |
+| **Production container baseline**    | Separate runtime and migration images plus a Compose/Caddy reference boundary.                                   |
+| **GKE Autopilot**                    | Supported GCP reference with private Cloud SQL, isolated Codex worker pods, HTTPS Gateway, and immutable images. |
+| **AWS**                              | The portable runtime and Bedrock model adapter are available; a native AWS deployment module is planned.         |
+| **Other clouds**                     | Run the production image and provide equivalent PostgreSQL, secrets, ingress, egress, and monitoring controls.   |
+
+Start with [deployment targets](https://github.com/wardby/wardby/blob/main/deploy/README.md), the
+[portable production boundary](https://github.com/wardby/wardby/blob/main/deploy/production/README.md), or the
+[GKE getting-started guide](https://github.com/wardby/wardby/blob/main/docs/getting-started-gke.md). Reference deployments are examples,
 not a requirement to use one vendor.
 
-**A complete deployment runs more than `wardby mcp`.** `mcp` serves the MCP
-surface; the scheduler that fires due agents and the reconciler that recovers
-orphaned runs live in `wardby scheduler`. Run **`wardby serve`** to get all three
-in one process. It is the container image's default command and what a
-single-container deployment (Cloud Run, a lone VM) should run. Alternatively,
-run `mcp` and `scheduler` as two processes, as `deploy/production/compose.yml`
-does. Running `mcp` alone logs a startup warning if enabled schedules exist
-that nothing will fire.
+For a single-container deployment, run **`wardby serve`** to start MCP, the
+scheduler, and reconciliation together. Split deployments can run `wardby mcp`
+and `wardby scheduler` separately; `mcp` alone does not fire schedules. See the
+deployment guides above for the complete process boundary.
 
 ## Bring your own observability
 
@@ -172,7 +274,7 @@ npm run observability:down
 The included cloud deployments do not yet provision AWS or GCP collectors.
 Current metrics primarily cover the coding proxy; application/MCP metrics,
 production alerts, and SLOs remain operator responsibilities. See the
-[observability guide](docs/observability.md) for boundaries and retention.
+[observability guide](https://github.com/wardby/wardby/blob/main/docs/observability.md) for boundaries and retention.
 
 ## Security boundaries
 
@@ -195,48 +297,33 @@ production alerts, and SLOs remain operator responsibilities. See the
 - **Sanitized operations:** lifecycle events and metrics exclude prompts,
   repository content, credentials, diffs, and raw worker output.
 
-Read the [runtime architecture](docs/architecture-runtime.md),
-[coding-worker isolation model](docs/coding-worker-isolation.md), and
-[security deployment guide](docs/security-deployment.md) before enabling a
+Read the [runtime architecture](https://github.com/wardby/wardby/blob/main/docs/architecture-runtime.md),
+[coding-worker isolation model](https://github.com/wardby/wardby/blob/main/docs/coding-worker-isolation.md), and
+[security deployment guide](https://github.com/wardby/wardby/blob/main/docs/security-deployment.md) before enabling a
 production repository.
 
 Review policy is designed to support designated agents as well as people.
 Agent approvals will be recorded as workflow evidence; operators will decide
 whether that evidence permits an automated action or still requires a person.
 
-## Quickstart
-
-Requirements: Node.js 24 or newer, Docker, and one supported model-provider
-credential.
-
-```sh
-git clone https://github.com/wardby/wardby.git
-cd wardby
-npm ci
-cp .env.example .env
-```
+## Optional npm installation
 
-Edit `.env` and set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. Generate a local
-secret-encryption key with `openssl rand -hex 32` and use it as
-`SECRET_APP_KEY`. Then initialize the local database and start the stdio MCP
-server:
+The `npx` quickstart above requires no installation. To pin Wardby as a local
+project dependency instead:
 
 ```sh
-npm run db:up
-npm run prisma:generate
-npm run prisma:migrate
-npm run cli -- mcp
+npm install @wardby/cli
 ```
 
-Point Claude or Codex at `npm run cli -- mcp` with the repository as its working
-directory. The exact client configuration format differs, but both use Wardby's
-stdio transport locally. For shared or remote access, use Streamable HTTP with
-OAuth and the production boundary documented above.
+That install is audit-clean: the published package carries no Prisma CLI,
+`@prisma/config`, `deepmerge-ts`, or `mysql2`, so `npm audit` reports nothing
+and no `overrides` entry is needed in your own `package.json`.
 
-Once connected, ask the client to list the available Wardby tools, create an
-agent with a small budget, trigger it, and inspect the run. Coding-agent setup
-additionally requires a dedicated GitHub App, immutable worker images, and the
-proxy boundary described in the [local coding-agent setup guide](docs/coding-agent-setup.md).
+`wardby quickstart` and `wardby doctor` separately fetch the pinned Prisma CLI
+(`prisma@7.10.0`) on demand via `npx` to run migrations, so the machine running
+them needs npm registry access at that moment. See
+[Images and dependencies](https://github.com/wardby/wardby/blob/main/docs/security-deployment.md#images-and-dependencies)
+for the repository's own dependency-override policy.
 
 ## What is implemented
 
@@ -251,12 +338,12 @@ proxy boundary described in the [local coding-agent setup guide](docs/coding-age
 - In-process reconciliation and optional DBOS durable workflows.
 - Self-hosted or delegated OAuth for remote MCP access.
 - Prometheus metrics and provisioned Grafana dashboards for local operations.
-- Portable production images, a Compose/Caddy boundary, and a GCP control-plane
-  Terraform reference.
+- Portable production images, a Compose/Caddy boundary, and a GKE Autopilot
+  Terraform reference deployment.
 
 This project is under active development. Run the
-[release verification](docs/release-verification.md) checks and review the
-[security deployment guide](docs/security-deployment.md) before production use.
+[release verification](https://github.com/wardby/wardby/blob/main/docs/release-verification.md) checks and review the
+[security deployment guide](https://github.com/wardby/wardby/blob/main/docs/security-deployment.md) before production use.
 
 ## Repository map
 
@@ -273,10 +360,10 @@ docs/           Architecture, security, setup, and operator guidance
 
 ## License
 
-Apache License 2.0. See [LICENSE](LICENSE) for the license terms and
-[NOTICE](NOTICE) for attribution.
+Apache License 2.0. See [LICENSE](https://github.com/wardby/wardby/blob/main/LICENSE) for the license terms and
+[NOTICE](https://github.com/wardby/wardby/blob/main/NOTICE) for attribution.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute and [SECURITY.md](SECURITY.md)
+See [CONTRIBUTING.md](https://github.com/wardby/wardby/blob/main/CONTRIBUTING.md) to contribute and [SECURITY.md](https://github.com/wardby/wardby/blob/main/SECURITY.md)
 to report a vulnerability privately.
 
-Built as an independent reimplementation. See [CLEANROOM.md](CLEANROOM.md).
+Built as an independent reimplementation. See [CLEANROOM.md](https://github.com/wardby/wardby/blob/main/CLEANROOM.md).

package/deploy/local/docker-compose.yml

@@ -2,15 +2,15 @@ services:
   postgres:
     image: postgres:16-alpine
     environment:
-      POSTGRES_USER: wardby
-      POSTGRES_PASSWORD: wardby
-      POSTGRES_DB: wardby
+      POSTGRES_USER: ${WARDBY_POSTGRES_USER:-wardby}
+      POSTGRES_PASSWORD: ${WARDBY_POSTGRES_PASSWORD:-wardby}
+      POSTGRES_DB: ${WARDBY_POSTGRES_DB:-wardby}
     ports:
-      - "55432:5432"
+      - "${WARDBY_POSTGRES_PORT:-55432}:5432"
     volumes:
       - wardby-postgres-data:/var/lib/postgresql/data
     healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U wardby -d wardby"]
+      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
       interval: 5s
       timeout: 5s
       retries: 12

package/dist/claude-coding-worker/driver.d.ts

@@ -20,6 +20,7 @@ export declare const CLAUDE_OUTPUT_JSON_SCHEMA: {
         };
         readonly tag: {
             readonly type: "string";
+            readonly description: "Optional short label shown in the pull request title, such as a ticket id. At most 32 characters: letters, digits, '.', '_', '/', '-', starting with a letter or digit, with no spaces. Example: \"add-jokes\". Omit it when there is no natural label.";
         };
         readonly tests: {
             readonly type: "array";

package/dist/claude-coding-worker/driver.js

@@ -13,7 +13,10 @@ export const CLAUDE_OUTPUT_JSON_SCHEMA = {
         runId: { type: "string" },
         outcome: { type: "string", enum: ["changes_ready", "no_changes", "budget_exhausted"] },
         summary: { type: "string" },
-        tag: { type: "string" },
+        tag: {
+            type: "string",
+            description: "Optional short label shown in the pull request title, such as a ticket id. At most 32 characters: letters, digits, '.', '_', '/', '-', starting with a letter or digit, with no spaces. Example: \"add-jokes\". Omit it when there is no natural label.",
+        },
         tests: {
             type: "array",
             maxItems: 64,

package/dist/claude-coding-worker/main.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readCodingInput, writeCodingOutputAtomic } from "../coding-worker/artifact.js";
-import { safeWorkerErrorCode } from "../coding-worker/errors.js";
+import { safeOutputIssues, safeWorkerErrorCode } from "../coding-worker/errors.js";
 import { runClaudeCodingWorker } from "./driver.js";
 import { createClaudeSdkQuery } from "./sdk.js";
 const INPUT_PATH = "/run/wardby/input/input.json";
@@ -36,6 +36,7 @@ catch (error) {
         : safeCode === "worker_failed"
             ? `worker_${stage}_failed`
             : safeCode;
-    process.stderr.write(`${JSON.stringify({ error: code })}\n`);
+    const issues = code === "coding_output_invalid" ? safeOutputIssues(error) : undefined;
+    process.stderr.write(`${JSON.stringify({ error: code, ...(issues ? { issues } : {}) })}\n`);
     process.exitCode = controller.signal.aborted ? 143 : 1;
 }

package/dist/cli-help.d.ts

@@ -1 +1 @@
-export declare const CLI_USAGE = "usage:\n  wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule \"<cron>\"] [--timezone <tz>] [--max-turns <n>]\n  wardby agent list\n  wardby agent schedule <name> --cron \"<expr>\" [--timezone <tz>] [--disable]\n  wardby tool create --name <n> --description <d> --params <file> --code <file>\n  wardby tool attach <tool-name> <agent-name>\n  wardby tool detach <tool-name> <agent-name>\n  wardby tool list [--agent <name>]\n  wardby run <name>\n  wardby runs [--agent <name>] [--limit N] [--status <s>]\n  wardby coding preflight   (JOB_LAUNCHER=docker or kubernetes)\n  wardby coding cleanup --run-id <id>\n  wardby scheduler [--scope default]\n  wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport)\n  wardby serve [--scope default]   (mcp + scheduler + reconciler in one process; http only)\n  wardby import <bundle-dir> --owner <subject> [--public] [--include-secrets --transfer-key <pem>] [--default-budget <usd>] [--dry-run] [--prefix <p>] [--on-conflict fail|skip|rename] [--allow-open-fetch]\n\noptions:\n  -h, --help       Show this help\n  -v, --version    Show the installed Wardby version";
+export declare const CLI_USAGE = "usage:\n  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--skip-demo] [--non-interactive --yes]\n  wardby doctor\n  wardby status\n  wardby logs [--tail N] [--follow]\n  wardby down [--volumes]\n  wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule \"<cron>\"] [--timezone <tz>] [--max-turns <n>]\n  wardby agent list\n  wardby agent schedule <name> --cron \"<expr>\" [--timezone <tz>] [--disable]\n  wardby tool create --name <n> --description <d> --params <file> --code <file>\n  wardby tool attach <tool-name> <agent-name>\n  wardby tool detach <tool-name> <agent-name>\n  wardby tool list [--agent <name>]\n  wardby run <name>\n  wardby runs [--agent <name>] [--limit N] [--status <s>]\n  wardby coding preflight   (JOB_LAUNCHER=docker or kubernetes)\n  wardby coding cleanup --run-id <id>\n  wardby scheduler [--scope default]\n  wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport)\n  wardby serve [--scope default]   (mcp + scheduler + reconciler in one process; http only)\n  wardby import <bundle-dir> --owner <subject> [--public] [--include-secrets --transfer-key <pem>] [--default-budget <usd>] [--dry-run] [--prefix <p>] [--on-conflict fail|skip|rename] [--allow-open-fetch]\n\noptions:\n  -h, --help       Show this help\n  -v, --version    Show the installed Wardby version";

package/dist/cli-help.js

@@ -1,4 +1,9 @@
 export const CLI_USAGE = `usage:
+  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--skip-demo] [--non-interactive --yes]
+  wardby doctor
+  wardby status
+  wardby logs [--tail N] [--follow]
+  wardby down [--volumes]
   wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule "<cron>"] [--timezone <tz>] [--max-turns <n>]
   wardby agent list
   wardby agent schedule <name> --cron "<expr>" [--timezone <tz>] [--disable]

package/dist/coding/protocol.d.ts

@@ -6,10 +6,35 @@ export declare const MAX_CODING_SUMMARY_BYTES: number;
 export declare const MAX_CODING_TESTS = 64;
 export declare const MAX_CODING_TEST_COMMAND_BYTES: number;
 export declare const MAX_TAG_BYTES = 32;
+/**
+ * A worker's output-schema failure, reduced to where and how it failed, never
+ * what the model wrote: `<path>:<zod issue code>`, where the path is dot-joined
+ * schema keys and array indices (`$` for the root). Unrecognized keys the model
+ * invented are carried only as the `unrecognized_keys` code, never by name.
+ */
+export declare const MAX_CODING_OUTPUT_ISSUES = 8;
+export declare const SAFE_CODING_OUTPUT_ISSUE: RegExp;
 export declare function normalizeGitHubRepository(value: string): string;
 export declare function normalizeGitRef(value: string): string;
 export declare const CodingBaseRefSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
 export declare const CodingTaskOverrideSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+/**
+ * A coding worker receives only its task text, so a coding agent's own
+ * instructions (its systemPrompt) travel inside that text, ahead of the
+ * request. Blank instructions leave the task unchanged. The combination must
+ * still fit MAX_CODING_TASK_BYTES; exceeding it is an error naming both parts
+ * rather than a silent truncation of either.
+ */
+export declare function composeCodingTask(instructions: string | null | undefined, task: string): string;
+/**
+ * The tag only labels a pull request title, so a model's malformed tag must not
+ * sink an otherwise finished run. A tag that already passes is kept as-is; any
+ * other string becomes a lowercase slug (runs of disallowed characters to "-",
+ * no leading or trailing punctuation, at most MAX_TAG_BYTES), and one with
+ * nothing usable left, or a non-string, becomes null. GitHub finalization still
+ * re-validates whatever survives.
+ */
+export declare function normalizeCodingTag(value: unknown): string | null | undefined;
 export declare const CodingTaskInputSchema: z.ZodEffects<z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     runId: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
@@ -103,7 +128,7 @@ export declare const CodingAgentOutputSchema: z.ZodEffects<z.ZodObject<{
         command: string;
         outcome: "passed" | "failed" | "skipped";
     }>, "many">;
-    tag: z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | undefined, string | null | undefined>;
+    tag: z.ZodEffects<z.ZodEffects<z.ZodOptional<z.ZodNullable<z.ZodString>>, string | undefined, string | null | undefined>, string | undefined, unknown>;
 }, "strict", z.ZodTypeAny, {
     outcome: "changes_ready" | "no_changes" | "budget_exhausted";
     schemaVersion: 1;
@@ -123,7 +148,7 @@ export declare const CodingAgentOutputSchema: z.ZodEffects<z.ZodObject<{
         command: string;
         outcome: "passed" | "failed" | "skipped";
     }[];
-    tag?: string | null | undefined;
+    tag?: unknown;
 }>, {
     tag?: string | undefined;
     summary: string;
@@ -143,7 +168,7 @@ export declare const CodingAgentOutputSchema: z.ZodEffects<z.ZodObject<{
         command: string;
         outcome: "passed" | "failed" | "skipped";
     }[];
-    tag?: string | null | undefined;
+    tag?: unknown;
 }>;
 export declare const CodingRunResultSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;