portage-cli 0.7.0 → 0.7.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c2f71cd7ac7290b314bc824678fc8a9fbc31b6e43cdea4c4e78077440c555c9
-  data.tar.gz: f63510ff1b5d5d945e6e9753b0cf1a521d8da6b084d562c230c4d6b5a98ad6ad
+  metadata.gz: 58834de7ed60ddb98da33896147737f518ccb8d02d58f0d3aeceb645ecef8ea6
+  data.tar.gz: 24e471dfb23e48b8ff1f157dbac941442ca84571120ad754451dfb36d9c08d60
 SHA512:
-  metadata.gz: 802fb90a17c93986ff7f9101e09e845af467e11607985ddd62cefcd4704f25c5f05292f871c168adeebf386d92620471d6ea6bd8273a74fabb11a3c765324f7d
-  data.tar.gz: '021008e8975eb3002986f0e9f27d5d776b1da067c3fbc6083909abbecde99a616680d3569c609fae0d87ae402e4002577c8cca6bd62ca4811d95c580d8ba8d10'
+  metadata.gz: 70c1a8b9db25d281091e496db0eb7e45de1e54b0afbc943a35866cc9ec2efb4a292b043a0720932ff5f3c2a93757ec3b217785d96ec4f2ece6e637132aed1d04
+  data.tar.gz: af42b5fb85cc582d86e60d616f38f177df92b6c53df59a7ccedcd8780855adb15f876e32ddbfda384bd579825ed90f68c5a833fd061ed79fce43e3a2c056edcd

data/CHANGELOG.md

@@ -4,6 +4,148 @@ 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.4] - 2026-09-25
+
+- **`portage doctor` reports how it was installed, and warns when another
+  `portage` shadows it** (`docs/plans/homebrew-distribution.md` Phase 4).
+  New findings, all offline and without shelling out to `brew`:
+  - `install`: `homebrew` (with the Cellar keg) when this gem or its Ruby
+    lives under `HOMEBREW_PREFIX/Cellar/portage/` (`$HOMEBREW_PREFIX`,
+    then `/opt/homebrew`, `/usr/local`, `/home/linuxbrew/.linuxbrew`),
+    otherwise `gem` with the gem's own path;
+  - `runtime`: the Ruby version and `RbConfig.ruby` path, plus the
+    `portage-cli` version;
+  - `adapters`: each first-party adapter gem (plus `webmcp` and
+    `decision`), whether it loads and at which version. A gem install
+    without adapters is normal; a Homebrew install missing one is a
+    warning, since the formula bundles them all. A broken adapter is
+    reported, never raised;
+  - `path`: every `portage` on `PATH`, compared by resolved Cellar
+    location rather than raw path. Warns when a Homebrew install is
+    shadowed by an earlier `portage` (typically a `gem install` copy in a
+    mise/rbenv/asdf/rvm Ruby), naming the winner and how to fix it, and
+    when a gem install is shadowed by a Homebrew one.
+- `portage doctor` also warns when the `PORTAGE_SHIP_*` address is missing
+  or incomplete, naming the missing variables. Without
+  `PORTAGE_SHIP_COUNTRY` a native UCP store gets no buyer context, which
+  is how a live Shopify store ended up reporting in-stock items as out of
+  stock.
+- `doctor` findings now carry a `level` (`warning` or `info`) and, for the
+  new checks, structured `details`, both in `--json`. The JSON is still a
+  top-level array. Only warnings make doctor exit 1; the text output lists
+  info findings first, then the warnings or `No issues found.`.
+- `ShippingProfile` treats an empty `PORTAGE_SHIP_*` value as unset, the
+  way `BuyerContext` and the WooCommerce billing fallback already did, so
+  a `.env` copied from `.env.example` with blanks left in no longer
+  submits an address of empty strings.
+
+## [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

data/README.md

@@ -49,27 +49,83 @@ No single adapter gem is a hard dependency — install whichever
 
 ## Installation
 
+**Homebrew** (macOS and Linux) — recommended for using the CLI:
+
+```bash
+brew install tomtom87/portage/portage
+```
+
+The formula installs `portage-cli` plus every adapter gem (Shopify, Wix,
+WooCommerce, BigCommerce, Magento, Etsy, Instagram, WebMCP, Decision) into
+its own directory, running on Homebrew's own `ruby`, so it doesn't depend on
+or change whichever Ruby you use for anything else. It gives you `portage`
+and `portage-console`.
+
+**RubyGems** — on any Ruby ≥ 3.2, or when you only want some adapters:
+
+```bash
+gem install portage-cli
+gem install portage-ucp-shopify   # optional: add only the adapters you need
+```
+
+In an app's `Gemfile` instead:
+
 ```ruby
-# Gemfile
 gem "portage-cli"
 ```
 
+### Upgrading
+
+- Homebrew: `brew upgrade portage`. Your config and data in `~/.portage`
+  (policy, payment-method metadata, transaction log, order ledger,
+  `config.json`) are left alone, as they are by `brew uninstall`.
+- RubyGems: `gem update portage-cli` (and any adapter gems you added).
+
+Portage has no self-update command, by design: whichever tool installed it
+owns upgrades.
+
+### Linux: stored secrets need `secret-tool`
+
+On Linux, stored payment tokens (`portage payment enroll`) and proxy
+passwords (`password_ref`) live in the Secret Service (GNOME Keyring,
+KWallet) via the `secret-tool` command. It comes from your distribution,
+not from the formula or the gem:
+
 ```bash
-bundle install
+sudo apt install libsecret-tools   # Debian/Ubuntu
+sudo dnf install libsecret         # Fedora
 ```
 
