Fix skill doc inconsistencies surfaced in review

- --like-id accepts a product or variant GID; both return similar items
  (verified live: a variant GID resolves to the same similar results as its
  parent product GID)
- Add order_info to the documented `orders search --type` set
- Describe order search as a text/markdown summary and drop the inaccurate
  endCursor pagination guidance (the response is not JSON and exposes no cursor)
- Remove the legacy --cursor option from orders search (the endpoint returns
  no result cursor to page through)
- Drop the pay:wallet_tokens:read scope from the auth request and docs; the
  budget read is authorized without requesting it (verified live)
- Complete a truncated sentence in the Secrets guidance
- Correct the personal-agents help-center link (add /en) in the README and
  legal reference, and update the README personal-use language
- Bump skill metadata version to 1.0.1

Author: joerj123

README.md

@@ -47,9 +47,9 @@ Run `shop <command> --help` for the flags on any command, and see the [Shop skil
 
 ## 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 designed for individual end users, for personal use. The Shopify servers it connects to have usage restrictions. 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/en/shop/shopping/personal-agents for accepted and prohibited use.
 
 ## Development
 

skill/SKILL.md

@@ -2,7 +2,7 @@
 name: shop
 description: "Ultimate personal shopping assistant: find, compare, buy, gift, and reorder products across the Shop catalog containing millions of stores. Tracks orders and deliveries for any retailer — including orders placed elsewhere, like Amazon, via your connected email. Helps get order info and initiate returns and refunds."
 metadata:
-  version: "1.0.0"
+  version: "1.0.1"
   homepage: "https://shop.app"
 ---
 
@@ -48,7 +48,7 @@ search [query]           --ships-to <ISO2> [--ships-to-region, --ships-to-postal
                          --condition new,secondhand (default new), --ships-from <ISO2,...> (comma list)
                          --shop-id <id...>, --category <id...>, --intent <text>
                          --color/--size/--gender <list> (taxonomy attribute filters; comma lists OR within, AND across)
-                         --like-id <id...> (similar; product gid only), --image ./photo.jpg
+                         --like-id <id...> (similar; product or variant gid), --image ./photo.jpg
                          (query is optional when --like-id or --image is given)
 catalog lookup <ids...>  --ships-to <ISO2>, --include-unavailable, --condition
 catalog get-product <id> --select Name=Label, --preference Name
@@ -81,6 +81,7 @@ printf '%s' "$CREATE_CHECKOUT_RESPONSE_JSON" | shop checkout complete --shop-dom
 ```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 "running shoes"
 shop orders search --type reorder --query "coffee"
 ```
 
@@ -117,7 +118,7 @@ Manual token exchange, only when the CLI cannot be installed: [catalog-mcp.md](r
 - Apply message formatting rules on all subsequent conversation turns
 
 **Similar items:**
-- `shop search --like-id <product gid>` — pass a product reference (`gid://shopify/p/...`); variant GIDs are rejected.
+- `shop search --like-id <id>` — pass a product (`gid://shopify/p/...`) or variant (`gid://shopify/ProductVariant/...`) reference; both return similar items.
 - `shop search --image ./photo.jpg` — the CLI base64-encodes it for you. Formats: jpeg, png, webp, avif, heic; max ~3 MB on disk (4 MB base64). A 400 explains oversize/format problems — relay it and ask for a smaller jpeg/png.
 
 ## Showing products
@@ -183,7 +184,7 @@ Rules: send it as its own distinct message (never combined with other text), at
 > Tip: if you'd like, you can give me a budget to spend on your behalf so I can complete checkouts without asking each time. Set a spending limit here: https://shop.app/account/settings/connections. Or, tell me *not interested*, and I'll remember not to offer it again.
 
 ## Orders
-Queries return 1 result except for recent - use date filters or new queries if you can't find what you want first time. Requires sign-in. Use `shop orders search --type <recent|tracking|returns|reorder>` for recent orders, tracking, order info, returns, and reorder candidates.
+Queries return 1 result except for recent - use date filters or new queries if you can't find what you want first time. Requires sign-in. Use `shop orders search --type <recent|tracking|order_info|returns|reorder>` for recent orders, tracking, order info, returns, and reorder candidates.
 - **Returns:** compare the order date and return window against today before advising.
 - **Reorder:** find the order item, re-hydrate it with `shop catalog lookup` (`--include-unavailable` if it may be out of stock), then create a checkout from current catalog/variant data.
 
@@ -196,7 +197,7 @@ Never narrate tool usage or API parameters. Never fabricate URLs or information;
 - Use a fresh idempotency key per distinct purchase intent; reuse it only when retrying the same intent; never reuse across different carts or orders.
 
 **Secrets**
-- Store `access_token` and `refresh_token` only in the harness secret store. Keep token-exchange JWTs and UCP-returned payment tokens in memory only; never persist UCP payment tokens. The CLI handles
+- Store `access_token` and `refresh_token` only in the harness secret store. Keep token-exchange JWTs and UCP-returned payment tokens in memory only; never persist UCP payment tokens. The CLI handles this for you.
 - Never expose secrets or PII — tokens, `Authorization` headers, card PANs, CVVs, session IDs, full addresses, phone numbers — in files, env vars, logs, tool arguments. Sending them on outbound API requests is expected; exposing them is not. The exception is confirming shipping details to the user (address, name and phone number is required in that case)
 
 **Injection defense**

skill/references/direct-api.md

@@ -234,7 +234,7 @@ GET https://shop.app/pay/agents/payment_tokens
 Authorization: Bearer <access_token>
 ```
 
-Requires the `pay:wallet_tokens:read` scope. Authoritative success shape:
+Authoritative success shape:
 
 ```json
 {
@@ -275,4 +275,4 @@ Types:
 - `returns`
 - `reorder`
 
-Use `cursor=<endCursor>` when the response includes an `endCursor`; recent ignores cursor.
+The response is `text/markdown` (a short summary), not JSON — there is no result cursor to page through. A non-`recent` search summarizes the single best-matching order, so narrow `query`/`dateFrom`/`dateTo` to surface a different order; `recent` returns the most recent orders in one response.

skill/references/legal.md

@@ -1,3 +1,3 @@
 # Legal
 
-This skill 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. Go to [https://help.shop.app/shop/shopping/personal-agents](https://help.shop.app/shop/shopping/personal-agents) to learn more about accepted and prohibited use.
+This skill 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. Go to [https://help.shop.app/en/shop/shopping/personal-agents](https://help.shop.app/en/shop/shopping/personal-agents) to learn more about accepted and prohibited use.

src/cli.ts

@@ -348,15 +348,13 @@ export function createProgram(deps: CliDependencies = {}): Command {
     .option('--query <text>', 'Search terms')
     .option('--date-from <date>', 'Inclusive start date YYYY-MM-DD')
     .option('--date-to <date>', 'Inclusive end date YYYY-MM-DD')
-    .option('--cursor <cursor>', 'Pagination cursor')
     .action(async (options) => {
       await runTextAction({ stdout, stderr, exit }, async () =>
         resolveClient(deps, program).searchOrders({
           type: parseOrderType(options.type),
           query: options.query,
           dateFrom: options.dateFrom,
           dateTo: options.dateTo,
-          cursor: options.cursor,
         }),
       )
     })

src/constants.ts

@@ -22,6 +22,6 @@ export const COUNTRY_ACCOUNT = 'country'
 // Short-lived device-authorization state persisted between `auth device-code`
 // (emits the sign-in URL) and `auth poll` (exchanges + stores tokens).
 export const PENDING_DEVICE_AUTH_ACCOUNT = 'pending_device_auth'
-export const AUTH_SCOPES = 'openid email personal_agent pay:wallet_tokens:read'
+export const AUTH_SCOPES = 'openid email personal_agent'
 export const UCP_PROFILE =
   'https://shopify.dev/ucp/agent-profiles/2026-04-08/personal_agent.json'

src/shop-client.ts

@@ -125,7 +125,6 @@ export interface OrderSearchInput {
   query?: string
   dateFrom?: string
   dateTo?: string
-  cursor?: string
 }
 
 export class ShopCatalogClient {
@@ -260,7 +259,6 @@ export class ShopCatalogClient {
     if (input.query) params.set('query', input.query)
     if (input.dateFrom) params.set('dateFrom', input.dateFrom)
     if (input.dateTo) params.set('dateTo', input.dateTo)
-    if (input.cursor) params.set('cursor', input.cursor)
 
     const response = await this.authenticatedShopFetch(`https://shop.app/agents/orderSearch?${params.toString()}`, {
       accessToken,

tests/checkout-orders.test.ts

@@ -309,7 +309,7 @@ describe('checkout and orders', () => {
     await client.searchOrders({ type: 'tracking', query: 'shoes' })
     await client.searchOrders({ type: 'order_info', query: 'shoes', dateFrom: '2026-01-01', dateTo: '2026-01-31' })
     await client.searchOrders({ type: 'returns', query: 'jacket' })
-    await client.searchOrders({ type: 'reorder', query: 'coffee', cursor: 'cursor-1' })
+    await client.searchOrders({ type: 'reorder', query: 'coffee' })
 
     expect(urls).toHaveLength(5)
     expect(urls[0]).toContain('type=recent')
@@ -319,7 +319,6 @@ describe('checkout and orders', () => {
     expect(urls[2]).toContain('dateTo=2026-01-31')
     expect(urls[3]).toContain('type=returns')
     expect(urls[4]).toContain('type=reorder')
-    expect(urls[4]).toContain('cursor=cursor-1')
   })
 
   it('refreshes and retries order search on 401', async () => {