portage-cli 0.7.5 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a682278ec8b34cb6e2cd649f345cb6779a7cec5d0bc22e6950721f7996a2d877
-  data.tar.gz: ed490b87284e6a8c9bd9ab280ea600d16877820240386d34e239309a8204b16d
+  metadata.gz: 3d34c9ba25977baefa9f1f802e38ae6b2175e455d246f7a0dd3a2833136c46e8
+  data.tar.gz: 2c1d701bafd9c914115bdb02ab661906eaddba139e0627a56bfa0cf094e71d06
 SHA512:
-  metadata.gz: c22fd29667f7281c0173503cc9797158de1cd9d494cfcc98795bbce3ecfbaa03ed67ecb1321b3adf83000cf251168a62118db703bf1fb7b5417ba615a672b8c5
-  data.tar.gz: 42016dd1b716169b2dbaadef6f83a210ab8750584b23464e8c38c76aa39374988eeda97cfdc133c3edffaaf3c3ef8b34a76aa2fd57a9c96ad32292d529878df4
+  metadata.gz: ec3b6bf08d832abbe197591050b229f38a3650603feb6e94b47a6e84fbb9d3b9ddf531c51e84d71c8b708131b655e6b501e6a55662908eb6edb60981da4f14a2
+  data.tar.gz: 137b718fd1283383aa70879a6f2290a35dc1bc3f3a898ceff6965019b110329caf943dcf3ef39c04c29d1661beee3da6edd3a056877b7a6c3a932debce90c99f

data/CHANGELOG.md

@@ -4,6 +4,622 @@ 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.
 