-Or standalone:
+Without it (or without a live D-Bus session, e.g. over SSH or in CI),
+Portage uses the headless tier: the token comes from
+`PORTAGE_PAYMENT_TOKEN` and nothing is stored locally. On macOS the
+Keychain is used and nothing extra is needed.
+
+### Two copies on PATH
+
+A `gem install` copy and a Homebrew copy can both be installed, and your
+shell runs whichever `portage` comes first on `PATH`. A common case is an
+old gem copy in a mise, rbenv, asdf or rvm Ruby's `bin`, which then keeps
+running after `brew install` or `brew upgrade`. `portage doctor` warns
+about this. To check:
 
 ```bash
-gem install portage-cli
+which -a portage
 ```
 
+To fix it, keep one copy: `gem uninstall portage-cli` (with the Ruby that
+owns the gem copy active) to use Homebrew's, or `brew uninstall portage` to
+use the gem's. Or reorder `PATH` so the one you want comes first.
+
 ## Usage
 
+<!-- usage-start -->
 ```bash
 portage buy <url> --query "..." [--qty N] [--payment-token TOKEN] [--product-id ID]
-                                [--yes] [--dry-run] [--decision-backend jev|laya]
+                                [--yes] [--dry-run] [--auto-open|--no-auto-open]
+                                [--notify-webhook URL] [--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]
@@ -88,7 +144,24 @@ 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]
+portage doctor [--require FILE] [--adapter CLASS_NAME] [--json]   # aliases: configure, setup
+portage generate adapter NAME [--dir DIR]
+portage generate agent-profile [--out FILE] [--key-out FILE] [--rotate]
+portage --version
 ```
+<!-- usage-end -->
+
+`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.
@@ -102,7 +175,10 @@ 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.
@@ -270,6 +346,166 @@ 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).
+
+### Doctor
+
+```bash
+portage doctor          # aliases: portage configure, portage setup
+portage doctor --json
+```
+
+Checks this machine's setup without touching the network (apart from
+probing any proxy you've configured). It first reports how Portage is
+installed, then lists anything that needs fixing:
+
+- `install`: `homebrew` (with the Cellar path) or `gem` (with the gem's
+  path).
+- `runtime`: the Ruby version and path it runs on, and the `portage-cli`
+  version.
+- `adapters`: which first-party adapter gems load, and at which version.
+  Missing adapters are expected on a gem install; on Homebrew, which
+  bundles them all, a missing one is a warning.
+- `path`: which `portage` your shell actually runs. Warns when another copy
+  earlier on `PATH` shadows this one (see "Two copies on PATH" above).
+- `shipping`: warns when `PORTAGE_SHIP_*` is missing or incomplete (see
+  "Shipping address" below), naming the variables to set.
+- Seller-side checks against `Portage::Ucp.configuration` (authenticator,
+  rate limiter, signing keys, payment handlers; pass `--require` to load
+  your app's initializer first), the confidence gate's backend, the
+  User-Agent, and proxy settings.
+
+With `--json` the output is an array of findings, each with `check`,
+`message`, `level` (`warning` or `info`) and, for the install checks,
+`details`. Doctor exits `1` when there's at least one warning, else `0`.
+
+### 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
@@ -366,12 +602,11 @@ 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)
+### Shipping address
 
-When buying against your own store (`portage buy`'s step 2 adapter-credentials
-fallback, described at the top of this file) and that adapter supports
-`dev.ucp.shopping.fulfillment`, set a default shipping address via env
-rather than a flag, same posture as adapter credentials:
+Set your shipping address via env rather than a flag, the same way as
+adapter credentials (`.env.example` at the repo root lists them all).
+`portage doctor` warns until the required ones are set:
 
 ```bash
 export PORTAGE_SHIP_STREET="1 Main St"
@@ -384,12 +619,26 @@ export PORTAGE_SHIP_LAST_NAME="Lovelace" # optional
 export PORTAGE_SHIP_PHONE="+1..."        # optional
 ```
 
-`street`/`city`/`country`/`postal_code` are required — a partial profile is
-treated as no profile at all. Once the merchant prices shipping options
-against that address, `portage buy` auto-picks the cheapest per fulfillment
-group; there's no interactive rate picker, since this drives one automated
-purchase. Native (non-adapter) UCP stores don't get this yet — see
-`portage-ucp`'s design log for why.
+`street`/`city`/`country`/`postal_code` are required — a partial profile
+(or one with empty values) is treated as no profile at all.
+
+The variables are used in two ways:
+
+- **Native UCP stores** (`buy` and `find` over HTTP) get
+  `PORTAGE_SHIP_COUNTRY`, `_REGION` and `_POSTAL_CODE` (plus
+  `PORTAGE_CURRENCY` and `PORTAGE_LANGUAGE`, if set) as UCP buyer context,
+  which a store uses to pick the market it prices and stocks in. These
+  work on their own, without the full address.
+  Without at least the country, a live Shopify store can report in-stock
+  items as out of stock.
+- **Your own store** (`portage buy`'s adapter-credentials fallback,
+  described at the top of this file), when its adapter supports
+  `dev.ucp.shopping.fulfillment`, also gets the full address as the
+  checkout's shipping destination. Once the merchant prices shipping
+  options against it, `portage buy` auto-picks the cheapest per fulfillment
+  group; there's no interactive rate picker, since this drives one
+  automated purchase. Native (non-adapter) UCP stores don't get the full
+  address yet — see `portage-ucp`'s design log for why.
 
 ## Buying without a URL