@commercelayer/agent-cli 0.5.0 → 0.5.2

package/README.md

@@ -10,6 +10,7 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 - **The website comes with the store.** Every store has a hosted theme at its preview URL, set by a few `theme:` settings and the product data: `apply` is all it takes. A custom storefront (your own web app) is opt-in: `storefront init`, `publish` and `check`.
 - **JSON only.** Every command prints one JSON object. A failure exits 1 with `{ "error": { "code", "message", "hint" } }`; the hint is the fix.
 - **Safe to re-run.** Every command is idempotent; a failed step can be fixed and run again.
+- **Always current.** Run it as `npx -y @commercelayer/agent-cli@latest`, even where a `c11r` binary is installed; the note `init` writes in `AGENTS.md` and `CLAUDE.md` says so. The CLI sends `User-Agent: c11r/<version> (node/<major>)`, and an outdated one gets a `cli_outdated` entry in `warnings`, with `current`, `latest` and a `hint`.
 - **No secrets in git.** `init` writes the sandbox token to `.commercelayer/credentials` (`C11R_ORG`, `C11R_TOKEN`) and gitignores it. The keys of a catalog source go in the same file.
 ## Commands
 | Command | Does |
@@ -34,15 +35,15 @@ npx -y @commercelayer/agent-cli@latest init --name "The Blue Brand"   # runs c11
 | `fulfillment list [--status <status>\|all] [--limit <n>]` · `show <shipment>` | The shipments, by default the ones not shipped yet. A shipment is its number (`1001/S/001`), its id, or its order's number. |
 | `fulfillment hold` · `pick` · `pack` · `ready` · `ship <shipment> [--carrier] [--tracking] [--tracking-url]` · `deliver` | Move a shipment; each prints the shipment after it. |
 | `ucp profile [--agent]` | The store's UCP business profile (`/.well-known/ucp`); with `--agent`, this CLI's own platform profile. |
