Trim README to a concise overview; defer detail to the Shop skill

Author: joerj123

README.md

@@ -1,23 +1,14 @@
 # Shop CLI
 
-Personal shopping CLI for the Shop catalog: search millions of stores, look up
-products, sign in to your Shop account, build and complete UCP checkouts, and
-search your orders for tracking, returns, and reorders.
+Personal shopping CLI for the Shop catalog: search millions of stores, look up products, sign in to your Shop account, build and complete UCP checkouts, and search your orders for tracking, returns, and reorders.
 
-It talks to the Shopify Global Catalog over MCP and to Shop's auth, checkout,
-and orders APIs. Tokens are stored in your OS secret store (Keychain on macOS,
-the equivalent secret service elsewhere) via `keytar` — nothing sensitive is
-written to disk in plaintext.
+It talks to the Shopify Global Catalog over MCP and to Shop's auth, checkout, and orders APIs. Tokens are stored in your OS secret store via `keytar`.
 
 ## Companion to the Shop skill
 
-This CLI is the companion to the **Shop skill**, the agent-facing playbook that
-drives the end-to-end shopping conversation (offer sign-in → search → show
-products → visualize → checkout → orders). The skill calls these commands under
-the hood, and when the CLI can't be installed its reference files mirror every
-command via the direct API.
+This CLI is the companion to the **Shop skill**, the agent-facing playbook that drives the end-to-end shopping conversation. The skill calls these commands under the hood and documents every command, flag, and workflow in full.
 
-The skill lives at **https://shop.app/SKILL.md**.
+The skill lives at **https://shop.app/SKILL.md** — see it for the complete reference.
 
 ## Install
 
@@ -31,197 +22,34 @@ Or with npm:
 npm install --global @shopify/shop-cli
 ```
 
-From source:
-
-```bash
-git clone https://github.com/Shopify/shop-cli && cd shop-cli
-pnpm install && pnpm build && pnpm link --global
-shop --help
-```
-
 Requires Node.js >= 20.
 
-## Quick start
+## Usage
 
 ```bash
 shop --help
 shop auth status
 shop search "trail running shoes" --limit 10
 shop catalog lookup gid://shopify/ProductVariant/50362300006715
