@paybond/kit 0.10.0 → 0.11.1

package/dist/cli/commands/setup.d.ts

@@ -2,7 +2,10 @@ import { commandPath, type CliContext } from "../context.js";
 import { type CommandResult } from "../types.js";
 declare function readJsonFile(filePath: string): Promise<Record<string, unknown>>;
 export declare function handleLogin(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleInitWizard(ctx: CliContext, argv: string[]): Promise<CommandResult>;
 export declare function handleInitGuardrail(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleInitAgentMiddleware(ctx: CliContext, argv: string[]): Promise<CommandResult>;
+export declare function handleInitCompletion(ctx: CliContext, argv: string[]): Promise<CommandResult>;
 export declare function handleMcpServe(ctx: CliContext, argv: string[]): Promise<CommandResult>;
 export declare function handleMcpTools(ctx: CliContext): Promise<CommandResult>;
 export declare function handleMcpInstall(ctx: CliContext, argv: string[]): Promise<CommandResult>;

package/dist/cli/commands/setup.js

@@ -4,15 +4,20 @@ import { readJsonBody } from "../automation.js";
 import { listConfigEntries, resolveConfigValue, setConfigValue, unsetConfigValue } from "../config.js";
 import { commandPath, withGateway } from "../context.js";
 import { assertApiKeyShape, resolveApiKey, resolvedDefaultsForDoctor } from "../credentials.js";
+import { runAgentMiddlewareDoctorCheck } from "../doctor-agent-middleware.js";
 import { packageVersion, runAgentMcpChecks } from "../doctor-agent.js";
+import { runCompletionCatalogDoctorChecks } from "../../doctor-completion.js";
 import { consumeBooleanFlag, consumeFlag } from "../globals.js";
 import { maskApiKey, redactConfigValue } from "../redact.js";
-import { mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, } from "../mcp-policy.js";
+import { mergeMcpToolPolicy, parseMcpToolAllowlist, parseMcpToolPolicy, resolveMcpToolPolicy, } from "../mcp-policy.js";
 import { parseMcpInstallFormat, parseMcpInstallHost, parseMcpInstallScope, planMcpInstall, } from "../mcp-install.js";
 import { verifyMcpInstallPlan } from "../mcp-verify-config.js";
 import { buildSupportDiagnostics, formatSupportDiagnosticsTable } from "../support-diagnostics.js";
 import { CliError } from "../types.js";
 import { main as runInitMain } from "../../init.js";
+import { parseCompletionInitArgs, scaffoldCompletionInit } from "../../completion-init.js";
+import { parseProjectInitArgv, runProjectInit } from "../../project-init.js";
+import { copyTemplateToDirectory, normalizeTemplateId, templateInitUsage, } from "../../template-init.js";
 import { parseArgs as parseLoginArgs, runLogin } from "../../login.js";
 import { main as runMcpServerMain } from "../../mcp-server.js";
 import { PaybondMCPServer } from "../../mcp-server.js";
@@ -89,19 +94,105 @@ export async function handleLogin(ctx, argv) {
     }
     return { data: loginResultData(result) };
 }
+export async function handleInitWizard(ctx, argv) {
+    let parsed;
+    try {
+        parsed = parseProjectInitArgv(argv);
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "usage",
+            code: "cli.usage.invalid_init",
+        });
+    }
+    if (parsed === "help") {
+        throw new CliError(templateInitUsage(), { category: "usage", code: "cli.help" });
+    }
+    try {
+        if (parsed.template) {
+            const result = await copyTemplateToDirectory({
+                cwd: ctx.cwd,
+                templateId: normalizeTemplateId(parsed.template),
+                framework: parsed.framework,
+                force: parsed.force,
+                writeStdout(line) {
+                    if (ctx.globals.format !== "json") {
+                        ctx.stdout.write(`${line}\n`);
+                    }
+                },
+            });
+            return { data: result };
+        }
+        const { template: _template, ...wizardOptions } = parsed;
+        const result = await runProjectInit({
+            cwd: ctx.cwd,
+            ...wizardOptions,
+            writeStdout(line) {
+                if (ctx.globals.format !== "json") {
+                    ctx.stdout.write(`${line}\n`);
+                }
+            },
+        });
+        return { data: result };
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "validation",
+            code: "cli.init.failed",
+        });
+    }
+}
 export async function handleInitGuardrail(ctx, argv) {
-    const code = await runInitMain(argv);
+    return handleInitScaffold(ctx, argv, "paid-tool-guard", "paybond-paid-tool-guard.ts");
+}
+export async function handleInitAgentMiddleware(ctx, argv) {
+    return handleInitScaffold(ctx, argv, "agent-middleware", "paybond-agent-middleware.ts");
+}
+async function handleInitScaffold(ctx, argv, defaultPreset, defaultOut) {
+    const code = await runInitMain(["--preset", defaultPreset, ...argv]);
     if (code !== 0) {
-        throw new CliError("init guardrail failed", { category: "validation", code: "cli.init.failed", exitCode: code });
+        throw new CliError(`init ${defaultPreset} failed`, { category: "validation", code: "cli.init.failed", exitCode: code });
     }
     const outFlag = consumeFlag(argv, "--out");
     const frameworkFlag = consumeFlag(argv, "--framework");
-    const presetFlag = consumeFlag(argv, "--preset");
     return {
         data: {
-            out: outFlag.value ?? "paybond-paid-tool-guard.ts",
-            preset: presetFlag.value ?? "paid-tool-guard",
-            framework: frameworkFlag.value ?? "provider-agnostic",
+            out: outFlag.value ?? defaultOut,
+            preset: defaultPreset,
+            framework: frameworkFlag.value ?? (defaultPreset === "agent-middleware" ? "generic" : "provider-agnostic"),
+            bytes_written: true,
+            completion_preset: "cost_and_completion",
+        },
+    };
+}
+export async function handleInitCompletion(ctx, argv) {
+    let parsed;
+    try {
+        const result = parseCompletionInitArgs(argv);
+        if (result === "help") {
+            throw new CliError("help", { category: "usage", code: "cli.help" });
+        }
+        parsed = result;
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "usage",
+            code: "cli.usage.invalid_init_completion",
+        });
+    }
+    try {
+        await scaffoldCompletionInit(parsed);
+    }
+    catch (err) {
+        throw new CliError(err instanceof Error ? err.message : String(err), {
+            category: "validation",
+            code: "cli.init.failed",
+        });
+    }
+    return {
+        data: {
+            out: parsed.out,
+            preset: parsed.preset,
             bytes_written: true,
         },
     };
@@ -158,7 +249,7 @@ export async function handleMcpInstall(ctx, argv) {
         out: outFlag.value,
         cwd: ctx.cwd,
         home: process.env.HOME ?? process.env.USERPROFILE ?? ctx.cwd,
-        toolPolicy: toolPolicy.policy ? toolPolicy : null,
+        toolPolicy: resolveMcpToolPolicy(toolPolicy),
     });
     if (plan.printed) {
         if (ctx.globals.format !== "json") {
@@ -301,7 +392,32 @@ export async function handleDoctor(ctx, argv) {
             });
             checks.push(...agentChecks);
         }
+        if (apiKey) {
+            checks.push(await runAgentMiddlewareDoctorCheck(ctx, apiKey));
+        }
+        else {
+            checks.push({
+                name: "agent_middleware_smoke",
+                ok: false,
+                message: "skipped (missing API key)",
+            });
+        }
     }
