portage-cli 0.6.4 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72d2d335f8f6d40abab7b9307f4e3dcfc21b2cb9dfc4fc5f67c490dd2d42e5ee
-  data.tar.gz: 98065dbee850dd5db2141731f45078526b00b877bbe67278b13c5b6ffa7a448e
+  metadata.gz: 996ddc0acd1ec2676257f402fbb03148e8a38c40af9d5cf4fbe50d176416a334
+  data.tar.gz: a451d4e8130b1891fb2630d9b5e9edc1efde9486afda2ca3ff863342943d4a09
 SHA512:
-  metadata.gz: 2ad81909c54bbf4ca6e588c8b3f72b19d8d7788d4762754b0f38783a51ce44dca60cd6e9a2aba7f05faeb0e7ca122bece589884194c44b982d7009615322432f
-  data.tar.gz: 81a8c3098e6dad475ec1138c44de866be4a349a3bc57a133330c6684b9924b050eebd44f1440292f2f28d0cd87bb1f6c3cbd356c85ccc4f769e7162dbff1803b
+  metadata.gz: dd25c1c868d3e70f6ef469975f0d2b24f478c1f96bf83a739d2e4a473c38d2695fbd3586e0243ac21f9d75562b080413ad173c18924024ff1135279cfe8622be
+  data.tar.gz: e8578d6935466578e44e9e4f2e2caae61e1b9a1b2b52051934989fd28ec8ea9a163d943e3f68aac3704bdae72557d600f4694c7c81b8e9fe00b16685640a10b6

data/CHANGELOG.md