-```
-
-## Global options
-
-These apply to every command:
-
-```text
---country <ISO2>     Buyer country as a catalog *context* signal (default: US).
-                     Not a ships-to filter. Transient — use `shop config
-                     set-country` to persist a default.
---profile-url <url>  UCP agent profile URL for global catalog calls.
---format md|json     Output format for catalog (search/lookup/get-product)
-                     results: md (default) or json. md is far more compact;
-                     json payloads are large. Auth and checkout always emit
-                     JSON; orders always emit markdown.
---memory-store       Use in-memory token storage (for tests and dry runs).
-```
-
-## Commands
-
-### Search the catalog
-
-`shop search` is the single entry point for catalog discovery — free-text,
-similar items (`--like-id`), and visual search (`--image`). The query argument is
-optional when you pass `--like-id` or `--image`.
-
-```bash
-shop search "black crewneck sweater" --limit 10
-shop search "boots" --country US --ships-to US --ships-from US
-shop search "tshirt" --color White --size M --gender Female
-shop search --like-id gid://shopify/p/abc123
-shop search --image ./photo.jpg
-```
-
-Useful flags:
-
-```text
---country <ISO2>             Buyer country context for this call
---ships-to <ISO2>            Destination filter (hard filter). Alone, also
-                             localizes catalog context to that country.
---ships-to-region <code>     ships-to region (requires --ships-to)
---ships-to-postal <code>     ships-to postal code (requires --ships-to)
---ships-from <ISO2>          Merchant origin country
--l, --limit <number>         Result limit, 1-50
---min-price / --max-price    Price bounds in minor units (15000 = $150.00)
---currency <code>            Currency signal
---language <code>            Language signal
---intent <text>              Buyer intent context
---condition <list>           Comma list, e.g. new,secondhand
---include-unavailable        Include out-of-stock products
---shop-id <id...>            Filter to specific shop IDs
---category <id...>           Filter to taxonomy category IDs
---color/--size/--gender      Comma-list taxonomy attribute filters
---like-id <id...>            Find similar items (product gid only)
---image <path>               Find similar items by image (CLI base64-encodes it)
---view <name>                Catalog response view
---format md|json             (global) output format
-```
-
-### Catalog lookup & product detail
-
-Use `lookup` for IDs you already hold (orders, wishlist, reorder); use
-`get-product` for a full product detail record including variant `checkout_url`.
-
-```bash
-shop catalog lookup <product-or-variant-id...>
-shop catalog lookup gid://shopify/ProductVariant/50362300006715 --include-unavailable
-shop catalog get-product gid://shopify/p/abc --select Color=Black --select Size=M
-```
-
-`lookup` flags: `--country`, `--currency`, `--ships-to[-region|-postal]`,
-`--include-unavailable`, `--condition`, `--view`.
-`get-product` flags: `--country`, `--currency`, `--select Name=Label`,
-`--preference Name`, `--view`.
-
-### Auth
-
-Sign-in is optional (search works signed-out) but unlocks shipping rates, your
-default address, and order history. Tokens are stored in the OS secret store.
-
-```bash
-shop auth status     # check whether stored auth is valid
-shop auth logout     # delete stored tokens and preferences
-```
-
-There are two ways to sign in:
-
-```bash
-# Blocking: runs device authorization end-to-end and stores tokens
-shop auth login --device-name "My laptop"
-
-# Non-blocking (preferred for agents): two steps
-shop auth device-code --device-name "My laptop"   # prints the sign-in URL
-# ...user authorizes in the browser...
-shop auth poll                                     # exchanges + stores tokens;
-                                                   # re-run while it reports pending
-```
-
-### Checkout
-
-UCP checkout runs on the merchant's domain. Checkout JSON is read from stdin
-with `--checkout-stdin`. `--shop-domain` must be a bare merchant hostname (no
-scheme, path, port, or IP).
-
-```bash
-# Create from a variant
-printf '{"email":"buyer@example.com"}' | \
-  shop checkout create \
-    --shop-domain example.myshopify.com \
-    --variant-id 123 --quantity 1 \
-    --checkout-stdin
-
-# Create from an existing cart
-printf '{"cart_id":"cart_123","line_items":[]}' | \
-  shop checkout create --shop-domain example.myshopify.com --checkout-stdin
-
-# Update an existing checkout
-printf '{"fulfillment":{"methods":[]}}' | \
-  shop checkout update \
-    --shop-domain example.myshopify.com \
-    --checkout-id CHECKOUT_ID --checkout-stdin
-
-# Complete (pipe the create_checkout response so its payment instruments are echoed back)
-printf '%s' "$CREATE_CHECKOUT_RESPONSE" | \
-  shop checkout complete \
-    --shop-domain example.myshopify.com \
-    --checkout-id CHECKOUT_ID --checkout-stdin \
-    --idempotency-key UNIQUE_KEY --confirm
-```
-
-`shop checkout complete` **requires `--confirm`** and refuses to run without it.
-Only complete after confirming the item, variant, quantity, price, shipping
-address, shipping method, and total cost with the user. Use a fresh
-`--idempotency-key` per distinct purchase intent.
-
-`create`/`update`/`complete` surface UCP `messages[]` warnings (e.g.
-`final_sale`, `prop65`, `age_restricted`, disclosures) above the raw JSON so they
-aren't missed. The buyer public IP is forwarded to the merchant for fraud/risk
-checks — auto-detected via `api.ipify.org`, overridable with `--buyer-ip` or the
-`SHOP_BUYER_IP` environment variable.
-
-### Orders
-
-Requires sign-in. Returns a markdown summary.
-
-```bash
 shop orders search --type recent
-shop orders search --type tracking --query "running shoes" --date-from 2026-01-01
-shop orders search --type order_info --query "order #1234"
-shop orders search --type returns --query "jacket"
-shop orders search --type reorder --query "coffee"
 ```
 
-`--type` is one of `recent`, `tracking`, `order_info`, `returns`, `reorder`.
-Other flags: `--query`, `--date-from`, `--date-to`, `--cursor`.
-
-### Config
+## Commands
 
-Persist CLI preferences (stored alongside auth in the OS secret store).
+- `shop search` — search the catalog by text, similar items (`--like-id`), or image (`--image`).
+- `shop catalog lookup` / `shop catalog get-product` — look up IDs you already hold and fetch full product detail.
+- `shop auth` — sign in (`login`, or the non-blocking `device-code` + `poll`), check `status`, or `logout`.
+- `shop checkout` — `create`, `update`, and `complete` a UCP checkout on the merchant domain (`complete` requires `--confirm`).
+- `shop orders search` — search recent orders, tracking, order info, returns, and reorder candidates.
+- `shop config` — persist CLI preferences such as a default country.
 
-```bash
-shop config set-country US   # default --country when not passed explicitly
-shop config show             # show stored preferences
-```
+Run `shop <command> --help` for the flags on any command, and see the [Shop skill](https://shop.app/SKILL.md) for the full reference and shopping workflow.
 
 ## Personal-use limits
 
-This CLI is for individual end-users only. Building commercial services, resale
-platforms, aggregators, or anything that provides third parties with
-programmatic access to Shopify's catalog, checkout, delegated payments, or
-aggregated user data is prohibited.
+This CLI is for individual end-users only. Building commercial services, resale platforms, aggregators, or anything that provides third parties with programmatic access to Shopify's catalog, checkout, delegated payments, or aggregated user data is prohibited.
 
-See https://help.shop.app/shop/shopping/personal-agents for accepted and
-prohibited use.
+See https://help.shop.app/shop/shopping/personal-agents for accepted and prohibited use.
 
 ## License