-| `ucp search [<words>] [--category <name>] [--min-price <n>] [--max-price <n>] [--country <CC>]` · `ucp product <id>` | Buy for the human, step by step (see [Buying for the human](#buying-for-the-human)): the store's products with their categories, prices in major units in `price.display`, sale prices, shipping and the market the prices are for. |
+| `ucp search [<words>] [--category <name>] [--min-price <n>] [--max-price <n>] [--country <CC>] [--images]` · `ucp product <id> [--images]` | Buy for the human, step by step (see [Buying for the human](#buying-for-the-human)): the store's products with their categories, prices in major units in `price.display`, sale prices, shipping and the market the prices are for. |
 | `ucp checkout create --item <variant id>[:<qty>] … [--code <discount>] [--country <CC>]` | Open a checkout; `messages` say what is still missing (email, shipping address). |
 | `ucp checkout update <id> [--email …] [--street …] [--item <variant id>:<qty>] [--code …] [--shipping <option>]` | Give the buyer's details (flags, or YAML or JSON on stdin or `-f`), change items or codes; `ready_for_complete` once nothing is missing, with shipping in the total. |
 | `ucp checkout show <id>` · `cancel <id>` · `complete <id> [--decline]` | Read, cancel, or pay a checkout with the sandbox handler (after the human said yes): `order` has `label` and `permalink_url`. |
 | `ucp order <id>` · `ucp ask "<question>"` | Read an order the CLI placed; ask the store a question. Every `ucp` buying command takes `--store <host>` to buy from any store that speaks UCP. |
 | `ucp check` | Walk every UCP capability the store advertises and report what passes. Places and pays one real test order on the way (the output says which). Exits 1 on a failed check. |
-| `status` | The sandbox, the sales channel client id, the published storefront, what is applied, the last import job (`apply`), the pending changes (exactly what `plan` lists; a store that does not load is pending too, with the error), orders, the UCP profile URL. |
+| `status` | The sandbox, the sales channel client id, the published storefront, what is applied, the last import job (`apply`), the pending changes (exactly what `plan` lists; a store that does not load is pending too, with the error), orders, the store's semantic search index (`search`: model, status, vectors, embedded, updated_at, error; null before its first run), the UCP profile URL. |
 | `claim` | Start the device flow that keeps the sandbox: a URL and a code for the human. |
-| `help [<command>]` | Describe the commands. `--version` prints the version. |
+| `help [<command>]` | Describe the commands. `--version` prints the version and `latest_hint`, how to always run the newest. |
 ## store.yml
 `init` writes a commented template. A filled-in store looks like this:
 ```yaml
@@ -159,9 +160,9 @@ A custom storefront replaces the theme: `storefront.path` in `store.yml` names i
 Error codes: `invalid_theme`, `invalid_storefront`, `invalid_promotion`, `promotion_exists`, `promotion_not_managed`, `flex_unavailable`, `promotions_unsupported`, `invalid_link`, `link_exists`, `link_not_managed` (reserved), `links_unsupported`, `missing_images`, `asset_too_large`, `no_store`, `invalid_yaml`, `invalid_store`, `invalid_market`, `invalid_product`, `missing_price`, `deletes_need_approval`, `apply_failed`, `apply_pending`, `apply_in_progress`, `storefront_exists`, `no_storefront`, `storefront_unreachable`, `not_applied`, `not_found`, `missing_argument`, `invalid_argument`, `unknown_command`, `unauthorized`, `expired`, `api_unreachable`, `api_error`, `no_product`, `checkout_not_ready`, `ucp_error`, `ucp_profile_unreachable`, `ucp_profile_malformed`, `ucp_version_unsupported`, `ucp_no_rest_service`, `internal`.
 ## Orders and fulfillment
 
-Orders land **placed** with the payment **authorized**, not taken: the store no longer approves or captures them. The merchant, through the agent, accepts an order with `orders approve <n> --capture` (or approves now and runs `orders capture <n>` later), cancels one it doesn't want (`orders cancel`, which voids the authorization; a shipped order can't be cancelled, a captured one is refunded instead), and gives money back with `orders refund <n> [--amount <major units>]` (the last of it cancels the order). `orders archive` hides an order from the list, whatever its status; `orders list --archived` shows them. Every command prints the order after it and a `next` that says what it waits for; a move the order doesn't allow answers `invalid_transition`, with the commands it allows now in the hint.
+Orders land **placed** with the payment **authorized**, not taken: the store no longer approves or captures them. The merchant, through the agent, accepts an order with `orders approve <n> --capture` (or approves now and runs `orders capture <n>` later; Commerce Layer also captures a placed order), cancels one it doesn't want before it ships (`orders cancel`, which voids an authorization or refunds a captured payment; a shipped order is refunded, not cancelled), and gives money back with `orders refund <n> [--amount <major units>]` (the last of it cancels the order). `orders archive` hides an order from the list, whatever its status; `orders list --archived` shows them. Every command prints the order after it and a `next` that says what it waits for; a move the order doesn't allow answers `invalid_transition`, with the commands it allows now in the hint.
 
-Each order has one shipment, `upcoming` when placed. `fulfillment hold` works on a placed order; `pick`, `pack`, `ready` and `ship` need the order approved, and `on_hold`, `picking`, `packing` and `ready_to_ship` move freely between each other. `ship` takes the carrier's `--carrier`, `--tracking` and `--tracking-url` (https); `deliver` follows `ship`. An API older than these routes answers `orders_unsupported` or `fulfillment_unsupported`.
+Each order has one shipment, `upcoming` when placed. `fulfillment hold` works on a placed order; `pick`, `pack`, `ready` and `ship` need the order approved, and `on_hold`, `picking`, `packing` and `ready_to_ship` move freely between each other and on to `shipped`. An `upcoming` shipment goes only to `hold` or `pick`, as Commerce Layer refuses to ship it straight away. `ship` takes the carrier's `--carrier`, `--tracking` and `--tracking-url` (https); `deliver` follows `ship`. An API older than these routes answers `orders_unsupported` or `fulfillment_unsupported`.
 
 ## The store speaks UCP
 Each store is a UCP business at `https://<org>.sandbox.commercelayer.store` (live stores: `<slug>.commercelayer.store`), implementing release **2026-08-25** over REST:
@@ -181,6 +182,8 @@ The CLI is a UCP **platform**: its profile is served at `https://commercelayer.a
 
 An agent can buy from any UCP store on behalf of its human, one step per command, talking to the human in between: `ucp search` to show the products (words in any order; `--category`, which includes the subcategories, and `--min-price`/`--max-price` in major units narrow it; the `messages` the store sends, such as its categories when nothing matched, are passed on), `ucp checkout create --item <variant id>:<qty>` for what they picked (the `variants[].id` search lists; the sku on Commerce Layer stores), `ucp checkout update <id>` with the email and shipping address they give (never invented), then, once they said yes to the total, `ucp checkout complete <id>`, and the order's `label` and `permalink_url` back to them. Money comes as `{ amount, currency, major, display }`: `amount` in minor units as UCP has it, `display` for the human. The store is `--store <hostname or origin>`, or this folder's store when there is one; checkout and order ids are remembered with their store (in `~/.local/state/c11r/ucp.json`), so later steps need no `--store`. Paying needs the store's sandbox handler (`ai.commercelayer.sandbox`, test payments only): any store without it (every store taking real payments) answers `payment_handler_unsupported`, and the human pays at the checkout's `continue_url`. Responses are signature-checked like `orders test`: `signature` is `verified`, `invalid`, `unknown_key` or `unsigned`.
 
+`--images` is for agents that can read image files and want to look at or describe a product: it saves each product's `image_url` under `<tmpdir>/c11r/images/<store host>/` (the first 24, in parallel, 5 s each, a file already there reused) and adds `image_file`, the absolute path, or `image_error`. Showing a thumbnail in a chat needs only `image_url`, which checkout and order line items carry too.
+
 ## Requirements
 
 Node 20 or later. One runtime dependency (`yaml`).

package/dist/api/client.js

@@ -1,5 +1,6 @@
 // The client for the management API at api.commercelayer.ai.
-import { CliError, fail } from '../output.js';
+import { CliError, fail, notice } from '../output.js';
+import { NPX } from '../version.js';
 import { apiUrl, DEFAULT_API_URL, send } from './transport.js';
 export function createApi(auth) {
     const base = apiUrl() === 'stub' ? DEFAULT_API_URL : apiUrl().replace(/\/$/, '');
@@ -20,6 +21,19 @@ export function createApi(auth) {
         catch {
             fail('api_error', `${base} answered ${res.status} with something that is not JSON.`, 'Try again. If it keeps happening, tell the human, with the output of `c11r status`.');
         }
+        // The API flags an outdated CLI (from the User-Agent) in warnings, on any answer, errors included.
+        const warnings = data && typeof data === 'object' && !Array.isArray(data) ? data.warnings : undefined;
+        if (Array.isArray(warnings)) {
+            const isOutdated = (w) => !!w && typeof w === 'object' && w.code === 'cli_outdated';
+            for (const n of warnings.filter(isOutdated))
+                notice({ ...n, hint: n.hint ?? `Run the commands with ${NPX}. If c11r is installed globally, tell the human it is on ${n.current} and ${n.latest} exists.` });
+            // Printed once, at the top of the output, not inside the order or store it came with.
+            const rest = warnings.filter((w) => !isOutdated(w));
+            if (rest.length)
+                data.warnings = rest;
+            else
+                delete data.warnings;
+        }
         if (res.status < 400)
             return data;
         const err = data?.error;

package/dist/api/stub/index.js

@@ -16,7 +16,7 @@ export function handle(req) {
         url = new URL(`https://${prefixed[1]}${prefixed[2] ?? '/'}${url.search}`);
     const org = orgOfHost(url.hostname);
     if (org === null)
-        return handleManagement({ ...req, url });
+        return outdated(req, handleManagement({ ...req, url }));
     const db = readDb();
     const store = db[org];
     if (!store)
@@ -25,3 +25,28 @@ export function handle(req) {
     writeDb(db);
     return res;
 }
+/** "0.5.1" → [0, 5, 1], for comparing versions. */
+const parts = (v) => v.split('.').map((n) => Number.parseInt(n, 10) || 0);
+const older = (a, b) => {
+    const [x, y] = [parts(a), parts(b)];
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) < (y[i] ?? 0);
+    return false;
+};
+/**
+ * Like the API: a CLI whose User-Agent (c11r/<version>) is older than the latest gets a
+ * cli_outdated warning on every JSON object it is answered. The stub's latest is
+ * C11R_STUB_LATEST_CLI; unset, every CLI is current.
+ */
+function outdated(req, res) {
+    const latest = process.env.C11R_STUB_LATEST_CLI;
+    const current = req.headers['user-agent']?.match(/^c11r\/(\d+\.\d+\.\d+)/)?.[1];
+    if (!latest || !current || !older(current, latest) || !res.body)
+        return res;
+    const body = JSON.parse(res.body.toString());
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return res;
+    const warning = { code: 'cli_outdated', current, latest, hint: `Run the commands with npx -y @commercelayer/agent-cli@latest. If c11r is installed globally, tell the human it is on ${current} and ${latest} exists.` };
+    return { ...res, body: JSON.stringify({ ...body, warnings: [...(Array.isArray(body.warnings) ? body.warnings : []), warning] }) };
+}

package/dist/api/stub/orders.js

@@ -4,7 +4,8 @@
 //
 // An order lands placed with its payment authorized. approve (optionally with
 // capture), capture, cancel, refund, archive and unarchive move it; its one shipment
-// goes upcoming → on_hold | picking | packing | ready_to_ship → shipped → delivered.
+// goes upcoming → on_hold | picking → packing → ready_to_ship → shipped → delivered; as in
+// Commerce Layer, an upcoming shipment ships only once it is picking (or past it).
 import { money } from '../../ucp/shop.js';
 import { minorUnits } from '../../ucp/platform.js';
 import { baseLanguage } from './locale.js';
@@ -147,9 +148,9 @@ function orderCommands(o) {
     const out = [];
     if (m.status === 'placed')
         out.push(`c11r orders approve ${n} [--capture]`);
-    if (m.status === 'approved' && pay === 'authorized')
+    if (m.status !== 'cancelled' && pay === 'authorized')
         out.push(`c11r orders capture ${n}`);
-    if (m.status !== 'cancelled' && !['shipped', 'delivered'].includes(m.shipment.status) && ['authorized', 'free'].includes(pay))
+    if (m.status !== 'cancelled' && !['shipped', 'delivered'].includes(m.shipment.status))
         out.push(`c11r orders cancel ${n}`);
     if (['paid', 'partially_refunded'].includes(pay))
         out.push(`c11r orders refund ${n} [--amount <major>]`);
@@ -206,8 +207,9 @@ export function orderAction(r, id, action, body) {
                 capture();
             break;
         case 'capture':
-            if (m.status !== 'approved' || paymentStatus(o) !== 'authorized')
-                refuse(`Order ${number(o)} is ${m.status} with payment ${paymentStatus(o)}: only an approved order with an authorized payment can be captured.`, orderCommands(o));
+            // As in Commerce Layer: a placed order can be captured before it is approved.
+            if (m.status === 'cancelled' || paymentStatus(o) !== 'authorized')
+                refuse(`Order ${number(o)} is ${m.status} with payment ${paymentStatus(o)}: only an authorized payment can be captured.`, orderCommands(o));
             capture();
             break;
         case 'cancel':
@@ -215,10 +217,12 @@ export function orderAction(r, id, action, body) {
                 refuse(`Order ${number(o)} is already cancelled.`, orderCommands(o));
             if (['shipped', 'delivered'].includes(m.shipment.status))
                 refuse(`Order ${number(o)} has shipped: it cannot be cancelled.`, orderCommands(o));
-            if (!['authorized', 'free'].includes(paymentStatus(o)))
-                refuse(`Order ${number(o)} has payment ${paymentStatus(o)}: refund it to cancel it.`, orderCommands(o));
+            // Commerce Layer voids an authorized payment and refunds a captured one.
             if (paymentStatus(o) === 'authorized')
                 m.transactions.push({ type: 'void', amount: total(o), succeeded: true, at });
+            const left = sum(o, 'capture') - sum(o, 'refund');
+            if (left > 0)
+                m.transactions.push({ type: 'refund', amount: left, succeeded: true, at });
             m.status = 'cancelled';
             m.shipment.status = 'cancelled';
             break;
@@ -286,7 +290,7 @@ function shipmentCommands(o) {
     can('pick', approved && ['upcoming', 'on_hold', 'packing', 'ready_to_ship'].includes(s.status));
     can('pack', approved && ['on_hold', 'picking', 'ready_to_ship'].includes(s.status));
     can('ready', approved && ['on_hold', 'picking', 'packing'].includes(s.status));
-    can('ship', approved && OPEN_SHIPMENTS.includes(s.status));
+    can('ship', approved && WORKING.includes(s.status));
     can('deliver', s.status === 'shipped');
     if (!out.length && merchant(o).status === 'placed')
         out.push(`c11r orders approve ${number(o)} [--capture]`);
@@ -346,7 +350,7 @@ export function shipmentAction(r, id, action, body) {
             }
             if (body?.tracking_url !== undefined && !URL_RE.test(body.tracking_url))
                 throw new OrderError(422, 'invalid_argument', `tracking_url ${body.tracking_url} is not an https URL.`, 'Give --tracking-url the carrier\'s tracking page, starting with https://.');
-            move('shipped', OPEN_SHIPMENTS, true);
+            move('shipped', WORKING, true);
             if (body?.carrier || body?.tracking || body?.tracking_url)
                 s.tracking = { carrier: body.carrier, number: body.tracking, url: body.tracking_url };
             return showShipment(r, s.id);

package/dist/api/stub/theme.js

@@ -155,8 +155,23 @@ function renderPage(r, path, search, locale) {
     return page(r, { lang: locale ? tag(locale) : 'en', title, head: locale ? alternates(localesOf(r), path) : '', header, body, description: tagline, home: `${prefix}/${keep}` });
 }
 const xml = (t) => String(t ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]);
-/** /tiles/<sku>.svg and /tiles/hero.svg: a plain stand-in for the store host's generated tiles. */
+/** A 1×1 PNG: the stand-in for a generated PNG tile. */
+const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkqF9fDwAEAQG/jvkFNQAAAABJRU5ErkJggg==', 'base64');
+/** /tiles/<sku>.svg, /tiles/<sku>.png and /tiles/hero.svg: a plain stand-in for the store host's generated tiles. */
 export function renderTile(r, path, search) {
+    const png = path.match(/^\/tiles\/([^/]+)\.png$/);
+    if (png) {
+        let sku;
+        try {
+            sku = decodeURIComponent(png[1]);
+        }
+        catch {
+            return null;
+        }
+        if (!r.applied?.products[sku])
+            return null;
+        return { status: 200, headers: { 'content-type': 'image/png', 'cache-control': 'public, max-age=300', 'x-content-type-options': 'nosniff' }, body: PNG };
+    }
     const m = path.match(/^\/tiles\/([^/]+)\.svg$/);
     if (!m)
         return null;

package/dist/api/stub/ucp.js

@@ -68,7 +68,7 @@ function negotiate(platformUrl) {
 // ---------- the REST service
 const protocolError = (status, code, content, headers = {}) => json(status, { code, content }, headers);
 function withUcpHeaders(r, res) {
-    const digest = contentDigest(res.body);
+    const digest = contentDigest(res.body.toString());
     const values = { '@status': String(res.status), 'content-digest': digest, 'content-type': res.headers['content-type'] ?? 'application/json' };
     const sig = signHeaders('sig1', values, { components: ['@status', 'content-digest', 'content-type'], keyid: r.ucp.kid, created: Math.floor(Date.now() / 1000) }, r.ucp.private_jwk);
     return { ...res, headers: { ...res.headers, 'content-digest': digest, ...sig } };
@@ -114,7 +114,7 @@ function handleService(req, r, origin, path) {
     const res = dispatch(ctx, req.method, path, parsed);
     res.headers['content-language'] = ctx.language;
     if (mutating && key)
-        r.ucp.idempotency[`${req.method} ${path} ${key}`] = { digest, status: res.status, headers: res.headers, body: res.body };
+        r.ucp.idempotency[`${req.method} ${path} ${key}`] = { digest, status: res.status, headers: res.headers, body: res.body.toString() };
     return res;
 }
 function dispatch(ctx, method, path, body) {

package/dist/api/transport.js

@@ -5,23 +5,33 @@
 // stands in for the whole platform.
 import { fail } from '../output.js';
 import { handle } from './stub/index.js';
+import { USER_AGENT } from '../version.js';
 export const DEFAULT_API_URL = 'https://api.commercelayer.ai';
 export const apiUrl = () => process.env.C11R_API_URL ?? DEFAULT_API_URL;
+/** Where a request goes: to a local API, other hosts through its /-/<host>/ prefix. */
+function targetOf(url) {
+    const base = apiUrl();
+    const baseUrl = new URL(base);
+    const targetUrl = new URL(url);
+    if (base !== DEFAULT_API_URL && targetUrl.host !== baseUrl.host && !url.startsWith(base)) {
+        return `${base.replace(/\/$/, '')}/-/${targetUrl.host}${targetUrl.pathname}${targetUrl.search}`;
+    }
+    return url;
+}
 export async function send(method, url, headers = {}, body) {
     const base = apiUrl();
     const lower = {};
     for (const [k, v] of Object.entries(headers))
         lower[k.toLowerCase()] = v;
+    // On every request, to the API and to stores: the API tells an outdated CLI so (cli_outdated).
+    lower['user-agent'] ??= USER_AGENT;
     if (body !== undefined && !lower['content-type'])
         lower['content-type'] = 'application/json';
-    if (base === 'stub')
-        return handle({ method, url: new URL(url), headers: lower, body });
-    let target = url;
-    const baseUrl = new URL(base);
-    const targetUrl = new URL(url);
-    if (base !== DEFAULT_API_URL && targetUrl.host !== baseUrl.host && !url.startsWith(base)) {
-        target = `${base.replace(/\/$/, '')}/-/${targetUrl.host}${targetUrl.pathname}${targetUrl.search}`;
+    if (base === 'stub') {
+        const r = handle({ method, url: new URL(url), headers: lower, body });
+        return { ...r, body: r.body.toString() };
     }
+    const target = targetOf(url);
     let res;
     try {
         // Never follow redirects: UCP forbids it for profiles, and the 302/303 of
@@ -35,3 +45,13 @@ export async function send(method, url, headers = {}, body) {
     res.headers.forEach((v, k) => (resHeaders[k] = v));
     return { status: res.status, headers: resHeaders, body: await res.text() };
 }
+/** A file over GET, as bytes, within timeoutMs; redirects are followed (images sit behind CDNs). Throws on failure. */
+export async function download(url, timeoutMs) {
+    const headers = { 'user-agent': USER_AGENT, accept: 'image/*' };
+    if (apiUrl() === 'stub') {
+        const r = handle({ method: 'GET', url: new URL(url), headers });
+        return { status: r.status, type: r.headers['content-type'] ?? '', bytes: Buffer.from(r.body) };
+    }
+    const res = await fetch(targetOf(url), { headers, signal: AbortSignal.timeout(timeoutMs) });
+    return { status: res.status, type: res.headers.get('content-type') ?? '', bytes: Buffer.from(await res.arrayBuffer()) };
+}

package/dist/bin.js

@@ -4,6 +4,7 @@
 // Output is always JSON; exit code 1 on an error or a failed check.
 import * as cmd from './commands.js';
 import { CliError, print } from './output.js';
+import { LATEST_HINT, NPX } from './version.js';
 const VALUE_OPTIONS = new Set(['--name', '--sku', '--quantity', '--country', '--code', '--file', '--store', '--item', '--email', '--first-name', '--last-name', '--phone', '--street', '--city', '--postal-code', '--region', '--shipping', '--category', '--min-price', '--max-price', '--status', '--payment', '--fulfillment', '--limit', '--archived', '--amount', '--carrier', '--tracking', '--tracking-url']);
 const argv = process.argv.slice(2);
 const flags = new Set();
@@ -36,7 +37,7 @@ for (let i = 0; i < argv.length; i++) {
 const [name, sub] = args;
 async function run() {
     if (flags.has('--version') || name === 'version')
-        return { version: cmd.VERSION };
+        return { version: cmd.VERSION, latest_hint: LATEST_HINT };
     switch (name) {
         case undefined:
         case 'help':
@@ -113,9 +114,9 @@ async function run() {
             if (sub === 'check')
                 return cmd.ucpCheck();
             if (sub === 'search')
-                return cmd.ucpSearch(args.slice(2).join(' '), values, lists);
+                return cmd.ucpSearch(args.slice(2).join(' '), values, lists, flags);
             if (sub === 'product')
-                return cmd.ucpProduct(args[2], values);
+                return cmd.ucpProduct(args[2], values, flags);
             if (sub === 'order')
                 return cmd.ucpOrder(args[2], values);
             if (sub === 'ask')
@@ -151,7 +152,7 @@ run()
     }
     else {
         const message = e instanceof Error ? e.message : String(e);
-        print({ error: { code: 'internal', message, hint: 'This is a bug in the CLI. Tell the human, with this output, and try again with npx -y @commercelayer/agent-cli@latest in case it is already fixed.' } });
+        print({ error: { code: 'internal', message, hint: `This is a bug in the CLI. Tell the human, with this output, and try again with ${NPX} in case it is already fixed.` } });
     }
     process.exit(1);
 });

package/dist/commands.js

@@ -1,7 +1,6 @@
 // One function per command. Each returns the object the CLI prints, or throws a
 // CliError. Every command is safe to re-run.
 import fs from 'node:fs';
-import { createRequire } from 'node:module';
 import path from 'node:path';
 import { createApi } from './api/client.js';
 import { ignoreCredentials, paths, readCredentials, requireCredentials, writeAgentNotes, writeCredentials } from './files.js';
@@ -17,10 +16,11 @@ import { storefrontCheck } from './check.js';
 import { buy } from './ucp/buy.js';
 import { check } from './ucp/check.js';
 import { discover } from './ucp/client.js';
+import { MAX_IMAGES, withImages } from './ucp/images.js';
 import * as shop from './ucp/shop.js';
 import { agentProfile, AGENT_PROFILE_URL } from './ucp/platform.js';
-/** The package version, read from package.json so a release bumps it in one place. */
-export const VERSION = createRequire(import.meta.url)('../package.json').version;
+import { LATEST_HINT, VERSION } from './version.js';
+export { VERSION } from './version.js';
 export const HELP = {
     init: 'Create a sandbox store for this repo, with no login: c11r init --name "<business name>" (the folder name when --name is absent). The name becomes the organization\'s name, and the org slug and store hostname derive from it. Writes .commercelayer/store.yml and .commercelayer/credentials, and a section in AGENTS.md and CLAUDE.md (created, or appended once) that points later agents in this repo to the skills: commit them. Reuses the store if store.yml already exists.',
     plan: 'Show what apply would create, update or delete: markets, products, images, and the store\'s name, language, policies and theme; missing_images lists references with no file in .commercelayer/img/ (apply refuses them), unused_images files nothing references, from .commercelayer/store.yml and the product files under .commercelayer/products/ (*.yml lists, *.csv rows, merged by sku). Products may carry other languages: name, description and category as { <ll>: text } maps (the base language, store.yml language:, default en, among them), or name_<ll>, description_<ll>, category_<ll> CSV columns; at most 6 languages. warnings lists a language no country of the store speaks.',
@@ -46,8 +46,8 @@ export const HELP = {
     'orders list': "The store's orders, live in Commerce Layer, newest first: by default the placed and approved ones, not archived, 25 at most. c11r orders list [--status placed|approved|cancelled|editing|all] [--payment authorized|paid|refunded|partially_refunded|voided|...] [--fulfillment unfulfilled|in_progress|fulfilled|not_required] [--archived [all]] [--limit 1-100]; a comma list takes several (--status placed,cancelled). Returns { count, orders: [{ id, number, status, payment_status, fulfillment_status, placed_at, market, country, currency, total: { amount, currency, major, display }, email, items, shipments: [{ id, number, status, tracking }], archived }], next }. Orders arrive placed with the payment authorized, not taken: they wait for the human to accept them.",
     'orders show': 'One order as the merchant sees it: c11r orders show <number, #number or id>. Returns { order: { ...as in orders list, line_items: [{ sku, name, quantity, unit_price, total }], totals: { subtotal, discount, shipping, taxes, total, codes }, shipping_address, billing_address, shipping_method, payment: { method, source, status, captured, refundable }, transactions: [{ type, amount, succeeded, at }], language, archived_at, ucp: { id, permalink_url } }, next }. next says what the order is waiting for.',
     'orders approve': "Accept a placed order, only once the human said to: c11r orders approve <number> [--capture]. With --capture the authorized payment is taken too; without, take it later with orders capture. Returns { status, order, next } with the order after it. An order that cannot be approved answers invalid_transition: its hint lists what it allows now.",
-    'orders capture': 'Take the authorized payment of an approved order, once the human said to: c11r orders capture <number>. Returns { status, order, next }; invalid_transition when it is not approved or already captured.',
-    'orders cancel': "Cancel an order the human does not want, before it ships: c11r orders cancel <number>. An authorized payment is voided. A shipped order cannot be cancelled, and a captured one is refunded instead (orders refund): both answer invalid_transition, with what is allowed in the hint. Returns { status, order, next }.",
+    'orders capture': 'Take the authorized payment of an order, once the human said to: c11r orders capture <number>. Usually after approving it (or at once with orders approve --capture); a placed order can be captured too. Returns { status, order, next }; invalid_transition when nothing authorized is left to capture.',
+    'orders cancel': "Cancel an order the human does not want, before it ships: c11r orders cancel <number>. An authorized payment is voided, a captured one refunded in full. A shipped order cannot be cancelled (refund it with orders refund): invalid_transition, with what is allowed in the hint. Returns { status, order, next }.",
     'orders refund': "Give money back on a captured order, only the amount the human said: c11r orders refund <number> [--amount <n>]. --amount is in major units (4.50); without it, everything still refundable. Refunding the last of the payment cancels the order. Returns { status, order, next }; refund_exceeds when the amount is more than payment.refundable.",
     'orders archive': 'Hide an order from orders list (any status), for orders that need nothing more: c11r orders archive <number>. Idempotent. orders list --archived shows them.',
     'orders unarchive': 'Bring an archived order back into orders list: c11r orders unarchive <number>. Idempotent.',
@@ -57,20 +57,20 @@ export const HELP = {
     'fulfillment pick': 'Mark a shipment as being picked: c11r fulfillment pick <shipment>. Needs the order approved. on_hold, picking, packing and ready_to_ship move freely between each other. Returns { status, shipment, next }; invalid_transition says what is allowed now.',
     'fulfillment pack': 'Mark a shipment as being packed: c11r fulfillment pack <shipment>. Needs the order approved. Returns { status, shipment, next }.',
     'fulfillment ready': 'Mark a shipment ready to ship: c11r fulfillment ready <shipment>. Needs the order approved. Returns { status, shipment, next }.',
-    'fulfillment ship': "Mark a shipment shipped, with the carrier's tracking when the human has it: c11r fulfillment ship <shipment> [--carrier <name>] [--tracking <number>] [--tracking-url <https url>]. Needs the order approved; works from upcoming or any step before. Ask the human for the tracking, never invent it. Returns { status, shipment, next }.",
+    'fulfillment ship': "Mark a shipment shipped, with the carrier's tracking when the human has it: c11r fulfillment ship <shipment> [--carrier <name>] [--tracking <number>] [--tracking-url <https url>]. Needs the order approved and the shipment picked first (c11r fulfillment pick <shipment>): an upcoming shipment cannot ship. Ask the human for the tracking, never invent it. Returns { status, shipment, next }.",
     'fulfillment deliver': 'Mark a shipped shipment delivered: c11r fulfillment deliver <shipment>. Returns { status, shipment, next }.',
     'ucp profile': 'Show the store\'s UCP business profile (/.well-known/ucp). With --agent, this CLI\'s own platform profile instead.',
     'ucp check': 'Walk every UCP capability the store advertises and report what passes. Places and pays one real test order on the way. Exits 1 when a check fails.',
-    'ucp search': "Buy for the human, step 1: search a store's catalog over UCP. c11r ucp search [<words>] [--category <name>] [--min-price <n>] [--max-price <n>] [--country CC] [--store <host>]. Search with the words that matter, in any order (\"dark roast coffee\" or \"coffee dark\"): the store ranks products with every word first; no words lists the whole catalog (up to 50). --category narrows to a category or its subcategories (\"Coffee\" includes \"Coffee > Single origin\"), repeat it for any of several; --min-price and --max-price are in major units of the store's currency (15 means 15.00); --country is the human's country: prices, shipping and availability for it. Returns { store, query, prices: { market, market_name, currency, countries, tax_included }, filters, count, total_count, has_more, products: [{ id, title, description, url, image_url, categories: [\"Coffee > Single origin\"], partial, matched_on, variants: [{ id, sku, title, price: { amount, currency, major, display }, list_price, available, availability, shipping: { to, option, price, earliest, latest, ships_to_country } }] }], messages, signature }. list_price is the price before a sale, only when there is one; partial: true marks a product with only some of the words. Show the human the titles, categories and price.display (amount is in minor units: never show it), with shipping.price.display and the arrival dates when they ask what it costs delivered; let them pick, then c11r ucp checkout create --item <variant id>. Read messages and pass on what they say: with no results or a partial match they list the store's categories, and prices says which market the prices are for. --store is any store that speaks UCP (hostname or https origin); the default is this folder's store.",
-    'ucp product': 'Look at one product over UCP, with every variant and the full description: c11r ucp product <product id> [--country CC] [--store <host>]. Returns { store, product: { id, title, description, url, image_url, variants: [...] }, signature }, variants as in ucp search.',
-    'ucp checkout create': "Buy for the human, step 2: open a checkout with the items the human picked. c11r ucp checkout create --item <variant id>[:<qty>] [--item ...] [--code <discount>] [--country CC] [--store <host>]. Returns the checkout: { id, status, store, currency, line_items: [{ id, item_id, title, quantity, unit_price, total }], buyer, ship_to, shipping, discounts, codes, totals: [{ type, label, amount, major, display }], total, messages, continue_url, expires_at, links, signature }. status is incomplete until the buyer's email and shipping address are given: messages say what is missing. Ask the human for them, never invent them, then c11r ucp checkout update <id>. The id is remembered with its store: later steps need no --store.",
+    'ucp search': "Buy for the human, step 1: search a store's catalog over UCP. c11r ucp search [<words>] [--category <name>] [--min-price <n>] [--max-price <n>] [--country CC] [--images] [--store <host>]. Search with the words that matter, in any order (\"dark roast coffee\" or \"coffee dark\"): the store ranks products with every word first; no words lists the whole catalog (up to 50). --category narrows to a category or its subcategories (\"Coffee\" includes \"Coffee > Single origin\"), repeat it for any of several; --min-price and --max-price are in major units of the store's currency (15 means 15.00); --country is the human's country: prices, shipping and availability for it. Returns { store, query, prices: { market, market_name, currency, countries, tax_included }, filters, count, total_count, has_more, products: [{ id, title, description, url, image_url, categories: [\"Coffee > Single origin\"], partial, matched_on, variants: [{ id, sku, title, price: { amount, currency, major, display }, list_price, available, availability, shipping: { to, option, price, earliest, latest, ships_to_country } }] }], messages, signature }. list_price is the price before a sale, only when there is one; partial: true marks a product with only some of the words. Show the human the titles, categories and price.display (amount is in minor units: never show it), with shipping.price.display and the arrival dates when they ask what it costs delivered; let them pick, then c11r ucp checkout create --item <variant id>. Read messages and pass on what they say: with no results or a partial match they list the store's categories, and prices says which market the prices are for. --store is any store that speaks UCP (hostname or https origin); the default is this folder's store. --images is for agents that can read image files and want to look at or describe a product: it saves each product's image (the first 24) and adds image_file, the file's absolute path, or image_error when the download failed; showing a thumbnail in a chat needs only image_url.",
+    'ucp product': "Look at one product over UCP, with every variant and the full description: c11r ucp product <product id> [--country CC] [--images] [--store <host>]. Returns { store, product: { id, title, description, url, image_url, variants: [...] }, signature }, variants as in ucp search. --images is for agents that can read image files and want to look at or describe a product: it saves the product's image and adds image_file, the file's absolute path, or image_error when the download failed; showing a thumbnail in a chat needs only image_url.",
+    'ucp checkout create': "Buy for the human, step 2: open a checkout with the items the human picked. c11r ucp checkout create --item <variant id>[:<qty>] [--item ...] [--code <discount>] [--country CC] [--store <host>]. Returns the checkout: { id, status, store, currency, line_items: [{ id, item_id, title, image_url, quantity, unit_price, total }], buyer, ship_to, shipping, discounts, codes, totals: [{ type, label, amount, major, display }], total, messages, continue_url, expires_at, links, signature }. status is incomplete until the buyer's email and shipping address are given: messages say what is missing. Ask the human for them, never invent them, then c11r ucp checkout update <id>. The id is remembered with its store: later steps need no --store.",
     'ucp checkout update': "Buy for the human, step 3: give the buyer's details, change items or codes. c11r ucp checkout update <id> [--email --first-name --last-name --phone] [--street --city --postal-code --region --country] [--item <variant id>:<qty> (0 removes)] [--code <discount> (adds)] [--shipping <option id>]; or the same as YAML or JSON on stdin or -f <file>: { buyer: { email, first_name, last_name, phone_number }, address: { street_address, address_locality, postal_code, address_region, address_country }, items: [\"ID:2\"], codes: [...] (replaces), shipping }. Only what is given changes. Returns the checkout as in create: status ready_for_complete once nothing is missing, with shipping and the total including it; or incomplete with messages (address_undeliverable says where the store ships). Show the human the line items, shipping and total.display, ask for an explicit yes, then c11r ucp checkout complete <id>.",
     'ucp checkout show': 'Show a checkout as the store has it now: c11r ucp checkout show <id> [--store <host>]. Returns the checkout as in ucp checkout create.',
     'ucp checkout cancel': 'Cancel a checkout the human no longer wants: c11r ucp checkout cancel <id> [--store <host>]. Returns the checkout, status canceled.',
     'ucp checkout complete': "Buy for the human, step 4, only after the human said yes to the total: pay the checkout. c11r ucp checkout complete <id> [--decline] [--store <host>]. Pays with the ai.commercelayer.sandbox test handler (no money moves): only stores that advertise it can be paid; --decline uses the declined test card. Returns the checkout with status completed and order: { id, label, permalink_url }, plus payment_handler. Tell the human the order label and give them permalink_url. A store without that handler (any store taking real payments) answers payment_handler_unsupported: give the human continue_url to pay there. A declined payment leaves status ready_for_complete with a payment_failed message.",
-    'ucp order': 'Read an order this CLI placed: c11r ucp order <id> [--store <host>]. Returns { id, label, permalink_url, store, checkout_id, currency, line_items: [{ item_id, title, quantity, status, total }], fulfillment: [{ method, destination, description }], events, totals, signature }.',
+    'ucp order': 'Read an order this CLI placed: c11r ucp order <id> [--store <host>]. Returns { id, label, permalink_url, store, checkout_id, currency, line_items: [{ item_id, title, image_url, quantity, status, total }], fulfillment: [{ method, destination, description }], events, totals, signature }.',
     'ucp ask': 'Ask a store a question in plain language over UCP (shipping, returns, what it sells): c11r ucp ask "<question>" [--store <host>]. Returns { store, question, answer, links, messages, signature }. The answer is the store\'s: quote it, do not embellish it. Ask only answers; buy with ucp checkout.',
-    status: 'Show the sandbox, what is applied, and whether the store files have changes not yet applied (the same changes plan lists).',
+    status: 'Show the sandbox, what is applied, and whether the store files have changes not yet applied (the same changes plan lists). search is the store\'s semantic search index: { model, status: indexing|ready|failed|too_large, vectors, embedded, updated_at, error }, or null before it first runs; until it is ready the store\'s search matches words only.',
     claim: 'Start keeping this sandbox store: returns a URL and a code for the human to approve in the browser.',
     help: 'Describe the commands. `c11r help <command>` for one command, `c11r help <group>` (catalog, fulfillment, links, orders, promotions, storefront, ucp) for a group.',
 };
@@ -87,7 +87,7 @@ export function help(name) {
         const showsFormat = name === 'apply' || name === 'plan';
         return { command: name, description: HELP[name], store_format: showsFormat ? template('<name>') : undefined };
     }
-    return { version: VERSION, commands: HELP, note: 'Every command prints JSON. The store format is documented in the comments of .commercelayer/store.yml; large catalogs go in .commercelayer/products/ as .yml or .csv files.' };
+    return { version: VERSION, latest_hint: LATEST_HINT, commands: HELP, note: 'Every command prints JSON. The store format is documented in the comments of .commercelayer/store.yml; large catalogs go in .commercelayer/products/ as .yml or .csv files.' };
 }
 export async function init(values) {
     const existing = readCredentials();
@@ -305,7 +305,7 @@ export async function ordersTest(flags, values) {
         messages: p.checkout.messages ?? p.ready.messages,
         payment_handler: 'ai.commercelayer.sandbox (test payments only)',
         steps: p.steps,
-        next: p.checkout.status === 'completed' ? `Placed, payment authorized: approve and capture it with c11r orders approve ${String(p.order?.label ?? p.order?.id).replace(/^#/, '')} --capture, then ship it with c11r fulfillment ship.` : undefined,
+        next: p.checkout.status === 'completed' ? `Placed, payment authorized: approve and capture it with c11r orders approve ${String(p.order?.label ?? p.order?.id).replace(/^#/, '')} --capture, then ship it with c11r fulfillment pick and ship.` : undefined,
     };
 }
 // Orders and shipments, live in Commerce Layer through the API. An order lands placed with its
@@ -323,13 +323,15 @@ function orderNext(o) {
     const shipment = o.shipments?.[0];
     if (o.status === 'cancelled')
         return `Order ${n} is cancelled (payment ${o.payment_status}). Nothing more to do; archive it to keep the list short: c11r orders archive ${n}.`;
+    if (o.status === 'placed' && o.payment_status !== 'authorized')
+        return `Order ${n} is placed; its payment is ${o.payment_status?.replace(/_/g, ' ')} (taken before approving). When the human accepts it, approve it: c11r orders approve ${n}. If they don't want it: c11r orders cancel ${n} (Commerce Layer refunds what was taken).`;
     if (o.status === 'placed')
         return `Order ${n} is placed and its payment is authorized, not taken. When the human accepts it, approve it and take the payment: c11r orders approve ${n} --capture (without --capture to take it later). If they don't want it: c11r orders cancel ${n}.`;
     if (o.payment_status === 'authorized')
         return `Order ${n} is approved; the payment is authorized but not taken. Take it when the human says so: c11r orders capture ${n}.`;
     if (o.fulfillment_status === 'fulfilled')
         return `Order ${n} has shipped${shipment?.tracking?.number ? ` (tracking ${shipment.tracking.number})` : ''}. Mark it delivered when it arrives: c11r fulfillment deliver ${shipment?.number ?? n}; refund all or part if the human asks: c11r orders refund ${n} [--amount <n>].`;
-    return `Order ${n} is approved and paid (${o.total?.display}). Ship it: c11r fulfillment ship ${shipment?.number ?? n} [--carrier <name> --tracking <number> --tracking-url <url>], or move it through picking and packing first (c11r fulfillment pick, pack, ready).`;
+    return `Order ${n} is approved and paid (${o.total?.display}). Pick it, then ship it: c11r fulfillment pick ${shipment?.number ?? n}, then c11r fulfillment ship ${shipment?.number ?? n} [--carrier <name> --tracking <number> --tracking-url <url>] (pack and ready in between if the human tracks them).`;
 }
 export async function ordersList(values, flags) {
     const api = createApi(requireCredentials());
@@ -378,6 +380,8 @@ function shipmentNext(s) {
         return `Shipment ${n} is on its way${s.tracking?.number ? ` (tracking ${s.tracking.number})` : ''}. Mark it delivered when it arrives: c11r fulfillment deliver ${n}.`;
     if (s.order?.status === 'placed')
         return `Shipment ${n} waits for its order ${s.order.number} to be approved: c11r orders approve ${s.order.number} --capture, once the human accepts it. It can be held meanwhile: c11r fulfillment hold ${n}.`;
+    if (s.status === 'upcoming')
+        return `Shipment ${n} is upcoming. Pick it first: c11r fulfillment pick ${n}; then ship it when it leaves: c11r fulfillment ship ${n} [--carrier <name> --tracking <number> --tracking-url <url>].`;
     return `Shipment ${n} is ${s.status.replace(/_/g, ' ')}. Ship it when it leaves: c11r fulfillment ship ${n} [--carrier <name> --tracking <number> --tracking-url <url>]; or move it on: c11r fulfillment pick, pack, ready or hold ${n}.`;
 }
 export async function fulfillmentList(values) {
@@ -462,6 +466,8 @@ export async function status() {
         markets: s.applied ? Object.keys(s.applied.markets) : [],
         products: s.applied ? Object.keys(s.applied.products).length : 0,
         orders: s.orders.map((o) => ({ id: o.id, label: o.label })),
+        // Semantic search: until it is ready, the store's search matches words only.
+        search: s.search ? { model: s.search.model, status: s.search.status, vectors: s.search.vectors, embedded: s.search.embedded, updated_at: s.search.updated_at, error: s.search.error } : null,
         ucp_profile: `${s.preview_url}/.well-known/ucp`,
         next: s.apply?.status === 'in_progress' ? 'An apply is running: run `c11r status` again to follow it, or `c11r apply` to wait for it.' : storeError ? 'Fix the store files (see store_error), then run `c11r plan`.' : pending.length ? 'Run `c11r plan` to see the changes, then `c11r apply`.' : undefined,
     };
@@ -509,7 +515,14 @@ const checkoutNext = (ck) => {
     const errors = (ck.messages ?? []).filter((m) => m.type === 'error').map((m) => m.content);
     return `Still needed: ${errors.join(' ') || 'see messages'} Ask the human (never invent buyer details), then run c11r ucp checkout update ${ck.id} with what they said.`;
 };
-export async function ucpSearch(query, values, lists = {}) {
+/** --images: each product's image saved to a file (image_file, or image_error), at most MAX_IMAGES. */
+async function addImages(r, list) {
+    const { products, skipped } = await withImages(r.store, list);
+    return skipped
+        ? { products, warnings: [{ code: 'images_capped', message: `Images were saved for the first ${MAX_IMAGES} products only; ${skipped} more have none.`, hint: 'Narrow the search (words, --category, prices) to get the images of the others.' }] }
+        : { products };
+}
+export async function ucpSearch(query, values, lists = {}, flags = new Set()) {
     const price = (flag) => {
         const raw = values[flag];
         if (raw === undefined)
@@ -527,12 +540,16 @@ export async function ucpSearch(query, values, lists = {}) {
     const next = r.count
         ? 'Show the human the products (title, categories, price.display, and list_price.display when it is on sale), let them pick, then c11r ucp checkout create --item <variant id>[:<qty>] (variants[].id).'
         : 'Nothing matched: read messages (the store may list its categories there), then try other words, a --category, wider prices, or no query for the whole catalog.';
-    return { ...r, next };
+    return flags.has('--images') ? { ...r, ...(await addImages(r, r.products)), next } : { ...r, next };
 }
-export async function ucpProduct(id, values) {
+export async function ucpProduct(id, values, flags = new Set()) {
     if (!id)
         fail('missing_argument', 'ucp product needs a product id.', 'Use a product id from c11r ucp search.');
-    return shop.product(await shopOrigin(values), id, values.country);
+    const r = await shop.product(await shopOrigin(values), id, values.country);
+    if (!flags.has('--images'))
+        return r;
+    const [product] = (await withImages(r.store, [r.product])).products;
+    return { ...r, product };
 }
 export async function ucpCheckoutCreate(values, lists) {
     const items = (lists.item ?? []).map(shop.parseItem);

package/dist/files.js

@@ -63,18 +63,30 @@ export function ignoreCredentials() {
 }
 /** The note that sends a future agent in this repo to the skills. No skill names: it never goes stale. */
 const AGENT_NOTE_HEADING = '# Store on Commerce Layer';
+const SKILLS = 'Before any task about the store (products, prices, markets, storefront, orders, promotions, agents), fetch `https://commercelayer.ai/skills.md` with `curl -fsSL` and load the skill for the task from `skills/<name>.md`; follow it rather than calling the Commerce Layer API directly. If `.commercelayer/store.yml` is missing, start from `https://commercelayer.ai/start.md`.';
 export const AGENT_NOTE = `${AGENT_NOTE_HEADING}
-This store is managed with \`c11r\` (\`npx @commercelayer/agent-cli\`), configured in \`.commercelayer/store.yml\`. Before any task about the store (products, prices, markets, storefront, orders, promotions, agents), fetch \`https://commercelayer.ai/skills.md\` with \`curl -fsSL\` and load the skill for the task from \`skills/<name>.md\`; follow it rather than calling the Commerce Layer API directly. If \`.commercelayer/store.yml\` is missing, start from \`https://commercelayer.ai/start.md\`.
+This store is managed with \`c11r\`, run as \`npx -y @commercelayer/agent-cli@latest\`, configured in \`.commercelayer/store.yml\`. Always use that form, even if a \`c11r\` binary is installed: it stays on the current version. ${SKILLS}
+`;
+/** The note CLIs before 0.5.1 wrote: replaced by the current one when a file has it word for word. */
+const OLD_AGENT_NOTE = `${AGENT_NOTE_HEADING}
+This store is managed with \`c11r\` (\`npx @commercelayer/agent-cli\`), configured in \`.commercelayer/store.yml\`. ${SKILLS}
 `;
 /**
  * Write the note to AGENTS.md and CLAUDE.md (Claude Code reads that name) in the repo root:
  * created when absent, appended as a section when the file has other content, left alone
- * when the section is already there. Returns the files written.
+ * when the section is already there (replaced when it is an older CLI's, word for word).
+ * Returns the files written.
  */
 export function writeAgentNotes() {
     const written = [];
     for (const file of ['AGENTS.md', 'CLAUDE.md']) {
         const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+        // A note an older CLI wrote, untouched since: bring it up to date. An edited one stays as it is.
+        if (before.includes(OLD_AGENT_NOTE)) {
+            fs.writeFileSync(file, before.replace(OLD_AGENT_NOTE, AGENT_NOTE));
+            written.push(file);
+            continue;
+        }
         if (before.split('\n').some((line) => line.trim() === AGENT_NOTE_HEADING))
             continue;
         fs.writeFileSync(file, before.trim() ? `${before.replace(/\s*$/, '')}\n\n${AGENT_NOTE}` : AGENT_NOTE);

package/dist/output.js

@@ -2,6 +2,7 @@
 // A failure is { error: { code, message, hint } } with exit code 1. The hint is
 // the fix: an agent reads it and acts on it before trying anything else.
 // A command that waits (apply) writes progress to stderr, one JSON object per line.
+// Warnings the API sends about the CLI itself (cli_outdated) go into whatever is printed.
 export class CliError extends Error {
     code;
     hint;
@@ -17,6 +18,18 @@ export function fail(code, message, hint) {
 export function progress(data) {
     process.stderr.write(JSON.stringify(data) + '\n');
 }
+const notices = [];
+/** Keep a warning to print with the result, once per code. */
+export function notice(n) {
+    if (!notices.some((x) => x.code === n.code))
+        notices.push(n);
+}
 export function print(data) {
-    process.stdout.write(JSON.stringify(data, null, 2) + '\n');
+    let out = data;
+    if (notices.length && data && typeof data === 'object' && !Array.isArray(data)) {
+        const own = data.warnings;
+        // A command's own warnings are strings or objects; the API's are added after them.
+        out = { ...data, warnings: [...(Array.isArray(own) ? own : own === undefined ? [] : [own]), ...notices] };
+    }
+    process.stdout.write(JSON.stringify(out, null, 2) + '\n');
 }

package/dist/ucp/images.js

@@ -0,0 +1,62 @@
+// --images: each product's image_url saved as a file, for agents that can read images and
+// want to look at or describe a product. Files go under <tmpdir>/c11r/images/<store host>/,
+// named by product id and a hash of the URL, so a file already there is reused and a new
+// image gets a new file. A chat thumbnail needs only image_url, never this.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { download } from '../api/transport.js';
+export const MAX_IMAGES = 24;
+const TIMEOUT_MS = 5000;
+const MAX_BYTES = 10 * 1024 * 1024;
+const EXT = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif', 'image/avif': 'avif', 'image/svg+xml': 'svg' };
+/** The folder of a store's images: C11R_IMAGES_DIR (tests) or the OS temp dir. */
+export const imagesDir = (origin) => path.join(process.env.C11R_IMAGES_DIR ?? path.join(os.tmpdir(), 'c11r', 'images'), new URL(origin).host);
+const safe = (s) => s.replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 80) || 'product';
+/** One product's image: the path of its file, or why there is none. */
+async function fetchImage(dir, p) {
+    const url = p.image_url;
+    if (typeof url !== 'string' || !url)
+        return { image_error: 'The product has no image_url.' };
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { image_error: `image_url ${url} is not a URL.` };
+    }
+    if (!['https:', 'http:'].includes(parsed.protocol))
+        return { image_error: `image_url ${url} is not an http(s) address.` };
+    const stem = `${safe(String(p.id ?? ''))}-${crypto.createHash('sha256').update(url).digest('hex').slice(0, 10)}`;
+    const kept = fs.existsSync(dir) ? fs.readdirSync(dir).find((f) => f.startsWith(`${stem}.`) && Object.values(EXT).includes(f.slice(stem.length + 1))) : undefined;
+    if (kept)
+        return { image_file: path.join(dir, kept) };
+    try {
+        const r = await download(url, TIMEOUT_MS);
+        if (r.status !== 200)
+            return { image_error: `The store answered ${r.status} for ${url}.` };
+        const ext = EXT[r.type.split(';')[0].trim().toLowerCase()];
+        if (!ext)
+            return { image_error: `${url} is not an image (content-type ${r.type || 'missing'}).` };
+        if (r.bytes.length > MAX_BYTES)
+            return { image_error: `${url} is over 10 MB.` };
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, `${stem}.${ext}`);
+        // Written aside then renamed, so a parallel run never reads half a file.
+        const tmp = `${file}.${process.pid}.part`;
+        fs.writeFileSync(tmp, r.bytes);
+        fs.renameSync(tmp, file);
+        return { image_file: file };
+    }
+    catch (e) {
+        const err = e;
+        return { image_error: err.name === 'TimeoutError' ? `${url} took more than ${TIMEOUT_MS / 1000} s.` : `Could not download ${url}: ${err.message}` };
+    }
+}
+/** Products with image_file or image_error, the first MAX_IMAGES in parallel; how many were left out. */
+export async function withImages(origin, products) {
+    const dir = imagesDir(origin);
+    const got = await Promise.all(products.slice(0, MAX_IMAGES).map((p) => fetchImage(dir, p)));
+    return { products: products.map((p, i) => (i < MAX_IMAGES ? { ...p, ...got[i] } : p)), skipped: Math.max(0, products.length - MAX_IMAGES) };
+}

package/dist/ucp/shop.js

@@ -128,6 +128,7 @@ export function checkoutView(ck, origin, call) {
             id: l.id,
             item_id: l.item?.id,
             title: l.item?.title,
+            image_url: l.item?.image_url,
             quantity: l.quantity,
             unit_price: l.item?.price === undefined ? undefined : money(l.item.price, cur),
             total: money((l.totals ?? []).find((t) => t.type === 'total')?.amount ?? 0, cur),
@@ -160,6 +161,7 @@ export function orderView(o, origin, call) {
         line_items: (o.line_items ?? []).map((l) => ({
             item_id: l.item?.id,
             title: l.item?.title,
+            image_url: l.item?.image_url,
             quantity: l.quantity?.total ?? l.quantity,
             status: l.status,
             total: money((l.totals ?? []).find((t) => t.type === 'total')?.amount ?? 0, cur),

package/dist/version.js

@@ -0,0 +1,9 @@
+// The CLI's version and how it names itself on the wire.
+import { createRequire } from 'node:module';
+/** The package version, read from package.json so a release bumps it in one place. */
+export const VERSION = createRequire(import.meta.url)('../package.json').version;
+/** The User-Agent of every request: the API answers cli_outdated when a newer CLI exists. */
+export const USER_AGENT = `c11r/${VERSION} (node/${process.versions.node.split('.')[0]})`;
+/** The one way to run the CLI that is always current, whatever is installed. */
+export const NPX = 'npx -y @commercelayer/agent-cli@latest';
+export const LATEST_HINT = `${NPX} always runs the newest version, even where a c11r binary is installed.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "c11r: the Commerce Layer CLI for coding agents. Builds a sandbox store that people and shopping agents can buy from.",
   "homepage": "https://commercelayer.ai",
   "keywords": [