@@ -4,6 +4,222 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
+## [0.7.3] - 2026-09-25
+
+- **Proxy support** (`docs/plans/proxy-support.md` Phases 2-3). Every
+  network command (`buy`, `find`, `compare`, `doctor`, `payment enroll`)
+  takes `--proxy`, `--proxy-mode`, `--proxy-header`, `--no-proxy`,
+  `--proxy-route`, `--proxy-chain`, `--proxy-passthrough`, `--proxy-ca` and
+  `--no-env-proxy`, resolved per field against `PORTAGE_PROXY*` env vars
+  and `~/.portage/config.json`'s `proxy` section into core's
+  `Support::ProxyConfig`. `proxy.password_ref` resolves through Keychain or
+  Secret Service (service `portage-cli-proxy`). The payment route stays
+  direct unless a proxy is named for it explicitly, so payment traffic no
+  longer inherits a bare `$http_proxy`/`$https_proxy`. `portage doctor`
+  probes each configured proxy through `Support::Connection` and warns on
+  plaintext credentials in `config.json`.
+- Requires `portage-ucp` `~> 0.10` (for `Support::Connection` and
+  `ProxyConfig`) and `portage-ucp-client` `>= 0.6.3` (for
+  `Client::USER_AGENT`, which the default User-Agent is built from). Both
+  floors were too low before: against `portage-ucp` 0.9.0 or
+  `portage-ucp-client` 0.6.2, `require "portage/cli"` raised `NameError`.
+- `portage --version` (also `-v` and `portage version`) prints the gem's
+  version and exits 0. Needed so a packaged install — the Homebrew
+  formula's offline `test do` block, or anyone else scripting around a
+  release — can confirm which build is on `PATH` without hitting the
+  network.
+- **`portage-console` failed to start on Ruby 4.0.** It requires `irb`,
+  which stopped being a default gem in Ruby 4.0 (it's a bundled gem now),
+  and the gemspec never declared it, so any isolated install
+  (Homebrew's, or anything under Bundler) raised `LoadError: cannot load
+  such file -- irb`. `irb` is now a runtime dependency.
+- **Did the shopper finish the checkout? `portage orders reconcile`.**
+  Every checkout `portage buy` hands to the shopper's own browser
+  (`requires_escalation`, `permission_denied`, `no_payment_token`,
+  `policy_blocked`, `low_confidence`, `checkout_mismatch`) now reserves a
+  pending record in the transaction log (best-effort — a failed write is a
+  report warning, never blocks the hand-off). `portage orders reconcile
+  [--checkout ID] [--json]` re-fetches each pending checkout from the store
+  and settles it: `complete` only on a store-reported `completed` status,
+  `failed` on `canceled` or an unanswered expiry, otherwise stays pending.
+  Never infers success from a vanished checkout or a plain timeout. Safe to
+  run from cron/launchd. See `docs/plans/handoff-reconcile.md`.
+- **`handoff_spend_mode`** (`PORTAGE_HANDOFF_SPEND_MODE`, config.json) —
+  whether a reconciled shopper purchase counts toward the buyer's own spend
+  cap/velocity limit. `block` (default): counts like any agent purchase.
+  `warn`: recorded but excluded from cap math. `precheck`: `block`, plus a
+  spend-cap check at hand-off time that suppresses auto-open (never the
+  URL) when this checkout would already exceed the cap.
+- Phase 0 of the plan above (a live signal check against a real store) was
+  not run before this shipped — see `docs/design-log.md` §44.
+- **`portage buy --wait [--wait-timeout DURATION|off]`.** After a hand-off,
+  polls `HandoffReconciler` with backoff (2s → 30s, plus jitter) until the
+  checkout settles or its deadline passes — the earlier of
+  `handoff_wait_timeout` (`PORTAGE_HANDOFF_WAIT_TIMEOUT`, config.json;
+  default 30m, `off` removes it) and the checkout's own `expires_at`.
+  Ctrl-C or the deadline leaves the record pending for a later `portage
+  orders reconcile`; it never settles from the wait itself. Under `--wait
+  --json`, stdout streams NDJSON (`handoff`, `handoff_status` on each
+  store-reported status change, `handoff_settled`) followed by the final
+  report object; plain `--json` with no `--wait` is unchanged byte-for-byte.
+- **`reconcile_notify`** (`PORTAGE_RECONCILE_NOTIFY`, config.json) — a comma
+  list of channels a settled hand-off notifies on, from `--wait` or `portage
+  orders reconcile`. Default `webhook`. Adds `macos` (a native notification,
+  merchant/amount escaped into a fixed AppleScript template) and `terminal`
+  (a printed line, forced on for a plain-text `--wait` regardless of
+  configuration). `journal` is accepted for documentation — the Phase 1
+  order-snapshot journal write was already unconditional.
+- **WebMCP outbound, opt-in (Phase 4, partial).** `Buy.new(webmcp_bridge:)`
+  takes a `portage-ucp-webmcp` outbound bridge already pointed at a
+  navigated page; when given one, `portage-cli` tries it after native-UCP
+  discovery finds nothing and before a platform-adapter fallback. Only
+  `webmcp_checkout_mode: express_stop` (the default) is implemented: it
+  builds the cart/checkout and always hands off (reason `express_stop`),
+  feeding Phases 1-3 unchanged, since a WebMCP page doesn't expose
+  `complete_checkout` by default anyway. `token` mode reports
+  `webmcp_token_unsupported` rather than attempting completion — it still
+  needs a `Confirmer`-swap seam in `Mcp::Server.build` and payment-token
+  enrollment that don't exist yet. No new hard runtime dependency:
+  `portage-ucp-webmcp` is lazily `require`d, same posture as an optional
+  platform adapter gem.
+
+## [0.7.2] - 2026-09-24
+
+- The User-Agent every store-facing request sends (`Cli::UserAgent`, née
+  `Cli::USER_AGENT`/`Cli::HTTP_HEADERS`) is now configurable: `PORTAGE_USER_AGENT`
+  beats `~/.portage/config.json`'s `user_agent` key, both of which beat the
+  `portage-cli/<ver> portage-ucp-client/<ver> (+https://github.com/...)`
+  default — same precedence `Notifier`'s webhook URL already uses. `portage
+  doctor` (and its `configure`/`setup` aliases) now flags a configured value
+  containing a stray newline, since `Net::HTTP` would otherwise raise on it
+  mid-checkout instead of at setup time.
+
+## [0.7.1] - 2026-09-24
+
+- Fix: `buy <url> --max-price` (and `--product-id` with `--max-price`) was
+  silently ignored — `add_search_options` only wired `--max-price` into the
+  `find` options, not `buy`, so a URL-driven buy could complete over the cap
+  the caller set. `Buy#select_product` now filters to products within
+  `max_price` first, using a variant's own price where available and
+  otherwise the product's lowest price (unpriced products stay eligible,
+  same rule `Find` already used). `no_match_message` now names the cap.
+- Every store-facing request (`discover()` calls and the notifier webhook
+  POST) now sends `portage-cli/<ver> portage-ucp-client/<ver>
+  (+https://github.com/tomtom87/Portage)` instead of Ruby's or Faraday's
+  default User-Agent. New `Cli::USER_AGENT`/`Cli::HTTP_HEADERS`
+  (`lib/portage/cli/user_agent.rb`) replace the ad-hoc UA strings each of
+  `portage-buy`, `portage-find` and `portage-payment-enroll` built on their
+  own. Requires `portage-ucp-client >= 0.6.3`.
+
+## [0.7.0] - 2026-09-23
+
+- **The decision layer is wired in.** `buy`/`find` make their judgment
+  calls through the same rules `portage-ucp-decision` wraps. Ranking,
+  escalation and the policy check live in `portage-ucp` core
+  (`Support::OfferRanking`, `Support::Escalation`, `PolicyGuard`), so they
+  run the same with or without that gem. `portage-ucp-decision` stays an
+  optional plugin that only the confidence gate needs. Every checkout
+  report carries the verdicts under `decisions:` (`escalation`, `policy`,
+  and `confidence` when enabled). Requires `portage-ucp ~> 0.9`.
+  - `find` ranks offers buyable first, then cheapest, then unpriced. The
+    order is unchanged.
+  - When a checkout both requires escalation and mismatches the request
+    under `PORTAGE_ABORT_ON_CHECKOUT_MISMATCH`, `buy` now reports the
+    store's escalation, not the mismatch. Both hand off the checkout.
+  - `buy --yes` now checks your spend policy before completing, on remote
+    native-UCP stores too. Before, only the own-store flow's in-process
+    `Dispatcher` enforced it, so a remote store never saw your caps,
+    allowlist or token scopes. A blocked purchase hands off the checkout.
+  - New opt-in confidence gate: `--decision-backend jev|laya` /
+    `PORTAGE_DECISION_BACKEND`, with a threshold from `--min-confidence` /
+    `PORTAGE_MIN_CONFIDENCE` (default `0.8`). Needs `portage-ucp-decision`.
+    A low score, a backend that can't answer, or a missing gem holds the
+    purchase and hands off the checkout.
+  - Every verdict carries a `reason`: a string, or null when the gate
+    passed, the same in-process as in `--json`. `confidence.reason` is
+    `below_threshold`, `backend_error` or `not_installed`, and
+    `confidence.error` holds the detail behind the last two.
+- **`buy` checked out sold-out items when in-stock matches were right
+  there.** It took the top search hit and its first variant unconditionally,
+  so a sold-out top hit dead-ended on the store's "Sold out" refusal
+  (allbirds.com and billabong.com, 2026-09-23). It now takes the first hit
+  with stock, and that product's first in-stock variant. When nothing
+  reports stock it still falls back to the top hit, and `--product-id`
+  still buys exactly that product.
+- `doctor` accepts `TYPESAFE_API_KEY` in place of `JEV_API_KEY`, matching
+  `portage-ucp-decision`'s Jev backend.
+- **An agent couldn't tell a held purchase from a bought one without reading
+  prose.** `decisions:` only covers the three gates, so a missing payment
+  token, a permission-denied store, a dry run or a missing `--yes` all
+  showed `escalate: false, allowed: true`. Every `buy` report now carries
+  `outcome` (`purchased`, `no_payment_token`, `policy_blocked`, ... — the
+  full list is in the README), and the text output leads with it as
+  `[outcome]`. Checkout reports also carry `items`, what the checkout
+  actually holds, alongside `products`, the search results.
+- **History recorded the wrong things.**
+  - A purchase entry listed all ten search results, not what was bought,
+    and had no way to tell a completed purchase from a dry run or a held
+    one. Entries now carry `outcome`, `items`, `total`/`currency`,
+    `checkout_id`, `source`, and the `checkout_url` for anything not
+    completed.
+  - A `buy` whose search matched nothing was logged as a purchase. It's now
+    a search at that store, as are browse-only and dead-end buys, which
+    weren't logged anywhere.
+  - The search behind a `buy` with no URL wasn't logged at all.
+- **Checkout hand-off webhooks.** The body now includes the report's
+  `message`, the `store` and the shopper's `query`, so a Slack/Zapier relay
+  can post it without a lookup. A plain-text 2xx (Slack's `ok`) was
+  reported as a failed delivery, because the reply was parsed as JSON; any
+  2xx now counts. The POST times out after 5s instead of stalling the buy
+  for up to two minutes.
+- **The confidence gate could crash a buy after the checkout existed.** Only
+  `Decision::Error` was rescued, so a backend's timeout, parse error or
+  missing binary escaped as a backtrace with no report, hand-off or history
+  entry. Any failure now holds the purchase like a low score does.
+- **The spend policy failed open on a checkout with no total.** PolicyGuard
+  skips both caps without an amount, so `buy --yes` completed past a
+  configured cap while reporting `allowed: true`. It's now denied as
+  `total_unknown` whenever a cap is set.
+- `doctor` checks the confidence backend you selected
+  (`PORTAGE_DECISION_BACKEND`): the gem missing, an unknown name, a missing
+  `JEV_API_KEY` or Laya bridge, or a bad `PORTAGE_MIN_CONFIDENCE`. It no
+  longer asks for `JEV_API_KEY` when no backend is selected.
+- The no-buyer-context warning names every variable it reads and says to
+  set at least `PORTAGE_SHIP_COUNTRY`.
+- **Settings resolve one way everywhere.** The auto-open toggle, the
+  notify webhook, `PORTAGE_ABORT_ON_CHECKOUT_MISMATCH` and the confidence
+  gate's backend/threshold each parsed their own env var and repeated the
+  "flag, then env var, then `config.json`" order. They now share
+  `Portage::Cli::Setting`. Two edge cases change:
+  - A blank flag or env var (`PORTAGE_AUTO_OPEN_CHECKOUT=`,
+    `--notify-webhook ""`) is unset and falls through to the next level.
+    Before, an empty auto-open env var turned auto-open off, and an empty
+    `--notify-webhook` turned the webhook off.
+  - A `config.json` `"auto_open_checkout"` string is read like the env var,
+    so `"no"` means off. Before, any non-empty value meant on.
+- Report totals and the policy check's amount come from core's
+  `Support::Totals.amount` instead of their own lookups.
+- **Remote purchases didn't count toward the rolling cap or velocity
+  limit.** Both count the transaction log (`~/.portage/transactions.json`),
+  and only the own-store `Dispatcher` wrote to it, so `buy --yes` against a
+  remote native-UCP store never added to either. `buy` now records a remote
+  completion there under the merchant host, with its amount, currency and
+  token ref: reserved before the store is asked, settled `complete` only
+  when it comes back purchased, `failed` otherwise. The own-store loopback
+  path is still left to `Dispatcher`, so nothing is counted twice. If the
+  log can't be written after the purchase, the report says so in
+  `warnings` rather than losing the purchase to an exception.
+- **A garbage `PORTAGE_MIN_CONFIDENCE` broke every `buy`**, even with no
+  decision backend selected, because the threshold was parsed up front
+  either way. The env var is now read, and validated, only once a backend
+  is selected. An explicit `--min-confidence` is still always validated.
+- **`buy --json` could refuse a flag without any JSON.** An out-of-range
+  threshold went to stderr as a bare line, and a flag OptionParser couldn't
+  read (`--min-confidence high`, an unknown flag) escaped as a backtrace.
+  Under `--json` both now print a report with `outcome: "invalid_option"`
+  and exit 1; without it, both are one line on stderr. The threshold is
+  also checked before the search when `buy` has no URL, not after it.
+
 ## [0.6.4] - 2026-09-22
 
 - **Every dead-end hand-off pointed the shopper at the store's refund

data/README.md

@@ -68,7 +68,9 @@ gem install portage-cli
 
 ```bash
 portage buy <url> --query "..." [--qty N] [--payment-token TOKEN] [--product-id ID]
-                                [--yes] [--dry-run] [--json]
+                                [--yes] [--dry-run] [--decision-backend jev|laya]
+                                [--min-confidence N] [--json]
+                                [--wait [--wait-timeout DURATION|off]]
 portage buy --query "..." [--store URL] [--max-price N] [--limit N] ...
 portage find --query "..." [--max-price N] [--limit N] [--json]
 portage compare <url> --product-id ID [--id VALUE ...] [--results N]
@@ -87,8 +89,20 @@ portage policy set [--per-transaction-cap N --currency CUR]
                     [--rolling-cap N --rolling-window-seconds N --currency CUR]
                     [--velocity-count N --velocity-window-seconds N]
                     [--allow HOST ...] [--clear-allowlist]
+portage orders reconcile [--checkout ID] [--json]
 ```
 
+`buy`/`find`/`compare`/`doctor`/`payment enroll` (the network-touching commands —
+`orders reconcile` doesn't take these) also accept:
+
+```
+[--proxy URL] [--proxy-mode forward|gateway] [--proxy-header "Name: value"]
+[--no-proxy HOSTS] [--proxy-route ROUTE=URL|direct] [--proxy-chain URL,URL,...]
+[--proxy-passthrough HEADER] [--proxy-ca FILE] [--no-env-proxy]
+```
+
+See "Proxy" below.
+
 - `--query` — search term. Against the store's catalog when you name a store,
   against the search backends when you don't.
 - `--qty` — quantity, default `1`.
@@ -101,15 +115,27 @@ portage policy set [--per-transaction-cap N --currency CUR]
   search ranks first. If the id isn't in the results, nothing is bought.
 - `--store` — name the merchant without giving a full URL; skips the search.
 - `--max-price` — in major units (`400` means 400), compared per offer in that
-  offer's own currency. No FX conversion.
+  offer's own currency. No FX conversion. Applies per unit, to the search and
+  to the store's own catalog once one is settled (a URL, `--store`, or a
+  picked offer): nothing priced above it is checked out, even with
+  `--product-id`. A product with no price is still eligible.
 - `--limit` — how many candidate stores to probe, capped at 12.
 - `--yes` — skip the confirmation prompt before completing checkout.
 - `--dry-run` — resolve and price the order without completing checkout.
+- `--decision-backend` — opt into the confidence gate (see "Decisions" below):
+  `jev` or `laya`. Defaults to `PORTAGE_DECISION_BACKEND`; unset means off.
+- `--min-confidence` — the gate's threshold, `0.0`–`1.0`. Defaults to
+  `PORTAGE_MIN_CONFIDENCE`, then `0.8`. The flag is always checked; the env
+  var is read (and checked) only while a backend is selected, so a stale
+  value can't block a buy that doesn't use the gate.
 - `--json` — machine-readable report instead of the human-readable summary.
 
 Exits `0` when a checkout completed (or a dry-run/browse/search resolved
 successfully), `1` otherwise — including the "no native manifest, no adapter
-credentials" dead-end case, so it's scriptable in CI.
+credentials" dead-end case, so it's scriptable in CI. A flag that can't be
+used (an unreadable value, an out-of-range threshold) stops the buy before
+anything runs: on stderr normally, or as a JSON report with `outcome:
+"invalid_option"` under `--json`.
 
 ### Compare
 
@@ -162,10 +188,15 @@ abandoned carts on someone else's site; left out of scope for now.
 
 ### History
 
-Every `find` (and `buy`, once it reaches a search) and every `buy` that
-reaches checkout is logged locally to `~/.portage/history.json` — most recent
-200 entries each, purchases and searches kept separately. Browse-only `buy`
-reports (no checkout reached) aren't logged as purchases.
+Every `portage buy` that creates a checkout is logged locally to
+`~/.portage/history.json` as a purchase, whatever came of it. Each entry
+carries the report's `outcome` (`purchased`, `dry_run`, `policy_blocked`,
+...), what the checkout held (`items`), its `total`, and, when it wasn't
+completed, the `checkout_url` to finish it. "What did I already buy" is
+the entries whose `outcome` is `purchased`. A `buy` that never reached a
+checkout (no match, browse-only, a dead end) is logged as a search at that
+store instead, as is every `find`, `compare`, and the search behind a
+`buy` with no URL. The most recent 200 entries of each are kept.
 
 ```bash
 portage history                       # both lists, most recent last
@@ -255,6 +286,231 @@ opt-in guardrail, not a default-deny one. Per-token scopes (merchant/amount
 limits bound to one enrolled card) are set via `portage payment enroll
 --scope-*` above, not here.
 
+### Orders reconcile
+
+Nearly every real checkout `portage buy` can't finish itself hands the
+shopper a link — `requires_escalation`, `permission_denied`,
+`no_payment_token`, `policy_blocked`, `low_confidence`, or
+`checkout_mismatch`. That's a pending purchase this process knows nothing
+more about until something asks the store. `portage orders reconcile`
+re-fetches each pending hand-off from the store and settles it once the
+store itself reports a terminal status:
+
+```bash
+portage orders reconcile              # every pending hand-off
+portage orders reconcile --checkout chk_123
+portage orders reconcile --json
+```
+
+A `completed` checkout settles `complete` — using the store's own total at
+settle time, not the hand-off-time snapshot — records the order (when one
+exists) and a journal entry, and is counted toward your spend policy's
+rolling cap/velocity per `handoff_spend_mode` below. A `canceled` checkout,
+or one that expires with no answer, settles `failed`. Anything still
+in-progress, or not currently reachable, is left pending for the next run —
+safe to put on a cron/launchd schedule; two overlapping runs never
+double-settle the same record.
+
+`handoff_spend_mode` (`PORTAGE_HANDOFF_SPEND_MODE`, config.json's
+`handoff_spend_mode`) controls whether a reconciled shopper purchase counts
+toward the caps `portage policy set` configures:
+
+- `block` (default) — counts like any agent-completed purchase.
+- `warn` — recorded, but excluded from the cap/velocity math; still notifies
+  when it would have pushed spend over the cap.
+- `precheck` — `block`, plus a spend-cap check at hand-off time
+  (`portage buy`, not reconcile): if this checkout's total would already
+  exceed your cap, the URL is still printed but auto-open is suppressed.
+
+`--wait [--wait-timeout DURATION|off]` on `portage buy` polls the same
+reconciler right after a hand-off, instead of waiting for a separate
+`orders reconcile` run. It backs off (2s → 30s, plus jitter) until the
+checkout settles or its deadline passes — the earlier of
+`handoff_wait_timeout` (`PORTAGE_HANDOFF_WAIT_TIMEOUT`, config.json; default
+`30m`, `off` removes it) and the checkout's own `expires_at`. Ctrl-C, or
+the deadline, leaves the record pending for a later `portage orders
+reconcile` — it never settles from the wait itself. Under `--wait --json`,
+stdout streams NDJSON — `handoff`, `handoff_status` on each store-reported
+status change, `handoff_settled` — followed by the final report object;
+plain `--json` without `--wait` is unchanged.
+
+`reconcile_notify` (`PORTAGE_RECONCILE_NOTIFY`, config.json's
+`reconcile_notify`) is a comma list of channels a settled hand-off notifies
+on, from `--wait` or `orders reconcile`: `webhook` (default), `macos` (a
+native notification), `terminal` (a printed line — forced on for a
+plain-text `--wait` regardless of configuration), and `journal` (the order
+snapshot journal write, already unconditional — listing it just documents
+that).
+
+### Proxy
+
+`buy`, `find`, `compare`, `doctor`, and `payment enroll` accept the flags below,
+resolved (per field, flag > env > `~/.portage/config.json`) into a
+`Portage::Ucp::Support::ProxyConfig` by `Portage::Cli::ProxySettings` — see
+[`docs/proxy.md`](../docs/proxy.md) for corporate egress, a rotating residential
+pool, an API gateway, mitmproxy for debugging, and nginx/Cloudflare in front of the
+MCP/WebMCP endpoints, worked through end to end.
+
+| Flag | Meaning |
+| --- | --- |
+| `--proxy URL` | The default proxy's URL (`http://user:pass@host:port`). Overrides only `proxy.default.url`; every other configured field (`no_proxy`, `routes`, `chains`, ...) stays as set in config.json. |
+| `--proxy-mode forward\|gateway` | The default profile's mode. `forward` (the default) is a standard HTTP proxy; `gateway` is a URL-rewriting gateway — see `docs/proxy.md`. |
+| `--proxy-header "Name: value"` | Repeatable. Sent only to the proxy (on the `CONNECT` request, or the gateway request) — never to the real target. `Authorization`/`User-Agent`/`X-Shopify-*-Access-Token`/`X-Payment-Token` are refused here, always. |
+| `--no-proxy HOSTS` | Comma-separated hostnames/suffixes/CIDRs (or a bare `*`) to always bypass the proxy for, whatever the route resolves to. |
+| `--proxy-route ROUTE=URL\|direct` | Repeatable. Points one fixed route (`store`, `search`, `notify`, `payment`, `platform`, `probe`) at its own URL, or forces it `direct` regardless of `default`. |
+| `--proxy-chain URL,URL,...` | An ad-hoc multi-hop chain for this run — each hop is `forward` unless prefixed `gateway+https://...`. Overrides the whole `default` profile (not just its `url`), since a chain has no single "url" field to merge with config.json's own. |
+| `--proxy-passthrough HEADER` | Repeatable, server commands only. Allowlists an inbound request header to ride along on outbound calls made while serving it — see `docs/proxy.md`'s passthrough section. Refuses a protected header name at parse time. |
+| `--proxy-ca FILE` | A PEM file trusted in addition to the system store — for a TLS-intercepting corporate proxy or a debugging proxy like mitmproxy. |
+| `--no-env-proxy` | Ignore `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` (and their lowercase forms) entirely for this run — otherwise they're still the fallback for any route nothing else configured. |
+
+**Env vars** (checked when the matching flag is absent, before config.json):
+
+| Var | Matches |
+| --- | --- |
+| `PORTAGE_PROXY` | `--proxy` |
+| `PORTAGE_PROXY_MODE` | `--proxy-mode` |
+| `PORTAGE_NO_PROXY` | `--no-proxy` |
+| `PORTAGE_PROXY_CA` | `--proxy-ca` |
+| `PORTAGE_PROXY_HEADERS` | A JSON object of header name → value, merged under any `--proxy-header` flags (flags win on a name collision). |
+
+Below all of the above, the standard `HTTPS_PROXY`/`HTTP_PROXY`/`NO_PROXY` (and
+lowercase) variables are still the fallback for any route nothing here configures
+at all — existing environments keep working unless `--no-env-proxy` is set. The
+**`payment` route is always forced `direct`** unless a proxy is named for it
+explicitly (`--proxy-route payment=...` or config.json's `routes.payment`) — it
+never inherits a bare `default`/env proxy the way every other route does, so an
+egress proxy nobody meant to hand payment tokens to never sees them by accident.
+
+`${ENV_VAR}` inside a config.json header value (`proxy_headers`, `forward_headers.add`)
+is expanded from the process environment at resolve time, so a secret can live in
+the environment rather than the file itself. A proxy password can also live in
+`password_ref` (resolved through the same macOS Keychain/Linux Secret Service tiers
+`portage payment` uses, under its own `portage-cli-proxy` service name) instead of
+plaintext in the URL — `portage doctor` warns when it finds a plaintext one anyway.
+
+`portage doctor` reports, per route, what's effectively configured (credentials
+redacted), whether each configured proxy/gateway is actually reachable, and flags
+plaintext proxy credentials and an intercepting proxy (`ca_file` or `gateway` mode)
+sitting on the `payment` route.
+
+### WebMCP (library use, opt-in)
+
+`portage buy` from the shell has no browser of its own, so there's no CLI
+flag for this — it's for a caller embedding `Portage::Cli::Buy` directly
+alongside its own browser automation:
+
+```ruby
+Portage::Cli::Buy.new(url: "shop.example", query: "mug",
+                      webmcp_bridge: my_portage_ucp_webmcp_bridge).call
+```
+
+Given a `portage-ucp-webmcp` outbound bridge already pointed at a navigated
+page, `Buy` tries it after native-UCP discovery finds nothing at that URL
+and before falling back to a platform adapter. `webmcp_checkout_mode`
+(`PORTAGE_WEBMCP_CHECKOUT_MODE`, config.json's `webmcp_checkout_mode`)
+controls how it finishes: `express_stop` (default) builds the cart/checkout
+and always hands off — reason `express_stop`, so `--wait`/`orders
+reconcile`/`handoff_spend_mode` all apply exactly as they do to any other
+hand-off. `token` isn't implemented yet; it reports
+`webmcp_token_unsupported` rather than attempting completion. Requires
+`gem install portage-ucp-webmcp` — not a hard dependency of `portage-cli`.
+
+### Decisions
+
+`portage buy` and `portage find` make their judgment calls
+(`docs/plans/system-one-decision-layer.md`) through rules that live in
+`portage-ucp` core: `Support::OfferRanking`, `Support::Escalation` and
+`PolicyGuard`. `portage-ucp-decision` wraps the same modules as typed
+verdicts, so ranking, escalation and the policy check answer the same way
+whether or not it's installed. It's an optional plugin, not a dependency:
+
+```bash
+gem install portage-ucp-decision   # only needed for the confidence gate
+```
+
+The confidence gate is the one feature that needs the gem, because the
+model backends live there.
+
+Every `portage buy` report carries an `outcome`, so a script or agent loop
+can branch on data rather than on the message text. The text output leads
+with the same value, as `[outcome]`.
+
+| `outcome` | Meaning | `checkout_url`? |
+| --- | --- | --- |
+| `purchased` | Completed. | no |
+| `needs_confirmation` | Checkout ready; rerun with `--yes`. | no |
+| `dry_run` | Checkout created, `--dry-run` stopped it. | no |
+| `requires_escalation` | The store wants the shopper to finish. | yes |
+| `checkout_mismatch` | Checkout differs from the request (`PORTAGE_ABORT_ON_CHECKOUT_MISMATCH`). | yes |
+| `no_payment_token` | No `--payment-token` and no default payment method. | yes |
+| `policy_blocked` | Your spend policy denied it; `decisions.policy.reason` says why. | yes |
+| `low_confidence` | The confidence gate held it. | yes |
+| `permission_denied` | The store doesn't let this agent complete checkout. | yes |
+| `store_refused` | The store refused a cart/checkout call (e.g. sold out). | when the store gave one |
+| `no_match` | Nothing in the store's results matched. | no |
+| `browse_only` | The store has a catalog but no UCP checkout. | when an adapter offers a link |
+| `agent_profile_missing`, `request_rejected`, `unsupported_wire_shape` | Native UCP setup problems; the message names the fix. | no |
+| `adapter_error`, `adapter_misconfigured` | Your own-store adapter failed; the message quotes it. | no |
+| `dead_end` | No UCP and no adapter for this store. | no |
+| `invalid_option` | A flag was refused before the buy started (`--json` only); `message` says which. | no |
+
+Checkout reports also carry `items` (what the checkout holds, as opposed to
+`products`, the search results) and the verdicts under `decisions:`:
+
+```json
+"decisions": {
+  "escalation": { "escalate": false, "reason": null },
+  "policy":     { "allowed": true, "reason": null },
+  "confidence": { "proceed": false, "reason": "below_threshold", "confidence": 0.41,
+                  "threshold": 0.8, "backend": "jev", "error": null }
+}
+```
+
+Every verdict has a `reason`: `null` when the gate let the purchase through,
+otherwise a string naming why it stopped it.
+
+- **escalation** — `Support::Escalation`. A `requires_escalation` checkout
+  always escalates (`reason: "requires_escalation"`). A checkout that doesn't
+  match the request escalates (`reason: "mismatch"`) only under
+  `PORTAGE_ABORT_ON_CHECKOUT_MISMATCH`; otherwise it's reported as `warnings`.
+- **policy** — `PolicyGuard`, run on your policy file (see "Policy" above)
+  before any `--yes` completion. `reason` is the guard's own
+  (`per_transaction_cap_exceeded`, `rolling_spend_cap_exceeded`,
+  `velocity_exceeded`, `merchant_not_allowlisted`, `token_scope_merchant`,
+  `token_scope_amount`, `currency_mismatch`, or `total_unknown`, below).
+  It applies to remote native-UCP stores too. Before this check, only the
+  own-store adapter flow's in-process `Dispatcher` enforced the policy.
+  Rolling caps and velocity limits count the completed purchases at that
+  merchant in `~/.portage/transactions.json`. `Dispatcher` records
+  own-store purchases there, and `portage buy` records remote ones: reserved
+  before the store is asked to complete, then settled as `complete` only
+  when the store answers that it's purchased.
+- **confidence** — `ConfidenceGate`, off unless `--decision-backend` or
+  `PORTAGE_DECISION_BACKEND` names a backend. Right before a `--yes`
+  completion it asks the backend whether the checkout matches the request
+  and is safe to complete unattended. It sends the query, merchant,
+  quantity, line items, totals and warnings, never the payment token. The
+  gate fails closed, so three things hold the purchase: a score below the
+  threshold (`reason: "below_threshold"`), a backend that can't answer
+  (`"backend_error"`), and naming a backend without `portage-ucp-decision`
+  installed (`"not_installed"`). For the last two, `error` says what went
+  wrong. `jev` needs `JEV_API_KEY`; `laya` needs `LAYA_BRIDGE_SCRIPT` (see
+  `portage-ucp-decision`'s README). `portage doctor` flags whichever of
+  these is missing for the selected backend.
+- **policy** also denies a checkout with no `total` line as
+  `total_unknown` whenever a spend cap is set, rather than skipping the cap.
+
+A blocked or held purchase hands the checkout off the same way an escalation
+does (`checkout_url`, plus `--auto-open`/`--notify-webhook` if set). The
+shopper can finish it themselves. The webhook body is JSON: `event`
+(`checkout_handoff`), `reason` (the report's `outcome`), `message` (the
+report's own sentence), `store`, `query`, `checkout_url`, `checkout_id`,
+`source`, `totals` and `warnings`. Any 2xx counts as delivered; the POST
+gives up after 5 seconds and reports `notify_error` instead.
+
+`portage find`'s offer order comes from `Support::OfferRanking`: buyable
+first, then cheapest, then unpriced.
+
 ### Shipping address (own-store checkouts only)
 
 When buying against your own store (`portage buy`'s step 2 adapter-credentials