+## [Unreleased]
+
+## [0.9.0] - 2026-09-29
+
+- **Human pick and approve** (`docs/plans/human-pick-and-approve.md`, Phases 1-3).
+  Loop steps 3 and 5 now have a ready-made interface for a person at a terminal
+  and for an agent relaying their answer.
+  - **Offer refs.** Each `find` offer carries an `offer_ref` (`of_` and 6 hex
+    digits), and the report a `search_id` (`se_` and 8 hex digits). Both are saved
+    with the search in history, so `history --json` searches now hold `search_id`
+    and `offers[]`. `compare` saves its offers with refs and a `search_id` too.
+    `portage buy --offer REF` takes the store, product and query from the saved
+    offer; an unknown ref is `offer_not_found`.
+  - **Quotes.** A `buy --dry-run` that priced a checkout saves a quote in
+    `~/.portage/quotes/` and reports `quote_id`. `buy --quote QUOTE_ID --yes`
+    buys exactly that quote, capped at the quoted total: if the real checkout costs
+    more (or is in another currency) it refuses with `quote_changed`, carrying
+    `quoted_total` and `current_total`, without charging or handing off. Quotes don't
+    expire and are used once (`purchased` or any hand-off). `quote_not_found` and
+    `quote_used` cover the rest.
+  - **`portage pick`.** Loop step 3. `needs_pick` returns `choices[]` (`ref`, `label`,
+    `url`, plus the offer's fields) and a last "Compare an offer across stores"
+    choice; `--choose REF` relays an answer (`picked`, `by: "agent_relayed"`),
+    `--compare REF` runs compare and shows the pick again over its results,
+    `--search LAST|SEARCH_ID` picks the search. At a terminal it asks on `/dev/tty`
+    (`by: "person"`).
+  - **`portage approve QUOTE_ID`.** Loop step 5. `needs_approval` returns a
+    `summary` (title, store, qty, total, `total_display`, `url`); `--relayed-yes`
+    records `approved_by: "agent_relayed"`; a yes typed at a terminal records
+    `"person"`. The quote also keeps `approved`, `approved_by` and `approved_at`.
+  - **`--via auto|tty|agent`.** `tty` asks on `/dev/tty` (so it works with stdout
+    piped) and returns `no_terminal` when there's none; `agent` asks nobody;
+    `auto` is `tty` with a terminal and no `--json`, else `agent`.
+  - **`--view REF` / `approve --view` and `v N` / `v` at a prompt** open the product
+    page and never count as an answer. Only an `http(s)` URL on the offer's own
+    store host is opened; anything else is `view_refused`. `pick`'s compare
+    choice uses the proxy settings from env and config (there are no `--proxy`
+    flags on `pick`).
+  - **`policy set --require-approval person|any|off`** (default `any`, stored as
+    `require_approval` in `~/.portage/policy.json`, always shown by `policy show`).
+    Lowering it needs a yes typed at a terminal. It raises the bar against an agent
+    but isn't a hard guarantee: a process with a shell can edit the policy or quote
+    files. Docs: `docs/api/cli-json.md`, `docs/agentic-flow.md`,
+    `docs/cli-usage-tutorial.md`.
+  - **Upgrade note.** Under the default `any`, a `buy --yes` without an approved
+    `--quote` no longer buys: it dry-runs and returns `needs_approval` (exit `0`).
+    Restore the old behaviour with `portage policy set --require-approval off`
+    from a terminal. `buy --query`'s numbered pick now asks on `/dev/tty` too.
+
+- Documentation only, no code change. The README said a
+  `webmcp_mapping_unconfirmed` report returns the proposed mapping "for the
+  caller to pass back". No flag takes a mapping back, and `Buy` has no
+  `tool_names:` keyword. The README now says what each caller can do. From
+  the CLI, re-run the command in a real terminal without `--json`
+  (`--dry-run` is enough) and answer the prompt; the approved mapping is
+  saved to `~/.portage/webmcp_mappings.json`. From Ruby, inject
+  `webmcp_mapping_confirm:` or `webmcp_mappings:`, or pass `tool_names:` to
+  `WebMcp.connect` yourself.
+
+## [0.8.0] - 2026-09-29
+
+- **Requires `portage-ucp-webmcp` 0.2.0 or newer for WebMCP paths.**
+  `Webmcp.available?` now treats an older install as not installed
+  (`Webmcp::MIN_VERSION`), since `WebMcp::Autofill`, `Presets`, `Matcher`
+  and `Fingerprint` first shipped in 0.2.0. With 0.1.1 installed, the
+  profile hand-off falls back to showing the link instead of raising a
+  `NameError`.
+
+- **`find --max-price` now filters offer-source offers too.** Offers from
+  `OfferSources` (`ShopifyCatalog`, the retailer APIs) skipped the
+  `--max-price` check that probed stores' offers go through, so a
+  `--max-price 150` search could list a £190 catalog offer. Unpriced offers
+  still stay in, as before. `find`'s summary also counts stores from the
+  offers themselves ("Found 1 offer(s) across 1 store(s)."), not just the
+  probed ones, which reported "0 UCP store(s)" for catalog-only results.
+  Both found by the clean-session `/buy` check.
+- **Docs release for Phases 1-7** (`docs/plans/buy-skill-and-local-browser.md`
+  Phase 8). `README.md` here gains full documentation of everything the
+  above entries shipped that wasn't written up yet: the usage banner now
+  lists `index`, `browser import`, `browser profile` and `setup`; new
+  sections cover Tiers A/B/C, `--handoff-target`/hand-off-only hosts (now
+  reflecting Phase 6's built `profile` target and Phase 7's retail hosts),
+  categories/routing, the local store index and its sources, browser
+  import, the Portage browser profile, the five retailer offer source env
+  vars, and the `setup` wizard's step order; the Search backends table
+  gains the `Index` backend and a note on `OfferSources` merging offers
+  directly. `Doctor`'s bullet list documents the `index`/`handoff`/
+  `retailer_offer_sources` findings added in Phases 2b/5/7. No code
+  changed.
+- **Retailer offer sources, hand-off only** (`docs/plans/
+  buy-skill-and-local-browser.md` Phase 7). `Portage::Cli::OfferSources`
+  gains five official, opt-in buyer-side retailer APIs alongside
+  `ShopifyCatalog`: `WalmartAffiliate`, `EbayBrowse` (Buy It Now only —
+  `filter=buyingOptions:{FIXED_PRICE}`, checked again in code, and never
+  eBay's Order API/guest checkout, which takes raw card data),
+  `BestBuyProducts`, `EtsyListings` (Etsy Open API v3's
+  `findAllListingsActive`, the *buyer*-side surface — `portage-ucp-etsy`
+  stays the seller-side adapter, untouched) and `AmazonCreators`. Each is
+  gated on its own key/token env var (`WALMART_AFFILIATE_API_KEY`,
+  `EBAY_BROWSE_ACCESS_TOKEN`, `BESTBUY_API_KEY`, `ETSY_LISTINGS_API_KEY`,
+  `AMAZON_CREATORS_ACCESS_TOKEN`), `#available?` false and silently
+  excluded from `OfferSources.default` with none set — a fresh install's
+  `find` is unchanged. Every request goes through
+  `Portage::Ucp::Support::Connection` (via `SearchBackends.get_json`,
+  never raw `Net::HTTP`), 5s timeout, failures swallowed exactly like
+  `ShopifyCatalog`. None of the five is wired into `Index::Sources`, so
+  nothing they return is ever written to `~/.portage/index/
+  {stores,products}.json` — the plan's "honour each API's caching terms,
+  default to not persisting" is enforced by simply having no code path
+  that would.
+  **Amazon PA-API vs. Creators API (live web search, 2026-09-28):**
+  PA-API 5 is deprecated, retiring 2026-05-15 (already past), no longer
+  onboarding new integrations; Creators API is its OAuth2 successor.
+  `AmazonCreators` targets Creators API's search endpoint with a
+  user-supplied bearer token (no OAuth dance or refresh implemented here,
+  same "bring your own token" posture `EbayBrowse` uses for eBay's
+  Application Access Token) and reads the long-stable PA-API
+  `SearchItems`/`GetItems` item shape (`ASIN`/`DetailPageURL`/
+  `Offers.Listings[0].Price`), which Amazon's own docs describe Creators
+  API as continuing — **not live-checked**, no Associates account
+  available this session; a schema mismatch only drops an offer
+  (`#offer`'s nil guard), never a purchase-automation risk, since Amazon
+  is already Tier C.
+  Every offer ends in hand-off, never a completed purchase. Amazon
+  already routed through the existing Tier C `HandoffOnly` path
+  unchanged. `Buy#handoff_only?` now also checks
+  `OfferSources.retail_handoff_host?` (walmart.com/ebay.com/bestbuy.com,
+  unconditional — no adapter, no UCP, not a user-editable policy choice)
+  and a new `#etsy_buyer_host?` (etsy.com, *unless* the process already
+  has its own `ETSY_ACCESS_TOKEN`/`ETSY_API_KEY`/`ETSY_SHOP_ID` set, in
+  which case the existing `portage-ucp-etsy` seller-adapter flow still
+  applies unchanged) — every one of these hosts is checked before a
+  single UCP probe or homepage fetch, same "never even scraped" guarantee
+  Amazon already had. `handoff_only_checkout_url` returns the exact URL
+  passed to `portage buy` for these hosts (the real product page a
+  retailer offer source found), rather than falling back to the origin
+  homepage the way an unknown Tier C host still does.
+  `portage setup` gains an eighth, opt-in wizard step (`Steps::
+  RetailerKeys`, between search keys and the agent profile) for the five
+  keys, written to `~/.portage/.env`, never echoed back. `portage doctor`
+  gains a `retailer_offer_sources` finding (always info) naming which are
+  active and restating that none of them can complete a purchase.
+  **Open question 3 resolved:** kept in `portage-cli`'s `OfferSources`
+  (one class per retailer, one file), not split into per-retailer gems or
+  a `portage-ucp-retail` gem — Phase 1's seam (`OfferSource#offers`) is a
+  small interface with no adapter-style `Client`/`Adapter` pair to split
+  out, each source is ~50-70 lines with no shared state beyond
+  `OfferSources.origin_of`, none of them completes a purchase (the usual
+  reason an adapter earns its own gem — its own `Client`/credentials/
+  fulfillment logic), and a separate gem per retailer would mean five new
+  `require`/`rescue LoadError` seams for zero behavioral gain over the
+  `#available?` opt-in gate already in place. Revisit only if a future
+  phase adds real purchase automation for one of these.
+  `plugins/buy/skills/buy/SKILL.md`, `references/outcomes.md` and
+  `references/handoff-only.md` updated; `plugins/buy/.claude-plugin/
+  plugin.json` bumped to `0.6.0`. `claude plugin validate .` and `claude
+  plugin validate plugins/buy` still pass.
+  `portage-cli`: 925 → 961 examples (+36), 0 failures; `rubocop` clean, no
+  new cop disables. **Not live-checked at all** (docs/plans/
+  buy-skill-and-local-browser.md Phase 7 rule: "you almost certainly have
+  no API keys"): every source's spec stubs the HTTP boundary with WebMock,
+  none of Walmart/eBay/Best Buy/Etsy/Amazon Creators was called for real,
+  and no real cart was touched anywhere.
+- **Portage browser profile** (`docs/plans/buy-skill-and-local-browser.md`
+  Phase 6, Tier B). `portage browser profile init|open|status [--browser
+  chrome|edge|brave|arc] [--port N] [--url URL (open only)] [--json]`
+  manages a dedicated Chromium-family profile directory under
+  `~/.portage/browser/<browser>/profile`, launched with remote debugging
+  bound to that profile only — never the browser's own default profile
+  (`init!` only ever creates its own directory; `Launcher` only ever
+  passes that directory as `--user-data-dir`; Chrome 136+ refuses remote
+  debugging on the default profile anyway). `open` launches the browser
+  if it isn't already running on its own port, waits for its CDP endpoint
+  to answer, then attaches to an existing tab or opens a new one at
+  `--url`; `status` reports `/json/version`; the user signs into their
+  shopping sites in this profile once — nothing here ever reads a
+  credential, cookie or autofill store from it.
+  `--handoff-target profile` now actually does something: `Cli.
+  run_buy`/`execute_buy` attaches a `Portage::Cli::BrowserProfile::Bridge`
+  as `Buy#webmcp_bridge` whenever `portage-ucp-webmcp` is installed and
+  the profile is running (`Cli.profile_webmcp_bridge`) — reusing an
+  existing tab already on the store's host, or opening a new one — so
+  `#webmcp_flow` (`docs/plans/webmcp-universal-outbound.md`) drives that
+  same browser, and Phase 3's `WebMcp::Autofill` runs in it unchanged
+  (`Bridge#headless?` is always `false`, so `autofill_needs_headed_browser`
+  never fires for this profile — asserted directly). `Buy#dispatch_to_target`'s
+  `"profile"` case now navigates the attached bridge to the checkout URL
+  and reports `opened: true`, or — no bridge attached (gem missing,
+  profile not running) — tells the shopper to run `portage browser
+  profile open` first, same "report, never raise" posture as every other
+  hand-off dispatch.
+  Driving is limited to a domain allowlist (`Portage::Cli::BrowserProfile::
+  Allowlist`, reusing `HandoffOnly`'s own host normalization/matching):
+  seeded with the store's own host, and permitted to include a checkout
+  host only when `Bridge#navigate` deliberately opens it — a page-driven
+  navigation to anything else raises `DomainNotAllowedError` on the very
+  next driven call (there's no navigation-event hook in this minimal a
+  CDP client, so it's caught on next use, not mid-navigation), which
+  `Bridges::ScriptEvaluator#evaluate` re-wraps as its own `BridgeError` —
+  still caught by `Buy#webmcp_flow`'s existing rescue, so the run stops
+  the same way any other WebMCP failure does. `Portage::Cli::BrowserProfile::
+  CdpSocket` is a small, dependency-free WebSocket JSON-RPC client (RFC
+  6455 handshake, masked outbound / unmasked inbound frames) for Chrome
+  DevTools Protocol's `Runtime.evaluate`/`Page.navigate`/`Page.enable`;
+  `Portage::Cli::BrowserProfile::Cdp` covers the plain-HTTP half
+  (`/json/version`, `/json/list`, `/json/new`). No raw card data is ever
+  read or typed by any of this; Portage never touches a payment field and
+  never clicks pay. `portage-cli`: 865 → 925 examples (+60), 0 failures;
+  `rubocop` clean (one documented `Metrics/ClassLength` exclude for
+  `CdpSocket`, same "one small self-contained protocol end to end"
+  rationale already given to `Index::Builder`/`BrowserImport::Importer`).
+  Specs never launch a real browser or open a real socket — `Process.spawn`
+  is injected (`Launcher`), CDP HTTP calls go through WebMock
+  (`Portage::Ucp::Support::Connection`, same as every other network call
+  in this gem), and the WebSocket layer is proven against an in-memory
+  fake transport (`cdp_socket_spec.rb`), including RFC 6455's own §1.3
+  worked handshake example.
+
+- **Hand-off targets + hand-off-only hosts** (`docs/plans/
+  buy-skill-and-local-browser.md` Phase 5). `portage buy --handoff-target
+  default|print|profile|agent:<name>` (also `PORTAGE_HANDOFF_TARGET` /
+  `~/.portage/config.json`'s `"handoff_target"`, same precedence as every
+  other `Setting`) decides where a dead-end `checkout_url` goes:
+  `default` is today's `CheckoutHandoff` auto-open, unchanged; `print`
+  just reports the URL; `profile` is accepted but says the Portage browser
+  profile isn't built yet (Phase 6) and behaves like `print`; `agent:<name>`
+  passes the checkout URL and the same cart-summary payload
+  `--notify-webhook` sends to a named agent the user has approved once in
+  `~/.portage/config.json`'s new `handoff_agents` (a `command` argv run
+  with a scrubbed environment, stdin JSON and a 30s timeout — never a
+  shell string — or an `https` `webhook`), never invoked unless
+  `"approved": true`. Every hand-off report's `handoff` object now also
+  carries `handoff_target`, plus `agent_delivered`/`agent_error` for an
+  `agent:<name>` target. New `Portage::Cli::HandoffTarget`, `HandoffAgents`
+  (`lib/portage/cli/handoff_{target,agents}.rb`), and `Buy#handoff_notify_payload`
+  now also carries `items:`.
+  New `Portage::Cli::HandoffOnly` (`lib/portage/cli/handoff_only.rb`) is
+  the one place Tier C's host list lives — every Amazon marketplace by
+  default, fully replaced by `~/.portage/config.json`'s
+  `"handoff_only_hosts"` once that key is present. `portage buy` against
+  one of these hosts returns outcome `handoff_only` **before any request
+  to that host** — no UCP probe, no homepage fetch, no cart — with a
+  `checkout_url` (a product page/cart-add URL when a product id is known,
+  the retailer's own search URL for the query when it's Amazon, or the
+  origin's homepage otherwise, always built and never fetched) and a
+  `legal_notice` (facts plus the as-is/no-warranty line). `portage find`
+  and `portage index build`/`add`/`refresh` never probe a hand-off-only
+  origin either — `find` still lists it as a candidate, marked
+  `handoff_only: true`. `portage browser import`'s existing
+  `handoff_only_hosts:` seam is now wired to the real list. `portage
+  compare` and `PaymentMethods#enroll` (`portage payment enroll`) also
+  refuse a hand-off-only origin before ever probing it (`compare` reports
+  it hand-off only with the legal notice; enrollment reports
+  `status: "handoff_only"` — "there's nothing to set up here"), and
+  `HandoffReconciler#reconnect` refuses one too, as defense in depth (Buy's
+  `handoff_only` outcome never reserves a pending record in the first
+  place, so this path shouldn't be reachable, but it's the one place every
+  reconcile fetches a store again from a saved record). `HandoffOnly#hosts`
+  normalizes each configured entry — `"www.example.com"`,
+  `"example.com/path"`, and `"https://www.example.com/s?k=x"` all reduce
+  to `"example.com"` — the same normalization `BrowserImport::Importer`
+  already applies to a history/bookmark domain. `portage
+  doctor` gains a `handoff` finding (current target, the hand-off-only
+  list, the disclaimer), and `portage setup`'s Hand-off step now also sets
+  the target, approves a named agent, and edits the hand-off-only list.
+  **Review caught three more real bugs before this shipped, all fixed:**
+  (1) `HandoffAgents::Command`'s timeout never actually killed the child —
+  `Open3.popen3`'s block form joins `wait_thr` in its own `ensure` once the
+  block returns, so a `Timeout.timeout` firing inside it just meant popen3
+  itself then hung waiting for the still-running child; fixed to
+  `SIGTERM`, then `SIGKILL` after a short grace, and to actually wait for
+  the child to die before leaving the block, plus draining stdout/stderr
+  on their own threads (same as `Open3.capture3`) so a child that fills
+  the stderr pipe can't deadlock a sequential read of stdout first. (2)
+  `Index::Builder#reverify_stale` skipped by an entry's *stored*
+  `handoff_only` flag rather than the live config, which was wrong in
+  both directions — an origin whose UCP probe simply failed (stored
+  `handoff_only: true`, but not a Tier C host) would never be re-verified
+  again, and a stale entry recorded before the user added its host to
+  `handoff_only_hosts` (stored `handoff_only: false`) would keep being
+  probed; fixed to check `handoff_only_origin?` against live config
+  instead, flipping a now-hand-off-only entry's stored flag with no
+  request when it disagrees. (3) `Compare#resolve_origin` and
+  `PaymentMethods#discover_session` still probed whatever origin/store URL
+  they were given, including a hand-off-only one (`portage compare
+  <amazon-url>` and `portage payment enroll <amazon-url>` both reached
+  Amazon) — fixed as described above.
+  `portage-cli`: 783 → 865 examples (+82: +70 from the phase's first pass,
+  +12 from the review round above — a real-subprocess kill-on-timeout
+  spec for `HandoffAgents::Command`, `Index::Builder#refresh` specs for
+  both reverify-skip directions plus a `--dry-run` one, and one
+  zero-requests spec each for `Compare`, `PaymentMethods#enroll`,
+  `HandoffReconciler#reconnect`, and `HandoffOnly#hosts` normalization),
+  0 failures; `rubocop` clean, no new cop disables.
+
+- **`portage setup` — interactive setup wizard** (`docs/plans/
+  buy-skill-and-local-browser.md` Phase 4). On a TTY, `portage setup` (and
+  `portage doctor`/`configure` when `Doctor#nothing_configured?` — no
+  `.env` file loaded, no shipping address, no policy at all) now walks
+  through seven skippable steps: shipping address, search API keys, the
+  agent profile, browser import, the local store index, spending policy
+  caps, and hand-off. Under `--json` or with no TTY on stdin, every one of
+  `doctor`/`configure`/`setup` stays exactly today's read-only report —
+  proven by spec, not just described. New `Portage::Cli::SetupWizard` (`lib/
+  portage/cli/setup_wizard.rb` + `setup_wizard/prompt.rb` +
+  `setup_wizard/steps/{shipping,search_keys,agent_profile,browser_import,
+  index_build,policy,handoff}.rb`). Each step delegates to the real command
+  it configures — `portage generate agent-profile`, `portage browser
+  import` (with its own confirm-before-save prompt intact), `portage index
+  build`, `portage policy set` — rather than reimplementing any of them, so
+  the wizard has nothing UCP- or network-specific of its own to get wrong.
+  `Portage::Cli::DotEnv` gains `.update!`, the wizard's only writer to
+  `~/.portage/.env`: updates a key in place (never duplicating it on a
+  re-run), keeps every other line and comment untouched, creates
+  `~/.portage` if needed, and is mode 0600 from the very first byte —
+  a brand-new file is created with that mode already set (`File.open`,
+  not `File.write` then `File.chmod`, which would briefly leave it at the
+  process umask's default), and an existing file is chmod'd 600 *before*
+  anything is written into it. Every secret prompt (Brave/Google CSE API
+  keys) reads via `IO#noecho` on a real terminal and never echoes the
+  value back, even in the wizard's own summary; Enter on any question
+  keeps whatever's already set rather than clearing it, so re-running the
+  wizard is always safe. `Steps::Policy` rejects a non-numeric or
+  non-positive spending cap ("abc", "12x", "0") rather than silently
+  coercing it to a 0 cap via `String#to_f`, and reuses
+  `Portage::Cli.to_minor_units` (private, via `send`) for the major-to-
+  minor-units conversion instead of a second implementation. The hand-off
+  step configures the one hand-off setting that exists today
+  (`CheckoutHandoff`'s auto-open toggle) and explains that a fuller choice
+  of hand-off targets and the hand-off-only host list are Phase 5, not
+  invented here — a deliberately easy seam for that phase to extend rather
+  than a guess at its shape. `portage-cli`: 727 → 783 examples (+56), 0
+  failures; `rubocop` clean, no new cop disables.
+- **`portage browser import` — bookmarks and history as index seeds**
+  (`docs/plans/buy-skill-and-local-browser.md` Phase 3, Tier A).
+  `portage browser import [--browser chrome|edge|brave|arc|firefox|safari]
+  [--profile-root DIR] [--history-days 90] [--include-product-pages]
+  [--max-probes 200] [--exclude HOST,...] [--dry-run] [--yes] [--json]`
+  (new `Portage::Cli::BrowserImport`). Reads only a profile's history and
+  bookmark files — Chromium `History`/`Bookmarks`, Firefox
+  `places.sqlite`, Safari `History.db`/`Bookmarks.plist`
+  (`BrowserImport::Profiles::ALLOWED_FILES`) — and never a password,
+  cookie or autofill store; a spec wraps every Ruby file/dir/subprocess
+  entry point and fails if anything else in a fixture profile full of
+  `Login Data`/`Cookies`/`Web Data`/`logins.json`/`key4.db`/
+  `cookies.sqlite`/`formhistory.sqlite` decoys is touched. SQLite
+  databases are copied (with their `-wal`) into a private tmpdir and
+  queried with the system `sqlite3` CLI in `-readonly -json` mode, then
+  deleted; Safari's binary plist goes through macOS's own `plutil` and a
+  small XML-plist reader — no new gem dependency. Rows are reduced to
+  domains, and obvious non-shops (`SearchBackends::NON_STORE_HOSTS`,
+  webmail, banks/payment hosts, localhost/intranet/IP hosts, common
+  tools and social sites) are skipped locally, as are domains already in
+  the local index or the known-stores list. At most `--max-probes`
+  (default 200) unknown domains, most-visited first, each get one
+  `GET /.well-known/ucp` through `Portage::Ucp::Client.discover` and
+  `ProbeCache` (5s timeout) — nothing else about the history is sent
+  anywhere. A domain is kept when it answers, matches a WebMCP preset
+  (skipped with no bridge), or is on the hand-off-only list (an
+  injectable `handoff_only_hosts:` seam, empty until Phase 5). Each kept
+  domain is classified from the user's own page titles, bookmark folder
+  names and URL slugs, weighted by visit count; a domain that matches no
+  category stays uncategorised. The list (with category names) is shown
+  first and saved only after a "y" at a TTY prompt or an explicit
+  `--yes` — under `--json` or with no TTY and no `--yes`, nothing is
+  written and the report says `needs_confirmation: true`. Safari without
+  Full Disk Access (and any other permission error) is explained and the
+  command stops; it never works around it. Kept domains are written to
+  `~/.portage/index/stores.json` with `sources: ["history"]`/
+  `["bookmark"]`; `--include-product-pages` also writes product-page
+  titles to `products.json` with the same labels.
+- **`SearchBackends::Index` routes a store the query names** (its host, or
+  its bare name as a whole word), after product matches and ahead of
+  category matches — the only route an uncategorised browser-imported
+  domain gets. Imported entries are otherwise ordinary untrusted index
+  entries: `source: "index"`, never `merchant_allowlist`, never past the
+  `--store`/interactive-pick gate for `--yes`.
+- **`Index::Exporter` treats `history`/`bookmark` as personal** (alongside
+  `browser`): a store found only that way is never exported, the labels
+  are stripped from mixed-source entries, and a product whose only
+  `sources` are personal (a `--include-product-pages` entry) is dropped
+  even at a store a real source also found. `Index::ProductStore` entries
+  now carry a `sources` list (the union of every sighting's), and
+  `index build` records its own source on each product.
+- **`Index::Sources::Browser` is now a pointer, not a reader.** It yields
+  nothing, isn't a default `index build` source any more, and its
+  `portage index sources` description points at `portage browser import`
+  — `index build` never reads a browser on its own, since that would skip
+  the import's approval step. The Phase 2b `browser-import.json` hand-off
+  file is gone.
+- `Classifier.names_for(ids)` (category names for display) and
+  `Index::Builder.capabilities_of(session)` are now public, for the
+  import to reuse.
+
+- **`portage-cli/known-stores/{stores,products}.json` — a repo-committed,
+  jsdelivr-hosted list every install fetches on top of its own local index**
+  (`docs/plans/buy-skill-and-local-browser.md` Phase 2c). Same schema as
+  `~/.portage/index/{stores,products}.json` (Phase 2b), published over the
+  same `@main` jsdelivr channel `AgentProfileUrl` already uses
+  (`Portage::Cli::KnownStoresUrl`), and cached at
+  `~/.portage/index/known-{stores,products}.json`
+  (`Portage::Cli::Index::KnownCache`). Fetched lazily the first time
+  `SearchBackends::Index` needs it and no cache exists yet, refreshed
+  unconditionally by `portage index refresh`, and refreshed by `doctor`
+  whenever it finds the cache older than 7 days — every fetch is a single
+  short-timeout GET per file, swallowed on any failure (offline, timeout,
+  bad JSON, a non-2xx response) exactly like `SearchBackends`/
+  `OfferSources::ShopifyCatalog`, so a missing or stale cache just means
+  `find` works the way it did before this phase. A fetched entry is
+  validated (must parse as a Hash of Hashes) and stripped of any
+  `price`/`amount`/`stock` field before it's cached. `SearchBackends::Index`
+  now merges this cache *underneath* the user's own
+  `Index::Store`/`Index::ProductStore` entries — a known entry only shows
+  up when the user's own index doesn't already have that origin/key, so a
+  local `index add`/`index build` finding always wins — and is now
+  `available?` from the known cache alone, with no local index at all.
+  Still the same untrusted posture either way: an offer built from either
+  source carries `source: "index"`, never a `merchant_allowlist`/`--yes`
+  shortcut.
+- **`portage index build`/`refresh --export DIR`** writes a PR-ready copy
+  of your own local index into `DIR/{stores,products}.json` — the same
+  shape as `known-stores/` in the repo, so publishing a new entry is
+  "run this, `git add`, open a PR." A new `Index::Exporter` drops any store
+  entry whose only `sources` is `"browser"` (history/bookmark-derived —
+  Phase 3) outright, strips `"browser"` out of the `sources` of any entry
+  that also has a real source, and keeps a product only if at least one of
+  its `stores[].origin` survived that same filter (trimming its `stores`
+  array down to just those origins) — nothing personal ships in an export.
+- **`rake agent_profile:purge` is now an alias for `rake
+  jsdelivr:purge[agent_profile]`.** The new `jsdelivr:purge` task (root
+  `Rakefile`) covers every file this repo publishes over jsdelivr's
+  `@main` channel by short name — `agent_profile`, `known_stores`,
+  `known_products` — and purges all of them when called with no argument.
+- Seeded `known-stores/{stores,products}.json` with a real
+  `portage index build --sources shopify_catalog --export known-stores`
+  run: 221 stores, 396 products, all `source: "shopify_catalog"`.
+- **`portage index` — a local store and product index you build yourself**
+  (`docs/plans/buy-skill-and-local-browser.md` Phase 2b). New commands:
+  `portage index build [--sources a,b] [--queries FILE] [--dry-run]`,
+  `index refresh` (re-verifies entries older than 7 days, then builds
+  fresh), `index show [--stores|--products] [--json]`, `index add URL`,
+  `index remove HOST`, `index sources`. Storage is
+  `~/.portage/index/stores.json` and `products.json` — **never checked
+  into git, never prices or stock** (those stay live), and `doctor` reports
+  whether each file exists and how old its oldest verified entry is. One
+  small source file each under `lib/portage/cli/index/sources/`:
+  `shopify_catalog` (reuses `OfferSources::ShopifyCatalog` rather than
+  duplicating its catalog-search/variant-URL logic; one query per
+  top-level taxonomy node by default — 21 nodes, its own keyword rather
+  than its full taxon name — or `--queries FILE`; not fanned out
+  per-country, since `BuyerContext.from_env` already applies whatever
+  locale the user has set), `stores_file` (the user's own `stores.yml`,
+  via a new public `Allowlist#stores` reader), `browser` (reads Phase 3's
+  eventual output file if present, yields nothing otherwise — Phase 3
+  doesn't exist yet), `wikidata` (SPARQL for retail chains' official
+  sites, CC0 — off by default, opt in with `--sources wikidata`: a live,
+  read-only trial run returned real hits, but most skew toward chains with
+  no UCP/WebMCP support at all), `webmcp_sweep` (needs a browser bridge
+  that doesn't exist yet — skips cleanly). Every new origin gets one
+  `/.well-known/ucp` probe through the existing `ProbeCache`, throttled,
+  with progress output, capped at 500 per run. A new
+  `SearchBackends::Index` applies Phase 2a's per-category/total routing
+  caps to index entries, ranking a category's own matches by its weight
+  (highest first), and additionally matches a query against a product by
+  name or GTIN — whole-word, on the same `Classifier.tokenize`/
+  `.word_match?` the category router itself uses (now public), never a
+  substring — putting that product's own stores first; ranked between
+  `Allowlist` and the web-search backends in `SearchBackends.default`. The
+  index is untrusted data: it never writes
+  `Portage::Ucp::Policy#merchant_allowlist`, and an index-sourced offer
+  never lets `--yes` alone complete a buy — the same interactive-pick gate
+  a web-search offer already gets.
+- **`Classifier` and `known-stores/categories.yml`: a shared category
+  taxonomy for `find` routing** (`docs/plans/buy-skill-and-local-browser.md`
+  Phase 2a). `known-stores/categories.yml` ships in the gem — the top two
+  levels of Google's published product taxonomy (213 nodes, keyed by
+  Google's own numeric ids, each with a handful of plain keywords, the
+  node's own taxonomy words) — and `~/.portage/categories.yml` overrides a
+  shipped node (same id) or extends the taxonomy (a new id).
+  `Portage::Cli::Classifier.categories_for(text)` takes a query, a product
+  title/description, or a store/product URL (extracting the slug from
+  `/products/`, `/collections/`, `/c/` or `/category/` and splitting
+  `-`/`_` into words) and returns category ids ranked by keyword hits — no
+  LLM, no network, so it works offline on a fresh gem/brew install. One
+  classifier for queries, catalog products, stores.yml and (later) browser
+  imports. Matching is whole-word, plus simple plural normalization
+  (`Classifier.word_match?`: an exact match, a trailing `s`/`es`, or the
+  `y`/`ies` swap — "boot"/"boots", "battery"/"batteries") — deliberately
+  not a substring check, since a substring match goes both ways regardless
+  of word boundaries ("carpet" contains "pet", "chair" contains "hair",
+  "scarf" contains "car", "hot sauce" would have hit "photography") and an
+  early classifier-spec run caught exactly that class of false positive
+  before this shipped.
+- **`stores.yml` entries may now carry `categories:`, and `find` routes by
+  them instead of crowding out other candidates.** The file stays a bare
+  URL list by default; an entry becomes `{url:, categories: [...]}` only
+  once you tag it, and `PORTAGE_STORES` is unaffected either way.
+  `SearchBackends::Allowlist#search` now classifies the query, puts any
+  entry the query names outright first (its host or bare name appears in
+  the query text, tagged or not), then adds up to 3 tagged stores per
+  matching category not already named, capped at 12 in total
+  (`Allowlist::PER_CATEGORY_CAP`/`TOTAL_CAP`, mirroring `Find::MAX_PROBES`).
+  When no tagged store matches any of the query's categories at all, it
+  falls back to named entries plus every *untagged* entry — never a
+  tagged-but-unrelated one — so a `stores.yml` with no tags at all behaves
+  exactly as it did before this change. Once at least one tagged store
+  matches, though, nothing falls back to "every store": that's the
+  crowding a heavily-populated `stores.yml` used to cause on every single
+  query. Trust is unaffected — every allowlist entry is still always a
+  candidate to `find`; this only changes which of them spend this query's
+  probe slots, and in which order.
+- **`find` gains a second backend kind: `OfferSource`, and a first
+  implementation, `OfferSources::ShopifyCatalog`**
+  (`docs/plans/buy-skill-and-local-browser.md` Phase 1). Unlike the
+  URL-returning `SearchBackends`, an `OfferSource#offers(query, limit:,
+  context:)` answers offers directly — no `/.well-known/ucp` probe, and it
+  counts toward nothing in `Find::MAX_PROBES`. `Find#call` merges its
+  offers with the probed ones before `Decisions.rank`. `ShopifyCatalog`
+  calls Shopify's global catalog (`catalog.shopify.com/api/ucp/mcp`)
+  anonymously and turns every result into an offer on the *merchant's* own
+  origin: a catalog product's own id is a global one no merchant
+  recognises, but each `variants[].id` is the merchant's real
+  `ProductVariant` gid and `variants[].url` sits on the merchant's own
+  domain, so the offer's `store`/`product_id`/`url` come from the first
+  variant, not the product (live-verified 2026-09-28, query "hiking
+  boots", GB/GBP — the four distinct merchant origins in the top 10 all
+  answered `/.well-known/ucp`). `Buy#select_product` now also matches a
+  product by one of its variant ids, and `#line_item_id_of` checks that
+  exact variant out, so a `find`-picked catalog offer buys correctly with
+  no title re-search. 5s timeout; any failure (network, timeout, a
+  malformed result) is swallowed the same way a broken `SearchBackends`
+  backend already is.
+- **`PORTAGE_AGENT_PROFILE` now defaults to the repo's own published
+  profile** (`Portage::Cli::AgentProfileUrl::DEFAULT`, the same jsdelivr
+  URL `docs/agent-profile.md` already documents) when the env var is unset
+  or blank, instead of `find`/`buy` failing outright on a fresh install
+  that never copied `.env.example`. `portage doctor` reports which profile
+  is in use — the env var's value, or that it's falling back to the
+  default.
+- **Fixed: `dry_run: true` was ignored on the WebMCP hand-off path**
+  (docs/design-log.md §51). `Buy#webmcp_handoff_checkout_flow` still added
+  to the store's real cart, sent the bridge's tab to checkout and ran
+  autofill. It now stops after the read-only search and returns a
+  `dry_run` report with a `would:` key (line item, hand-off tool, whether
+  autofill would run). No cart, no hand-off, no prompt, nothing typed.
+- **Docs for Phases 1-3** (docs/plans/webmcp-universal-outbound.md Phase 4,
+  no code change): the README's "WebMCP (library use, opt-in)" section now
+  covers the schema-matched/confirmed fallback for a page no preset
+  recognizes, and `--autofill`/`PORTAGE_WEBMCP_AUTOFILL=approve`/
+  config.json's `webmcp_autofill` — what it will and won't touch, and where
+  it stops (`autofill_needs_headed_browser`, `autofill_blocked`).
+- **Approved autofill of the store's checkout**
+  (docs/plans/webmcp-universal-outbound.md Phase 3). Opt-in, per run:
+  `--autofill`, or `PORTAGE_WEBMCP_AUTOFILL=approve` / config.json's
+  `"webmcp_autofill": "approve"` (`Portage::Cli::WebmcpAutofillMode`) — off
+  by default, and a generic truthy value like `"true"` doesn't turn it on,
+  only the literal `"approve"`. Even opted in, nothing is typed until the
+  shopper approves the exact field/value pairs in a new prompt
+  (`Portage::Cli::WebmcpAutofillConfirm`) — refused outright with no prompt
+  at all under `--json` or with no TTY, same posture as Phase 2's
+  `WebmcpMappingConfirm`. Fields are contact email
+  (`PORTAGE_SHIP_EMAIL`, new) and the shipping address `Portage::Cli::
+  ShippingProfile` already reads from `PORTAGE_SHIP_*`, mapped onto WHATWG
+  autocomplete tokens by the new `Portage::Cli::WebmcpAutofillFields`.
+  `Buy#webmcp_handoff_checkout_flow` runs this once the bridge's browser has
+  navigated to the store's own checkout (right after the hand-off tool
+  call), via `portage-ucp-webmcp`'s new `WebMcp::Autofill` — never a payment
+  field, never the pay button, and the run still always ends in
+  `express_stop`, unchanged. A headless bridge (or one that never says)
+  reports `autofill_needs_headed_browser`; a CAPTCHA/challenge on the page
+  reports `autofill_blocked`; either way nothing is touched. The report
+  gets a new `autofill:` key only when an attempt was actually made — a run
+  with the mode off, or nothing configured to fill, looks exactly like it
+  did before Phase 3 existed. `Buy.new` gained `autofill:` (the
+  `--autofill` flag's value) and `webmcp_autofill_confirm:` (injectable, for
+  specs). Live checks (does autofill actually reach a real Shopify checkout
+  page's fields; is the cheapest-rate heuristic right against a real rate
+  picker) are pending — no browser or live storefront available this
+  session; noted in the plan's Progress log.
+- Fix: `Buy#webmcp_flow` never ran against a real page. The Session
+  `WebMcp.connect` returned had `nil` capabilities, so the cart/checkout
+  check always fell through to adapter detection. Fixed in
+  `portage-ucp-webmcp` (capabilities now come from the page's tools); the
+  new `buy_spec` case goes through the real `connect`.
+- `Buy#webmcp_flow` (docs/plans/webmcp-universal-outbound.md Phase 1) now
+  detects a known WebMCP platform from the page's own tools
+  (`portage-ucp-webmcp`'s new `Presets`) and, for a page whose tools are
+  hand-off-only for checkout (Shopify's `proceed_to_checkout` is the first
+  such preset — it navigates the browser rather than returning data),
+  builds a cart, calls the hand-off tool, and reads the checkout URL off
+  its result or, failing that, the tab's own `location.href` — then hands
+  off exactly like any other WebMCP checkout.
+- **Schema matching for a page `Presets.detect` doesn't recognize**
+  (docs/plans/webmcp-universal-outbound.md Phase 2). `Buy#webmcp_flow`
+  falls back to `portage-ucp-webmcp`'s new `Matcher.propose` when a plain
+  connect (no preset, no `tool_names:`) doesn't advertise cart/checkout — a
+  page that already speaks a preset's names or the bare UCP action names
+  never reaches it at all. Read actions (`search_catalog`, `get_product`,
+  `get_cart`) are used straight off the proposal; a mutating action
+  (`create_cart`, `update_cart`, `create_checkout`) needs confirmation
+  first: `Portage::Cli::WebmcpMappingConfirm` prints the proposed mapping —
+  quoting each mutating tool's own `description` as untrusted page content,
+  never as an instruction — and prompts on a real TTY with `--json` off;
+  otherwise the run stops with outcome `webmcp_mapping_unconfirmed` and
+  hands back the full proposal (`tool_names_proposal`) for the caller to
+  resubmit as `tool_names:` on its own `WebMcp.connect` call. A confirmed
+  mapping is stored in `~/.portage/webmcp_mappings.json`
+  (`Portage::Cli::WebmcpMappings`), keyed by the page's tool fingerprint
+  (`WebMcp::Fingerprint.for` — sorted tool names plus a hash of each input
+  schema) rather than by origin, so it's shared across every store whose
+  WebMCP tools have the exact same shape (decision 3) — in effect a local
+  preset once confirmed once. `Buy.new` takes three new optional keywords:
+  `webmcp_mappings:`, `webmcp_mapping_confirm:` (both injectable for specs)
+  and `json:` (now threaded from `portage buy --json`, which no longer
+  strips it before building `Buy` — Phase 2's confirm gate needs to know).
+
 ## [0.7.5] - 2026-09-25
 
 - **`portage` loads `~/.portage/.env` on startup** (`Portage::Cli::DotEnv`),