@wardby/cli 0.2.0 → 0.3.0

package/dist/quickstart/migrate.js

@@ -0,0 +1,125 @@
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+// The installed npm package does not carry the Prisma CLI (a devDependency:
+// its tree pulled advisories into every consumer install), so quickstart and
+// doctor first look for a `prisma` executable on PATH and use it only if it
+// reports exactly this version; anything else -- wrong version, not on PATH,
+// a spawn error, a non-zero exit, or a timeout -- falls back to running the
+// pinned version through npx, with a config file shipped in the package.
+// Keep this equal to package.json's devDependencies.prisma (migrate.test.ts
+// enforces it).
+//
+// Not supported on Windows: npx is `npx.cmd` there (and a local install would
+// be `prisma.cmd`), which spawnSync can only run through a shell, and
+// quickstart has no win32 handling anywhere else (Docker Compose paths,
+// POSIX file modes) either.
+export const PRISMA_CLI_VERSION = "7.10.0";
+export const FETCH_NOTICE = `Fetching the Prisma CLI (prisma@${PRISMA_CLI_VERSION})…`;
+export const REGISTRY_FAILURE_MESSAGE = `Could not download the Prisma CLI (prisma@${PRISMA_CLI_VERSION}) from the npm registry. ` +
+    "quickstart and doctor fetch it on demand. Check your internet connection or npm registry settings " +
+    "(.npmrc, proxy), then retry. You can also install it yourself " +
+    `(\`npm i -g prisma@${PRISMA_CLI_VERSION}\`) and rerun quickstart -- doctor benefits too.`;
+export const migrateConfigFile = fileURLToPath(new URL("../../prisma/migrate.config.mjs", import.meta.url));
+// A short timeout so a wedged or misbehaving local binary can't stall
+// quickstart/doctor -- any hang past this falls back to npx.
+const LOCAL_PRISMA_PROBE_TIMEOUT_MS = 5000;
+// `prisma --version` prints a fixed-label, padded-column report, e.g.:
+//   prisma               : 7.10.0
+//   @prisma/client       : 7.10.0
+//   Operating System     : darwin
+//   ...
+// Several other lines carry their own version-shaped numbers (Node.js,
+// TypeScript, the schema engine hash), so key off the "prisma" label
+// specifically -- not the first x.y.z token anywhere in the output.
+const LOCAL_VERSION_LINE = /^prisma\s*:\s*(\S+)$/m;
+export function parseLocalPrismaVersion(stdout) {
+    return LOCAL_VERSION_LINE.exec(stdout)?.[1];
+}
+// Runs a local `prisma --version` under the given env's PATH and returns the
+// version it reports, or undefined for anything that isn't a clean match:
+// not on PATH, a spawn error, a non-zero exit, a timeout, or unparseable
+// output. Never throws.
+export function probeLocalPrismaVersion(env) {
+    const result = spawnSync("prisma", ["--version"], {
+        env,
+        encoding: "utf8",
+        stdio: "pipe",
+        timeout: LOCAL_PRISMA_PROBE_TIMEOUT_MS,
+    });
+    if (result.error || result.status !== 0)
+        return undefined;
+    return parseLocalPrismaVersion(result.stdout ?? "");
+}
+// DATABASE_URL travels in the child's environment only -- never argv, where
+// any local user could read it from the process table. `probe` is injectable
+// so tests never depend on the developer's real PATH.
+export function prismaMigrateInvocation(subcommand, env, probe = probeLocalPrismaVersion) {
+    const childEnv = {
+        ...env,
+        PRISMA_HIDE_UPDATE_MESSAGE: "1",
+        npm_config_update_notifier: "false",
+        npm_config_fund: "false",
+    };
+    if (probe(childEnv) === PRISMA_CLI_VERSION) {
+        return {
+            command: "prisma",
+            args: ["migrate", subcommand, "--config", migrateConfigFile],
+            env: childEnv,
+            local: true,
+        };
+    }
+    return {
+        command: "npx",
+        args: ["--yes", `prisma@${PRISMA_CLI_VERSION}`, "migrate", subcommand, "--config", migrateConfigFile],
+        env: childEnv,
+        local: false,
+    };
+}
+// npm's own error lines when it cannot fetch a package (npm 7+ prints
+// "npm error", older "npm ERR!"): network failures and registry HTTP / version
+// errors. A failed migration is printed by Prisma itself and never carries
+// these -- in particular a database ECONNREFUSED is Prisma's P1001, not an
+// "npm error code" line.
+const REGISTRY_ERROR = /^npm (?:error|ERR!) (?:code|errno) (?:ENOTFOUND|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN|ETARGET|E[45]\d\d)\b|^npm (?:error|ERR!) network /m;
+// `local` marks that `result`/`spawnError` came from the locally installed
+// binary rather than npx: nothing was fetched, so neither an npm-shaped
+// error line nor a spawn error is a registry failure there -- a spawn error
+// still gets a clear message (below), just not that one.
+export function classifyMigrateResult(result, spawnError, local = false) {
+    if (spawnError) {
+        if (local)
+            return { ...result, status: 1, stderr: spawnError.message };
+        return { ...result, status: 1, stderr: spawnError.message, registryFailure: true };
+    }
+    if (!local && result.status !== 0 && REGISTRY_ERROR.test(result.stderr))
+        return { ...result, registryFailure: true };
+    return result;
+}
+// The one-line reason for a failed run: the registry message, or Prisma's own
+// first error line (URLs masked, though Prisma prints host and database only).
+export function migrateFailureReason(result) {
+    if (result.registryFailure)
+        return REGISTRY_FAILURE_MESSAGE;
+    const lines = `${result.stderr}\n${result.stdout}`
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean);
+    // A line that starts with "Error", or that carries a Prisma error code anywhere.
+    const line = lines.find((candidate) => candidate.startsWith("Error") || /\bP\d{4}\b/.test(candidate)) ?? lines[0] ?? "no output";
+    return line.replace(/postgres(ql)?:\/\/[^\s`'"]+/gi, "<database url>");
+}
+// Runs an already-resolved invocation (from `prismaMigrateInvocation`). Split
+// out so callers can decide whether to print `FETCH_NOTICE` -- which only
+// applies to the npx path -- before running it.
+export function runPrismaMigrateInvocation(invocation, cwd) {
+    const result = spawnSync(invocation.command, invocation.args, {
+        cwd,
+        env: invocation.env,
+        encoding: "utf8",
+        stdio: "pipe",
+    });
+    return classifyMigrateResult({ status: result.status ?? 1, stdout: result.stdout ?? "", stderr: result.stderr ?? "" }, result.error, invocation.local);
+}
+export function runPrismaMigrate(subcommand, env, cwd, probe) {
+    return runPrismaMigrateInvocation(prismaMigrateInvocation(subcommand, env, probe), cwd);
+}

package/dist/sandbox/fetch-policy.d.ts

@@ -4,15 +4,33 @@ export type ResolvedAddress = {
 };
 export type Resolver = (hostname: string) => Promise<ResolvedAddress[]>;
 export interface FetchPolicyOptions {
+    /**
+     * Egress allowlist, enforced only with `restrictToAllowedHosts`. It can only
+     * NARROW where fetch may go: a listed host must still resolve exclusively to
+     * global addresses. Tool-controlled lists belong here.
+     */
     allowedHosts?: string[];
-    allowPrivateHosts?: boolean;
-    resolve?: Resolver;
     restrictToAllowedHosts?: boolean;
+    /**
+     * Hosts that may resolve to a non-global (private/loopback/link-local)
+     * address. Operator-controlled ONLY (WARDBY_FETCH_ALLOWED_HOSTS) — never
+     * populate it from a tool's or caller's own capability list. Cloud metadata
+     * endpoints stay blocked even when listed here.
+     */
+    privateHostAllowlist?: string[];
+    resolve?: Resolver;
 }
 export declare class FetchPolicyError extends Error {
     constructor();
 }
 export declare function isGlobalAddress(address: string): boolean;
+/**
+ * True for a cloud metadata address, including IPv6 encodings of the IPv4
+ * ones: IPv4-mapped/-compatible (::ffff:0:0/96, ::/96), NAT64 well-known
+ * (64:ff9b::/96), RFC 8215 local-use NAT64 (64:ff9b:1::/48, /96 and RFC 6052
+ * /48 layouts) and 6to4 (2002::/16). A zone id is ignored for the comparison.
+ */
+export declare function isCloudMetadataAddress(address: string): boolean;
 export declare function normalizeHost(host: string): string;
 export declare function parseAllowedHosts(value: string | undefined): string[];
 export declare function resolveDestination(urlString: string, options?: FetchPolicyOptions): Promise<{

package/dist/sandbox/fetch-policy.js

@@ -33,6 +33,9 @@ function v6(ip) {
     return groups.reduce((n, g) => (n << 16n) + BigInt("0x" + g), 0n);
 }
 export function isGlobalAddress(address) {
+    // Zone-scoped (fe80::1%eth0) answers are link-local by nature; never global.
+    if (address.includes("%"))
+        return false;
     if (isIP(address) === 4)
         return !blockedV4.some(([net, prefix]) => v4(address) >>> (32 - prefix) === v4(net) >>> (32 - prefix));
     if (isIP(address) !== 6)
@@ -51,9 +54,57 @@ export function isGlobalAddress(address) {
             return n >> shift === v6(net) >> shift;
         }));
 }
+/**
+ * Cloud instance-metadata endpoints: GCP/AWS/Azure IMDS, GKE metadata proxy,
+ * ECS task credentials, EKS Pod Identity, Alibaba Cloud; plus the AWS, EKS and
+ * GCE IPv6 addresses.
+ */
+const METADATA_V4 = new Set([
+    "169.254.169.254",
+    "169.254.169.252",
+    "169.254.170.2",
+    "169.254.170.23",
+    "100.100.100.200",
+]);
+const METADATA_V6 = new Set(["fd00:ec2::254", "fd00:ec2::23", "fd20:ce::254"].map(v6));
+const METADATA_HOSTNAMES = new Set(["metadata.google.internal", "metadata"]);
+const NAT64_WELL_KNOWN = v6("64:ff9b::") >> 32n;
+const NAT64_LOCAL_USE = v6("64:ff9b:1::") >> 80n;
+const SIX_TO_FOUR = 0x2002n;
+function v4FromBits(bits) {
+    const n = Number(bits & 0xffffffffn);
+    return [24, 16, 8, 0].map((shift) => (n >>> shift) & 0xff).join(".");
+}
+/**
+ * True for a cloud metadata address, including IPv6 encodings of the IPv4
+ * ones: IPv4-mapped/-compatible (::ffff:0:0/96, ::/96), NAT64 well-known
+ * (64:ff9b::/96), RFC 8215 local-use NAT64 (64:ff9b:1::/48, /96 and RFC 6052
+ * /48 layouts) and 6to4 (2002::/16). A zone id is ignored for the comparison.
+ */
+export function isCloudMetadataAddress(address) {
+    const bare = address.split("%")[0];
+    if (isIP(bare) === 4)
+        return METADATA_V4.has(bare);
+    if (isIP(bare) !== 6)
+        return false;
+    const n = v6(new URL("http://[" + bare + "]").hostname.slice(1, -1));
+    if (METADATA_V6.has(n))
+        return true;
+    const embedded = [];
+    const high96 = n >> 32n;
+    if (high96 === 0n || high96 === 0xffffn || high96 === NAT64_WELL_KNOWN)
+        embedded.push(n);
+    if (n >> 80n === NAT64_LOCAL_USE)
+        embedded.push(n, (((n >> 64n) & 0xffffn) << 16n) | ((n >> 40n) & 0xffffn));
+    if (n >> 112n === SIX_TO_FOUR)
+        embedded.push(n >> 80n);
+    return embedded.some((bits) => METADATA_V4.has(v4FromBits(bits)));
+}
 export function normalizeHost(host) {
     if (!host || /[\s*/@?#\\]/.test(host))
         throw new FetchPolicyError();
+    if (host.startsWith("[") !== host.endsWith("]"))
+        throw new FetchPolicyError();
     const value = host.startsWith("[") ? host.slice(1, -1) : host;
     if (isIP(value))
         return new URL(isIP(value) === 6 ? "http://[" + value + "]" : "http://" + value).hostname
@@ -61,7 +112,10 @@ export function normalizeHost(host) {
             .toLowerCase();
     if (host.includes(":"))
         throw new FetchPolicyError();
-    return new URL("http://" + host).hostname.toLowerCase().replace(/\.$/, "");
+    const name = new URL("http://" + host).hostname.toLowerCase().replace(/\.+$/, "");
+    if (!name)
+        throw new FetchPolicyError();
+    return name;
 }
 export function parseAllowedHosts(value) {
     return value === undefined || value === "" ? [] : value.split(",").map((host) => normalizeHost(host.trim()));
@@ -77,17 +131,24 @@ export async function resolveDestination(urlString, options = {}) {
     if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || urlString.length > 8192)
         throw new FetchPolicyError();
     const hostname = normalizeHost(url.hostname);
+    if (METADATA_HOSTNAMES.has(hostname))
+        throw new FetchPolicyError();
     const allowed = (options.allowedHosts ?? []).map(normalizeHost).includes(hostname);
     if (options.restrictToAllowedHosts && !allowed)
         throw new FetchPolicyError();
+    // Only the operator list may open a non-global destination; a restricted
+    // caller additionally needs the host in its own list (checked just above).
+    const privateAllowed = (options.privateHostAllowlist ?? []).map(normalizeHost).includes(hostname);
     const version = isIP(hostname);
     const addresses = version
         ? [{ address: hostname, family: version }]
         : await (options.resolve ?? ((host) => lookup(host, { all: true })))(hostname);
     if (!addresses.length ||
-        addresses.some((a) => !isIP(a.address) ||
+        addresses.some((a) => a.address.includes("%") ||
+            !isIP(a.address) ||
             isIP(a.address) !== a.family ||
-            (!isGlobalAddress(a.address) && !(allowed && options.allowPrivateHosts !== false))))
+            isCloudMetadataAddress(a.address) ||
+            (!isGlobalAddress(a.address) && !privateAllowed)))
         throw new FetchPolicyError();
     return { url, hostname, address: addresses[0].address, family: addresses[0].family };
 }

package/dist/sandbox/host-functions.d.ts

@@ -8,8 +8,16 @@ import type { QuickJSContext, QuickJSRuntime } from "quickjs-emscripten";
 import type { Datastore } from "../providers/datastore/types.js";
 import type { SecretsAccessor } from "../core/secrets.js";
 import type { SharedDatastoreAccessor } from "../core/datastores.js";
+import { type FetchPolicyOptions } from "./fetch-policy.js";
 import { type Logger } from "../core/logger.js";
 import { type ParserWorkerPool } from "./parser-worker/pool.js";
+/**
+ * Fetch policy for one tool invocation. The tool's own host list only narrows
+ * egress; private destinations open solely via the operator's
+ * WARDBY_FETCH_ALLOWED_HOSTS (and, for a non-wildcard tool, only when the tool
+ * also lists the host). Cloud metadata stays blocked either way (fetch-policy.ts).
+ */
+export declare function sandboxFetchPolicy(toolHosts: readonly string[], operatorHosts?: readonly string[]): FetchPolicyOptions;
 export interface HostFunctionOptions {
     signal?: AbortSignal;
     agentId: string;
@@ -23,7 +31,7 @@ export interface HostFunctionOptions {
     logger?: Logger;
     /** Overrides the shared default parser-worker pool — mainly for tests. */
     parserPool?: ParserWorkerPool;
-    /** Hosts this specific tool attachment may fetch. Omitted/empty = no outbound fetch at all; a literal "*" element lifts the restriction (existing SSRF protection against private/link-local addresses still applies). */
+    /** Hosts this specific tool attachment may fetch. Omitted/empty = no outbound fetch at all; a literal "*" element lifts the restriction. Either way this list only narrows egress: private/link-local destinations need the operator's WARDBY_FETCH_ALLOWED_HOSTS, and cloud metadata is always blocked. */
     allowedFetchHosts?: string[];
 }
 export declare function installHostFunctions(context: QuickJSContext, runtime: QuickJSRuntime, options: HostFunctionOptions): void;

package/dist/sandbox/host-functions.js

@@ -19,6 +19,17 @@ import { redactPii } from "./pii-redaction.js";
 const MIN_REDACTABLE_SECRET_LENGTH = 6;
 const FETCH_ALLOWED_HOSTS = parseAllowedHosts(process.env.WARDBY_FETCH_ALLOWED_HOSTS);
 let sharedParserPool;
+/**
+ * Fetch policy for one tool invocation. The tool's own host list only narrows
+ * egress; private destinations open solely via the operator's
+ * WARDBY_FETCH_ALLOWED_HOSTS (and, for a non-wildcard tool, only when the tool
+ * also lists the host). Cloud metadata stays blocked either way (fetch-policy.ts).
+ */
+export function sandboxFetchPolicy(toolHosts, operatorHosts = FETCH_ALLOWED_HOSTS) {
+    if (toolHosts.includes(FETCH_WILDCARD))
+        return { privateHostAllowlist: [...operatorHosts] };
+    return { allowedHosts: [...toolHosts], restrictToAllowedHosts: true, privateHostAllowlist: [...operatorHosts] };
+}
 function args(argsJson) {
     return JSON.parse(argsJson);
 }
@@ -74,11 +85,7 @@ export function installHostFunctions(context, runtime, options) {
     });
     register("__bridge_fetch", async (argsJson) => {
         const [url, init] = args(argsJson);
-        const hosts = allowedFetchHosts ?? [];
-        if (hosts.includes(FETCH_WILDCARD)) {
-            return safeFetch(url, init, { allowedHosts: FETCH_ALLOWED_HOSTS, signal });
-        }
-        return safeFetch(url, init, { allowedHosts: hosts, restrictToAllowedHosts: true, signal });
+        return safeFetch(url, init, { ...sandboxFetchPolicy(allowedFetchHosts ?? []), signal });
     });
     register("__bridge_datastoreGet", async (argsJson) => {
         const [key] = args(argsJson);

package/dist/serve.js

@@ -33,7 +33,7 @@ export async function startServe(options = {}) {
     const concurrency = loadCodingConcurrencyConfig();
     const providers = options.providers ?? buildMcpProviders().providers;
     const mcp = await startMcp({ providers, schedulerAttached: true });
-    const reconciler = startReconciler({ executor: providers.executor });
+    const reconciler = startReconciler({ executor: providers.executor, reviewHosts: providers.reviewHosts });
     const scheduler = startScheduler({
         executor: providers.executor,
         scope: options.scope,

package/dist/wardby-bin.js

@@ -36,6 +36,12 @@ async function main() {
         const { downCommand } = await import("./quickstart/index.js");
         await downCommand(process.argv.slice(3));
     }
+    else if (command === "help") {
+        // Help is bundled and offline: avoid loading the runtime environment,
+        // database client, or HTTP runtime just to search documentation.
+        const { helpCommand } = await import("./help/cli.js");
+        await helpCommand(process.argv.slice(3));
+    }
     else {
         await import("./cli.js");
     }

package/docs/README.md

@@ -0,0 +1,30 @@
+# Documentation
+
+- [Getting started](getting-started.md) runs Wardby locally from npm with
+  containerized PostgreSQL and a budgeted sample agent.
+- [Getting started on GKE](getting-started-gke.md) covers the supported Google
+  Cloud deployment from project setup through verification and teardown.
+- [Bring your own identity provider](getting-started-identity-provider.md)
+  configures an existing OAuth/OIDC provider to protect remote MCP access.
+- [Runtime architecture](architecture-runtime.md) explains the control-plane,
+  provider, persistence, and execution boundaries.
+- [Coding-agent setup](coding-agent-setup.md) configures the local trusted proxy
+  and isolated Codex or Claude Code workers.
+- [Coding-worker isolation](coding-worker-isolation.md) documents the threat
+  model and enforced worker boundary.
+- [Bring-your-own worker images](coding-worker-byo-images.md) explains how to
+  extend the reviewed worker image contract.
+- [Installing packages in coding runs](coding-packages.md) covers the coding
+  package registry: allowlists, safeguards, limits, and error codes.
+- [Services for coding runs](coding-services.md) gives coding runs fresh
+  PostgreSQL, Redis or MySQL instances declared in `.wardby/services.yaml`:
+  the catalog, per-agent permission, variables, and errors.
+- [Observability](observability.md) covers Prometheus metrics, Grafana, cloud
+  collectors, retention, and production ownership.
+- [Release verification](release-verification.md) lists the automated and live
+  checks for a release candidate.
+- [Security deployment](security-deployment.md) covers authentication, secrets,
+  networking, migrations, recovery, and known limitations.
+
+Historical implementation plans, dated evidence, and internal design records
+are intentionally maintained outside the public repository.

package/docs/architecture-runtime.md

@@ -0,0 +1,90 @@
+# Runtime architecture — GitHub trigger path + observability
+
+Two independent subsystems currently run side by side on the same host and
+share only Postgres and a Docker Compose network: the `wardby mcp` process
+(agents/runs/webhooks/MCP tools) and the local observability stack
+(coding-proxy metrics → Prometheus → Grafana). Neither depends on the other;
+restarting one has no effect on the other.
+
+```mermaid
+flowchart TB
+    subgraph GH["GitHub — your-org/your-repo"]
+        Issue["Issue or comment that\nmentions your agent"]
+        Action["Actions workflow that\nPOSTs the task to wardby"]
+        PRout["Draft PR opened"]
+        Issue --> Action
+    end
+
+    Action -->|"POST /webhooks/:id\nx-webhook-secret"| Tunnel
+
+    subgraph Public["Public HTTPS"]
+        Tunnel["HTTPS tunnel (e.g. ngrok)\n<your-domain> -> :8080\n(TLS terminated here)"]
+    end
+
+    Tunnel --> MCP
+
+    subgraph Host["Your machine"]
+        subgraph MCPBox["wardby mcp (Node/tsx)\nMCP_TRANSPORT=http, self-hosted auth"]
+            MCP["/webhooks/:id - secret auth\n/mcp - OAuth auth (list_agents, trigger_agent, get_run, ...)\n/.well-known/oauth-protected-resource"]
+        end
+
+        MCP -->|"creates Run, dispatches via JobLauncher"| Worker
+        MCP <-->|"reads/writes"| PG[("local-postgres-1\nAgent, Run, Webhook,\nBudgetGroup, AgentMemory, Datastore")]
+
+        subgraph Docker["Docker"]
+            Worker["ephemeral coding worker\n(Codex / Claude Code)\none per Run"]
+            Proxy["wardby-coding-proxy\ncredential injection +\ntoken/cost metering\n:9464/metrics (private net only)"]
+            Worker -->|"OpenAI/Anthropic calls,\nproxied"| Proxy
+            Proxy -->|"usage/cost ledger"| PG
+        end
+
+        Worker -->|"push branch"| PRout
+
+        Proxy -->|"scraped"| Prom["local-prometheus-1\n127.0.0.1:9090 (loopback)\n24h retention"]
+        Prom -->|"query"| Graf["local-grafana-1\n127.0.0.1:3000 (loopback)\ndashboards: wardby-coding-proxy,\nwardby-coding-budget"]
+    end
+```
+
+## Key boundaries
+
+- **Only one thing is reachable from outside this machine:** the HTTPS
+  tunnel into `wardby mcp:8080`. Postgres, coding-proxy, Prometheus, and
+  Grafana are all either fully private-network-only (`coding-proxy:9464`
+  has no `ports:` mapping at all) or explicitly loopback-bound
+  (`127.0.0.1:9090`, `127.0.0.1:3000`) — Grafana/Prometheus are not exposed
+  through the tunnel.
+- **The coding worker never sees real API credentials.** `wardby-coding-proxy`
+  sits between it and OpenAI/Anthropic, injecting credentials and metering
+  tokens/cost — this is also where `/metrics` lives.
+- **Two write paths into Postgres:** `wardby mcp` owns the agent/run/webhook
+  config tables directly; `coding-proxy` writes its own usage/cost ledger
+  directly during a run, which `wardby mcp` reconciles back into the `Run`
+  row once the container finishes (the "cap at the boundary, reconcile
+  after" pattern for opaque agent runs).
+- **`wardby mcp` restarts don't affect observability, and vice versa.** The
+  control plane and metrics stack can be deployed and restarted independently.
+
+## Where the worker actually runs
+
+The diagram above shows `JOB_LAUNCHER=docker`, which is what this host uses.
+The worker's execution backend is a seam (`WorkspaceJobLauncher`), and the
+choice does not change any boundary above — the worker still holds no
+credentials, still reaches only the proxy, and the proxy still owns the ledger.
+
+| `JOB_LAUNCHER` | Worker runs in                   | Isolation                                            |
+| -------------- | -------------------------------- | ---------------------------------------------------- |
+| `local`        | a child process on this host     | development only, no isolation                       |
+| `docker`       | a container on a per-run network | the diagram above                                    |
+| `kubernetes`   | a pod in a namespace             | per-run NetworkPolicy, attested pod, optional gVisor |
+
+Under `kubernetes` the shape is the same with different nouns: the per-run
+Docker network becomes a NetworkPolicy, the keeper and worker share a pod
+instead of a volume, and the proxy is a Service rather than a container name.
+Two things have no Docker equivalent. The pod read back from the API server is
+compared field by field against the pod wardby built, and any difference fails
+the run; and before the worker is released, the launcher proves the network
+policy is actually being enforced, because a cluster accepts a policy whether
+or not anything enforces it. See
+[coding-worker-isolation.md](coding-worker-isolation.md) for the mechanics and
+the [Kubernetes deployment guide](../deploy/kind-coding/README.md) for the local
+and GKE Autopilot overlays.

package/docs/assets/brand/wardby-icon.svg

@@ -0,0 +1,16 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-labelledby="title desc">
+  <title id="title">Wardby icon</title>
+  <desc id="desc">A friendly helmeted guardian carrying a budget shield.</desc>
+
+  <circle cx="64" cy="64" r="58" fill="#071d3b"/>
+  <path d="M20 55C20 25 40 12 64 12s44 13 44 43v35H20Z" fill="#fffaf0"/>
+  <rect x="30" y="43" width="68" height="45" rx="18" fill="#0a2850"/>
+  <path d="M27 48Q64 18 101 48" fill="none" stroke="#c8aa70" stroke-width="10" stroke-linecap="round"/>
+  <path d="M64 7V53" fill="none" stroke="#c8aa70" stroke-width="11" stroke-linecap="round"/>
+  <path d="M44 65q7 10 14 0M70 65q7 10 14 0" fill="none" stroke="#4be6b3" stroke-width="6" stroke-linecap="round"/>
+
+  <path d="M78 76 108 86v18c0 12-10 19-30 24-20-5-30-12-30-24V86Z" fill="#071d3b" stroke="#fffaf0" stroke-width="5" stroke-linejoin="round"/>
+  <g transform="translate(78 105) scale(.72) translate(-78 -105)">
+    <path d="M89 91c-3-4-7-6-12-6-7 0-12 4-12 9 0 6 5 8 13 10 8 2 13 5 13 11 0 7-5 11-13 11-7 0-13-3-17-8M78 82v46" fill="none" stroke="#4be6b3" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/>
+  </g>
+</svg>

package/docs/assets/brand/wardby-mascot.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1254 1254" role="img" aria-labelledby="title desc">
+  <title id="title">Wardby robot mascot</title>
+  <desc id="desc">A friendly helmeted robot carrying a shield marked with a dollar sign.</desc>
+  <image width="1254" height="1254" href="wardby-mascot.png" xlink:href="wardby-mascot.png" preserveAspectRatio="xMidYMid meet"/>
+</svg>

package/docs/assets/wardby-workflow.svg

@@ -0,0 +1,106 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="430" viewBox="0 0 1280 430" role="img" aria-labelledby="title desc">
+  <title id="title">Wardby agent workflow</title>
+  <desc id="desc">Five stages show a request moving from Claude or Codex through MCP, governed execution in Wardby, and an outcome controlled by review policy.</desc>
+  <defs>
+    <linearGradient id="background" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#f7faff"/>
+      <stop offset="1" stop-color="#edf8f7"/>
+    </linearGradient>
+    <linearGradient id="primary" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0f6bff"/>
+      <stop offset="1" stop-color="#0756d8"/>
+    </linearGradient>
+    <linearGradient id="success" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#2de3a6"/>
+      <stop offset="1" stop-color="#11b981"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="160%">
+      <feDropShadow dx="0" dy="5" stdDeviation="7" flood-color="#082850" flood-opacity="0.10"/>
+    </filter>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="#7c93b3"/>
+    </marker>
+  </defs>
+
+  <rect x="1" y="1" width="1278" height="428" rx="28" fill="url(#background)" stroke="#dbe7f5" stroke-width="2"/>
+
+  <text x="48" y="48" fill="#0f6bff" font-family="Arial, Helvetica, sans-serif" font-size="13" font-weight="700" letter-spacing="2">FULL AGENT LIFECYCLE</text>
+  <text x="48" y="76" fill="#082850" font-family="Arial, Helvetica, sans-serif" font-size="24" font-weight="700">From a conversation to a governed, reviewable outcome</text>
+
+  <g filter="url(#shadow)">
+    <rect x="45" y="112" width="210" height="172" rx="18" fill="#ffffff" stroke="#bcd4f7" stroke-width="2"/>
+    <circle cx="75" cy="142" r="17" fill="#e8f1ff"/>
+    <text x="75" y="148" text-anchor="middle" fill="#0f6bff" font-family="Arial, Helvetica, sans-serif" font-size="15" font-weight="700">1</text>
+    <text x="103" y="147" fill="#0f6bff" font-family="Arial, Helvetica, sans-serif" font-size="12" font-weight="700" letter-spacing="1.5">ASK</text>
+    <text x="70" y="190" fill="#082850" font-family="Arial, Helvetica, sans-serif" font-size="21" font-weight="700">Claude or Codex</text>
+    <text x="70" y="220" fill="#52677f" font-family="Arial, Helvetica, sans-serif" font-size="14">Describe the outcome</text>
+    <text x="70" y="243" fill="#52677f" font-family="Arial, Helvetica, sans-serif" font-size="14">in natural language</text>
+  </g>
+
+  <path d="M 263 198 H 284" fill="none" stroke="#7c93b3" stroke-width="3" marker-end="url(#arrow)"/>
+  <text x="273" y="184" text-anchor="middle" fill="#637b98" font-family="Arial, Helvetica, sans-serif" font-size="11" font-weight="700">MCP</text>
+
+  <g filter="url(#shadow)">
+    <rect x="295" y="112" width="210" height="172" rx="18" fill="#ffffff" stroke="#bcd4f7" stroke-width="2"/>
+    <circle cx="325" cy="142" r="17" fill="#e8f1ff"/>
+    <text x="325" y="148" text-anchor="middle" fill="#0f6bff" font-family="Arial, Helvetica, sans-serif" font-size="15" font-weight="700">2</text>
+    <text x="353" y="147" fill="#0f6bff" font-family="Arial, Helvetica, sans-serif" font-size="12" font-weight="700" letter-spacing="1.5">DEFINE</text>
+    <text x="320" y="190" fill="#082850" font-family="Arial, Helvetica, sans-serif" font-size="21" font-weight="700">Agent blueprint</text>
+    <text x="320" y="220" fill="#52677f" font-family="Arial, Helvetica, sans-serif" font-size="14">Model • tools • schedule</text>
+    <text x="320" y="243" fill="#52677f" font-family="Arial, Helvetica, sans-serif" font-size="14">Sub-agents • outcome</text>
+  </g>
+
+  <path d="M 513 198 H 534" fill="none" stroke="#7c93b3" stroke-width="3" marker-end="url(#arrow)"/>
+  <text x="523" y="184" text-anchor="middle" fill="#637b98" font-family="Arial, Helvetica, sans-serif" font-size="11" font-weight="700">POLICY</text>
+
+  <g filter="url(#shadow)">
+    <rect x="545" y="112" width="210" height="172" rx="18" fill="url(#primary)"/>
+    <circle cx="575" cy="142" r="17" fill="#ffffff" fill-opacity="0.20"/>
+    <text x="575" y="148" text-anchor="middle" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="15" font-weight="700">3</text>
+    <text x="603" y="147" fill="#dceaff" font-family="Arial, Helvetica, sans-serif" font-size="12" font-weight="700" letter-spacing="1.5">GOVERN</text>
+    <text x="570" y="190" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="21" font-weight="700">Wardby</text>
+    <text x="570" y="220" fill="#e7f0ff" font-family="Arial, Helvetica, sans-serif" font-size="14">Budget • secrets • owner</text>
+    <text x="570" y="243" fill="#e7f0ff" font-family="Arial, Helvetica, sans-serif" font-size="14">Audit • cancellation</text>
+  </g>
+
+  <path d="M 763 198 H 784" fill="none" stroke="#7c93b3" stroke-width="3" marker-end="url(#arrow)"/>
+  <text x="773" y="184" text-anchor="middle" fill="#637b98" font-family="Arial, Helvetica, sans-serif" font-size="11" font-weight="700">RUN</text>
+
+  <g filter="url(#shadow)">
+    <rect x="795" y="112" width="210" height="172" rx="18" fill="#ffffff" stroke="#bcd4f7" stroke-width="2"/>
+    <circle cx="825" cy="142" r="17" fill="#e8f1ff"/>
+    <text x="825" y="148" text-anchor="middle" fill="#0f6bff" font-family="Arial, Helvetica, sans-serif" font-size="15" font-weight="700">4</text>
+    <text x="853" y="147" fill="#0f6bff" font-family="Arial, Helvetica, sans-serif" font-size="12" font-weight="700" letter-spacing="1.5">EXECUTE</text>
+    <text x="820" y="190" fill="#082850" font-family="Arial, Helvetica, sans-serif" font-size="21" font-weight="700">Isolated workers</text>
+    <text x="820" y="220" fill="#52677f" font-family="Arial, Helvetica, sans-serif" font-size="14">Native • Codex • Claude</text>
+    <text x="820" y="243" fill="#52677f" font-family="Arial, Helvetica, sans-serif" font-size="14">Bounded tools and access</text>
+  </g>
+
+  <path d="M 1013 198 H 1034" fill="none" stroke="#7c93b3" stroke-width="3" marker-end="url(#arrow)"/>
+  <text x="1023" y="184" text-anchor="middle" fill="#637b98" font-family="Arial, Helvetica, sans-serif" font-size="11" font-weight="700">RESULT</text>
+
+  <g filter="url(#shadow)">
+    <rect x="1045" y="112" width="190" height="172" rx="18" fill="#ffffff" stroke="#22c995" stroke-width="2"/>
+    <circle cx="1075" cy="142" r="17" fill="url(#success)"/>
+    <text x="1075" y="148" text-anchor="middle" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="15" font-weight="700">5</text>
+    <text x="1103" y="147" fill="#09845f" font-family="Arial, Helvetica, sans-serif" font-size="12" font-weight="700" letter-spacing="1.5">REVIEW</text>
+    <text x="1070" y="190" fill="#082850" font-family="Arial, Helvetica, sans-serif" font-size="21" font-weight="700">Review policy</text>
+    <text x="1070" y="220" fill="#52677f" font-family="Arial, Helvetica, sans-serif" font-size="14">Agent or human review</text>
+    <text x="1070" y="243" fill="#09845f" font-family="Arial, Helvetica, sans-serif" font-size="14" font-weight="700">Authority stays explicit</text>
+  </g>
+
+  <rect x="45" y="324" width="1190" height="70" rx="16" fill="#082850"/>
+  <text x="72" y="351" fill="#70edc2" font-family="Arial, Helvetica, sans-serif" font-size="12" font-weight="700" letter-spacing="1.5">RUNS IN YOUR INFRASTRUCTURE</text>
+  <text x="72" y="378" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="17" font-weight="700">Your cloud • Your credentials • Your operating boundary</text>
+
+  <g font-family="Arial, Helvetica, sans-serif" font-size="12" font-weight="700" text-anchor="middle">
+    <rect x="605" y="343" width="140" height="32" rx="16" fill="#ffffff" fill-opacity="0.11"/>
+    <text x="675" y="364" fill="#ffffff">Budget enforced</text>
+    <rect x="757" y="343" width="168" height="32" rx="16" fill="#ffffff" fill-opacity="0.11"/>
+    <text x="841" y="364" fill="#ffffff">Credentials separated</text>
+    <rect x="937" y="343" width="135" height="32" rx="16" fill="#ffffff" fill-opacity="0.11"/>
+    <text x="1005" y="364" fill="#ffffff">Runs observable</text>
+    <rect x="1084" y="343" width="125" height="32" rx="16" fill="#ffffff" fill-opacity="0.11"/>
+    <text x="1147" y="364" fill="#ffffff">Action policy</text>
+  </g>
+</svg>