+    const completionChecks = await runCompletionCatalogDoctorChecks({
+        cwd: ctx.cwd,
+        gateway: apiKey
+            ? {
+                async getJson(path) {
+                    const result = await withGateway(ctx, async (gateway) => {
+                        const body = await gateway.getJson(path);
+                        return { data: body };
+                    });
+                    return result.data;
+                },
+            }
+            : undefined,
+    });
+    checks.push(...completionChecks);
     const summary = checks.every((check) => check.ok) ? "pass" : "fail";
     return { data: { checks, summary } };
 }

package/dist/cli/commands/workflows.js

@@ -146,23 +146,28 @@ export async function handleGuardrails(ctx, subcommand, argv) {
         if (subcommand === "bootstrap") {
             const operationFlag = consumeFlag(argv, "--operation");
             const spendFlag = consumeFlag(argv, "--requested-spend-cents");
+            const presetFlag = consumeFlag(argv, "--completion-preset");
             if (!operationFlag.value || !spendFlag.value) {
                 throw new CliError("guardrails bootstrap requires --operation and --requested-spend-cents", { category: "usage", code: "cli.usage.missing_args" });
             }
             const spendCents = parseRequiredNonNegativeInt(spendFlag.value, "--requested-spend-cents");
-            const body = await gateway.postJson("/v1/sandbox/guardrails/bootstrap", {
+            const bodyPayload = {
                 operation: operationFlag.value,
                 requested_spend_cents: spendCents,
-            });
+            };
+            if (presetFlag.value) {
+                bodyPayload.completion_preset = presetFlag.value;
+            }
+            const body = await gateway.postJson("/v1/sandbox/guardrails/bootstrap", bodyPayload);
             return {
-                data: {
+                data: redactSensitiveFields({
                     tenant_id: String(body.tenant_id ?? ""),
                     intent_id: String(body.intent_id ?? ""),
                     capability_token: String(body.capability_token ?? ""),
                     operation: String(body.operation ?? operationFlag.value),
                     requested_spend_cents: Number(body.requested_spend_cents ?? spendCents),
                     sandbox_lifecycle_status: String(body.sandbox_lifecycle_status ?? ""),
-                },
+                }),
             };
         }
         if (subcommand === "evidence") {

package/dist/cli/config.d.ts

@@ -1,4 +1,6 @@
 export type CliConfigFile = {
+    install_id?: string;
+    telemetry?: boolean;
     profiles?: Record<string, {
         env_file?: string;
         gateway?: string;

package/dist/cli/config.js

@@ -1,5 +1,6 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { redactConfigValue } from "./redact.js";
+import { validateCliGateway } from "./globals.js";
 import { CliError } from "./types.js";
 export function configFilePath() {
     const home = process.env.HOME?.trim() || process.env.USERPROFILE?.trim() || "";
@@ -40,15 +41,16 @@ export async function resolveConfigValue(key, profile) {
     return config.values?.[key];
 }
 export async function setConfigValue(key, value, profile) {
+    const storedValue = key.toLowerCase() === "gateway" ? validateCliGateway(value) : value;
     const config = await loadConfigFile();
     if (profile) {
         config.profiles ??= {};
         config.profiles[profile] ??= {};
-        config.profiles[profile][key] = value;
+        config.profiles[profile][key] = storedValue;
     }
     else {
         config.values ??= {};
-        config.values[key] = value;
+        config.values[key] = storedValue;
     }
     await saveConfigFile(config);
 }

package/dist/cli/context.js

@@ -1,7 +1,8 @@
 import { resolveApiKeyWithMeta } from "./credentials.js";
+import { requireSecureGatewayUrl } from "../gateway-url.js";
 import { CliError, exitCodeForHttpStatus, } from "./types.js";
 export function gatewayUrl(base, path) {
-    return `${base.trim().replace(/\/+$/, "")}${path.startsWith("/") ? path : `/${path}`}`;
+    return `${requireSecureGatewayUrl(base)}${path.startsWith("/") ? path : `/${path}`}`;
 }
 function parseGatewayErrorBody(body, status) {
     const nested = body.error;

package/dist/cli/credentials.js

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { resolveConfigValue } from "./config.js";
 import { CLI_WARN_ENV_FALLBACK, formatWarning } from "./automation.js";
-import { DEFAULT_ENV_FILE, DEFAULT_GATEWAY } from "./globals.js";
+import { DEFAULT_ENV_FILE, DEFAULT_GATEWAY, validateCliGateway } from "./globals.js";
 import { CliError } from "./types.js";
 function resolvePath(cwd, envFile) {
     return path.isAbsolute(envFile) ? path.resolve(envFile) : path.resolve(cwd, envFile);
@@ -68,7 +68,7 @@ export async function resolveApiKeyWithMeta(globals, cwd) {
             warnings.push(formatWarning(CLI_WARN_ENV_FALLBACK, `using profile ${globals.profile} env_file`));
         }
         if (profileGateway) {
-            gateway = profileGateway;
+            gateway = validateCliGateway(profileGateway);
             warnings.push(formatWarning(CLI_WARN_ENV_FALLBACK, `using profile ${globals.profile} gateway`));
         }
     }

package/dist/cli/doctor-agent-middleware.d.ts

@@ -0,0 +1,5 @@
+import type { CliContext } from "./context.js";
+import type { DoctorCheck } from "./doctor-agent.js";
+export declare const AGENT_MIDDLEWARE_SMOKE_NEXT = "paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json";
+/** Run sandbox middleware smoke as a doctor --agent check (uses ctx.fetch / project cwd). */
+export declare function runAgentMiddlewareDoctorCheck(ctx: CliContext, apiKey: string): Promise<DoctorCheck>;

package/dist/cli/doctor-agent-middleware.js

@@ -0,0 +1,49 @@
+import { apiKeyEnvironment } from "./agent/paybond.js";
+import { handleAgentSandboxSmoke } from "./commands/agent.js";
+import { CliError } from "./types.js";
+export const AGENT_MIDDLEWARE_SMOKE_NEXT = "paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json";
+/** Run sandbox middleware smoke as a doctor --agent check (uses ctx.fetch / project cwd). */
+export async function runAgentMiddlewareDoctorCheck(ctx, apiKey) {
+    if (!apiKey) {
+        return {
+            name: "agent_middleware_smoke",
+            ok: false,
+            message: "skipped (missing API key)",
+            details: { next_command: AGENT_MIDDLEWARE_SMOKE_NEXT },
+        };
+    }
+    if (apiKeyEnvironment(apiKey) === "live") {
+        return {
+            name: "agent_middleware_smoke",
+            ok: true,
+            message: "skipped (live API key; smoke uses sandbox guardrails bootstrap)",
+            details: { next_command: AGENT_MIDDLEWARE_SMOKE_NEXT },
+        };
+    }
+    try {
+        await handleAgentSandboxSmoke(ctx, [
+            "--operation",
+            "paid-tool",
+            "--requested-spend-cents",
+            "100",
+            "--evidence-preset",
+            "cost_and_completion",
+            "--result-body",
+            '{"status":"ok","cost_cents":100}',
+        ]);
+        return {
+            name: "agent_middleware_smoke",
+            ok: true,
+            message: "bind, authorize, execute, and auto-evidence succeeded",
+        };
+    }
+    catch (err) {
+        const message = err instanceof CliError ? err.message : err instanceof Error ? err.message : String(err);
+        return {
+            name: "agent_middleware_smoke",
+            ok: false,
+            message,
+            details: { next_command: AGENT_MIDDLEWARE_SMOKE_NEXT },
+        };
+    }
+}

package/dist/cli/globals.d.ts

@@ -3,6 +3,7 @@ export declare const DEFAULT_GATEWAY = "https://api.paybond.ai";
 export declare const DEFAULT_ENV_FILE = ".env.local";
 export declare const TENANT_OVERRIDE_FLAGS: readonly ["--tenant-id", "--tenant", "--tenant_id"];
 export declare function rejectsTenantOverrideFlag(arg: string): boolean;
+export declare function validateCliGateway(url: string): string;
 export declare function parseRequiredNonNegativeInt(raw: string, field: string): number;
 export declare function parseOptionalNonNegativeInt(raw: string | undefined, field: string): number;
 export declare function defaultGlobalOptions(): GlobalOptions;

package/dist/cli/globals.js

@@ -1,6 +1,7 @@
 import { generateRequestId } from "./request-id.js";
 import { parseColorMode, resolveColorModeFromEnv } from "./color.js";
 import { formatUnknownGlobalFlagMessage } from "./suggest.js";
+import { InsecureGatewayURLError, requireSecureGatewayUrl } from "../gateway-url.js";
 import { CliError } from "./types.js";
 export const DEFAULT_GATEWAY = "https://api.paybond.ai";
 export const DEFAULT_ENV_FILE = ".env.local";
@@ -13,6 +14,15 @@ export function rejectsTenantOverrideFlag(arg) {
     }
     return false;
 }
+export function validateCliGateway(url) {
+    try {
+        return requireSecureGatewayUrl(url);
+    }
+    catch (err) {
+        const message = err instanceof InsecureGatewayURLError ? err.message : String(err);
+        throw new CliError(message, { category: "validation", code: "cli.validation.insecure_gateway" });
+    }
+}
 export function parseRequiredNonNegativeInt(raw, field) {
     const text = raw.trim();
     if (!text) {
@@ -131,7 +141,7 @@ export function parseCliArgv(argv) {
             if (!value.trim()) {
                 throw new CliError("invalid --gateway", { category: "usage", code: "cli.usage.invalid_gateway" });
             }
-            globals.gateway = value.trim();
+            globals.gateway = validateCliGateway(value.trim());
             i += consumed;
             continue;
         }

package/dist/cli/help.d.ts

@@ -1,3 +1,3 @@
-export declare const ROOT_HELP = "Usage: paybond [--global-flags] <command> [<subcommand> ...] [args]\n\nGlobal flags:\n  --gateway <url>         Gateway base URL (default: https://api.paybond.ai)\n  --env-file <path>       Local secrets file (default: .env.local)\n  --format table|json     Human table or JSON envelope output (default: table)\n  --json <fields>         Field-selectable JSON for list/read commands (plain JSON; use --format json for envelope)\n  --jq <expr>             jq-style filter for list/read command output\n  --profile <name>        Named credential profile from the Paybond CLI config file\n  --request-id <id>       Correlation ID for Gateway calls and JSON output\n  --yes                   Skip confirmation for destructive operations\n  --no-open               Do not open a browser for device login\n  --color auto|always|never Colorize human table output and help text (default: auto)\n  --no-color              Disable color output (also honors NO_COLOR)\n\nCommands:\n  onboarding              Guided, non-destructive first-run checks\n  help                    Detailed help for a command\n  examples                Copy-paste examples from the command spec\n  completion bash|zsh|fish Shell completion scripts\n  login                   Sandbox device login\n  init guardrail          Scaffold a sandbox paid-tool guardrail integration file\n  mcp serve|install|verify-config|tools MCP server and host configuration\n  doctor                  Validate local runtime, credentials, and optional agent setup\n  version                 Print package version (use --verbose for runtime details)\n  diagnose                Emit a redacted support bundle with --redacted\n  config get|set|unset|list\n                          Manage CLI configuration values\n  whoami                  Resolve the authenticated principal and tenant realm\n  keys list|create|rotate|revoke\n                          Manage tenant service-account API keys\n  intents list|get|create|fund|evidence|settlement-confirm\n                          Harbor intent workflows\n  guardrails bootstrap|evidence\n                          Sandbox guardrail helpers\n  spend authorize         Authorize delegated spend for a tool call\n  signal reputation|portfolio|fraud\n                          Signal summaries and fraud reads\n  receipts get|verify\n                          Protocol settlement receipts\n  mandates verify|import\n                          Agent mandate verification and import\n  a2a card|contracts\n                          Agent card discovery and task contracts\n  audit exports list|get|verify|delete\n                          Compliance audit export jobs and local bundle verification\n\nGetting started:\n  Sandbox setup\n    Authenticate, validate the runtime, and confirm tenant context.\n    $ paybond login\n    $ paybond doctor --format json\n    Next: paybond whoami\n  Agent + MCP host\n    Preview MCP host config and list tools exposed to agents.\n    $ paybond mcp install --host claude --scope local\n    $ paybond mcp verify-config --host claude\n    $ paybond mcp tools\n    Next: paybond doctor --agent\n  Paid-tool guardrail\n    Scaffold a sandbox guardrail integration file for your agent runtime.\n    $ paybond init guardrail\n    $ paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100\n    Next: paybond spend authorize --help\n\nDocumentation: https://docs.paybond.ai/kit\n\nLearn more:\n  paybond help <command>     Detailed help for a command\n  paybond examples           Copy-paste command examples\n  paybond onboarding         Guided first-run checks\n  paybond completion <shell> Shell completions (bash|zsh|fish)\n\nLegacy aliases: paybond-kit-login, paybond-init, paybond-kit-init, paybond-mcp-server\n";
+export declare const ROOT_HELP = "Usage: paybond [--global-flags] <command> [<subcommand> ...] [args]\n\nGlobal flags:\n  --gateway <url>         Gateway base URL (default: https://api.paybond.ai)\n  --env-file <path>       Local secrets file (default: .env.local)\n  --format table|json     Human table or JSON envelope output (default: table)\n  --json <fields>         Field-selectable JSON for list/read commands (plain JSON; use --format json for envelope)\n  --jq <expr>             jq-style filter for list/read command output\n  --profile <name>        Named credential profile from the Paybond CLI config file\n  --request-id <id>       Correlation ID for Gateway calls and JSON output\n  --yes                   Skip confirmation for destructive operations\n  --no-open               Do not open a browser for device login\n  --color auto|always|never Colorize human table output and help text (default: auto)\n  --no-color              Disable color output (also honors NO_COLOR)\n\nCommands:\n  onboarding              Guided, non-destructive first-run checks\n  help                    Detailed help for a command\n  examples                Copy-paste examples from the command spec\n  completion bash|zsh|fish Shell completion scripts\n  login                   Sandbox device login\n  init                    Interactive first-run scaffold (solution, spend cap, framework, owned policy files)\n  init guardrail|completion|agent-middleware\n                          Scaffold sandbox guardrail, completion evidence, or agent middleware integration files\n  mcp serve|install|verify-config|tools MCP server and host configuration\n  doctor                  Validate local runtime, credentials, and optional agent setup\n  dev smoke|trace|loop|up\n                          Local sandbox developer loop: travel smoke, trace dashboard, WireMock up, and guided setup\n  version                 Print package version (use --verbose for runtime details)\n  diagnose                Emit a redacted support bundle with --redacted\n  config get|set|unset|list\n                          Manage CLI configuration values\n  whoami                  Resolve the authenticated principal and tenant realm\n  keys list|create|rotate|revoke\n                          Manage tenant service-account API keys\n  intents list|get|create|fund|evidence|settlement-confirm\n                          Harbor intent workflows\n  guardrails bootstrap|evidence\n                          Sandbox guardrail helpers\n  spend authorize         Authorize delegated spend for a tool call\n  signal reputation|portfolio|fraud\n                          Signal summaries and fraud reads\n  receipts get|verify\n                          Protocol settlement receipts\n  mandates verify|import\n                          Agent mandate verification and import\n  a2a card|contracts\n                          Agent card discovery and task contracts\n  policy init|init-org|extend|presets list|presets show|validate-tools|templates|preview|import-mcp-receipt|import-x402-receipt|validate-evidence\n                          Scaffold and validate paybond.policy.yaml (including enterprise org inheritance), browse policy presets and solutions, list completion presets, preview Harbor templates, and import receipts\n  agent run bind|status|trace|reload-policy|tool execute|validate|registry validate|sandbox smoke\n                          Agent middleware: bind runs, reload policy, execute tools, validate registry, sandbox smoke\n  audit exports list|get|verify|delete\n                          Compliance audit export jobs and local bundle verification\n\nGetting started:\n  Sandbox setup\n    Authenticate, validate the runtime, and confirm tenant context.\n    $ paybond login\n    $ paybond doctor --format json\n    Next: paybond whoami\n  Agent + MCP host\n    Preview MCP host config and list tools exposed to agents.\n    $ paybond mcp install --host claude --scope local\n    $ paybond mcp verify-config --host claude\n    $ paybond mcp tools\n    Next: paybond doctor --agent\n  Paid-tool guardrail\n    Scaffold a sandbox guardrail integration file for your agent runtime.\n    $ paybond init guardrail\n    $ paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100\n    Next: paybond spend authorize --help\n  Policy-driven agent sandbox\n    Validate and smoke-test agent middleware from a versioned paybond.policy.yaml file.\n    $ paybond policy init --out paybond.policy.yaml\n    $ paybond policy validate-tools --file paybond.policy.yaml\n    $ paybond agent sandbox smoke --policy-file paybond.policy.yaml --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' --format json\n    Next: paybond policy validate-tools --help\n  Agent middleware sandbox\n    Bind a sandbox run and execute a guarded tool with auto-evidence.\n    $ paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json\n    Next: paybond agent run bind --help\n  Completion preset\n    Scaffold catalog-aligned completion evidence for Harbor release predicates.\n    $ paybond init completion --preset api_response_ok\n    $ paybond policy templates\n    $ paybond policy preview --preset api_response_ok --evidence-file evidence.json\n    Next: paybond policy preview --help\n\nDocumentation: https://docs.paybond.ai/kit\n\nLearn more:\n  paybond help <command>     Detailed help for a command\n  paybond examples           Copy-paste command examples\n  paybond onboarding         Guided first-run checks\n  paybond completion <shell> Shell completions (bash|zsh|fish)\n\nLegacy aliases: paybond-kit-login, paybond-init, paybond-kit-init, paybond-mcp-server\n";
 export declare const COMMAND_HELP: Record<string, string>;
 export declare function helpForCommand(path: string): string;

package/dist/cli/help.js

@@ -1,17 +1,35 @@
 // Generated by kit/cli-parity/generate.mjs — do not edit by hand.
-export const ROOT_HELP = "Usage: paybond [--global-flags] <command> [<subcommand> ...] [args]\n\nGlobal flags:\n  --gateway <url>         Gateway base URL (default: https://api.paybond.ai)\n  --env-file <path>       Local secrets file (default: .env.local)\n  --format table|json     Human table or JSON envelope output (default: table)\n  --json <fields>         Field-selectable JSON for list/read commands (plain JSON; use --format json for envelope)\n  --jq <expr>             jq-style filter for list/read command output\n  --profile <name>        Named credential profile from the Paybond CLI config file\n  --request-id <id>       Correlation ID for Gateway calls and JSON output\n  --yes                   Skip confirmation for destructive operations\n  --no-open               Do not open a browser for device login\n  --color auto|always|never Colorize human table output and help text (default: auto)\n  --no-color              Disable color output (also honors NO_COLOR)\n\nCommands:\n  onboarding              Guided, non-destructive first-run checks\n  help                    Detailed help for a command\n  examples                Copy-paste examples from the command spec\n  completion bash|zsh|fish Shell completion scripts\n  login                   Sandbox device login\n  init guardrail          Scaffold a sandbox paid-tool guardrail integration file\n  mcp serve|install|verify-config|tools MCP server and host configuration\n  doctor                  Validate local runtime, credentials, and optional agent setup\n  version                 Print package version (use --verbose for runtime details)\n  diagnose                Emit a redacted support bundle with --redacted\n  config get|set|unset|list\n                          Manage CLI configuration values\n  whoami                  Resolve the authenticated principal and tenant realm\n  keys list|create|rotate|revoke\n                          Manage tenant service-account API keys\n  intents list|get|create|fund|evidence|settlement-confirm\n                          Harbor intent workflows\n  guardrails bootstrap|evidence\n                          Sandbox guardrail helpers\n  spend authorize         Authorize delegated spend for a tool call\n  signal reputation|portfolio|fraud\n                          Signal summaries and fraud reads\n  receipts get|verify\n                          Protocol settlement receipts\n  mandates verify|import\n                          Agent mandate verification and import\n  a2a card|contracts\n                          Agent card discovery and task contracts\n  audit exports list|get|verify|delete\n                          Compliance audit export jobs and local bundle verification\n\nGetting started:\n  Sandbox setup\n    Authenticate, validate the runtime, and confirm tenant context.\n    $ paybond login\n    $ paybond doctor --format json\n    Next: paybond whoami\n  Agent + MCP host\n    Preview MCP host config and list tools exposed to agents.\n    $ paybond mcp install --host claude --scope local\n    $ paybond mcp verify-config --host claude\n    $ paybond mcp tools\n    Next: paybond doctor --agent\n  Paid-tool guardrail\n    Scaffold a sandbox guardrail integration file for your agent runtime.\n    $ paybond init guardrail\n    $ paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100\n    Next: paybond spend authorize --help\n\nDocumentation: https://docs.paybond.ai/kit\n\nLearn more:\n  paybond help <command>     Detailed help for a command\n  paybond examples           Copy-paste command examples\n  paybond onboarding         Guided first-run checks\n  paybond completion <shell> Shell completions (bash|zsh|fish)\n\nLegacy aliases: paybond-kit-login, paybond-init, paybond-kit-init, paybond-mcp-server\n";
+export const ROOT_HELP = "Usage: paybond [--global-flags] <command> [<subcommand> ...] [args]\n\nGlobal flags:\n  --gateway <url>         Gateway base URL (default: https://api.paybond.ai)\n  --env-file <path>       Local secrets file (default: .env.local)\n  --format table|json     Human table or JSON envelope output (default: table)\n  --json <fields>         Field-selectable JSON for list/read commands (plain JSON; use --format json for envelope)\n  --jq <expr>             jq-style filter for list/read command output\n  --profile <name>        Named credential profile from the Paybond CLI config file\n  --request-id <id>       Correlation ID for Gateway calls and JSON output\n  --yes                   Skip confirmation for destructive operations\n  --no-open               Do not open a browser for device login\n  --color auto|always|never Colorize human table output and help text (default: auto)\n  --no-color              Disable color output (also honors NO_COLOR)\n\nCommands:\n  onboarding              Guided, non-destructive first-run checks\n  help                    Detailed help for a command\n  examples                Copy-paste examples from the command spec\n  completion bash|zsh|fish Shell completion scripts\n  login                   Sandbox device login\n  init                    Interactive first-run scaffold (solution, spend cap, framework, owned policy files)\n  init guardrail|completion|agent-middleware\n                          Scaffold sandbox guardrail, completion evidence, or agent middleware integration files\n  mcp serve|install|verify-config|tools MCP server and host configuration\n  doctor                  Validate local runtime, credentials, and optional agent setup\n  dev smoke|trace|loop|up\n                          Local sandbox developer loop: travel smoke, trace dashboard, WireMock up, and guided setup\n  version                 Print package version (use --verbose for runtime details)\n  diagnose                Emit a redacted support bundle with --redacted\n  config get|set|unset|list\n                          Manage CLI configuration values\n  whoami                  Resolve the authenticated principal and tenant realm\n  keys list|create|rotate|revoke\n                          Manage tenant service-account API keys\n  intents list|get|create|fund|evidence|settlement-confirm\n                          Harbor intent workflows\n  guardrails bootstrap|evidence\n                          Sandbox guardrail helpers\n  spend authorize         Authorize delegated spend for a tool call\n  signal reputation|portfolio|fraud\n                          Signal summaries and fraud reads\n  receipts get|verify\n                          Protocol settlement receipts\n  mandates verify|import\n                          Agent mandate verification and import\n  a2a card|contracts\n                          Agent card discovery and task contracts\n  policy init|init-org|extend|presets list|presets show|validate-tools|templates|preview|import-mcp-receipt|import-x402-receipt|validate-evidence\n                          Scaffold and validate paybond.policy.yaml (including enterprise org inheritance), browse policy presets and solutions, list completion presets, preview Harbor templates, and import receipts\n  agent run bind|status|trace|reload-policy|tool execute|validate|registry validate|sandbox smoke\n                          Agent middleware: bind runs, reload policy, execute tools, validate registry, sandbox smoke\n  audit exports list|get|verify|delete\n                          Compliance audit export jobs and local bundle verification\n\nGetting started:\n  Sandbox setup\n    Authenticate, validate the runtime, and confirm tenant context.\n    $ paybond login\n    $ paybond doctor --format json\n    Next: paybond whoami\n  Agent + MCP host\n    Preview MCP host config and list tools exposed to agents.\n    $ paybond mcp install --host claude --scope local\n    $ paybond mcp verify-config --host claude\n    $ paybond mcp tools\n    Next: paybond doctor --agent\n  Paid-tool guardrail\n    Scaffold a sandbox guardrail integration file for your agent runtime.\n    $ paybond init guardrail\n    $ paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100\n    Next: paybond spend authorize --help\n  Policy-driven agent sandbox\n    Validate and smoke-test agent middleware from a versioned paybond.policy.yaml file.\n    $ paybond policy init --out paybond.policy.yaml\n    $ paybond policy validate-tools --file paybond.policy.yaml\n    $ paybond agent sandbox smoke --policy-file paybond.policy.yaml --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' --format json\n    Next: paybond policy validate-tools --help\n  Agent middleware sandbox\n    Bind a sandbox run and execute a guarded tool with auto-evidence.\n    $ paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json\n    Next: paybond agent run bind --help\n  Completion preset\n    Scaffold catalog-aligned completion evidence for Harbor release predicates.\n    $ paybond init completion --preset api_response_ok\n    $ paybond policy templates\n    $ paybond policy preview --preset api_response_ok --evidence-file evidence.json\n    Next: paybond policy preview --help\n\nDocumentation: https://docs.paybond.ai/kit\n\nLearn more:\n  paybond help <command>     Detailed help for a command\n  paybond examples           Copy-paste command examples\n  paybond onboarding         Guided first-run checks\n  paybond completion <shell> Shell completions (bash|zsh|fish)\n\nLegacy aliases: paybond-kit-login, paybond-init, paybond-kit-init, paybond-mcp-server\n";
 export const COMMAND_HELP = {
     "onboarding": "Usage: paybond onboarding [--host claude|codex|openai|generic]\n\nRuns a guided, non-destructive first-run workflow: runtime check, login status, guardrail file status, MCP config preview, and doctor.\n\nExamples:\n  $ paybond onboarding\n  $ paybond onboarding --host claude --format json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond login",
     "help": "Usage: paybond help [<command> [<subcommand> ...]]\n\nShows detailed help for a command path. Without arguments, prints root help.\n\nExamples:\n  $ paybond help\n  $ paybond help login\n  $ paybond help mcp install",
     "examples": "Usage: paybond examples [<command> [<subcommand> ...]]\n\nLists copy-paste examples from the command spec. Filter with an optional command path.\n\nExamples:\n  $ paybond examples\n  $ paybond examples doctor",
     "completion": "Usage: paybond completion bash|zsh|fish\n\nPrints a shell completion script generated from the command spec. Pipe to your shell config.\n\nExamples:\n  $ paybond completion bash >> ~/.bashrc\n  $ paybond completion zsh >> ~/.zshrc\n  $ paybond completion fish | source",
     "login": "Usage: paybond login [--env sandbox] [--env-file .env.local] [--gateway <url>] [--no-open] [--force]\n\nStarts sandbox device login and writes PAYBOND_API_KEY to the env file.\n\nExamples:\n  $ paybond login\n  $ paybond login --no-open --format json\n\nDocs: https://docs.paybond.ai/kit/authentication\n\nNext: paybond doctor",
-    "init guardrail": "Usage: paybond init guardrail [--preset paid-tool-guard] [--framework <name>] [--out <path>] [--force]\n\nScaffolds a sandbox paid-tool guardrail integration file.\n\nExamples:\n  $ paybond init guardrail\n  $ paybond init guardrail --framework openai --out guard.ts\n\nDocs: https://docs.paybond.ai/kit/index\n\nNext: paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100",
+    "init": "Usage: paybond init [--solution shopping|travel|saas|mcp-server|aws] [--max-spend-usd <n>] [--framework openai|langgraph|mcp|generic] [--language typescript|python] [--non-interactive] [--force]\n\nInteractive first-run scaffold: solution bundle policy, client bootstrap, framework instrument stub, .env.example, and npm smoke script.\n\nExamples:\n  $ paybond init\n  $ paybond init --solution travel --max-spend-usd 500 --framework langgraph --non-interactive\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond login",
+    "init guardrail": "Usage: paybond init guardrail [--preset paid-tool-guard] [--framework <name>] [--out <path>] [--force]\n\nScaffolds a sandbox paid-tool guardrail integration file aligned with the cost_and_completion catalog archetype.\n\nExamples:\n  $ paybond init guardrail\n  $ paybond init guardrail --framework openai --out guard.ts\n\nDocs: https://docs.paybond.ai/kit/index\n\nNext: paybond guardrails bootstrap --operation paid-tool --requested-spend-cents 100",
+    "init completion": "Usage: paybond init completion --preset <archetype> [--out <path>] [--force]\n\nScaffolds a completion evidence helper from the shared preset catalog (evidence_schema, buildCompletionEvidence, policy_binding stub).\n\nExamples:\n  $ paybond init completion --preset api_response_ok\n  $ paybond init completion --preset cost_and_completion --out paybond-completion.ts\n\nDocs: https://docs.paybond.ai/kit/completion-presets\n\nNext: paybond policy preview --preset api_response_ok --evidence-file evidence.json",
+    "policy templates": "Usage: paybond policy templates\n\nLists completion preset archetypes from kit/completion-presets/catalog.json.\n\nExamples:\n  $ paybond policy templates\n  $ paybond policy templates --format json\n\nDocs: https://docs.paybond.ai/kit/completion-presets\n\nNext: paybond policy preview --preset api_response_ok --evidence-file evidence.json",
+    "policy preview": "Usage: paybond policy preview --template <id>|--preset <archetype> [--parameters-file <path>] --evidence-file <path> [--schema-file <path>] [--amount-cents <n>]\n\nMaterializes a Harbor managed template and evaluates sample evidence (preview + test) against the gateway.\n\nExamples:\n  $ paybond policy preview --preset api_response_ok --evidence-file evidence.json\n  $ paybond policy preview --template api_response_v1 --parameters-file parameters.json --evidence-file evidence.json\n\nDocs: https://docs.paybond.ai/kit/completion-presets",
+    "policy import-mcp-receipt": "Usage: paybond policy import-mcp-receipt --decision-file <path> --outcome-file <path> [--write-evidence-file <path>]\n\nVerifies Ed25519 signatures on paired SEP-2828 MCP decision and outcome records, then maps them into artifact_attested evidence fields.\n\nExamples:\n  $ paybond policy import-mcp-receipt --decision-file decision.json --outcome-file outcome.json\n  $ paybond policy import-mcp-receipt --decision-file decision.json --outcome-file outcome.json --write-evidence-file evidence.json\n\nDocs: https://docs.paybond.ai/kit/completion-presets",
+    "policy import-x402-receipt": "Usage: paybond policy import-x402-receipt --receipt-file <path> [--write-evidence-file <path>]\n\nVerifies a signed x402 offer-receipt artifact (JWS or EIP-712), then maps it into artifact_attested evidence fields (BLAKE3 digest of JCS-canonical receipt bytes).\n\nExamples:\n  $ paybond policy import-x402-receipt --receipt-file receipt.json\n  $ paybond policy import-x402-receipt --receipt-file receipt.json --write-evidence-file evidence.json\n\nDocs: https://docs.paybond.ai/kit/completion-presets",
+    "policy validate-evidence": "Usage: paybond policy validate-evidence --preset <id> [--vendor-file <path>] [--canonical-file <path>] [--frozen-api-version <ver>] [--frozen-vendor-schema-digest <hex>] [--frozen-canonical-schema-digest <hex>]\n\nPre-validates vendor and canonical completion evidence against catalog JSON Schemas and preset forbidden_evidence_fields (signal-only; Harbor remains authoritative at submit).\n\nExamples:\n  $ paybond policy validate-evidence --preset stripe_charge --vendor-file vendor.json\n  $ paybond policy validate-evidence --preset ach_travel_booking --vendor-file booking.json --frozen-api-version 2024-10-28.acacia\n\nDocs: https://docs.paybond.ai/kit/completion-presets",
+    "policy presets list": "Usage: paybond policy presets list\n\nLists bundled policy domains, guardrails, flat/composed presets, and solution manifests.\n\nExamples:\n  $ paybond policy presets list\n  $ paybond policy presets list --format json\n\nDocs: https://docs.paybond.ai/kit/agent-policy\n\nNext: paybond policy presets show travel",
+    "policy presets show": "Usage: paybond policy presets show <preset>|--preset <id> [--max-spend <usd>] [--domain <id> --guardrails <csv>]\n\nPreview composed paybond.policy.yaml for a bundled preset or custom domain + guardrails composition.\n\nExamples:\n  $ paybond policy presets show travel\n  $ paybond policy presets show --preset travel --max-spend 500\n  $ paybond policy presets show --domain travel --guardrails read-only,max-spend:500\n\nDocs: https://docs.paybond.ai/kit/agent-policy\n\nNext: paybond policy init --preset travel --out paybond.policy.yaml",
+    "policy init": "Usage: paybond policy init [--out <path>] [--preset <id>] [--domain <id> --guardrails <csv>] [--max-spend <usd>] [--operation <name>] [--evidence-preset <id>] [--force]\n\nScaffolds paybond.policy.yaml from a bundled vertical preset, composed domain + guardrails, or a single-operation starter template.\n\nExamples:\n  $ paybond policy init --preset travel --out paybond.policy.yaml\n  $ paybond policy init --preset travel --max-spend 500 --out paybond.policy.yaml\n  $ paybond policy init --domain travel --guardrails read-only,max-spend:500 --out paybond.policy.yaml\n  $ paybond policy init --out paybond.policy.yaml\n  $ paybond policy init --operation travel.book_hotel --evidence-preset cost_and_completion\n\nDocs: https://docs.paybond.ai/kit/agent-policy\n\nNext: paybond policy validate-tools --file paybond.policy.yaml",
+    "policy init-org": "Usage: paybond policy init-org --policy-id <id> [--out <path>] [--operation <name>] [--evidence-preset <id>] [--max-spend-cents <n>] [--force]\n\nScaffolds a v2 org base policy for platform operators. Publish with PUT /v1/admin/org-policies/{policy_id}?org_id=... after review.\n\nExamples:\n  $ paybond policy init-org --policy-id acme-agent-spend-v1 --out org-agent-spend-v1.yaml\n  $ paybond policy init-org --policy-id acme-agent-spend-v1 --operation travel.book_hotel --max-spend-cents 20000\n\nDocs: https://docs.paybond.ai/kit/enterprise-policy-inheritance\n\nNext: paybond policy extend --extends org_acme_corp/acme-agent-spend-v1",
+    "policy extend": "Usage: paybond policy extend --extends <org_id/org_policy_id> [--out <path>] [--name <overlay_name>] [--operation <tenant_tool>] [--evidence-preset <id>] [--base-policy <path>] [--force]\n\nScaffolds a v2 tenant overlay paybond.policy.yaml that extends a published org base policy.\n\nExamples:\n  $ paybond policy extend --extends org_acme_corp/acme-agent-spend-v1 --out paybond.policy.yaml\n  $ paybond policy extend --extends org_acme_corp/acme-agent-spend-v1 --operation acme.internal.approve_po --evidence-preset cost_and_completion\n\nDocs: https://docs.paybond.ai/kit/enterprise-policy-inheritance\n\nNext: paybond policy validate-tools --file paybond.policy.yaml --remote --resolve-inheritance",
+    "policy validate-tools": "Usage: paybond policy validate-tools --file <path> [--remote] [--local-only] [--strict] [--check-gateway] [--resolve-inheritance]\n\nValidates a paybond.policy.yaml file before deploy or agent bind. Uses Gateway POST /v1/policy/validate when logged in (--remote, or default with credentials). --resolve-inheritance merges org base server-side for tenant overlays.\n\nExamples:\n  $ paybond policy validate-tools --file paybond.policy.yaml --local-only\n  $ paybond policy validate-tools --file paybond.policy.yaml --remote --format json\n  $ paybond policy validate-tools --file paybond.policy.yaml --remote --resolve-inheritance --format json\n\nDocs: https://docs.paybond.ai/kit/agent-policy-validate",
     "mcp serve": "Usage: paybond mcp serve\n\nRuns the stdio MCP server until the host process exits. Diagnostics print to stderr; stdout is reserved for MCP JSON-RPC.\n\nExamples:\n  $ paybond mcp serve",
     "mcp install": "Usage: paybond mcp install --host claude|codex|openai|generic [--scope local|project|user] [--format json|toml] [--out <path>] [--env-file <path>] [--tool-policy readonly|spend-write|allowlist] [--tool-allowlist <names>]\n\nWrites a stdio MCP server entry that references PAYBOND_ENV_FILE (never raw API keys).\nDefault format is TOML for codex and JSON for other hosts. --scope local prints without writing.\nOptional --tool-policy controls which Paybond MCP tools the server exposes.\n\nExamples:\n  $ paybond mcp install --host claude\n  $ paybond mcp install --host generic --scope project --tool-policy readonly\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond mcp verify-config --host claude",
     "mcp verify-config": "Usage: paybond mcp verify-config --host claude|codex|openai|generic [--format json|toml] [--env-file <path>] [--config <path>]\n\nValidates a generated or on-disk MCP host config without launching the MCP server.\n\nExamples:\n  $ paybond mcp verify-config --host claude\n  $ paybond mcp verify-config --host generic --config .paybond/mcp.json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond doctor --agent",
     "mcp tools": "Usage: paybond mcp tools\n\nLists tools exposed by the local MCP server.\n\nExamples:\n  $ paybond mcp tools",
-    "doctor": "Usage: paybond doctor [--agent] [--host claude|codex|openai|generic]\n\nValidates runtime, package version, env file, key shape, principal lookup, and with --agent deep MCP checks (host config, env resolution, launch, initialize, tools/list, schema validation, stdout purity).\n\nExamples:\n  $ paybond doctor\n  $ paybond doctor --agent --format json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond mcp install --host claude --scope local",
+    "doctor": "Usage: paybond doctor [--agent] [--host claude|codex|openai|generic]\n\nValidates runtime, package version, env file, key shape, principal lookup, and with --agent deep MCP checks plus agent middleware sandbox smoke (bind, authorize, execute, auto-evidence).\n\nExamples:\n  $ paybond doctor\n  $ paybond doctor --agent --format json\n\nDocs: https://docs.paybond.ai/kit/coding-agent-setup\n\nNext: paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json",
+    "dev": "Usage: paybond dev <smoke|trace|loop|up> [args]\n\nLocal sandbox developer workflows: travel smoke with checklist output, trace dashboard, optional WireMock Gateway (`dev up`), and a guided login → policy → validate → smoke loop. Use `--offline` on smoke/loop for in-process mock capability and simulated settlement without PAYBOND_API_KEY.\n\nExamples:\n  $ paybond dev smoke --offline\n  $ paybond dev trace\n  $ paybond dev loop\n  $ paybond dev up\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond dev loop --offline",
+    "dev smoke": "Usage: paybond dev smoke [--preset travel] [--offline] [--format table|json]\n\nRuns agent sandbox smoke with travel preset defaults and records a local trace event. With `--offline`, uses an in-process mock capability and simulated settlement lifecycle (no PAYBOND_API_KEY required).\n\nExamples:\n  $ paybond dev smoke\n  $ paybond dev smoke --offline\n  $ paybond dev smoke --format json\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond dev trace",
+    "dev trace": "Usage: paybond dev trace [--port 9477]\n\nStarts a local HTTP trace dashboard on port 9477 showing recent tool authorization events from dev smoke runs.\n\nExamples:\n  $ paybond dev trace\n  $ paybond dev trace --port 9477\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent",
+    "dev loop": "Usage: paybond dev loop [--policy-file paybond.policy.yaml] [--offline] [--no-login]\n\nGuided local loop: login when needed (skipped with `--offline`), scaffold travel policy, validate tools locally, then run dev smoke. Prints a startup banner with trace and audit log paths.\n\nExamples:\n  $ paybond dev loop\n  $ paybond dev loop --offline\n  $ paybond dev loop --format json\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond dev trace",
+    "dev up": "Usage: paybond dev up [--port 18089] [--down]\n\nStarts or stops a local WireMock Gateway using bundled partner-dry-run mappings (Docker required). After `dev up`, point `--gateway` at the printed URL for HTTP-level sandbox smoke.\n\nExamples:\n  $ paybond dev up\n  $ paybond dev up --port 18089\n  $ paybond dev up --down\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent\n\nNext: paybond dev loop --gateway http://127.0.0.1:18089 --no-login",
     "version": "Usage: paybond version [--verbose]\n\nPrints the installed Kit package version. With --verbose, includes runtime, platform, config paths, gateway URL, request ID, MCP tool count, and redacted credential source.\n\nExamples:\n  $ paybond version\n  $ paybond version --verbose --format json\n\nDocs: https://docs.paybond.ai/kit/package-provenance",
     "diagnose": "Usage: paybond diagnose --redacted\n\nEmits a redacted support bundle for troubleshooting. Never prints raw API keys.\n\nExamples:\n  $ paybond diagnose --redacted\n  $ paybond diagnose --redacted --format json\n\nDocs: https://docs.paybond.ai/kit/package-provenance",
     "config get": "Usage: paybond config get <key>\n\nExamples:\n  $ paybond config get gateway",
@@ -41,6 +59,20 @@ export const COMMAND_HELP = {
     "mandates import": "Usage: paybond mandates import --body <json-file>\n\nExamples:\n  $ paybond mandates import --body mandate.json",
     "a2a card": "Usage: paybond a2a card\n\nExamples:\n  $ paybond a2a card",
     "a2a contracts": "Usage: paybond a2a contracts [--contract-id <id>]\n\nExamples:\n  $ paybond a2a contracts",
+    "init agent-middleware": "Usage: paybond init agent-middleware [--framework <name>] [--out <path>] [--force]\n\nScaffolds an agent middleware integration file (PaybondAgentRun, tool registry, interceptor). Default framework is generic (agent-agnostic).\n\nExamples:\n  $ paybond init agent-middleware\n  $ paybond init agent-middleware --framework claude-agents --out paybond-claude-agents.ts\n  $ paybond init agent-middleware --framework openai --out paybond-agent-middleware.ts\n\nDocs: https://docs.paybond.ai/kit/agent-middleware\n\nNext: paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}'",
+    "agent run bind": "Usage: paybond agent run bind [--sandbox] [--production] [--policy-file <path>] [--watch] [--operation <name> --requested-spend-cents <n>] [--completion-preset <id>] [--registry-file <path>] [--run-id <id>] [--attach-intent-id <id> --capability-token <token> --payee-did <did> --payee-signing-seed-hex <hex> --agent-recognition-key-id <id> --agent-recognition-signing-seed-hex <hex>] [--write-env]\n\nBind a run-scoped middleware context via sandbox bootstrap or attach an existing funded intent. Production attach requires payee and agent-recognition signing credentials (flags or APP_PAYEE_DID, APP_PAYEE_SEED_HEX, APP_AGENT_RECOGNITION_KEY_ID, APP_AGENT_RECOGNITION_SEED_HEX). Persists context to .paybond/runs/<run_id>.json (mode 0600). Use --watch with --policy-file to record file-watcher reload config for long-lived processes.\n\nExamples:\n  $ paybond agent run bind --policy-file paybond.policy.yaml --format json\n  $ paybond agent run bind --sandbox --operation travel.book_hotel --requested-spend-cents 20000 --completion-preset cost_and_completion --registry-file ./paybond.agent.registry.yaml --format json\n\nDocs: https://docs.paybond.ai/kit/agent-policy\n\nNext: paybond agent tool execute --help",
+    "agent run status": "Usage: paybond agent run status --run-id <id>\n\nInspect a bound run (tenant, intent, allowed tools, policy digest, reload metadata).\n\nExamples:\n  $ paybond agent run status --run-id run-123 --format json\n\nDocs: https://docs.paybond.ai/kit/agent-middleware",
+    "agent run trace": "Usage: paybond agent run trace --run-id <id>\n\nShow middleware trace events for a bound run (tool selection, spend authorization, evidence, settlement). Reads .paybond/runs/<run_id>.trace.json written during tool execute.\n\nExamples:\n  $ paybond agent run trace --run-id run-123 --format json\n  $ paybond agent run trace --run-id run-123 --format table\n\nDocs: https://docs.paybond.ai/kit/agent-middleware#trace-events-and-observability",
+    "agent run reload-policy": "Usage: paybond agent run reload-policy --run-id <id> [--policy-file <path>] [--remote] [--resolve-inheritance] [--allow-loosen]\n\nReload policy for a persisted run without re-binding the intent. Validates locally and optionally via Gateway before swapping the registry.\n\nExamples:\n  $ paybond agent run reload-policy --run-id run-123 --format json\n  $ paybond agent run reload-policy --run-id run-123 --policy-file ./paybond.policy.yaml --remote --format json\n\nDocs: https://docs.paybond.ai/kit/policy-hot-reload",
+    "agent tool execute": "Usage: paybond agent tool execute --run-id <id> --operation <name> --tool-call-id <id> [--arguments <json>] --result-body <json>|--result-file <path>\n\nRun one tool through the middleware interceptor: authorize, simulated execute, auto-evidence. CLI supplies --result-body; external processes are not invoked in v1.\n\nExamples:\n  $ paybond agent tool execute --run-id run-123 --operation travel.book_hotel --tool-call-id call-1 --arguments '{\"city\":\"Lisbon\",\"estimated_price_cents\":18700}' --result-body '{\"reservation\":{\"status\":\"confirmed\",\"price_cents\":18700}}' --format json\n\nDocs: https://docs.paybond.ai/kit/agent-middleware",
+    "agent tool validate": "Usage: paybond agent tool validate --run-id <id> --operation <name> [--requested-spend-cents <n>] [--arguments <json>]\n\nAuthorize-only dry run (no execute, no evidence). Useful for agents checking budget before side effects.\n\nExamples:\n  $ paybond agent tool validate --run-id run-123 --operation travel.book_hotel --requested-spend-cents 18700 --format json\n\nDocs: https://docs.paybond.ai/kit/agent-middleware",
+    "agent registry validate": "Usage: paybond agent registry validate --file <path>\n\nValidate a registry YAML/JSON file before bind (evidence_preset required on side-effecting tools).\n\nExamples:\n  $ paybond agent registry validate --file ./paybond.agent.registry.yaml --format json\n\nDocs: https://docs.paybond.ai/kit/agent-middleware",
+    "agent sandbox smoke": "Usage: paybond agent sandbox smoke [--production] [--preset <id>] [--policy-file <path>] [--operation <name> --requested-spend-cents <n> --evidence-preset <id>] --result-body <json>|--result-file <path>\n\nOne-shot end-to-end sandbox lifecycle: bind, tool execute, combined result. Ideal for CI and coding agents.\n\nExamples:\n  $ paybond agent sandbox smoke --preset travel --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' --format json\n  $ paybond agent sandbox smoke --policy-file paybond.policy.yaml --result-body '{\"status\":\"completed\",\"cost_cents\":18700}' --format json\n  $ paybond agent sandbox smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --result-body '{\"status\":\"ok\",\"cost_cents\":100}' --format json\n\nDocs: https://docs.paybond.ai/kit/quickstart-agent",
+    "agent demo vercel-ai smoke": "Usage: paybond agent demo vercel-ai smoke [--production] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM Vercel AI SDK sandbox demo: toolApproval, wrapped execute, and auto-evidence via MockLanguageModelV4.\n\nExamples:\n  $ paybond agent demo vercel-ai smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/vercel-ai",
+    "agent demo langgraph smoke": "Usage: paybond agent demo langgraph smoke [--production] [--runtime typescript|python] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM LangGraph sandbox demo: ToolNode interceptor, authorize, execute, and auto-evidence.\n\nExamples:\n  $ paybond agent demo langgraph smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/langgraph",
+    "agent demo generic smoke": "Usage: paybond agent demo generic smoke [--production] [--runtime typescript|python] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM agent-agnostic sandbox demo: createPaybondGenericAgentConfig, wrapped execute, and auto-evidence.\n\nExamples:\n  $ paybond agent demo generic smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/agent-agnostic",
+    "agent demo claude-agents smoke": "Usage: paybond agent demo claude-agents smoke [--production] [--runtime typescript|python] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM Claude Agent SDK sandbox demo: in-process MCP tool handlers, authorize, execute, and auto-evidence.\n\nExamples:\n  $ paybond agent demo claude-agents smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/claude-agents",
+    "agent demo openai-agents smoke": "Usage: paybond agent demo openai-agents smoke [--production] --operation <name> --requested-spend-cents <n> --evidence-preset <id>\n\nBundled no-LLM OpenAI Agents SDK sandbox demo: input guardrail pre-check, guarded invoke, and auto-evidence.\n\nExamples:\n  $ paybond agent demo openai-agents smoke --operation paid-tool --requested-spend-cents 100 --evidence-preset cost_and_completion --format json\n\nDocs: https://docs.paybond.ai/kit/openai-agents",
     "audit exports list": "Usage: paybond audit exports list\n\nExamples:\n  $ paybond audit exports list --format json",
     "audit exports get": "Usage: paybond audit exports get <job_id> [--issue-download]\n\nExamples:\n  $ paybond audit exports get job-123",
     "audit exports verify": "Usage: paybond audit exports verify <path>\n\nExamples:\n  $ paybond audit exports verify ./bundle",

package/dist/cli/mcp-install.js

@@ -1,5 +1,5 @@
 import { fileURLToPath } from "node:url";
-import { mcpToolPolicyEnv } from "./mcp-policy.js";
+import { mcpToolPolicyEnv, resolveMcpToolPolicy } from "./mcp-policy.js";
 export const MCP_INSTALL_HOSTS = ["claude", "codex", "openai", "generic"];
 export function resolvePackageLocalMcpServerCommand() {
     const mcpServerJs = fileURLToPath(new URL("../mcp-server.js", import.meta.url));
@@ -12,7 +12,7 @@ export function buildMcpServerEntry(envFile, serverCommand, toolPolicy) {
     return {
         command: serverCommand[0],
         args: serverCommand.slice(1),
-        env: { PAYBOND_ENV_FILE: envFile, ...mcpToolPolicyEnv(toolPolicy ?? { policy: null, allowlist: [] }) },
+        env: { PAYBOND_ENV_FILE: envFile, ...mcpToolPolicyEnv(resolveMcpToolPolicy(toolPolicy ?? { policy: null, allowlist: [] })) },
     };
 }
 export function serializeMcpInstallPayload(format, entry) {

package/dist/cli/mcp-policy.d.ts

@@ -1,11 +1,14 @@
 export type McpToolPolicy = "readonly" | "spend-write" | "allowlist";
 export declare const MCP_TOOL_POLICY_ENV = "PAYBOND_MCP_TOOL_POLICY";
 export declare const MCP_TOOL_ALLOWLIST_ENV = "PAYBOND_MCP_TOOL_ALLOWLIST";
+export declare const DEFAULT_MCP_TOOL_POLICY: McpToolPolicy;
 export declare const LIVE_MONEY_TOOL_NAMES: Set<string>;
 export type McpToolPolicyConfig = {
     policy: McpToolPolicy | null;
     allowlist: readonly string[];
 };
+export declare function defaultMcpToolPolicyConfig(): McpToolPolicyConfig;
+export declare function resolveMcpToolPolicy(config: McpToolPolicyConfig): McpToolPolicyConfig;
 export type McpToolAnnotations = {
     readOnlyHint?: boolean;
     destructiveHint?: boolean;