@paybond/kit 0.12.0 → 0.12.1

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                    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 and agent action receipts (--kind agent)\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 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 or Shopify setup\n  dev smoke|trace|loop|up\n                          Local sandbox developer loop: travel/shopping smoke, trace dashboard, WireMock up, and guided setup\n  shopify doctor|link|dev|webhook trigger|checkout smoke|order show|capture ready|payments doctor|payments smoke|payments session show\n                          Shopify agentic commerce orchestration: readiness, dev loop, webhook trigger, checkout smoke, and Payments app rail smoke\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 and agent action receipts (--kind agent)\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,5 +1,5 @@
 // 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                    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 and agent action receipts (--kind agent)\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 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 or Shopify setup\n  dev smoke|trace|loop|up\n                          Local sandbox developer loop: travel/shopping smoke, trace dashboard, WireMock up, and guided setup\n  shopify doctor|link|dev|webhook trigger|checkout smoke|order show|capture ready|payments doctor|payments smoke|payments session show\n                          Shopify agentic commerce orchestration: readiness, dev loop, webhook trigger, checkout smoke, and Payments app rail smoke\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 and agent action receipts (--kind agent)\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",
@@ -24,12 +24,22 @@ export const COMMAND_HELP = {
     "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 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",
+    "doctor": "Usage: paybond doctor [--agent] [--shopify] [--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. With --shopify, runs Shopify CLI readiness checks.\n\nExamples:\n  $ paybond doctor\n  $ paybond doctor --agent --format json\n  $ paybond doctor --shopify\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 loop": "Usage: paybond dev loop [--preset travel|shopping] [--shopify] [--policy-file paybond.policy.yaml] [--offline] [--no-login]\n\nGuided local loop: login when needed (skipped with `--offline`), scaffold policy from preset, validate tools locally, then run dev smoke. With `--shopify`, prints Shopify next-steps after smoke.\n\nExamples:\n  $ paybond dev loop\n  $ paybond dev loop --offline\n  $ paybond dev loop --preset shopping --shopify\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",
+    "shopify doctor": "Usage: paybond shopify doctor\n\nReadiness checklist: Shopify CLI and UCP CLI on PATH, linked shopify.app.toml, dev store env, Paybond shop link, manual capture, and shopify_authorized_order rail readiness.\n\nExamples:\n  $ paybond shopify doctor\n  $ paybond shopify doctor --format json\n\nDocs: https://docs.paybond.ai/kit/shopify-cli\n\nNext: paybond shopify link",
+    "shopify link": "Usage: paybond shopify link\n\nPrints guided setup: paybond login, Console settlement link, and the exact shopify app config link command.\n\nExamples:\n  $ paybond shopify link\n\nDocs: https://docs.paybond.ai/kit/shopify-cli\n\nNext: shopify app config link",
+    "shopify dev": "Usage: paybond shopify dev [--tunnel <url>]\n\nOrchestrated local dev instructions: paybond dev trace in one terminal, shopify app dev in another, with resolved sandbox webhook address.\n\nExamples:\n  $ paybond shopify dev\n  $ paybond shopify dev --tunnel https://example.ngrok-free.app\n\nDocs: https://docs.paybond.ai/kit/shopify-cli\n\nNext: paybond shopify checkout smoke",
+    "shopify webhook trigger": "Usage: paybond shopify webhook trigger [--topic orders/paid] [--gateway <url>] [--address <url>] [--dry-run]\n\nWraps shopify app webhook trigger with Paybond gateway webhook path pre-filled (/webhooks/sandbox/shopify).\n\nExamples:\n  $ paybond shopify webhook trigger --topic orders/paid --gateway https://api.paybond.ai\n  $ paybond shopify webhook trigger --address http://127.0.0.1:8081/webhooks/sandbox/shopify --dry-run\n\nDocs: https://docs.paybond.ai/kit/shopify-cli",
+    "shopify checkout smoke": "Usage: paybond shopify checkout smoke [--shop <domain>] [--requested-spend-cents 4500] [--offline]\n\nE2E Harbor middleware smoke with Shopify-shaped checkout result and binding guidance. Falls back to agent sandbox smoke when UCP CLI is absent.\n\nExamples:\n  $ paybond shopify checkout smoke --shop paybond-agent-commerce-dev.myshopify.com\n  $ paybond shopify checkout smoke --offline --format json\n\nDocs: https://docs.paybond.ai/kit/shopify-cli\n\nNext: paybond dev trace",
+    "shopify order show": "Usage: paybond shopify order show <id> [--shop <domain>]\n\nFetch order via Shopify UCP Order MCP and display binding metadata (dev only).\n\nExamples:\n  $ paybond shopify order show gid://shopify/Order/123 --shop paybond-agent-commerce-dev.myshopify.com\n\nDocs: https://docs.paybond.ai/kit/shopify-cli",
+    "shopify capture ready": "Usage: paybond shopify capture ready\n\nVerify merchant manual-capture setting and shopify_authorized_order rail prerequisites via settlement config.\n\nExamples:\n  $ paybond shopify capture ready\n  $ paybond shopify capture ready --format json\n\nDocs: https://docs.paybond.ai/kit/shopify-cli",
+    "shopify payments doctor": "Usage: paybond shopify payments doctor\n\nReadiness checklist for the shopify_payments_app rail: Shopify CLI, Paybond Payments app toml, dev store env, Payments app link, paymentsAppConfigure ready, mTLS ingress, and shopify_payments_app rail readiness.\n\nExamples:\n  $ paybond shopify payments doctor\n  $ paybond shopify payments doctor --format json\n\nDocs: https://docs.paybond.ai/guides/configure-shopify-settlement\n\nNext: paybond shopify payments smoke",
+    "shopify payments smoke": "Usage: paybond shopify payments smoke [--shop <domain>] [--requested-spend-cents 4500] [--offline]\n\nE2E Harbor middleware smoke with Shopify Payments app session-shaped result and dev-store next steps. Pair with `cd apps/shopify-payments && shopify app dev` for live checkout.\n\nExamples:\n  $ paybond shopify payments smoke --shop paybond-agent-commerce-dev.myshopify.com\n  $ paybond shopify payments smoke --offline --format json\n\nDocs: https://docs.paybond.ai/guides/configure-shopify-settlement\n\nNext: paybond shopify payments session show <payment_session_id>",
+    "shopify payments session show": "Usage: paybond shopify payments session show <id> [--shop <domain>]\n\nFetch a tenant-scoped Shopify Payments session row from the gateway idempotency store (requires paybond login).\n\nExamples:\n  $ paybond shopify payments session show paybond-smoke-payment-session --shop paybond-agent-commerce-dev.myshopify.com\n\nDocs: https://docs.paybond.ai/guides/configure-shopify-settlement",
     "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",

package/dist/cli/router.js

@@ -6,6 +6,7 @@ import { handleConfig, handleDoctor, handleDiagnose, handleInitCompletion, handl
 import { handlePolicyExtend, handlePolicyImportMcpReceipt, handlePolicyImportX402Receipt, handlePolicyInit, handlePolicyInitOrg, handlePolicyPresetsList, handlePolicyPresetsShow, handlePolicyPreview, handlePolicyTemplates, handlePolicyValidateEvidence, handlePolicyValidateTools, } from "./commands/policy.js";
 import { handleAgent } from "./commands/agent.js";
 import { handleDev } from "./commands/dev.js";
+import { handleShopify } from "./commands/shopify.js";
 import { handleGuardrails, handleIntents, handleKeys, handleSpendAuthorize, } from "./commands/workflows.js";
 import { failureEnvelope, prepareCommandOutput, successEnvelope, writeEnvelope, writeTableLines } from "./envelope.js";
 import { defaultGlobalOptions, parseCliArgv } from "./globals.js";
@@ -213,6 +214,13 @@ export async function runCli(argv, deps = {}) {
             canonical = "doctor";
             result = await handleDoctor(ctx, command.slice(1));
         }
+        else if (head === "shopify" && second) {
+            const isPaymentsSessionShow = second === "payments" && third === "session";
+            const fourth = isPaymentsSessionShow ? command[3] : undefined;
+            canonical = commandPath(["shopify", second, third, fourth].filter(Boolean));
+            const argvStart = isPaymentsSessionShow ? 4 : third ? 3 : 2;
+            result = await handleShopify(ctx, second, third, fourth, command.slice(argvStart));
+        }
         else if (head === "dev" && second) {
             canonical = commandPath(["dev", second]);
             result = await handleDev(ctx, second, tail);
@@ -361,7 +369,13 @@ export async function runCli(argv, deps = {}) {
                 }
             }
         }
-        else if ((canonical === "dev smoke" || canonical === "dev loop") &&
+        else if ((canonical === "dev smoke" ||
+            canonical === "dev loop" ||
+            canonical === "shopify doctor" ||
+            canonical === "shopify checkout smoke" ||
+            canonical === "shopify capture ready" ||
+            canonical === "shopify dev" ||
+            canonical === "shopify link") &&
             Array.isArray(result.data.checklist_lines)) {
             if (canonical === "dev loop" && Array.isArray(result.data.banner_lines)) {
                 writeTableLines(ctx.stdout, result.data.banner_lines);

package/dist/commerce-binding.d.ts

@@ -0,0 +1,59 @@
+export declare const PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY = "tenant_id";
+export declare const PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY = "paybond_intent_id";
+export type CommerceBinding = {
+    /**
+     * Tenant realm identifier.
+     *
+     * Must be sourced from authenticated Paybond session context — never from
+     * unauthenticated client input.
+     */
+    tenantId: string;
+    /**
+     * Harbor intent identifier (UUID).
+     *
+     * Must be sourced from authenticated Paybond session context — never from
+     * unauthenticated client input.
+     */
+    intentId: string;
+};
+export type StripeMetadata = Record<string, string>;
+export type ShopifyNoteAttribute = {
+    name: string;
+    value: string;
+};
+/**
+ * Validates and normalizes the canonical Paybond commerce binding.
+ *
+ * This helper is intentionally strict: the binding is used for tenant isolation
+ * and provider webhook preflight matching.
+ */
+export declare function normalizeCommerceBinding(binding: CommerceBinding): CommerceBinding;
+/**
+ * Encodes a canonical Paybond commerce binding into Stripe `metadata`.
+ *
+ * - Preserves unknown metadata keys.
+ * - Rejects collisions when an existing binding key disagrees.
+ */
+export declare function encodeCommerceBindingToStripeMetadata(binding: CommerceBinding, existingMetadata?: StripeMetadata): StripeMetadata;
+/**
+ * Decodes a canonical Paybond commerce binding from Stripe `metadata`.
+ *
+ * Returns `null` when binding keys are absent. Throws on empty values.
+ */
+export declare function decodeCommerceBindingFromStripeMetadata(metadata: Record<string, unknown> | null | undefined): CommerceBinding | null;
+/**
+ * Encodes a canonical Paybond commerce binding into Shopify `note_attributes`.
+ *
+ * - Preserves unknown attributes.
+ * - Removes any existing occurrences of binding keys (after verifying they match).
+ * - Appends canonical binding attributes in stable order.
+ */
+export declare function encodeCommerceBindingToShopifyNoteAttributes(binding: CommerceBinding, existingAttributes?: readonly ShopifyNoteAttribute[]): ShopifyNoteAttribute[];
+/**
+ * Decodes a canonical Paybond commerce binding from Shopify `note_attributes`.
+ *
+ * Returns `null` when binding keys are absent. Throws on:
+ * - empty binding values
+ * - multiple conflicting values for the same key
+ */
+export declare function decodeCommerceBindingFromShopifyNoteAttributes(noteAttributes: unknown): CommerceBinding | null;

package/dist/commerce-binding.js

@@ -0,0 +1,129 @@
+export const PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY = "tenant_id";
+export const PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY = "paybond_intent_id";
+function requireNonEmptyTrimmed(value, label) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new Error(`commerce-binding: ${label} is required`);
+    }
+    return trimmed;
+}
+function assertNoCollision(existingValue, nextValue, label) {
+    if (existingValue === undefined) {
+        return;
+    }
+    if (existingValue === nextValue) {
+        return;
+    }
+    throw new Error(`commerce-binding: ${label} collision (${JSON.stringify(existingValue)} != ${JSON.stringify(nextValue)})`);
+}
+/**
+ * Validates and normalizes the canonical Paybond commerce binding.
+ *
+ * This helper is intentionally strict: the binding is used for tenant isolation
+ * and provider webhook preflight matching.
+ */
+export function normalizeCommerceBinding(binding) {
+    return {
+        tenantId: requireNonEmptyTrimmed(binding.tenantId, "tenantId"),
+        intentId: requireNonEmptyTrimmed(binding.intentId, "intentId"),
+    };
+}
+/**
+ * Encodes a canonical Paybond commerce binding into Stripe `metadata`.
+ *
+ * - Preserves unknown metadata keys.
+ * - Rejects collisions when an existing binding key disagrees.
+ */
+export function encodeCommerceBindingToStripeMetadata(binding, existingMetadata) {
+    const normalized = normalizeCommerceBinding(binding);
+    const merged = { ...(existingMetadata ?? {}) };
+    assertNoCollision(merged[PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY], normalized.tenantId, PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY);
+    assertNoCollision(merged[PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY], normalized.intentId, PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY);
+    merged[PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY] = normalized.tenantId;
+    merged[PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY] = normalized.intentId;
+    return merged;
+}
+/**
+ * Decodes a canonical Paybond commerce binding from Stripe `metadata`.
+ *
+ * Returns `null` when binding keys are absent. Throws on empty values.
+ */
+export function decodeCommerceBindingFromStripeMetadata(metadata) {
+    if (!metadata) {
+        return null;
+    }
+    const rawTenantId = metadata[PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY];
+    const rawIntentId = metadata[PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY];
+    if (typeof rawTenantId !== "string" || typeof rawIntentId !== "string") {
+        return null;
+    }
+    return normalizeCommerceBinding({ tenantId: rawTenantId, intentId: rawIntentId });
+}
+/**
+ * Encodes a canonical Paybond commerce binding into Shopify `note_attributes`.
+ *
+ * - Preserves unknown attributes.
+ * - Removes any existing occurrences of binding keys (after verifying they match).
+ * - Appends canonical binding attributes in stable order.
+ */
+export function encodeCommerceBindingToShopifyNoteAttributes(binding, existingAttributes) {
+    const normalized = normalizeCommerceBinding(binding);
+    const attrs = [];
+    const input = existingAttributes ?? [];
+    for (const attr of input) {
+        if (!attr || typeof attr.name !== "string" || typeof attr.value !== "string") {
+            continue;
+        }
+        if (attr.name === PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY) {
+            assertNoCollision(attr.value, normalized.tenantId, attr.name);
+            continue;
+        }
+        if (attr.name === PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY) {
+            assertNoCollision(attr.value, normalized.intentId, attr.name);
+            continue;
+        }
+        attrs.push({ name: attr.name, value: attr.value });
+    }
+    attrs.push({ name: PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY, value: normalized.tenantId }, { name: PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY, value: normalized.intentId });
+    return attrs;
+}
+/**
+ * Decodes a canonical Paybond commerce binding from Shopify `note_attributes`.
+ *
+ * Returns `null` when binding keys are absent. Throws on:
+ * - empty binding values
+ * - multiple conflicting values for the same key
+ */
+export function decodeCommerceBindingFromShopifyNoteAttributes(noteAttributes) {
+    if (!Array.isArray(noteAttributes)) {
+        return null;
+    }
+    let tenantId;
+    let intentId;
+    for (const entry of noteAttributes) {
+        if (!entry || typeof entry !== "object") {
+            continue;
+        }
+        const name = entry.name;
+        const value = entry.value;
+        if (typeof name !== "string" || typeof value !== "string") {
+            continue;
+        }
+        if (name === PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY) {
+            if (tenantId !== undefined && tenantId !== value) {
+                throw new Error(`commerce-binding: ${name} collision (${JSON.stringify(tenantId)} != ${JSON.stringify(value)})`);
+            }
+            tenantId = value;
+        }
+        if (name === PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY) {
+            if (intentId !== undefined && intentId !== value) {
+                throw new Error(`commerce-binding: ${name} collision (${JSON.stringify(intentId)} != ${JSON.stringify(value)})`);
+            }
+            intentId = value;
+        }
+    }
+    if (tenantId === undefined || intentId === undefined) {
+        return null;
+    }
+    return normalizeCommerceBinding({ tenantId, intentId });
+}

package/dist/doctor-completion.d.ts

@@ -1,5 +1,12 @@
 /** Stripe payment-rail webhook event types that must not appear as tool-completion predicates. */
 export declare const STRIPE_FUNDING_WEBHOOK_EVENT_TYPES: readonly ["payment_intent.succeeded", "charge.succeeded"];
+/** Helper identifiers that satisfy the Stripe metadata-binding doctor check. */
+export declare const STRIPE_METADATA_HELPER_MARKERS: readonly ["buildPaybondStripeMetadata", "build_paybond_stripe_metadata"];
+/**
+ * Heuristic markers that a source file wraps Stripe payment / PaymentIntent APIs
+ * and therefore should bind Paybond metadata from an authenticated session.
+ */
+export declare const STRIPE_WRAPPING_SOURCE_MARKERS: readonly ["paymentIntents.create", "payment_intents.create", "PaymentIntent.create", "stripe.PaymentIntent", "stripe.paymentIntents", "charges.create", "Charge.create", "payments.charge_customer"];
 export type CompletionDoctorCheck = {
     name: string;
     ok: boolean;
@@ -7,6 +14,15 @@ export type CompletionDoctorCheck = {
     details?: Record<string, unknown>;
 };
 export declare function isStripeFundingWebhookEventType(eventType: unknown): boolean;
+/** True when source text appears to wrap Stripe charge / PaymentIntent APIs. */
+export declare function sourceLooksLikeStripeWrapping(body: string): boolean;
+/** True when source text references Paybond Stripe metadata helpers. */
+export declare function sourceUsesStripeMetadataHelper(body: string): boolean;
+/**
+ * Scan project sources for Stripe-wrapping tools that omit metadata helpers.
+ * Warns (ok: true) when helpers appear missing; never hard-fails.
+ */
+export declare function runStripeToolMetadataBindingDoctorCheck(cwd: string): Promise<CompletionDoctorCheck>;
 type GatewayJsonClient = {
     getJson(path: string): Promise<Record<string, unknown>>;
 };

package/dist/doctor-completion.js

@@ -1,4 +1,4 @@
-import { readdir, readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import { loadCompletionCatalog } from "./completion-catalog.js";
 import { completionPresetDeprecationWarning, isVendorPack, resolveCompletionPreset, vendorEvidenceSchema, } from "./completion-resolve.js";
@@ -7,6 +7,42 @@ export const STRIPE_FUNDING_WEBHOOK_EVENT_TYPES = [
     "payment_intent.succeeded",
     "charge.succeeded",
 ];
+/** Helper identifiers that satisfy the Stripe metadata-binding doctor check. */
+export const STRIPE_METADATA_HELPER_MARKERS = [
+    "buildPaybondStripeMetadata",
+    "build_paybond_stripe_metadata",
+];
+/**
+ * Heuristic markers that a source file wraps Stripe payment / PaymentIntent APIs
+ * and therefore should bind Paybond metadata from an authenticated session.
+ */
+export const STRIPE_WRAPPING_SOURCE_MARKERS = [
+    "paymentIntents.create",
+    "payment_intents.create",
+    "PaymentIntent.create",
+    "stripe.PaymentIntent",
+    "stripe.paymentIntents",
+    "charges.create",
+    "Charge.create",
+    "payments.charge_customer",
+];
+const SOURCE_FILE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".py"]);
+const SKIP_DIR_NAMES = new Set([
+    ".git",
+    ".hg",
+    ".svn",
+    ".paybond",
+    "node_modules",
+    "dist",
+    "build",
+    "coverage",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "target",
+    ".next",
+    ".turbo",
+]);
 function stableJson(value) {
     return JSON.stringify(value);
 }
@@ -73,6 +109,124 @@ export function isStripeFundingWebhookEventType(eventType) {
     return (typeof eventType === "string" &&
         STRIPE_FUNDING_WEBHOOK_EVENT_TYPES.includes(eventType));
 }
+/** True when source text appears to wrap Stripe charge / PaymentIntent APIs. */
+export function sourceLooksLikeStripeWrapping(body) {
+    return STRIPE_WRAPPING_SOURCE_MARKERS.some((marker) => body.includes(marker));
+}
+/** True when source text references Paybond Stripe metadata helpers. */
+export function sourceUsesStripeMetadataHelper(body) {
+    return STRIPE_METADATA_HELPER_MARKERS.some((marker) => body.includes(marker));
+}
+async function collectSourceFiles(root, maxFiles = 400) {
+    const files = [];
+    const queue = [root];
+    while (queue.length > 0 && files.length < maxFiles) {
+        const current = queue.shift();
+        if (!current) {
+            break;
+        }
+        let entries;
+        try {
+            entries = await readdir(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (files.length >= maxFiles) {
+                break;
+            }
+            if (entry.isDirectory()) {
+                if (SKIP_DIR_NAMES.has(entry.name) || entry.name.startsWith(".")) {
+                    continue;
+                }
+                queue.push(path.join(current, entry.name));
+                continue;
+            }
+            if (!entry.isFile()) {
+                continue;
+            }
+            const ext = path.extname(entry.name).toLowerCase();
+            if (!SOURCE_FILE_EXTENSIONS.has(ext)) {
+                continue;
+            }
+            files.push(path.join(current, entry.name));
+        }
+    }
+    return files;
+}
+/**
+ * Scan project sources for Stripe-wrapping tools that omit metadata helpers.
+ * Warns (ok: true) when helpers appear missing; never hard-fails.
+ */
+export async function runStripeToolMetadataBindingDoctorCheck(cwd) {
+    let rootStat;
+    try {
+        rootStat = await stat(cwd);
+    }
+    catch {
+        return {
+            name: "stripe_tool_metadata_binding",
+            ok: true,
+            message: "skipped Stripe tool metadata binding scan (cwd unreadable)",
+        };
+    }
+    if (!rootStat.isDirectory()) {
+        return {
+            name: "stripe_tool_metadata_binding",
+            ok: true,
+            message: "skipped Stripe tool metadata binding scan (cwd is not a directory)",
+        };
+    }
+    const sourceFiles = await collectSourceFiles(cwd);
+    const missingHelperFiles = [];
+    let stripeWrappingFiles = 0;
+    for (const filePath of sourceFiles) {
+        let body;
+        try {
+            body = await readFile(filePath, "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (!sourceLooksLikeStripeWrapping(body)) {
+            continue;
+        }
+        stripeWrappingFiles += 1;
+        if (!sourceUsesStripeMetadataHelper(body)) {
+            missingHelperFiles.push(path.relative(cwd, filePath) || path.basename(filePath));
+        }
+    }
+    if (stripeWrappingFiles === 0) {
+        return {
+            name: "stripe_tool_metadata_binding",
+            ok: true,
+            message: "Stripe tool metadata binding: no Stripe-wrapping sources detected (use buildPaybondStripeMetadata with tenant_id from Paybond session)",
+            details: { checked_files: sourceFiles.length, stripe_wrapping_files: 0 },
+        };
+    }
+    if (missingHelperFiles.length > 0) {
+        return {
+            name: "stripe_tool_metadata_binding",
+            ok: true,
+            message: `warn: Stripe-wrapping tool(s) may lack Paybond metadata helpers (${missingHelperFiles.slice(0, 5).join(", ")}${missingHelperFiles.length > 5 ? ", …" : ""}); use buildPaybondStripeMetadata / build_paybond_stripe_metadata with tenant_id from authenticated Paybond session credentials — never client input`,
+            details: {
+                checked_files: sourceFiles.length,
+                stripe_wrapping_files: stripeWrappingFiles,
+                missing_helper_files: missingHelperFiles,
+            },
+        };
+    }
+    return {
+        name: "stripe_tool_metadata_binding",
+        ok: true,
+        message: `Stripe tool metadata binding: ${stripeWrappingFiles} Stripe-wrapping source(s) reference Paybond metadata helpers`,
+        details: {
+            checked_files: sourceFiles.length,
+            stripe_wrapping_files: stripeWrappingFiles,
+        },
+    };
+}
 function extractTemplateParametersFromScaffold(body) {
     const tsMatch = body.match(/export const completionTemplateParameters = (\{[\s\S]*?\}) as const;/);
     if (tsMatch?.[1]) {
@@ -314,6 +468,7 @@ export async function runCompletionCatalogDoctorChecks(options) {
             message: "skipped policy head check (no gateway credentials)",
         });
         pushFundingEventMisuseCheck(checks, fundingEventWarnings, scaffoldPaths.length);
+        checks.push(await runStripeToolMetadataBindingDoctorCheck(options.cwd));
         return checks;
     }
     const archetypes = catalog.presets.filter((preset) => !isVendorPack(preset));
@@ -364,6 +519,7 @@ export async function runCompletionCatalogDoctorChecks(options) {
         });
     }
     pushFundingEventMisuseCheck(checks, fundingEventWarnings, scaffoldPaths.length);
+    checks.push(await runStripeToolMetadataBindingDoctorCheck(options.cwd));
     return checks;
 }
 function pushPackStaleCheck(checks, warnings, scaffoldCount) {

package/dist/index.d.ts

@@ -4,6 +4,7 @@
  */
 import { type BuildSignedCreateIntentParams, type BuildSignedCreateIntentWithPolicyBindingParams, type SettlementRail } from "./principal-intent.js";
 import { type SignPayeeEvidenceParams } from "./payee-evidence.js";
+import type { AgentReceiptExternalAttestationV1 } from "./agent-receipt.js";
 import { PaybondAgentRunFacade, type PaybondAgentCallable, PaybondInstrumentBuilder, PaybondInstrumentRuntime, PaybondToolRegistry, type CreateGuardedAgentInput, type CreateGuardedAgentResult, type PaybondInlinePolicy, type PaybondInstrumentAgentOptions, type PaybondInstrumentInput, type PaybondInstrumented, type PaybondToolRegistryConfig, type PaybondWrapToolsOptions } from "./agent/index.js";
 import { GatewayAgentRunTraceReporter } from "./agent/gateway-trace-reporter.js";
 import { PaybondAudit } from "./audit/index.js";
@@ -986,6 +987,10 @@ type GatewayHarborClientOptions = {
 type GatewayHarborMutationOptions = {
     idempotencyKey?: string;
     recognitionProof?: AgentRecognitionProofV1 | Record<string, unknown>;
+    /** Kit-verified external attestation digests forwarded for Gateway compose (evidence submit only). */
+    agentReceiptAttestations?: AgentReceiptExternalAttestationV1[];
+    /** Agent run id matching the attestation header for server-side audit. */
+    agentReceiptSourceRunId?: string;
 };
 /**
  * Gateway-backed Harbor surface for hosted Paybond integrations.
@@ -1204,6 +1209,12 @@ export type ServiceAccountSignalSessionInit = {
     maxRetries?: number;
 };
 export type ServiceAccountFraudSessionInit = ServiceAccountSignalSessionInit;
+/** Server-derived principal identity: tenant plus the deployment environment the API key is bound to. */
+export type ResolvedGatewayPrincipal = {
+    tenantId: string;
+    /** `"live"` or `"sandbox"` as reported by the gateway principal, or `null` when the field is absent. */
+    environment: PaybondEnvironment | null;
+};
 /**
  * Read-only tenant-bound Signal session for one service-account API key.
  */
@@ -1351,6 +1362,13 @@ export declare class Paybond {
     readonly audit: PaybondAudit;
     readonly agentRun: PaybondAgentRunFacade;
     readonly agent: PaybondAgentCallable;
+    /**
+     * Deployment environment this session is bound to, as reported by the gateway principal
+     * (`"live"` or `"sandbox"`), or `null` when the gateway did not report one. Server-derived —
+     * prefer this over the client-supplied `expectedEnvironment` hint when gating environment-sensitive
+     * behavior (for example, refusing live Stripe secrets in a sandbox-only demo).
+     */
+    readonly environment: PaybondEnvironment | null;
     private constructor();
     /** Open a tenant-bound hosted Paybond session from a service-account API key. */
     static open(init: PaybondOpenOptions): Promise<Paybond>;
@@ -1415,6 +1433,9 @@ export { artifactsDigest, evidenceSignBytesV1, signPayeeEvidenceBinding, type Si
 export { AGENT_RECOGNITION_GATEWAY_VERIFIER_ID, AGENT_RECOGNITION_PROOF_KIND_V1, AGENT_RECOGNITION_PURPOSE_CREATE, AGENT_RECOGNITION_PURPOSE_FUND, AGENT_RECOGNITION_PURPOSE_EVIDENCE_SUBMIT, newAgentRecognitionRequestEnvelope, signAgentRecognitionProofV1, signHarborCreateRecognitionProof, signHarborFundRecognitionProof, signHarborEvidenceSubmitRecognitionProof, signHarborSettlementConfirmRecognitionProof, type SignAgentRecognitionProofV1Params, type SignedAgentRecognitionProofV1, } from "./agent-recognition.js";
 export { executeFundWithX402, buildX402FundRequestEnvelope, PaybondX402FundingFailedError, PaybondX402FundingPendingError, type FundRequestEnvelope, type PaymentRequired, type X402FundPollOptions, } from "./x402-funding.js";
 export { executeFundWithMpp, executeFundWithMppCharge, executeFundWithMppSession, buildMppFundRequestEnvelope, parsePaymentAuthChallenge, selectMppChargeChallenge, selectMppSessionChallenge, PaybondMppFundingFailedError, PaybondMppFundingPendingError, type MppFundPollOptions, type ParsedPaymentAuthChallenge, type PaymentAuthChallenge, } from "./mpp-funding.js";
+export { buildPaybondStripeMetadata, assertNotStripeFundingWebhook, mapStripeToolResultToEvidence, STRIPE_COMMERCE_MAPPER_VERSION, PAYBOND_STRIPE_METADATA_TENANT_ID_KEY, PAYBOND_STRIPE_METADATA_INTENT_ID_KEY, PAYBOND_STRIPE_METADATA_RAIL_KEY, type BuildPaybondStripeMetadataParams, type CostAndCompletionEvidence, type MapStripeToolResultToEvidenceOptions, type PaybondStripeMetadata, type PaybondStripeSettlementRail, type StripeChargeVendorEvidence, type StripeCommerceEvidencePreset, type StripeToolResultInput, } from "./stripe-commerce/index.js";
+export { PAYBOND_UCP_AGENT_PROFILE_URL, PAYBOND_SHOPIFY_UCP_VERSION, SHOPIFY_COMMERCE_MAPPER_VERSION, assertNotShopifyFundingWebhook, createCheckoutWithBinding, createGuardedShopifyCheckoutHandler, getOrder, instrumentShopifyCheckout, mapShopifyToolResultToEvidence, mergeBindingIntoCheckoutPayload, toUcpCheckoutLineItems, type CreateCheckoutWithBindingParams, type CreateGuardedShopifyCheckoutHandlerOptions, type GetShopifyOrderParams, type InstrumentShopifyCheckoutInput, type MapShopifyToolResultToEvidenceOptions, type ShopifyCheckoutCreatePayload, type ShopifyCheckoutExecuteInput, type ShopifyCheckoutExecutor, type ShopifyCheckoutLineItemInput, type ShopifyCheckoutSessionBinding, type ShopifyCheckoutToolArgs, type ShopifyCheckoutToolResult, type ShopifyCommerceEvidencePreset, type ShopifyOrderSummary, type ShopifyUcpCheckoutLineItem, type ShopifyUcpFetch, } from "./shopify/index.js";
+export { normalizeCommerceBinding, encodeCommerceBindingToStripeMetadata, decodeCommerceBindingFromStripeMetadata, encodeCommerceBindingToShopifyNoteAttributes, decodeCommerceBindingFromShopifyNoteAttributes, PAYBOND_COMMERCE_BINDING_TENANT_ID_KEY, PAYBOND_COMMERCE_BINDING_INTENT_ID_KEY, type CommerceBinding, type ShopifyNoteAttribute, type StripeMetadata, } from "./commerce-binding.js";
 export { validateCompletionEvidence, type CompletionEvidenceValidationReport, } from "./completion-validate-evidence.js";
 export { completionSchemaDigestHex, computeVendorContractDigests, verifyVendorContract, verifyCatalogVendorContracts, type VendorContract, type VendorContractDigests, } from "./completion-contract-digest.js";
 export { contractSnapshotForPreset, mapVendorEvidenceToCanonical, resolveCompletionPreset, } from "./completion-resolve.js";
@@ -1423,5 +1444,9 @@ export { PaybondAudit, PaybondAuditExports, GatewayAuditExportsClient, parseAudi
 export { PaybondPolicy, composePolicyLayers, composeBundledPresetDefault, domain, guardrails, paybondPolicyPresets, resolveComposedPresetDocument, type LayeredPolicyPresetId, type PaybondPolicyPresets, type PolicyGuardrailLayer, type PolicyPresetId, type VerticalPolicyOptions, } from "./policy/index.js";
 export { getSolutionSmokeDefaults, isKnownSolutionId, listSolutionIds, loadSolutionManifest, paybondSolutionPresets, type PaybondSolutionBundle, type PaybondSolutionPresets, type SolutionId, type SolutionManifest, type SolutionSmokeDefaults, } from "./solutions/index.js";
 export { appendDirectHarborPaymentAuthorization, formatPaymentAuthorizationValue, PAYBOND_PAYMENT_AUTHORIZATION_HEADER, PAYMENT_TRANSPORT_RESPONSE_HEADERS, paymentAuthorizationGatewayHeader, readFundPaymentTransportHeaders, type FundPaymentTransportHeaders, } from "./payment-transport.js";
-export { AGENT_RECEIPT_KIND_V1, AGENT_RECEIPT_SCHEMA_VERSION, AGENT_RECEIPT_SCOPE_ACTION, AGENT_RECEIPT_SCOPE_INTENT_TERMINAL, AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519, AGENT_RECEIPT_VERSION_V1, AGENT_RECEIPT_WELL_KNOWN_PATH, actionReceiptId, canonicalAgentReceiptBytes, configHashSha256Hex, promptHashSha256Hex, valueDigestSha256Hex, verifyAgentReceiptV1, type AgentReceiptAgentV1, type AgentReceiptAuthorizationV1, type AgentReceiptEvidenceV1, type AgentReceiptExecutionV1, type AgentReceiptExternalAttestationV1, type AgentReceiptMerchantV1, type AgentReceiptOutcomeV1, type AgentReceiptPaymentV1, type AgentReceiptPolicyV1, type AgentReceiptReferencesV1, type AgentReceiptV1, type ConfigHashInput, } from "./agent-receipt.js";
-export { AGENT_RECEIPT_EXTERNAL_SOURCE_SEP2828, AGENT_RECEIPT_EXTERNAL_SOURCE_X402, partnerRecordDigestSha256Hex, resolveExternalAttestations, sep2828RecordsToExternalAttestations, x402ReceiptToExternalAttestations, type PaybondExternalAttestationInput, } from "./agent-receipt-external-attestations.js";
+export { AGENT_RECEIPT_KIND_V1, AGENT_RECEIPT_SCHEMA_VERSION, AGENT_RECEIPT_SCOPE_ACTION, AGENT_RECEIPT_SCOPE_INTENT_TERMINAL, AGENT_RECEIPT_SIGNING_ALGORITHM_ED25519, AGENT_RECEIPT_VERSION_V1, AGENT_RECEIPT_SIGNING_KEYS_WELL_KNOWN_PATH, AGENT_RECEIPT_WELL_KNOWN_PATH, PAYBOND_AGENT_RECEIPT_ATTESTATIONS_HEADER, PAYBOND_AGENT_RECEIPT_SOURCE_RUN_HEADER, actionReceiptId, attachOperatorAttestationV1, canonicalAgentReceiptBytes, configHashSha256Hex, promptHashSha256Hex, valueDigestSha256Hex, verifyAgentReceiptV1, verifyAgentReceiptV1FromJSON, type AgentReceiptAgentV1, type AgentReceiptAuthorizationV1, type AgentReceiptEvidenceV1, type AgentReceiptExecutionV1, type AgentReceiptExternalAttestationV1, type AgentReceiptMerchantV1, type AgentReceiptOperatorAttestationV1, type AgentReceiptOutcomeV1, type AgentReceiptPaymentV1, type AgentReceiptPolicyV1, type AgentReceiptReferencesV1, type AgentReceiptV1, type ConfigHashInput, type VerifyAgentReceiptV1Options, } from "./agent-receipt.js";
+export { FORBIDDEN_AGENT_RECEIPT_FIELDS, parseAgentReceiptJSON, validateAgentReceiptJSON, } from "./agent-receipt-prevalidate.js";
+export { AGENT_RECEIPT_EXTERNAL_SOURCE_AP2, AGENT_RECEIPT_EXTERNAL_SOURCE_SEP2828, AGENT_RECEIPT_EXTERNAL_SOURCE_X402, partnerRecordDigestSha256Hex, protocolAuthorizationReceiptToExternalAttestations, protocolSettlementReceiptToExternalAttestations, resolveExternalAttestations, sep2828RecordsToExternalAttestations, signedMandateToExternalAttestations, x402ReceiptToExternalAttestations, type PaybondExternalAttestationInput, } from "./agent-receipt-external-attestations.js";
+export { AGENT_RECEIPT_PDF_EXPORT_DERIVED_VIEW_LABEL, AGENT_RECEIPT_PDF_EXPORT_MANIFEST_KIND, AGENT_RECEIPT_PDF_EXPORT_MANIFEST_SCHEMA_VERSION, FORBIDDEN_PDF_EXPORT_MANIFEST_FIELDS, gateAgentReceiptPDFExport, parseAgentReceiptPDFExportManifestJSON, validateAgentReceiptPDFExportManifestJSON, type AgentReceiptPDFExportFooterStamp, type AgentReceiptPDFExportManifest, type AgentReceiptPDFExportSourceKind, type GateAgentReceiptPDFExportInput, } from "./agent-receipt-pdf-export.js";
+export { AGENT_AUTHORIZATION_KIND_PRINCIPAL, AGENT_AUTHORIZATION_KIND_TENANT, AGENT_MANDATE_KIND_V1, AGENT_MANDATE_SCHEMA_VERSION, AGENT_MANDATE_SIGNING_ALGORITHM_ED25519_SHA256, CONSTRAINT_REFERENCE_KIND_POLICY, CONSTRAINT_REFERENCE_KIND_PREDICATE, HUMAN_PRESENCE_MODE_HUMAN_NOT_PRESENT, HUMAN_PRESENCE_MODE_HUMAN_PRESENT, agentMandateDigestSha256Hex, canonicalAgentMandateJsonBytes, normalizeAgentMandateV1, signAgentMandateV1, verifySignedAgentMandateV1, } from "./agent-mandate.js";
+export { PROTOCOL_AUTHORIZATION_RECEIPT_KIND_V1, PROTOCOL_RECEIPT_SCHEMA_VERSION, PROTOCOL_RECEIPT_SIGNING_ALGORITHM_ED25519_SHA256, PROTOCOL_RECEIPT_STATUS_AUTHORIZED, PROTOCOL_RECEIPT_VERSION_V1, PROTOCOL_SETTLEMENT_RECEIPT_KIND_V1, PROTOCOL_SOURCE_ACP, PROTOCOL_SOURCE_AP2, PROTOCOL_SOURCE_UCP, normalizeProtocolAuthorizationReceiptV1, normalizeProtocolSettlementReceiptV1, signProtocolAuthorizationReceiptV1, signProtocolSettlementReceiptV1, verifyProtocolAuthorizationReceiptV1, verifyProtocolSettlementReceiptV1, } from "./protocol-receipt.js";