Changelog¶
The root changelog below covers the workspace, shared docs, and anything spanning more than one gem. Each gem keeps its own changelog for its own API — linked rather than duplicated here:
portage-ucpportage-ucp-clientportage-ucp-decisionportage-ucp-journalportage-ucp-webmcpportage-cliportage-ucp-shopifyportage-ucp-wixportage-ucp-woocommerceportage-ucp-bigcommerceportage-ucp-magentoportage-ucp-etsyportage-ucp-instagram
Add your entry under the unreleased heading of every changelog your change affects — see Contributing § Changelogs.
Workspace changelog¶
Changelog¶
Repo-level changes — the workspace, its shared docs, and anything spanning more
than one gem. Each gem keeps its own CHANGELOG.md for its own API; look there
for changes to portage-ucp, an adapter, the client, or the CLI.
Format loosely follows Keep a Changelog; this project is pre-1.0, so APIs may still shift between minor versions.
[Unreleased]¶
- Docs caught up with release set 0.23.0. The
portage-ucp-clientAPI page and README cover the REST transport (connect(transport: :rest),Session#transport_name,Transports::Rest, and REST indiscoverand the error table), and the API pages nameportage-ucp-client0.8.0 andportage-ucp-decision0.1.2. The CLI JSON reference namesportage-cli0.16.0 and documentsorders list --json. The README's Docker example usesportage-mcp:0.16.0, and theportage-cliREADME says discovery works over REST too. The UCP 2026-08-25 plan is marked done.
[0.23.0] - 2026-11-18¶
- Release set:
portage-ucp-client0.8.0 andportage-cli0.16.0. Portage can now buy from stores that advertise only the UCP REST transport (UCP 2026-08-25's core transport), such as the sandbox in issue #178. The client picks MCP or REST from the manifest (MCP wins when both are offered), addsconnect(transport:)andSession#transport_name, andportage-cliworks with REST-only stores inbuyandfind, keeps a store's HTTP status and text in refusals, and sends the agent profile oncomplete_checkout.portage-clirequiresportage-ucp-client~> 0.8.portage-ucp, the adapter gems andportage-ucp-webmcp(whose client range already admits 0.8) are unchanged and not released, and thebuyand OpenClaw plugins didn't change. The rootDockerfileandserver.jsonpoint atportage-cli0.16.0; the store image andserver.store.jsonstay put. Live interop against the #178 sandbox is still to do, waiting on its test credential.
[0.22.0] - 2026-10-22¶
-
Release set:
portage-ucp0.17.0,portage-ucp-client0.7.0 andportage-cli0.15.0, all onmcp~> 1.8(was~> 0.24), which serves MCP spec 2026-07-28 throughserver/discoverand keepsinitializefor 2025-11-25 and earlier. Minor bumps because themcprequirement moved from 0.x to 1.x; the upgrade itself needed no code changes.portage-clinow requiresportage-ucp~> 0.17andportage-ucp-client~> 0.7, andportage-ucp0.17.0 also ships thelist_orderstool added since 0.16.0. The two MCP images and both registry entries point at the new releases. The adapter gems'portage-ucpranges already admit 0.17.0, so they are unchanged and not released, and thebuyand OpenClaw plugins didn't change. -
The root
Dockerfileis the buyer image; the store image moved toDockerfile.store. The rootDockerfileinstallsportage-cliand runsportage mcp(ghcr.io/tomtom87/portage-mcp, withPORTAGE_HANDOFF_TARGET=printsince a container can't open the shopper's browser). Glama builds the rootDockerfile, so it now lists the buyer server.server.jsonis the registry entryio.github.tomtom87/portagefor that image, taking the shopper's~/.portageas a mounted volume; the store server isio.github.tomtom87/portage-ucpinserver.store.json. Both images now run onruby:4.0-slim, and the store image installsportage-ucp-shopify0.7.0 (was 0.6.1). The README has a "Use Portage from any MCP client" section. -
The
serve-via-ucpskill's scripts sit besideSKILL.md.conformance.sh,detect_stack.sh,doctor.sh,install.shandverify.shmoved up out ofscripts/, so a registry that reads only a skill folder's top level, such as mcprush's repo import, gets the whole skill and can track it from git tags. The skill's steps now name the scripts without thescripts/prefix. Copies already installed keep working, since each one is self-contained. - The
buyskill's reference files sit besideSKILL.md.outcomes.mdandhandoff-only.mdmoved up out ofreferences/, so a registry that reads only a skill folder's top level, such as mcprush's repo import, gets the whole skill and can track it from git tags. The skill's links, the docs pages (nowdocs/skills/outcomes.mdanddocs/skills/handoff-only.md), the README install notes and the OpenClaw plugin's copy test follow the move. Copies already installed or published keep working, since each one is self-contained.
[0.18.0] - 2026-10-07¶
-
Release set:
portage-ucp0.13.0,portage-cli0.13.1,portage-ucp-shopify0.6.1, andportage-ucp-wix,portage-ucp-bigcommerceandportage-ucp-magento0.2.1.portage orders reconcilecan now settle a hand-off: it sends the agent profile a native UCP store requires, and the four adapters ask their platform whether a checkout the shopper paid in the browser became an order, through the newSupport::CheckoutStateplatform hook inportage-ucp0.13.0. Those four adapters now requireportage-ucp~> 0.13. A dry run of a store that escalates its checkout now saves a quote (dry_runwithhandoff_expected: true), so it can be approved underrequire_approval. WooCommerce has no order-to-cart link to look up, so its gem only gained a comment and stays at 0.3.0;portage-clikeepsportage-ucp~> 0.11. None of the platform order lookups has been tried against a live store yet (design-log §55). Thebuyand OpenClaw plugins didn't change and stay at 0.10.5. -
README:
shop-researchis on ClawHub. The OpenClaw bullet said it wasn't published yet; it links to the@tomtom87/portage-shop-researchlisting now.
[0.17.0] - 2026-10-05¶
-
Release set:
portage-ucp0.12.0,portage-cli0.13.0,portage-ucp-shopify0.6.0,portage-ucp-woocommerce0.3.0,portage-ucp-wix,portage-ucp-bigcommerce,portage-ucp-magentoandportage-ucp-instagram0.2.0, plus thebuyplugin and the OpenClaw plugin@tomtom87/portage0.10.5. Mostly the over-engineering cleanup: dead public methods and constants removed (minor bumps, each one marked breaking in its gem's changelog), duplicated helpers shared, andportage browser importreading history through thesqlite3gem instead of thesqlite3CLI. Fixes:Security::Signatureanswers a malformed trusted JWK with a 401 instead of a 500, andpayment enroll's own-store fallback finds the session again and follows homepage redirects. Thebuyplugin drops its raw-UCP direct-checkout fallback (see below). Dependency ranges are unchanged;portage-clistill takesportage-ucp~> 0.11.portage-ucp-client,portage-ucp-webmcpandportage-ucp-etsychanged only in docs, comments or internals, so they stay unreleased. The ClawHub listings are published separately. -
Security: the
buyskill no longer has a raw-UCP direct-checkout fallback. Found by ClawHub's security audit of theportage-buyskill 0.10.4, which flagged its "No CLI available" section (Description-Behavior Mismatch and Context-Inappropriate Capability, both medium): withportagemissing, it had the agent create and pay a store's checkout over raw UCP/MCP itself (references/raw-ucp.md), outside the CLI's spending policy, approval and checkout-mismatch checks the rest of the skill relies on. That section now tells the agent to ask the user to install or upgradeportageand stop, and never to drive a store's endpoint, cart, checkout or payment with a shell, web fetch or browser, the same stop the OpenClaw plugin's copy already had.references/raw-ucp.mdand its docs page are gone; buying over raw UCP stays in the standaloneshop-via-ucpskill. The OpenClaw plugin's build no longer has a file to leave out, and a test checks the source skills carry no direct-checkout path. Thebuyplugin and the OpenClaw plugin move to 0.10.5 for the republish. -
One shared
examples/portage_ucp.rb, inportage-ucp. The seven adapter gems each carried a byte-identical copy (apart from thebundle execline in a comment). The single copy now lives atportage-ucp/examples/portage_ucp.rb, with a generic usage comment; the adapter exes' header comments, the Etsy and Instagram READMEs, the root README and the adapter docs link to it on GitHub, and the Etsy and Instagramexe_specs load it from there. The files were never in a gem'sfileslist, so no gem contents change. -
Retired four finished plans from
docs/plans/.woocommerce-fixes,woocommerce-local-validation,openclaw-pluginandhomebrew-distributionwere done and nothing built on them. They are deleted, and the references to them (the root and gem changelogs, the WooCommerce README,script/homebrew-formula, comments inportage-cli) now point at permalinks at commit d51200f, where the files can still be read.docs/design-log.mdhas an index entry saying so. -
One shared RuboCop config for the seven adapter gems. Their
.rubocop.ymlfiles were the same apart from each gem'sMetrics/ModuleLengthandMetrics/ClassLengthexemptions. The shared part now lives in.rubocop-adapter.ymlat the repo root, and each adapter's.rubocop.ymlinherits it and keeps only its own exemptions. What RuboCop checks is unchanged. -
OpenClaw plugin: small tidy-ups, no behaviour change.
DEFAULT_CONFIGis no longer exported fromsrc/config.ts(nothing imported it),createRunnertakes the sharedPortageConfigtype, andscripts/copy-skills.mjsdrops a redundantmkdirSync(cpSyncalready creates the target).
[0.16.2] - 2026-10-01¶
-
Release set:
buyplugin 0.10.4 and the OpenClaw plugin@tomtom87/portage0.10.4, for the ClawHub security audit fixes below (0.10.3 shipped the runner change on its own). Thebuyandshop-researchskills are reworded, with no instruction changes. No gem changed. -
Security: the OpenClaw plugin runs
portagethrough OpenClaw's own command helper. ClawHub's security audit of@tomtom87/portage0.10.2 still reported the runner'schild_process.execFilecall as shell execution (suspicious.dangerous_exec). The runner now hands the argument array toapi.runtime.system.runCommandWithTimeout, the helper OpenClaw gives plugins for running a native command, which always spawns without a shell, so the plugin has nochild_processcode of its own. It still only starts aportageBinnamedportage, with the per-call timeout, the 16 MB output cap and the same error messages; output past the cap is now a plain error, andportagegets an empty stdin. The helper caps output only from OpenClaw 2026.5.28, so that is the plugin's new minimum (was 2026.3.24). Tests run the runner against OpenClaw's real helper. The package README's safety model and the docs page say so. The plugin and thebuyplugin move to 0.10.3 for the republish; thebuyskills change only in theirversion. - Security: the
buyandshop-researchskills are reworded so ClawHub's audit stops misreading them. ClawHub's SkillSpector audit of@tomtom87/portage0.10.2 flagged the bundled skills' text, not anything they do:chmod 600read as root execution,~/.portage/.envfollowed by a space and the words "access token" read as credential theft, a regex running from "write UI code" to a later~/.portagepath read as session persistence, and the hard rule's quoted"ignore previous"example read as tool-metadata poisoning. The skills now say the file must be readable only by the user (file mode600), put the path in backticks in every env var description, call the Etsy and eBay tokens OAuth tokens (and Amazon's an API token), say the payment credential lives in the OS's secure credential store, and describe the injection example instead of quoting it;requires.configis a flow list with the same two paths. Thebuydescription now triggers only on an explicit buy, order or reorder request (with examples), Portage setup or order tracking, and names what it isn't for, after the audit called its trigger too broad. No instruction changes. Thebuyplugin and the OpenClaw plugin move to 0.10.4 for the republish.
[0.16.1] - 2026-10-01¶
- Release set:
buyplugin 0.10.2 and the OpenClaw plugin@tomtom87/portage0.10.2. The OpenClaw plugin now declares theintegrationscategory, so its ClawHub listing moves out of Other. Thebuyskills change only in theirversion(the OpenClaw plugin's version follows thebuyplugin's). No gem changed.
[0.16.0] - 2026-10-01¶
-
Release set:
buyplugin 0.10.1 and the new OpenClaw plugin@tomtom87/portage0.10.1, whose version follows thebuyplugin's. The OpenClaw plugin carries the ClawHub security audit fixes below: no raw-UCP direct-checkout fallback in its bundledbuyskill, and a runner that only startsportage. Thebuyplugin's skills change only in theirversion(kept equal toplugin.json). No gem changed. Both ClawHub listings are published separately, from thetomtom87account. -
New: an OpenClaw plugin,
openclaw-plugin/(@tomtom87/portage). A native OpenClaw plugin that gives an agent 23 typedportage_*tools over theportageCLI (arguments passed as an array, never a shell), where the ClawHub skill left the agent to putportagecommands together from the skill text. Thirteen read-only tools are on by default; the ten that price, approve, buy, hand off, open a browser or edit the index are opt-in. Portage's own policy still decides every payment: no tool passes--yesfor a URL or an offer,portage_approverelays a yes only when told the user gave it, and policy, payment,setupand history clearing are not exposed (guardrail tests pin this). It bundles thebuyandshop-researchskills, copied at build time, plus a shortportage-openclawskill mapping each buy step to its tool, declares anoutputSchemafor the common results, and needsportage-cli0.12.0 or newer (checked once per session). Its version follows thebuyplugin's, andrake openclaw:release_check(version match plus annpm pack --dry-runfile check) runs insiderake release_checkandrake publish_all. A docs page, a README bullet and the package README describe it. Not yet exercised against a live OpenClaw gateway, and not yet published to ClawHub. -
Security: the OpenClaw plugin no longer ships a direct-checkout fallback, and only ever starts
portage. Found by ClawHub's security audit of@tomtom87/portage0.10.0. The build's copy of thebuyskill now leaves outreferences/raw-ucp.md(the "no CLI" fallback, where the agent creates and completes a store's checkout over raw UCP itself, outside Portage's policy, approval and checkout-mismatch checks) and replaces that section with a stop: installportage, never drive a store's checkout or payment by hand.portage-openclaw(now 0.1.1) says the same. The runner, the plugin's onechild_process.execFilecall, already ran without a shell; it now also refuses anyportageBinthat doesn't name theportageexecutable, and the manifest's config schema carries the same pattern. Tests pin both, and the package README's safety model and the docs page explain thechild_processuse the scan reports. Thebuyplugin's own skill is unchanged.
[0.15.0] - 2026-10-01¶
-
Release set:
portage-cli0.12.0 (a checkout mismatch now stops every purchase and every WebMCP hand-off, the opt-in confidence check is hardened and runs before every WebMCP hand-off, andfind --storesearches one store live),portage-ucp-decision0.1.2 (a backend answer that isn't a probability now raisesBackendError, so the purchase is held) andbuyplugin 0.10.0 (the hardened decision check, theshop-researchskill, narrower triggers, andfind --storere-checks;plugin.jsonand both skills'versionkept equal).portage-clikeepsportage-ucp~> 0.11and its optionalportage-ucp-decision. The skills' minimumportage-clistays 0.9.0, with the new features gated on 0.12.0 and the older-install fallbacks kept. No other gem changed, so the docs-only notes inportage-ucp-clientandportage-ucp-webmcpstay unreleased. The ClawHub listing is published separately, atbuy0.10.0. -
The
buyandshop-researchskills re-check an index hit withportage find --store URL --query .... That command now exists (seeportage-cli's changelog), so the live re-check searches only the store the hit came from instead of re-running a cross-storefind.shop-researchlists it as a read-only command, and both skills fall back tofind --querywhenportage find --helpdoesn't list--store. The CLI JSON reference, README and local-catalogue plan name the same command. -
Security: the
buyskill describes the hardened decision check. Followsportage-cli's andportage-ucp-decision's changes (see their changelogs): an extra priced line is now a checkout mismatch, the opt-in confidence check sends an allowlisted checkout summary and compares against the approved quote, it also runs before every WebMCP hand-off (a preset's own tool, or a page whose tools build a checkout), and a malformed backend answer holds the purchase. The skill now suggests the check for unattended buying, says it sends TypeSafe a minimal checkout summary and never the address or payment token, and that the user setsJEV_API_KEYthemselves; it declaresPORTAGE_DECISION_BACKEND,PORTAGE_MIN_CONFIDENCEandJEV_API_KEYin its OpenClawenvVars, and the packaging spec now checksJEV_/TYPESAFE_names too.references/outcomes.md,docs/api/cli-json.md,docs/plans/system-one-decision-layer.mdandportage-cli's README say so. -
Security: the
buyskill no longer describes a fail-open checkout mismatch. Followsportage-cli's change (see its changelog): any checkout mismatch now stops a real purchase before payment, with no setting to turn that off.references/outcomes.md, the skill's dry-run and buy steps,docs/agentic-flow.md,docs/api/cli-json.mdandportage-cli's README say so, document the dry run's newcheckout_mismatch: trueflag, and markPORTAGE_ABORT_ON_CHECKOUT_MISMATCHdeprecated and ignored. The skill drops it from its OpenClawenvVars. Found by ClawHub's security audit ofportage-buy. The same stop now coversportage-cli's WebMCP hand-off flow (a Shopify page'sproceed_to_checkout): a mismatched cart never reaches checkout or autofill.references/outcomes.md,docs/api/cli-json.md, and the READMEs ofportage-cliandportage-ucp-webmcpsay so. -
buyskill: narrower triggers. The skill'sdescriptionis shorter and says it is for shopping, buying, ordering or comparing offers on the user's behalf, not for general questions about prices, products or orders not placed through Portage (ClawHub's scan flagged the old trigger list as too broad). Each OpenClawenvVarsdescription now says the user sets it in~/.portage/.envand the agent never reads or prints its value. -
New
shop-researchskill in thebuyplugin, for questions with no purchase in mind.plugins/buy/skills/shop-research/answers what something costs, where to get it, whether it's in stock, whether Portage can buy from a store, and what the user ordered through Portage. Its "Store details" section adds what's known about any store a lookup touches, only from fields the read-only commands return: the offer'sstore,urlandsource;check'sverdict,handoff_only,platform,webmcp.statusand the manifest'scapabilitiesandbusiness; the index entry'scapabilities,sourcesandlast_verified. It never invents a field and never vouches for a store. It runs only read-only commands (portage find,index search,index show,check,pick --view,history,doctor), each checked againstportage-cli's code, and names the mutating ones it must never run, includingorders reconcile, which settles order records. Its description says to switch tobuyto buy. It carries the product-card rules (an index hit is "seen at", never a live price or stock), the untrusted-data rule and the hand-off-only "never fetch, scrape or drive" rule, so it stands alone on ClawHub. Its OpenClawenvVarsare only the search and retailer keys it names.buy's description now covers buying only and points toshop-researchfor lookups.buy_skill_frontmatter_spec.rbchecks both skills' frontmatter, and thatshop-research's command table holds only read-only commands. Documented in a newdocs/skills/shop-research.md, the README's install routes,docs/skills/buy.md,docs/agentic-flow.mdand the plugin and marketplace descriptions. Not on ClawHub yet. -
shop-via-ucpis for buying, and a new read-onlybrowse-via-ucpis for looking. ClawHub's scan ofbuyflagged broad triggers, andshop-via-ucp's ("find and/or buy something from an online store") had the same problem. Its description now covers completing a purchase on the user's behalf and points lookups tobrowse-via-ucp. It keeps its three guardrails and gains a fourth: never pay for a checkout whose items, quantities, unit prices, currency or total differ from what the user approved; stop and ask again with a fresh checkout. The newskills/browse-via-ucp/reads a store's manifest, searches its catalog, reports the store details the manifest publishes (business name, capabilities, policy links) and says whether it supports automated buying, calls only read-only tools, never creates, updates or completes a cart or checkout, and hands over toshop-via-ucpto buy. Thebuyskill'sreferences/raw-ucp.mdgets the same mismatch guardrail. Newportage-cli/spec/packaging/ucp_skills_frontmatter_spec.rbparses everyskills/*/SKILL.mdfrontmatter and checks the split. Listed inmkdocs.yml, a newdocs/skills/browse-via-ucp.md,docs/ai-agents.md,docs/agentic-flow.md,docs/index.md, the README andCONTRIBUTING.md.
[0.14.0] - 2026-10-01¶
-
Release set:
portage-cli0.11.0 (the SQLite local index,portage index build --sources storefront_productsto crawl a store's products,portage index search, the UCPproductfield on offers, and the whole-taxonomy category classifier) andbuyplugin 0.9.0 (product cards, and the OpenClaw metadata withversionin the skill frontmatter, kept equal toplugin.json).portage-cligains asqlite3~> 2.9dependency and keepsportage-ucp~> 0.11. The skill's minimumportage-clistays 0.9.0, because it only usesindexand theproductfield when they are there. No other gem changed, so the docs-only notes inportage-ucp-clientandportage-ucp-webmcpstay unreleased. The ClawHub listing is published separately, atbuy0.9.0. -
README: OpenClaw on ClawHub. A static "OpenClaw skill" badge in the badge row links to the ClawHub listing (
tomtom87/portage-buy; ClawHub has no official badge endpoint), and the OpenClaw bullet in "Other agents" now documentsopenclaw skills install @tomtom87/portage-buyandclawhub install @tomtom87/portage-buyalongside the manual copy route, replacing "planned but not published". The docs site picks it up through the existing include ondocs/skills/buy.md. The listing goes live whenbuy0.9.0 is published. -
README: Omarchy install steps. The Omarchy bullet now installs with Omarchy's own helper (
omarchy-mise-install gem:portage-cli portage), says a stock Omarchy needssudo pacman -S --needed makefirst (gccalready arrives throughclang; onlymakeis missing), and lists the skill directories Omarchy links its own skills into (~/.agents/skills,~/.claude/skills,~/.codex/skills). Checked against Omarchy8b4eae6and an Omarchy-like Arch container, seedocs/plans/local-catalogue.md. -
buyskill: OpenClaw metadata, one skill.plugins/buy/skills/buy/SKILL.mdfrontmatter gainsversion(kept equal toplugins/buy/.claude-plugin/plugin.json) and ametadata.openclawblock:requires.bins: [portage],requires.config, a brewinstallspec,homepage, and anenvVarsentry (allrequired: false) for every env var the skill and its references name, which is what ClawHub's metadata-mismatch scan checks. A new spec (portage-cli/spec/packaging/buy_skill_frontmatter_spec.rb) fails if the frontmatter stops parsing, the version drifts from the plugin, or an env var is named without being declared. README's "Other agents" block gains OpenClaw and Omarchy notes. Nothing is published to ClawHub. -
buyskill: product cards. A new section on showing offers as product cards from the offer'sproductfield (image, title, price or range, store, key options, link), host-agnostic, and on treatingindex searchhits (live: false, no price) as seeds to re-fetch live. Documented indocs/api/cli-json.mdanddocs/agentic-flow.md. Code is inportage-cli's changelog.
[0.13.0] - 2026-09-29¶
-
Release set:
portage-cli0.10.0 (portage check URL [--json]: can Portage buy from this store, and how),portage-ucp0.11.0 (Ucp::Checkfollows a homepage<link rel="ucp">manifest pointer, asbuydoes, and reportsmanifest_url), andbuyplugin 0.8.0 (a "Can Portage buy from this store?" step usingportage check, gated onportage --helplisting it).portage-clinow requiresportage-ucp~> 0.11. The docs-only notes inportage-ucp-clientandportage-ucp-webmcpstay unreleased. -
portage checkdocumented in thebuyskill,docs/checking-any-store.md, the CLI tutorial anddocs/api/cli-json.md. Code and details are inportage-cli's changelog.
[0.12.0] - 2026-09-29¶
-
Release set:
portage-cli0.9.0 (human pick and approve,docs/plans/human-pick-and-approve.mdPhases 1-3: offer refs andbuy --offer, priced quotes andbuy --quotewithquote_changed,portage pick,portage approve, product-page viewing andpolicy set --require-approval). Under the defaultrequire_approval: any, abuy --yeswithout an approved--quotenow dry-runs and returnsneeds_approvalinstead of buying;portage policy set --require-approval off, run from a terminal, restores the old behaviour.buyplugin 0.7.1 namesportage-cli0.9.0 as the release that shipspickandapprove. The docs-only[Unreleased]notes inportage-ucp,portage-ucp-clientandportage-ucp-webmcpstay unreleased: no code changed there. -
buyplugin 0.7.0: the person picks the store and approves the total throughportage. The skill's steps 3 and 5 now useportage pick --jsonandportage approve QUOTE_ID --json. Onneeds_pickit showschoices[]with a link to each product page (Claude Code'sAskUserQuestionwhen there is one, else a numbered list) and relays the answer withpick --choose REF. It then dry-runs withbuy --offer REF, shows the total and the product link, and relays a yes withapprove QUOTE_ID --relayed-yes. Underportage policy set --require-approval personit doesn't relay: it asks the person to runportage approve QUOTE_IDin their own terminal. It buys withbuy --quote QUOTE_ID --yesand handlesquote_changed.references/outcomes.mdgainsneeds_pick,picked,cancelled,needs_approval,approved,viewed,view_refused,no_terminal,search_not_found,offer_not_found,quote_not_found,quote_usedandquote_changed, and the exit codes. It needs theportage-cliwithpickandapprove(unreleased; seeportage-cli/CHANGELOG.md), not the released 0.8.0. The docs cover the same:docs/api/cli-json.md(pick,approve,--via, quotes, the new outcomes, the policy),docs/agentic-flow.md(the loop, tools and checklist),docs/skills/buy.md,docs/cli-usage-tutorial.md, and the usage banners in both READMEs. Upgrade note: under the default--require-approval any, abuy --yeswithout an approved--quoteno longer buys. It dry-runs and returnsneeds_approval. Restore the old behaviour withportage policy set --require-approval offfrom a terminal.personraises the bar but isn't a hard guarantee: an agent with a shell can edit~/.portage/policy.jsonor the quote files, or run its own terminal. -
Stale docs cleanup.
portage-cli's andportage-ucp-webmcp's READMEs no longer say awebmcp_mapping_unconfirmedproposal can be passed back. No flag orBuykeyword takes one. From the CLI, re-run in a real terminal without--json(--dry-runis enough) and the approved mapping is saved to~/.portage/webmcp_mappings.json. From Ruby, injectwebmcp_mapping_confirm:orwebmcp_mappings:, or passtool_names:toWebMcp.connect.docs/well-known-ucp.mdnow shows the nested manifest Shopify serves at"version": "2026-08-25", trimmed from a live store's. Cart and catalog are advertised there, so the only gap left is signing.Client.ucp_section's comment no longer saysPortage::Ucp::Manifestemits the flat shape, and says why the flat fallback stays.docs/security-hooks.mdanddocs/api/portage-ucp.mdnow say thatlist_payment_methodsandlist_addressesskip the authenticator and rate limiter by design, becauseoauth_token:guards them. -
buyplugin 0.6.3, and a strict docs build again.references/outcomes.mdnow matchesportage-cli0.8.0. It drops thewebmcpimport verdict, which the CLI never produces. It says what to do onwebmcp_mapping_unconfirmed: no flag passes a mapping back, so the user confirms it in their own terminal.checkout_mismatchonly happens underPORTAGE_ABORT_ON_CHECKOUT_MISMATCH, and the payment, policy and confidence gates only run on--yes. It also covers which buyshistoryrecords with anoutcome,invalid_option, and exit codes (handoff_onlyexits1). The docs site gets a page for each of the skill's reference files, so the skill's own relative links resolve there andmkdocs build --strictpasses.docs/api/portage-ucp.mdanddocs/security-hooks.mdnow say howMcp::Server.build's defaultConfirmer::Terminalbreakscomplete_checkoutover stdio. -
Docs site pass. New home page, a rewritten quickstart, an agentic flow tutorial (the
buyskill, your own loop aroundportage --jsonwith the approval gate in code, and direct UCP/MCP), and an API reference section: CLI JSON output,portage-ucp,portage-ucp-client,portage-ucp-decision,portage-ucp-journalandportage-ucp-webmcp, each checked against the source. Fixes thesite_url, theportage-ucp-clientdiscover examples (HTTP needsmeta: { agent_profile: }and returns hashes), and the claim that AP2 mandates are shape-checked only. -
README rewrite. Opens with what Portage does, then installing the
buyplugin (/plugin install buy@portage), adding it to other agents with dotagents or as a plain skill, and a firstfind/buy --dry-run. Adds a Safety section, merges the doc map and gem list into one table, syncs the usage banner withportage --help, and moves the proxy env-var caveats (corrected against the code) intodocs/proxy.md. The docs site's buy page now pulls its install steps from the README. -
buyplugin 0.6.2. The skill's minimum version is nowportage-cli0.8.0 (plusportage-ucp-webmcp0.2.0 for the browser profile and autofill), which shipped in 0.11.0. It still checksportage --helpbefore using newer commands, so older installs keep working.
[0.11.0] - 2026-09-29¶
-
Release set:
portage-cli0.8.0 (Phases 1-7 ofdocs/plans/buy-skill-and-local-browser.md: offer sources and the Shopify Catalog, categories and routing caps, the local store index and known-stores list, browser import, thesetupwizard, hand-off targets and hand-off-only hosts, the Portage browser profile and retailer offer sources),portage-ucp-webmcp0.2.0 (WebMCP Phases 1-4: platform presets, schema matching, approved checkout autofill), and patch releases ofportage-ucp-bigcommerce,-etsy,-magento,-wix(0.1.5) and-woocommerce(0.2.2), whose exes crashed at launch.portage-clineedsportage-ucp-webmcp0.2.0 or newer for its WebMCP paths and treats an older install as absent. -
Docs +
buyskill release (docs/plans/buy-skill-and-local-browser.mdPhase 8, the plan's last phase). Documents everything Phases 1-7 shipped — offer sources/Shopify Catalog, categories/Classifier, the local store index (portage index build/refresh/show/add/remove/sourcesand the repo's published known-stores list),portage browser import, theportage setupwizard,--handoff-target default|print|profile|agent: <name>, hand-off-only hosts (Tier C) and the as-is/MIT disclaimer, andportage browser profile init|open|status— in the root README, the CLI reference (portage-cli/README.md, single-sourced into the site),docs/cli-usage-tutorial.md, and a newdocs/skills/buy.mdpage (added tomkdocs.yml's nav).skills/shop-via-ucpnow points to the fullerbuyplugin for hosts with a plugin system.plugins/buy/.claude-plugin/ plugin.jsonbumped to0.6.1; the skill states the minimumportage-cliversion its references assume.docs/design-log.mdgains entry 52 on the three tiers and why Tier C is hand-off only (Amazon's Conditions of Use and its 2025 suit against Perplexity, and that a user-edited host list only ever changes the message — there's no automation code for a site without UCP or WebMCP for removing a host to unlock). The clean-session/buydry run the plan's own Phase 0/8 checklist calls for still needs an interactive Claude Code session this environment doesn't have — left pending, same as Phase 0's note. - Retailer offer sources, hand-off only (
docs/plans/ buy-skill-and-local-browser.mdPhase 7 — full change is inportage-cli/CHANGELOG.md). Five official, opt-in buyer-side retailer APIs (Walmart Affiliate, eBay Browse — Buy It Now only, Best Buy Products, Etsy Open API v3, Amazon Creators) joinOfferSourcesalongsideShopifyCatalog, each gated on its own key. Every offer they return still ends in hand-off — none completes a purchase, and none of them is ever written into the local index. Amazon already routed through the existing Tier C hand-off-only path; walmart.com/ebay.com/ bestbuy.com now do too (unconditionally — no adapter, no UCP), and so does etsy.com unless the process already has its own Etsy seller credentials configured, in which caseportage-ucp-etsy's existing adapter flow still applies.portage setupgains an eighth wizard step for the five keys;portage doctorreports which are active. Open question 3 (one gem per retailer vs. oneportage-ucp-retailgem) is resolved: kept inportage-cli'sOfferSources.plugins/buy/ .claude-plugin/plugin.jsonbumped to0.6.0. - Hand-off targets + hand-off-only hosts, and the
buyskill knows both (docs/plans/buy-skill-and-local-browser.mdPhase 5 — full change is inportage-cli/CHANGELOG.md).portage buy --handoff-target default|print|profile|agent:<name>decides where a dead-end checkout URL goes, including an approved external agent invoked by command or webhook with the same cart-summary payload--notify-webhooksends. Amazon (every marketplace) and any host in the user'shandoff_only_hostsconfig are hand-off only:portage buyreturnshandoff_onlywithout ever sending that host a request, andfind/index build/browser importnever probe one either.portage doctorandportage setup's Hand-off step both surface the current target, the hand-off-only list and the as-is/no-warranty disclaimer.plugins/buy/skills/buy/SKILL.md,references/outcomes.mdandreferences/handoff-only.mdupdated;plugins/buy/.claude-plugin/ plugin.jsonbumped to0.4.0.claude plugin validate .andclaude plugin validate plugins/buystill pass. portage setupinteractive wizard, and thebuyskill knows it's human-only (docs/plans/buy-skill-and-local-browser.mdPhase 4 — full change is inportage-cli/CHANGELOG.md).portage setupnow runs a seven-step wizard on a TTY (shipping, search keys, agent profile, browser import, local index, spending caps, hand-off);doctor/configureoffer it too, but only on a fresh install with nothing configured at all.--jsonor no TTY stays exactly today's read-only doctor report either way.plugins/buy/skills/buy/SKILL.mdnow tells the agent to suggest the user runportage setupthemselves rather than drive it, and that under--json/no TTY it's the same report asportage doctor --json.plugins/buy/.claude-plugin/plugin.jsonbumped to0.3.1.claude plugin validate .andclaude plugin validate plugins/buystill pass.- Browser import (Tier A) and the
buyskill'sbrowser importsteps (docs/plans/buy-skill-and-local-browser.mdPhase 3 — full change is inportage-cli/CHANGELOG.md).portage browser importturns the user's own bookmarks and history into shop-domain index entries: allowed history/bookmark files only (never password, cookie or autofill stores), one/.well-known/ucpprobe per unknown domain (at most 200), shown to the user and saved only on a TTY "y" or an explicit--yes, and never exported.plugins/buy/skills/buy/SKILL.md's browser-import bullet now walks the agent through dry-run → show the list →--yesonly after the user approves, and what to do with a Full Disk Access / permission error;references/outcomes.mdgains aportage browser import --jsontable.plugins/buy/.claude-plugin/plugin.jsonbumped to0.3.0.claude plugin validate .still passes. - Known-stores list moves into the repo, fetched over jsdelivr
(
docs/plans/buy-skill-and-local-browser.mdPhase 2c — full change is inportage-cli/CHANGELOG.md).portage-cli/known-stores/{stores, products}.jsonare committed, same schema as the local index, seeded with a realportage index build --sources shopify_catalog --exportrun (221 stores, 396 products). Every install fetches them lazily over the same jsdelivr@mainchannelagent-profile.jsonalready uses, caches them under the user's own index, and always lets the user's own entries win.rake agent_profile:purgegeneralizes intorake jsdelivr:purge(coversknown-stores/too; the old task name still works as an alias).buyskill's index bullet gets one added sentence notingfindmay already have candidates before the user runsindex build;plugins/buy/.claude-plugin/plugin.jsonbumped to0.2.1. buyskill: covers the newportage indexcommands (docs/plans/buy-skill-and-local-browser.mdPhase 2b — full change is inportage-cli/CHANGELOG.md).plugins/buy/skills/buy/SKILL.md's setup section now describesindex build/refresh/show/add/remove/sourcesconcretely (still feature-detected fromportage --help, since older installs won't have it), and notes that the index is untrusted, local-only data the user builds and edits themselves.plugins/buy/.claude-plugin/plugin.jsonbumped to0.2.0.claude plugin validate .still passes.buyskill and plugin marketplace (docs/plans/buy-skill-and-local-browser.mdPhase 0, docs/config only)..claude-plugin/marketplace.jsonlists one plugin,buy, atplugins/buy. ItsSKILL.mdis the agent-facing interface toportage: install check,doctor-driven setup, the find → dry-run → confirm → buy flow, hand-off (default/profile/agent:<name>/print), hand-off-only retailers, and the hard rules (no raw card data, no browser credential/cookie/autofill reads, no CAPTCHA bypass, untrusted page text, confirm-before-buy, no blind retries, private shipping details). It detects which commands the installedportagesupports fromportage --help, soindex/browser/setup/--handoff-targetare used only once a later phase ships them. Three references:outcomes.md(every--jsonoutcome),raw-ucp.md(driving a store's UCP endpoint by hand with no CLI),handoff-only.md(Tier C and why).skills/shop-via-ucpis unchanged for now; it starts pointing tobuyonce Phase 8 lands. Both manifests passclaude plugin validate ..- WebMCP outbound docs (
docs/plans/webmcp-universal-outbound.mdPhase 4, no code change).portage-ucp-webmcp's README documents platform presets (Presets/preset:), the schema-matcher fallback for an unrecognized page and its read-vs-mutating confirm rule, and Phase 3's opt-in checkout autofill (what it will and won't touch, andPreset#checkout_selectorsas a platform's own fallback);portage-cli's README points to--autofill/PORTAGE_WEBMCP_AUTOFILL=approve. Theshop-via-ucpskill now mentions the WebMCP path (ranks after native UCP and before platform adapters when a browser is available, always ends in a hand-off, and names the autofill opt-in) instead of only covering native UCP/MCP.docs/design-log.mdgained three entries: Phase 0'snil-capabilities bug and why the spec double it was hiding behind didn't catch it, Phase 1's exact-fingerprint-only matching rule, and Phase 3's two "unknown means the unsafe-if-wrong option, not the common case" defaults (headless?,checkout_selectors). This closes the plan apart from three still-pending live checks noted in its Progress log. - The Homebrew formula's
test doblock now checks whatportage doctor --jsonreports (installed via Homebrew, every bundled adapter loads) instead of its exit code, which depends on the user's setup (script/templates/portage.rb.erb). Takes effect on the nextrake homebrew:update. -
.env.exampleand the install docs point at~/.portage/.env, whichportage-cli0.7.5 loads on startup. -
Homebrew-first install docs (plan Phase 4). The README, quickstart, CLI tutorial and
portage-cliREADME listbrew install tomtom87/portage/portagefirst andgem install portage-clisecond, with upgrading, Linuxsecret-tool, and PATH shadowing covered. The README now shows the fullportageusage block under the quickstart in place of the shorter "Other CLI commands" list, and the docs site's quickstart includes the same block fromportage-cli/README.md. The CLI reference moved under "Getting started", above the CLI usage tutorial. .env.examplelists thePORTAGE_SHIP_*shipping address,PORTAGE_CURRENCY/PORTAGE_LANGUAGE, and the search-backend keys.- Fixed three doc links that made
mkdocs build --strictfail (links fromdocs/to files outside it), and refreshed the stale gem version tables.
[0.10.0] - 2026-09-25¶
- Proxy support across every gem (
docs/plans/proxy-support.mdPhases 0-3). Core gainsSupport::Connection,Support::ProxyConfig,Support::PassthroughContextandRack::ForwardedRequest; the CLI gains--proxy*flags,PORTAGE_PROXY*env vars, aproxysection inconfig.jsonand proxy checks indoctor. The release set isportage-ucp0.10.0,portage-ucp-client0.6.3,portage-ucp-webmcp0.1.1,portage-ucp-decision0.1.1,portage-cli0.7.3,portage-ucp-shopify0.5.1 andportage-ucp-instagram0.1.5. Every gem that calls the new core APIs now requiresportage-ucp~> 0.10, andportage-clirequiresportage-ucp-client>= 0.6.3. Their old floors let them resolve against published gems that lacked those APIs. - Documentation only, no code change. Fixes a
NoMethodError-shaped bug repeated in every bundled adapter'sexe/(portage-ucp-shopify/-wix/-woocommerce/-bigcommerce/-magento) and in the root README's "Usage" snippet: each called.starton the plainMCP::ServerMcp::Server.buildreturns, but that class (mcp gem 0.25.0) has no#start— onlyMCP::Server::Transports::StdioTransport#openreads stdio frames. See each affected gem's own CHANGELOG for its fix and newexe_spec.rb.
[0.9.0] - 2026-09-23¶
- New gem:
portage-ucp-webmcp. It adds WebMCP as a transport to the existingAdaptercontract, next to classic MCP (stdio, Streamable HTTP) and native UCP. It is not a new commerce backend. - Inbound: a store's pages register its catalog/cart/checkout tools on
document.modelContext, and each call goes back to the sameMcp::Server. - Outbound: a
portage-ucp-clienttransport drives the WebMCP tools of any page, through Ferrum, Playwright, Selenium or any JavaScript- evaluating callable. The page doesn't have to run Portage. - End-to-end specs run the real page scripts in node against the real Rack endpoint. They check that WebMCP returns the same documents as the in-process Loopback transport.
portage-ucp-client:get_cart,update_cartandcancel_cartwork again over the loopback and stdio transports. Before, both transports droppedcart_id. See that gem's changelog.portage-ucp0.9.0: one copy of each decision rule.portage-clikept hand-copied fallbacks ofportage-ucp-decision's offer-ranking and escalation rules, and ran every spec twice so the copies couldn't drift. Both rules now live in core (Support::OfferRanking,Support::Escalation) next toPolicyGuard. The gem'sOfferRankingandEscalationPolicywrap them, asPolicyCheckwrapsPolicyGuard, and the CLI calls them directly.portage-cliandportage-ucp-decisionnow requireportage-ucp ~> 0.9, and every lockfile pinsportage-ucp0.9.0.portage buy'sdecisions:verdicts now report string reasons in-process as well as in--json, andconfidencegained areasonalongside itserrordetail.Support::Totals.amountjoins them, replacing thetype == "total"lookup copied acrossportage-cli,DispatcherandReferenceAdapter. No adapter gem had its own copy.- Version bumps for gems whose code changed after their last publish.
publish_allskips any version already on rubygems.org, soportage-ucp-client0.6.1,portage-cli0.6.4 andportage-ucp-woocommerce0.2.0 would have been skipped with newer code sitting unreleased.portage-ucp-webmcpwould also have installed against the published client 0.6.1, which lacksTransports::UcpWireShape, and failed onrequire. They are nowportage-ucp-client0.6.2,portage-cli0.7.0 andportage-ucp-woocommerce0.2.1.portage-cliandportage-ucp-webmcprequireportage-ucp-client >= 0.6.2.
[0.8.2] - 2026-09-22¶
- Anonymous native UCP validated against thirteen unrelated live Shopify
stores, not just
catalog.shopify.comand this project's own dev store. Discovery, catalog, multi-line carts and checkout all answer with no token, no signature and no approval; a three-variant cart at quantity two returns three correctly-totalled lines, andcreate_checkoutfrom it returnsrequires_escalationwith the store's payment handlers, which is the documented no-grant outcome. Design log §43 has the full matrix, including the hostile inputs (negative/zero/absurd quantities, bogus variant ids) and two limits found with no fix: stores clamp quantity silently and by wildly different amounts, andcreate_cartis not idempotent server-side even though the client sends the key. - An omitted UCP
contexthas three outcomes, not the one 0.8.1 documented. Of nine stores, three built a correct cart without it, one emptied it, and five priced the cart in the market of the caller's IP address. The gem always sends a context, so nothing regressed — but the wrong-currency cart carries no message saying so, which makes it the harder failure of the two, and the docs said only "empties the cart". Sending one is also necessary rather than sufficient:mejuri.comempties aUS/USDcart for a product it publishes only toCA, while itssearch_catalogignores the context and reports that product available at CAD prices to every market.skills/shop-via-ucp.mdnow says so. portage-cli0.6.4 fixes the checkout hand-off pointing at the wrong page. It handed the shopper the first link in the checkout'slinks, which on every real store is a policy link — the checkout lives atcontinue_url. So the auto-open added in 0.8.1 opened the merchant's refund policy. Found by running the flow against third-party stores rather than the dev store, which is the only reason it surfaced before release.portage-cli0.6.3 /portage-ucp-client0.6.1: a store's own refusal (out of stock, a rejected line) is reported with the store's sentence andcontinue_urlinstead of crashingportage buywith a backtrace holding the store's entire error envelope.Client::ServerErrorgained#payload/#summary/#continue_url/#server_messages.portage-clinow requiresportage-ucp-client ~> 0.6; it was pinned~> 0.5while calling a constant added in 0.6.0.portage-ucp-woocommerce0.2.0 /portage-ucp0.8.1: same third-party validation pass found WooCommerce's hand-off, completion and error reporting genuinely broken, not just untested.Mapper.checkoutalways builtlinks: [], so the checkout hand-off couldn't fire on this backend at all;Resolver's WooCommerce entry never threadedpayment_methodorbilling_addressthrough to the adapter, socomplete_checkoutfailed with neither configured even when both env vars were set; and the Store API's/checkout400s without abilling_addressUCP's owncomplete_checkoutinterface has no parameter for.Mapper.checkoutnow takes a requiredsite_url:keyword — breaking for anyone callingMapperdirectly.portage-cli'sadapter_flowwas hiding a live adapter's own error. It rescuedLoadErrorandStandardErroridentically, so a real, actionable failure from an installed adapter (e.g. "no payment_method configured on this Adapter") surfaced as the same generic "no automated path" dead end as a platform with no adapter installed at all. Found while validating the WooCommerce fixes above.portage-ucp-shopify0.5.0 fixes catalog reads surfacing products that can't be bought:search_catalog/get_product/lookup_catalognow read through the Storefront API instead of Admin, which also returnsDRAFT/ARCHIVEDand unpublished products thatcartCreatethen rejects outright. Breaking for anyone callingMapperdirectly:Mapper#scalar_priceis removed andMapper#variantno longer takes acurrencyargument, since Storefront returns money asMoneyV2objects rather than Admin's bare scalar.rake release_checkandrake publish_allwere broken for every gem with a portage dependency — the require smoke-test put only the gem's ownlib/on the load path, so verifying a build failed withcannot load such file -- portage/ucpagainst a package that was in fact fine. It now runs that require withGEM_HOME/GEM_PATHpointed at the throwaway install dir.- jsdelivr caches
@mainfor a week, so for days after 0.8.1 the CDN kept serving the old agent profile — reproducing 0.8.1's ownTool not foundbug against correct code in the repo. Purged, and both.env.exampleanddocs/agent-profile.mdnow say to purge after every profile change (or to pin@<sha>).
[0.8.1] - 2026-09-22¶
- Native UCP tool calls against live Shopify stores work. They were failing
with
-32602 Tool not found: <name>on every catalog/cart/checkout call, and0.8.0's docs concluded that was a platform-side allowlist with no fix available. That was wrong. The cause was this repo's own agent profile: catalog is registered per action (dev.ucp.shopping.catalog.search,dev.ucp.shopping.catalog.lookup), the profile declared the coarsedev.ucp.shopping.catalog— becauseGenerate::AgentProfilereusedPortage::Ucp::Capabilities::CATALOG.name, right for our own server's manifest and wrong for an agent profile — and a server resolves an agent's tool registry from exactly those ids, so it resolved none. Versions were"1"where the registry uses spec revisions, andserviceswas{}, which declares an agent that speaks no service.portage generate agent-profilenow emits the real ids at2026-08-25with the shopping service declared, and the checked-inportage-cli/agent-profile/agent-profile.jsonis regenerated. Verified live, anonymously — no token, no signatures, no approval — againstcatalog.shopify.com, a third-party storefront, and this project's own dev store: search → cart → checkout, stopping at thecontinue_url. portage-ucp-client0.5.0: sends the UCPcontextobject (address_country/address_region/postal_code/currency/language) on catalog, cart and checkout calls. Without it a store scopes the call to no market and silently drops every cart line, answeringmerchandise_out_of_stockfor a product its ownsearch_catalogjust returned as available — a plausible wrong answer rather than an error.Sessiontakescontext:on those methods andcart_id:oncreate_checkout;Transports::{Loopback,Stdio}drop both, since they hand arguments to this gem's own flat-argument server.portage-cli0.6.1: newPortage::Cli::BuyerContextbuilds that context fromPORTAGE_SHIP_COUNTRY/_REGION/_POSTAL_CODEplusPORTAGE_CURRENCYandPORTAGE_LANGUAGE, andbuy/findpass it on every call.- Docs corrected rather than deleted:
docs/ucp-tool-gating-investigation.mdanddocs/agent-profile.mdnow lead with the real cause and keep the original allowlist reasoning below it, including why theget_order"forbidden" tell was misread.complete_checkoutremains genuinely case-by-case; nothing else does.
[0.8.0] - 2026-09-17¶
portage-ucpbumps to 0.8.0 for a breaking manifest shape change:Manifest#to_hnow nests everything under a top-levelucpobject, renamesucp_versiontoversion, and keyscapabilitiesby capability name, matching what live UCP stores actually serve (confirmed against Shopify's2026-08-25rollout across 35+ storefronts) instead of the flat shape this gem invented. Anything reading a Portage-served manifest by the old top-level keys needs updating;Rack::ManifestEndpointandskills/serve-via-ucp'sverify.shboth did, and are fixed here.portage-ucp-clientbumps to 0.4.0 for the same lesson on the outbound side:Transports::Httpwas sending every tool call flat and unwrapped, and real stores 422 it — arguments belong nested under a capability key, with ameta.ucp-agent.profileURL the store fetches to verify who's calling.Httpnow builds that shape, callers must passmeta: { agent_profile: }, and two new errors (MissingAgentProfileError,UnsupportedWireShapeError) say so plainly rather than letting a bare 422 through.Loopback/Stdioare unchanged.portage-clibumps to 0.6.0 forportage generate agent-profile(writes the UCP agent-identity document the above needs; the CLI's own is checked in and published to a stable URL by a new GitHub Pages workflow, which is wherePORTAGE_AGENT_PROFILEpoints by default), clearfind/buyfailures when that profile is missing or rejected, and a fix forbuysending a catalog product's own id as the purchasable line item — Shopify's cart takes aProductVariantGID, so every liveportage buyfailed with "Invalid id" until now.portage-ucp-shopifybumps to 0.4.4,portage-ucp-journalto 0.1.1, and-wix,-woocommerce,-bigcommerce,-magento,-etsy,-instagramto 0.1.4: pin-only releases, no behavior change, so each installs alongsideportage-ucp0.8.0 (their published~> 0.7pin is pessimistic and excludes it).- Repo:
rake publish_allbuilds, smoke-tests, and pushes every gem whose version isn't on rubygems.org yet, in dependency order, reusingrelease_check's build-from-the-gem's-own-directory verification — the 0.7.1 postmortem's checklist, now a task instead of a README paragraph. README gains a CLI quick start and a walkthrough atdocs/cli-usage-tutorial.md.
[0.7.1] - 2026-09-16¶
- No behavior change in any gem. 0.7.0's
portage-ucp,portage-cli,portage-ucp-shopify,portage-ucp-client,portage-ucp-wix, and the five smaller adapters were all built and pushed to RubyGems withgem buildrun from the workspace root instead of each gem's own directory — every gemspec'sspec.files = Dir["lib/**/*.rb", ...]resolved against the wrong working directory, so every 0.7.0-line package shipped empty (nolib/). All ten 0.7.0-line versions have been yanked; this release repackages the exact same code, correctly, one patch version up from each. Release checklist now builds from each gem directory and smoke-testsrequireafter install (rake release_check[gem_dir], see README's "Releasing a gem").
[0.7.0] - 2026-09-16¶
portage-ucpbumps to 0.7.0: cryptographic AP2 mandate signature verification (Ap2::MandateSignature, real ECDSA against a JWK trust-anchor set, plus arequire_signature:fail-closed option onMandateGuard, closing the gap 0.6.0's shape-only mandate validation left open), a cross-process idempotency race fix (FileStore#fetch_or_store, atomic temp-file-plus-rename persistence, a poisoned-file rescue, reaped per-key/ per-session locks, and a newConfiguration#idempotency_provider), aRails::Railtie+rails g portage:ucp:installgenerator, opt-in OpenTelemetry span emission alongside the existing JSON logging, andMcp::Server.build(journal:)— naming the seamportage-clinow wires a real journal through (see below) — plus#each_record/#allonTransactionLog/OrderLedger. Seeportage-ucp's ownCHANGELOG.md.portage-clibumps to 0.5.0 forportage-console(a read-only IRB REPL over the local transaction/order/journal stores),portage generate adapter(scaffolds a new adapter gem),portage doctor(sanity-checks a seller'sPortage::Ucp.configuration), and wiring a realPurchaseJournalintoportage buy's own-store loopback path — that path previously left the journal empty even thoughportage-consoleabove could read one. New runtime dependency onportage-ucp-journal(~> 0.1).portage-ucp-shopifybumps to 0.4.2 for a fix toGraphqlErrorcrashing instead of surfacing Shopify's real message whenerrorscomes back as a bare string, plus a new live-store buyer-journey spec.portage-ucp-client,portage-ucp-wix,portage-ucp-bigcommerce,-woocommerce,-etsy,-magento, and-instagramall take pin-only patch releases (no behavior change) so each can install alongsideportage-ucp0.7.0: their previously-published~> 0.6pin is pessimistic and excludes 0.7.x.portage-ucp-journal'sportage-ucpdependency (development-only, not a runtime dependency) also widens to~> 0.7in its gemspec, published as 0.1.0.
[0.6.0] - 2026-09-15¶
-
Fix:
portage-ucp-woocommerce,-bigcommerce,-magento,-etsy, and-instagramall bump to 0.1.1 for a standing bug, unrelated to theportage-ucpwork below and predating it: eachMapper.productbuilt aPortage::Ucp::Product/Variantwith keywords (price:,available:)dev.ucp.shopping.catalog's schema-conformance work removed in favor ofprice_range:/a realvariants:array (see that work's own changelog entries, back when onlyportage-ucp-shopifyand-wixgot their mappers migrated) — every realsearch_catalog/get_productcall against these five adapters raisedArgumentError: missing keyword: :price_range. Each adapter's#search_catalog/#get_productalso returned a bareArray<Product>/Productinstead of theCatalogSearchResult/ProductDetailwrapper theAdaptercontract documents, which would have failed UCP schema validation even once the first bug was fixed. Caught by running the core gem's schema-validation conformance examples (added earlier for the payment-enrollment slice below) against every adapter, not just Shopify/Wix's specs, which asserted the same wrong shape their mappers produced. -
portage-ucpbumps to 0.6.0 for the §22/§33-§35 payment-enrollment and signature-verification slice:PaymentEnrollmentGuard(validates everycreate_payment_enrollment/get_payment_enrollmentresponse — breaking, raisesInvalidPaymentEnrollmentErroron a malformed one), an AP2 mandate shape (Ap2::PaymentMandate/Ap2::MandateGuard, shape-only — no cryptographic verification), aStore/FileStoreextraction underSupport::TransactionLog/Support::OrderLedgerso either can be backed by something other than a file,app.portage-ucp.payment_method/saved_address/shopper_dataextensions,Dispatcher.new(journal:)wiring for the newportage-ucp-journalgem, RFC 9421 HTTP Message Signature verification (Security::Signature,Rack::SignatureVerification) for inbound requests, andConfirmer::Webhook— an out-of-band approval path for the confirmation gate (POST + poll, or a caller-suppliedwait:callback), alongside the existingTerminal/AutoApproveconfirmers. Seeportage-ucp's ownCHANGELOG.md. portage-ucp-journalis a new gem (0.1.0): a buyer-side purchase journal plus the injectableStoreabstractionportage-ucp's ownStore/FileStoresplit now mirrors.portage-clibumps to 0.4.1,portage-ucp-clientto 0.3.1,portage-ucp-shopifyto 0.4.1, andportage-ucp-wixto 0.1.1 — pin-only releases (no behavior change) so each can install alongsideportage-ucp0.6.0: their previously-published~> 0.5(~> 0.5for-wix's 0.1.0) pin is pessimistic and excludes 0.6.x. Every other gem'sportage-ucppin also widens to~> 0.6in its gemspec, with no release of its own needed beyond what's already covered above.
[0.5.0] - 2026-09-14¶
portage-ucpbumps to 0.5.0 for the agentic-payments work (docs/plans/agentic-payments.md):Adapter#create_payment_enrollment/#get_payment_enrollment(card-on-file enrollment without the card touching this process), a durableSupport::TransactionLogwired intocomplete_checkoutdispatch,PolicyGuard/Policy(per-transaction/rolling caps, velocity, merchant allowlist, per-token enrollment scopes), aConfirmergate (Terminal/AutoApprove) run just before dispatch, a durableSupport::OrderLedgersnapshot written after settlement,_metaucp-agent.profilethreading alongside the existingtraceparentcorrelation id, andAdapter#lookup_catalog(ids:)for batch product fetch by id — seeportage-ucp's ownCHANGELOG.md.portage-clibumps to 0.4.0 forportage payment list/enroll/set-default/ remove/freeze/revoke(Keychain / Secret Service / env-var-only storage) andportage policy show/set, both driving the newportage-ucppolicy and enrollment capabilities.portage-ucp-clientbumps to 0.3.0 forSession#create_payment_enrollment/#get_payment_enrollmentand an optionalmeta:kwarg threaded through every transport.portage-ucp-shopifybumps to 0.4.0 forAdapter#lookup_catalog(ids:), fetching several known product ids in one round trip via the Admin API'snodes(ids:)field.- Every adapter gemspec and
portage-cliwiden theirportage-ucppin to~> 0.5(andportage-cli'sportage-ucp-clientpin to~> 0.3) for the capabilities above; onlyportage-ucp,portage-ucp-shopify,portage-ucp-client, andportage-clihave ever been published to RubyGems.
[0.4.0] - 2026-08-28¶
portage-clibumps to 0.3.0 forportage compare(§22's "find this same item elsewhere" mode) andportage history(local purchase/search log), plus a fix for asearch_catalogenvelope-unwrapping bug that had been producing malformed offers against every real store since 0.2.0 — seeportage-cli's ownCHANGELOG.md.portage-ucpbumps to 0.4.0 for theapp.portage-ucp.reordercapability, per-request correlation ids threaded throughDispatcher/Mcp::Server/CheckoutStatefor observability, and a widenedObservability::REDACTED_KEYScovering the PII fields that actually flow through logged events — seeportage-ucp's ownCHANGELOG.md.portage-ucp-shopifybumps to 0.3.1 to widen itsportage-ucpdependency pin from~> 0.3to~> 0.4— no code change of its own. Every other adapter gemspec andportage-ucp-clientgot the same pin widened, but none has published a version yet, so there's no install-breakage to fix for them beyond keeping the constraint correct ahead of their first release.portage-cliandportage-ucpare the only two gems in this release with behavior changes;portage-ucpandportage-ucp-shopifyremain the only two gems ever published to RubyGems.
[0.3.0] - 2026-08-27¶
- All seven adapter gems now run the core gem's conformance kit against their
real
Adapterthrough a realDispatcher(spec/portage/ucp/<platform>/conformance_spec.rb), closing the follow-up design-log §17 left open when the kit shipped. No adapter needed body-matching stubs: the kit's reachable surface stops atcreate_checkout. - Core gem's
~> 0.2dependency pin widened to~> 0.3in every adapter,portage-cli, andportage-ucp-clientgemspec. portage-ucpandportage-ucp-shopifyboth bump to 0.3.0 — see each gem's ownCHANGELOG.mdforSupport::Retry,Support::SessionLock, the Shopify metadata_field config DSL, and the Shopify GraphQL shape fixes driving the bump.portage-cliandportage-ucp-clientare unchanged and stay at 0.2.0.
[0.2.0] - 2026-08-21¶
Added¶
~/.portage/— the first state anything here keeps outside the project directory.stores.ymlis the store allowlist you curate; the CLI writesdiscovery-cache.jsonto remember which origins answered/.well-known/ucp, so a URL-less search doesn't re-probe the same hosts on every run. Both are the CLI's, and both are documented inportage-cli.- Search-backend credentials as configuration that belongs to no adapter:
BRAVE_SEARCH_API_KEY,GOOGLE_CSE_KEY/GOOGLE_CSE_CX, andPORTAGE_STORES. The per-adapter variables in the root README's Requirements table decide which platforms the CLI can buy from; these decide which stores it can propose in the first place, so they sit outside that table. - Root
CHANGELOG.md(this file) — every gem already had one, the workspace itself didn't. docs/walkthrough.mdanddocs/well-known-ucp.md: the agent-buys-a-snowboard walkthrough and the/.well-known/ucprationale, moved out of the root README so it opens on how to install and run the thing.- A
## Licensesection in every adapter gem's README — all seven shipped aLICENSEfile without pointing at it. docs/design-log.md§15: how the CLI finds a store when the user has no URL, and why the search step uses documented APIs rather than a scraped results page. Ships alongsideportage findinportage-cli.
Changed¶
- Root README's gem table describes both ways into the CLI —
portage buy <url>when you know the shop, andportage find --query "..."when you don't. - Root README follows the
bundle gemsection order: Installation and Usage come first, then the gem table, then everything else. The table of contents now matches the rendered order (Requirements had been listed last and rendered second). - Root README's Requirements section is a per-adapter env-var table linking each adapter's own README, instead of restating credential setup those READMEs already own.
- Every README names its how-to-run section
## Usage, replacing the mix ofQuickstart(core, client) andUsing the adapter directly(adapters).
[0.1.0] - 2026-08-14¶
- Initial release: ten gems, published to RubyGems. See each gem's own
CHANGELOG.mdfor what it ships, and the design log for the rationale behind the split.