@commercelayer/agent-cli 1.0.0-dev.19 → 1.0.0-dev.21

package/README.md

@@ -28,9 +28,9 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 | --- | --- |
 | `c11r status` | Where this machine and folder stand: the organization picked and from where, its state, plan, mode, limits, usage and what is waiting; the stored login, if any. |
 | `c11r schema <noun>` | The noun's schema document: fields, filters, verbs, which verbs are destructive and which a loop may automate. |
-| `c11r sandbox create [--name] [--seed]` | An anonymous sandbox. Its token is stored on this machine and never printed; the folder is linked to it. |
+| `c11r sandbox create [--name] [--seed [coffee\|tshirts\|games\|custom]] [--catalogue <file>]` | An anonymous sandbox. Its token is stored on this machine and never printed; the folder is linked to it. With `--seed`, a demo shop of that type with its storefront on, and the shop link in `data.shop_url` and `next`. See below. |
 | `c11r sandbox get`, `reset`, `claim`, `destroy` | The sandbox's details; a fresh organization behind the same token; a claim URL for the human; the end of the sandbox. |
-| `c11r loops create <name> --skill --every [--allow] [--max-total] [--market]` | A loop in `loops.yml`: a skill, a policy and a cadence; with no `--allow` it only reports what is waiting. Also `list`, `get`, `update`, `delete`. |
+| `c11r loops create <name> --skill --every [--allow] [--max-total] [--market]` | A loop in `loops.yml`: a skill, a policy and a cadence; with no `--allow` it only reports what is waiting. A policy that allows a verb with no `--max-total` or no `--market` is saved with a `no_limit` warning naming what is unbounded. Also `list`, `get`, `update`, `delete`. |
 | `c11r loops run <name>` | One pass of a loop. The CLI is not a daemon: a scheduler repeats the pass. |
 | `c11r report sales [--from] [--to] [--by] [--interval] [--market] [--top]` | Sales in a window, from the Metrics API. A plain noun: its flags come from the API's schema. |
 | `c11r auth login [--client-id] [--secret-file] [--keep-file]` | The human's own Commerce Layer login, from their Provisioning API application. See below. |
@@ -68,13 +68,13 @@ Never from a flag or the environment. c11r exchanges the pair for a two hour tok
 | `--live` | Live data, on a claimed organization named with `--org` (or `C11R_ORG`), with the human's login: `?mode=live&org=` on every request. Without it, test mode. See below. |
 | `--help` | Describes the noun or verb it follows, from its schema. |
 
-Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sandbox reset` and `destroy`), and any verb the schema marks `confirm`, ask for confirmation in a terminal, then send `confirm=true`. With no terminal, as when an agent or a schedule runs the CLI, they never wait: without `--yes` they stop at once with `confirmation_required` and exit code 3. Its `next_step.command` is the same command without `--yes`: the agent asks the human first, and only on their yes runs it again with `--yes`. The API's own `confirmation_required` works the same way.
+Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sandbox reset` and `destroy`), and any verb the schema marks `confirm`, ask for confirmation in a terminal, then send `confirm=true`. With no terminal, as when an agent or a schedule runs the CLI, they never wait: without `--yes` they stop at once with `confirmation_required` and exit code 3. Its `next_step` is `{ "action": "confirm", "command": "c11r markets delete eu --yes" }`: the same command with `--yes`, and the action is the guard. The agent asks the human first, and runs the command only on their yes, never on its own. The API's own `confirmation_required` works the same way; when it names no command, the CLI fills in this one with `--yes`.
 
 ## Live mode
 
-`--live` acts on a claimed organization's live data. It always sends the human's login, never an organization token, and names the organization with `?org=`: from `--org`, or `C11R_ORG`, never from the folder's link or the default, which are a sandbox's. Without one it is `missing_value` before any call, with the command and `--org ORG_SLUG --live`.
+`--live` acts on a claimed organization's live data. It sends the human's login and names the organization with `?org=`: from `--org`, or `C11R_ORG`, never from the folder's link or the default, which are a sandbox's. Without one it is `missing_value` before any call, with the command and `--org ORG_SLUG --live`; in a linked folder, the message and the command name the linked organization instead of `ORG_SLUG`.
 
-- Without a login, nothing is checked on this machine: the request goes without a token, and the API's answer (`login_required`, or `state_required` for an organization not claimed) comes through as it is. So do `live_unavailable` (a plan without live), `forbidden` (the login is not an active admin of it) and `not_supported` for a verb that comes with a later step of go-live.
+- Without a login, nothing is checked on this machine: the request goes with the organization token this machine holds for the organization named, or with no token when it holds none (never `C11R_TOKEN`), and the API's answer (`login_required`, or `state_required` for an organization not claimed) comes through as it is. So do `live_unavailable` (a plan without live), `forbidden` (the login is not an active admin of it) and `not_supported` for a verb that comes with a later step of go-live.
 - A verb that never runs live (sandbox, plans, sales calls, `auth login`, `auth switch`, `shop`) stops on this machine with `state_required`.
 - `c11r events writes --live --org <slug>` (`--since 2026-11-12T00:00:00Z`, an ISO time, `--noun`, `--cursor`, `--limit`) is the audit of live writes, and runs only in live: without `--live` it is `missing_value` with the full command, before any call.
 - `c11r status --live --org <slug>` is the organization's live status, with `live_credential` and the warning `live_credential_held` while the API holds one.
@@ -101,6 +101,24 @@ Records that share a key (two shipping methods with the same name in one market,
 
 After a Configure write that went through (create, update, delete or a domain verb), in a folder whose `store.yml` names the same organization, the answer warns `config_drift` and `.c11r/drift` notes the write; `config plan` repeats the warning, and `config export` clears it.
 
+`c11r sandbox create --seed` loads a demo shop: `coffee` (also `--seed` alone, sent as `true`), `tshirts` or `games`, six products each, or `custom`, the person's own from `--catalogue shop.yml`. Each has the markets `eu` and `us`, shipping, a manual payment setting and the storefront on. `sandbox reset --seed <type>` takes the same values, and `--seed false` reseeds with nothing. The catalogue file is YAML:
+
+```yaml
+name: Fern & Clay
+products:
+  - name: Speckled mug
+    description: Stoneware, 350 ml.
+    prices: { EUR: 18, USD: 20 }
+    code: FC-MUG
+look:
+  color: "#7a4b2a"
+  font: rounded
+```
+
+`name` has 1 to 40 characters; `products` 1 to 24, each with a unique `name` (1 to 80), an optional `description` (up to 500), `prices` in EUR and USD (above 0, at most 100000, two decimals at most; a quoted amount such as "9.50" is taken too) and an optional unique `code` (2 to 24 capitals, digits and dashes). `look` takes `color`, `background`, `font`, `corners`, `tagline` and `badge`, as `scaffold storefront` does. The CLI checks the file before anything is sent: a refusal is `invalid_value` with the field in `path`, as the API names it (`catalogue.products[1].prices.USD`, counted from 0), and the file and line in `details`. `--catalogue` goes only with `--seed custom`, and `--seed custom` needs it. When the answer has a store, `data.shop_url` is its link and the first `next` is `c11r scaffold storefront`.
+
+`c11r scaffold storefront` sets the shop's look: `--name` (the shop's name in its title and header, 1 to 40 characters after trimming; the organization's name and slug stay), `--color` (`#rrggbb`), `--background` (`#rgb` or `#rrggbb`), `--font classic|modern|rounded|mono`, `--corners round|square`, `--tagline` (up to 120 characters), `--badge` (up to 20), `--logo`, `--hero`, and `--product-image SKU=FILE`, once per sku. An image is a local file or an https URL; a local file is read here and sent as `{ type, content_base64, sha256 }`. It must be svg, png, jpg or webp by its name and its first bytes, at most 512 KB, and one call carries at most 2 MB of files. An SVG the store would refuse is refused here, with the reason and the way out: a DOCTYPE or entity, script or embedded content (`<script>`, `<foreignObject>` and the like), an `on...` attribute, a script URL, a link or `url()` other than `#id` or a `data:image/...;base64` image, or an `@import`. `null` (or an empty value) takes a field off: `--logo null`, `--product-image SKU=null`. These checks run before anything is sent. The answer has the shop link in `data.shop_url` and in `next`. `config export` does not carry the look.
+
 `c11r scaffold drop-in --out <file>` writes the drop-in.js snippet as one HTML file: the part for the page's `<head>`, then the part for its `<body>`, each under a comment saying where it goes. The file must be inside the project folder: a path that leads out of it, by `..`, an absolute path or a symlink, is refused with `invalid_value` on `out` before anything is sent. It never replaces a different file without `--yes`. Without `--out`, the snippet stays in the JSON answer.
 
 `c11r exports get <id> --out <file>` downloads a completed export while its link lasts (5 minutes), unzipped unless the name ends in `.gz`; `--wait` reads the job again until it completes.
@@ -130,7 +148,7 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 }
 ```
 
-`code` is stable. `missing` is `{ noun, why }`, `path` the flag or field at fault, `next_step.action` one of `create_sandbox`, `claim`, `upgrade`, `contact_sales`, `create_dependency`, `fix_request`, `retry_later`, `human_step`, `none`. `human_step` is something only the human can do, such as saving a secret to a file, with a page in `url` when there is one. The CLI may add `did_you_mean` and `details`.
+`code` is stable. `missing` is `{ noun, why }`, `path` the flag or field at fault, `next_step.action` one of `create_sandbox`, `claim`, `upgrade`, `contact_sales`, `create_dependency`, `fix_request`, `retry_later`, `human_step`, `confirm`, `none`. `confirm` comes with every `confirmation_required`: its command carries `--yes`, run only on the human's yes. `human_step` is something only the human can do, such as saving a secret to a file, with a page in `url` when there is one. The CLI may add `did_you_mean` and `details`.
 
 | Exit | Meaning | Codes |
 | --- | --- | --- |
@@ -161,7 +179,7 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 
 `c11r skills sync` keeps copies of the skills in the project folder, where coding agents load them: `.claude/skills/<name>/SKILL.md`, one per skill as https://commercelayer.ai serves it, and in `AGENTS.md` a block between `<!-- c11r skills: start -->` and `<!-- c11r skills: end -->` listing them, for agents that read that file. Nothing outside the markers changes; without an `AGENTS.md`, sync creates one holding only the block, and says so with `agents_md: "created"`. The project folder is the one already holding the copies, else the one with `.c11r.json`, `store.yml` or `loops.yml`, else the git repository's root, else the current folder. It needs no organization and calls only commercelayer.ai, not the API.
 
-- It reads the index (`start.md`) with the ETag of the last sync, and fetches only the skills whose version changed. A skill the index dropped is removed. `.claude/skills/.c11r-skills.json` records what sync wrote, with each file's sha256; a folder sync did not write is never touched.
+- It reads the list of skills (`https://commercelayer.ai/skills.md`) with the ETag of the last sync, and fetches only the skills whose version changed. A skill the index dropped is removed. `.claude/skills/.c11r-skills.json` records what sync wrote, with each file's sha256; a folder sync did not write is never touched.
 - Every copy's sha256 is checked on each run, also when nothing new is in the index. A copy that is not what sync wrote is an edit: it is kept, neither replaced nor removed, and listed in `edited` with a `skill_edited` warning. `--yes`, on the human's yes, replaces or removes it.
 - `--except <skill>` (repeated) leaves a skill out, and later syncs remember it; `--include <skill>` takes it back.
 - A file whose name or version is not what the index says is not used (`skill_invalid`); a link off `commercelayer.ai/skills/` is skipped (`skill_skipped`).
@@ -178,6 +196,6 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 | `C11R_AUTH_URL` | Commerce Layer's token endpoint, `https://auth.commercelayer.io/oauth/token` by default: for tests. |
 | `C11R_TEST` | `1` marks a sandbox as a test organization, like a name starting `zztest`. |
 | `C11R_SCHEMA_CACHE` | `0` turns off the 10 minute schema cache in `~/.cache/c11r`. The cache records the `C11R-Schema` hash it was read under; an answer with another hash drops it, and a command the API refused on the old schema runs once more on the fresh one (without the header, after `confirmation_required`, `unknown_field` or `unknown_verb`). The second run asks what the fresh schema asks: it never adds `confirm=true` by itself. |
-| `C11R_SKILLS_URL` | The skills index, for a test site on localhost only: `https://commercelayer.ai/start.md` otherwise. |
+| `C11R_SKILLS_URL` | The skills index, for a test site on localhost only: `https://commercelayer.ai/skills.md` otherwise. |
 | `C11R_RETRY_CAP_S` | The longest the CLI waits before one retry, 30 by default. |
 | `C11R_TIMEOUT_MS` | How long a request may take, 30000 by default (sandbox create waits longer). |

package/dist/argv.js

@@ -96,6 +96,10 @@ export function parseFields(noun, verb, rest) {
             if (spec.type === 'boolean' && !sub.length) {
                 raw = next === 'true' || next === 'false' ? rest[++i] : 'true';
             }
+            else if (spec.bare && !sub.length && (next === undefined || /^--[a-z]/i.test(next))) {
+                values[top] = true;
+                continue;
+            }
             else {
                 if (next === undefined || /^--[a-z]/i.test(next))
                     fail('missing_value', `${toFlag(key)} needs a value.`, { path: key });
@@ -112,6 +116,11 @@ export function parseFields(noun, verb, rest) {
             target[sub[sub.length - 1]] = part in (spec.properties ?? {}) ? coerce(key, spec.properties[part], raw) : raw;
             continue;
         }
+        // A flag that may stand alone takes true and false as values too (--seed false).
+        if (spec.bare && !sub.length && (raw === 'true' || raw === 'false')) {
+            values[top] = raw === 'true';
+            continue;
+        }
         const value = coerce(key, spec, raw);
         values[top] = spec.type === 'array' ? [...(values[top] ?? []), ...value] : value;
     }

package/dist/builtins/auth.js

@@ -14,7 +14,7 @@ import { credentialsFile, readLink, setDefaultOrg, storedLogin, storedOrgs, stor
 import { terminal } from '../confirm.js';
 import { closest, errorBody, CliError, fail } from '../errors.js';
 import { envelope, request } from '../http.js';
-import { loginToken, mint, PROVISIONING_URL, readSecretFile, secretFileDefault, writeSecretTemplate } from '../login.js';
+import { hasLogin, loginToken, mint, PROVISIONING_URL, readSecretFile, secretFileDefault, writeSecretTemplate } from '../login.js';
 import { parseSchema } from '../schema.js';
 export const auth = {
     schema: parseSchema({
@@ -145,6 +145,9 @@ async function login(run) {
 async function logoutLive(run) {
     // The path names live already: the request carries ?org= and not ?mode=live.
     run.ctx.live = false;
+    // Revoking the live credential is the login's: never an organization token.
+    if (!hasLogin())
+        run.ctx.token = null;
     return run.send({ method: 'DELETE', path: '/auth/live' });
 }
 function logout() {

package/dist/builtins/extensions.js

@@ -18,6 +18,7 @@ import { fail } from '../errors.js';
 import { apiUrl } from '../http.js';
 import { clearDrift, driftWarning, readDrift, readStoreFiles, storeFileIs, writeStoreFiles } from '../project.js';
 import { resourceRequest } from '../resources.js';
+import { CALL_MAX, kb, lookImage, lookProblem, withShop } from '../storefront.js';
 const NAME_MAX = 25;
 export const organizations = {
     async run(run) {
@@ -330,8 +331,19 @@ export const scaffold = {
         'drop-in': {
             out: { type: 'string', to: 'local', description: 'Write the snippet to this HTML file: the part for the page\'s <head>, then the part for its <body>, each under a comment saying where it goes. It must be inside the project folder. A different file there is replaced only with --yes.' },
         },
+        storefront: {
+            product_image: {
+                type: 'array',
+                items: 'string',
+                to: 'local',
+                repeat: '--product-image SKU=FILE --product-image SKU=FILE, once per sku: a local svg, png, jpg or webp file, or an https URL; SKU=null takes the image off.',
+                description: 'The image of one sku in the shop, as SKU=FILE or SKU=https://...: a local file is read here and sent with its sha256. At most 512 KB a file and 2 MB a call.',
+            },
+        },
     },
     async run(run) {
+        if (run.verb.name === 'storefront')
+            return storefront(run);
         const out = run.parsed.values.out;
         if (run.verb.name !== 'drop-in' || !out)
             return undefined;
@@ -363,4 +375,57 @@ export const scaffold = {
         return { ...r, data: { ...rest, file, replaced: before !== null && before !== html } };
     },
 };
+/**
+ * scaffold storefront (48.3): the look checked here, the image files read into { type,
+ * content_base64, sha256 }, then one call; the answer carries the shop link.
+ */
+async function storefront(run) {
+    const v = { ...run.parsed.values };
+    for (const key of ['name', 'color', 'background', 'font', 'corners', 'tagline', 'badge']) {
+        if (v[key] === undefined)
+            continue;
+        const why = lookProblem(key, v[key]);
+        if (why)
+            fail('invalid_value', `--${key} ${JSON.stringify(v[key])} ${why}. Nothing was sent.`, { path: key, next_step: { action: 'fix_request', command: null } });
+    }
+    const pairs = v.product_image ?? [];
+    delete v.product_image;
+    if (pairs.length) {
+        const images = { ...(v.product_images ?? {}) };
+        for (const pair of pairs) {
+            const eq = pair.indexOf('=');
+            if (eq < 1)
+                fail('invalid_value', `--product-image ${JSON.stringify(pair)} is not SKU=FILE: the sku code, then = and a file or an https URL.`, { path: 'product_image', next_step: { action: 'fix_request', command: null } });
+            const sku = pair.slice(0, eq).trim();
+            const value = pair.slice(eq + 1).trim();
+            if (sku in images)
+                fail('invalid_value', `--product-image names ${sku} twice.`, { path: `product_images.${sku}` });
+            images[sku] = value === 'null' || value === '' ? null : value;
+        }
+        v.product_images = images;
+    }
+    let bytes = 0;
+    for (const key of ['logo', 'hero']) {
+        if (v[key] === undefined)
+            continue;
+        const r = lookImage(key, `--${key}`, v[key]);
+        v[key] = r.value;
+        bytes += r.bytes;
+    }
+    if (v.product_images && typeof v.product_images === 'object') {
+        const images = v.product_images;
+        for (const [sku, x] of Object.entries(images)) {
+            const r = lookImage(`product_images.${sku}`, `--product-image ${sku}=`, x);
+            images[sku] = r.value;
+            bytes += r.bytes;
+        }
+    }
+    if (bytes > CALL_MAX) {
+        fail('invalid_value', `The images of this call add up to ${kb(bytes)}: one call carries at most 2 MB. Send them in more than one c11r scaffold storefront. Nothing was sent.`, { path: 'product_images', details: { bytes, max: CALL_MAX }, next_step: { action: 'fix_request', command: null } });
+    }
+    const r = await run.send(resourceRequest('scaffold', run.verb, undefined, v));
+    if (run.globals.dryRun)
+        return r;
+    return withShop(r, r.data?.store);
+}
 export const extensions = { organizations, 'sales-calls': salesCalls, config, exports, scaffold };

package/dist/builtins/loops.js

@@ -193,7 +193,13 @@ async function checkPolicy(def) {
             fail('policy_forbidden', `A ${def.skill} loop may not allow ${verb}. ${allowed.verbs.length ? `It may allow ${allowed.verbs.join(', ')}.` : 'It allows no verb: it only reports what is waiting, so it takes no --allow.'}`, { path: 'allow', did_you_mean: closest(verb, allowed.verbs), details: { loopable: allowed.verbs }, next_step: fixWith(`c11r schema ${allowed.noun}`) });
         }
     }
-    return [];
+    // Allowed and bounded by nothing: kept, and said, so the agent tells the human.
+    const open = [];
+    if (def.policy.allow.length && def.policy.max_total === undefined)
+        open.push('any order total (no --max-total)');
+    if (def.policy.allow.length && !def.policy.markets?.length)
+        open.push('every market (no --market)');
+    return open.length ? [{ code: 'no_limit', message: `This loop may ${def.policy.allow.join(', ')} for ${open.join(' and in ')}. Tell the human in one line.` }] : [];
 }
 /**
  * The skills a loop can run, from the schemas of the nouns that have a loop (Manage and Report):

package/dist/builtins/sandbox.js

@@ -1,4 +1,4 @@
-// c11r sandbox create [--name] [--seed], get, reset, claim, destroy (contract section 4), and
+// c11r sandbox create [--name] [--seed [type]] [--catalogue file], get, reset, claim, destroy (contract sections 4 and 48), and
 // c11r status (section 5). They are built in for what happens on this machine: create stores the
 // sandbox token (mode 600, ~/.config/c11r/credentials.json) and links the folder (.c11r.json);
 // reset moves both to the new organization; destroy forgets them. The token is printed never,
@@ -10,8 +10,21 @@ import { apiUrl, envelope, request } from '../http.js';
 import { parseSchema } from '../schema.js';
 import { OUT_NOT_TRACKED, removeOrgSecrets } from '../secrets.js';
 import { VERSION } from '../version.js';
+import { readCatalogue, SEED_TYPES, withShop } from '../storefront.js';
 /** The longest sandbox name the API takes (contract: 422 invalid_argument past it). */
 const NAME_MAX = 25;
+const SEED = {
+    name: 'seed',
+    type: 'enum',
+    values: [...SEED_TYPES],
+    bare: true,
+    description: 'Loads a demo shop of this type: coffee, tshirts or games, six products each, or custom, the person\'s own from --catalogue. Each has two markets, shipping, a manual payment setting (Wire transfer) and a storefront on, enough to place a test order at once. --seed alone is coffee.',
+};
+const CATALOGUE = {
+    name: 'catalogue',
+    type: 'string',
+    description: 'With --seed custom: a YAML file with the shop\'s name, its products (name, description, prices in EUR and USD, code) and optionally its look. Checked here, then sent in the same call.',
+};
 export const sandbox = {
     schema: parseSchema({
         noun: 'sandbox',
@@ -28,9 +41,10 @@ export const sandbox = {
                 live: false,
                 body: [
                     { name: 'name', type: 'string', description: 'The organization name; without it, an invented one. A name starting zztest marks a test organization.' },
-                    { name: 'seed', type: 'boolean', description: 'Loads the demo dataset: two markets, six products, shipping and a manual payment setting (Wire transfer), enough to place a test order at once.' },
+                    SEED,
+                    CATALOGUE,
                 ],
-                effect: 'Creates a sandbox, stores its token on this machine (never printed) and links this folder to it with .c11r.json. With --seed it answers once the seed is applied, in about 10 seconds.',
+                effect: 'Creates a sandbox, stores its token on this machine (never printed) and links this folder to it with .c11r.json. With --seed it answers once the seed and its storefront are in place, in about 20 seconds, with the shop link.',
             },
             { verb: 'get', method: 'GET', path: '/v1/sandbox', live: false, effect: 'Returns the sandbox: organization, expiry, whether it is seeded, the token hint and the claim status.' },
             {
@@ -39,8 +53,8 @@ export const sandbox = {
                 path: '/v1/sandbox/reset',
                 live: false,
                 destructive: true,
-                body: [{ name: 'seed', type: 'boolean', description: 'Seeds the fresh organization, or not; without it, as before.' }],
-                effect: 'Replaces the sandbox with a fresh organization behind the same token, seeded as before, and retires the old one. The slug changes; this machine and .c11r.json follow it.',
+                body: [{ ...SEED, description: 'Seeds the fresh organization with this type, or not (--seed false); without it, as before. custom needs --catalogue again.' }, CATALOGUE],
+                effect: 'Replaces the sandbox with a fresh organization behind the same token, seeded as before (its storefront on again), and retires the old one. The slug changes; this machine and .c11r.json follow it.',
             },
             { verb: 'claim', method: 'POST', path: '/v1/sandbox/claim', live: false, effect: 'Returns a one-time claim URL, valid 30 minutes, for the human to open: they sign in with Commerce Layer and pick a plan. The agent never opens it for them.' },
             {
@@ -76,7 +90,7 @@ async function create(run, values) {
     if (name !== undefined && (name.trim() === '' || name.length > NAME_MAX)) {
         fail('invalid_value', `--name ${JSON.stringify(name)} is ${name.trim() === '' ? 'empty' : `${name.length} characters`}: a sandbox name has 1 to ${NAME_MAX}.`, { path: 'name', next_step: { action: 'fix_request', command: null } });
     }
-    const seed = Boolean(values.seed);
+    const { seed, catalogue } = seedBody(values);
     const test = process.env.C11R_TEST === '1' || Boolean(name?.startsWith('zztest'));
     // The token goes only when this folder, --org or C11R_ORG names a sandbox: the API then
     // finishes a failed seed there, or answers 409 conflict naming it, rather than make a second
@@ -85,7 +99,7 @@ async function create(run, values) {
     // A fresh key per create: after a 5xx or a lost connection the same create is repeated with it,
     // and the API answers the sandbox (and token) it made, rather than leave one with a lost token.
     const idempotencyKey = `c11r-${crypto.randomBytes(16).toString('base64url')}`;
-    const r = await request({ method: 'POST', path: '/sandboxes', body: { ...(name ? { name } : {}), seed, test }, dryRun: run.globals.dryRun, timeoutMs: seed ? 120_000 : 60_000, idempotencyKey }, { live: false, token: named ? run.org.token : null });
+    const r = await request({ method: 'POST', path: '/sandboxes', body: { ...(name ? { name } : {}), seed, ...(catalogue ? { catalogue } : {}), test }, dryRun: run.globals.dryRun, timeoutMs: seed ? 180_000 : 60_000, idempotencyKey }, { live: false, token: named ? run.org.token : null });
     if (run.globals.dryRun)
         return r;
     const { token, ...data } = r.data ?? {};
@@ -98,10 +112,28 @@ async function create(run, values) {
     const warnings = r.warnings.filter((w) => w.code !== 'token_shown_once');
     if (link.previous)
         warnings.push({ code: 'relinked', message: `${link.file} named ${link.previous}; it now names ${data.org}. The token of ${link.previous} stays stored.` });
-    return { ...r, data: { ...data, token_hint: hint, credentials: credentialsFile(), linked: link.file }, warnings };
+    return withShop({ ...r, data: { ...data, token_hint: hint, credentials: credentialsFile(), linked: link.file }, warnings }, data.store);
+}
+/** --seed and --catalogue as the API takes them: custom only with a catalogue, a catalogue only with custom. */
+function seedBody(values) {
+    const seed = values.seed ?? false;
+    const file = values.catalogue;
+    if (seed === 'custom' && file === undefined) {
+        fail('missing_value', '--seed custom needs --catalogue: a YAML file with the shop\'s name and its products. Write it from what the human described, show it to them, then run the command with --catalogue <file>.', { path: 'catalogue', next_step: { action: 'fix_request', command: null } });
+    }
+    if (file !== undefined && seed !== 'custom')
+        fail('invalid_value', '--catalogue goes only with --seed custom: the other types bring their own products.', { path: 'catalogue', next_step: { action: 'fix_request', command: null } });
+    return { seed, catalogue: file === undefined ? undefined : readCatalogue(file) };
 }
 async function reset(run, values) {
-    const r = await run.send({ method: 'POST', path: '/sandbox/reset', body: values.seed === undefined ? {} : { seed: values.seed } });
+    const body = {};
+    if (values.seed !== undefined || values.catalogue !== undefined) {
+        const { seed, catalogue } = seedBody(values);
+        body.seed = seed;
+        if (catalogue)
+            body.catalogue = catalogue;
+    }
+    const r = await run.send({ method: 'POST', path: '/sandbox/reset', body });
     if (run.globals.dryRun)
         return r;
     const { org, previous_org: previous } = r.data ?? {};
@@ -112,7 +144,7 @@ async function reset(run, values) {
         if (link?.org === before)
             writeLink(org);
     }
-    return r;
+    return withShop(r, r.data?.store);
 }
 async function destroy(run) {
     let r;

package/dist/builtins/skills.js

@@ -1,4 +1,4 @@
-// c11r skills sync: local copies of the skills, from the index the site publishes (start.md), so
+// c11r skills sync: local copies of the skills, from the list the site publishes (skills.md), so
 // any coding agent in the project finds them. State none: no token, no organization, no call to
 // the API; only commercelayer.ai.
 //
@@ -17,7 +17,7 @@ import { CliError, fail } from '../errors.js';
 import { envelope } from '../http.js';
 import { parseSchema } from '../schema.js';
 import { USER_AGENT } from '../version.js';
-const INDEX_URL = 'https://commercelayer.ai/start.md';
+const INDEX_URL = 'https://commercelayer.ai/skills.md';
 const SKILLS_DIR = path.join('.claude', 'skills');
 const MANIFEST = '.c11r-skills.json';
 const AGENTS_FILE = 'AGENTS.md';
@@ -31,7 +31,6 @@ export const skills = {
     schema: parseSchema({
         noun: 'skills',
         group: 'setup',
-        skill: 'start',
         kind: 'task',
         description: 'The local copies of the Commerce Layer skills, in the project folder, where coding agents load them: .claude/skills/<name>/SKILL.md, and a list of them in AGENTS.md.',
         verbs: [
@@ -154,12 +153,11 @@ const firstSentence = (d) => {
 };
 function agentsBlock(entries, rel) {
     const link = (n) => `${rel}/${n}/SKILL.md`;
-    const start = entries.find((e) => e.name === 'start');
     const lines = [
         START,
         '## Commerce Layer skills',
         '',
-        `Local copies of the Commerce Layer skills, kept up to date by \`c11r skills sync\`.${start ? ` Load [start](${link('start')}) first: it routes to the others.` : ''}`,
+        `Local copies of the Commerce Layer skills, from ${INDEX_URL}, kept up to date by \`c11r skills sync\`. When a skill's task comes, load its copy.`,
         '',
         ...entries.map((e) => `- [${e.name}](${link(e.name)}): ${firstSentence(e.description)}`),
         END,

package/dist/confirm.js

@@ -1,6 +1,7 @@
 // Confirmation for destructive verbs. --yes skips it. With a terminal, it asks on stderr and
 // reads one line. With no terminal (an agent, a pipe, a schedule) it never waits: it fails with
-// confirmation_required, and the agent asks the human, then repeats the command with --yes.
+// confirmation_required, next_step confirm with the command and --yes: the agent asks the human,
+// and runs it only on their yes.
 import readline from 'node:readline';
 import { fail } from './errors.js';
 export const terminal = {
@@ -40,6 +41,8 @@ export const terminal = {
         });
     },
 };
+/** The command the human's yes runs: the same, with --yes. */
+export const withYes = (command) => (/\s(--yes|-y)(\s|$)/.test(command) ? command : `${command} --yes`);
 /**
  * action names what needs a yes ("Destroy sandbox"). sentence, when given, is what the human is
  * shown instead, whole ("Sharing with shop.example.com: Ada Lovelace, ..."), and details go with
@@ -51,10 +54,10 @@ export async function confirm(action, command, opts) {
     const p = opts.prompter ?? terminal;
     const said = opts.sentence ? `${opts.sentence.replace(/\.?$/, '.')} This` : action;
     if (!p.interactive) {
-        // The agent asks the human; on a yes it repeats the command with --yes. next never carries the
-        // --yes itself: only the human's answer adds it.
-        fail('confirmation_required', `${said} needs confirmation, and there is no terminal to ask in. Ask the human first; on their yes, run it again with --yes.`, {
-            next_step: { action: 'fix_request', command },
+        // The agent asks the human, and runs the command, which carries --yes, only on their yes: the
+        // action confirm is the guard (contract section 3), never fix_request.
+        fail('confirmation_required', `${said} needs the human's yes, and there is no terminal to ask in. Ask the human first, and run the command only on their yes.`, {
+            next_step: { action: 'confirm', command: withYes(command) },
             ...(opts.details ? { details: opts.details } : {}),
         });
     }

package/dist/engine.js

@@ -5,7 +5,7 @@
 // everything. Every answer is the API's envelope, { data, state, warnings, next }.
 import { parseCommand, parseFields, toFlag } from './argv.js';
 import { forgetOutWritten, raiseProblem, resolveOrg } from './config.js';
-import { confirm, terminal } from './confirm.js';
+import { confirm, terminal, withYes } from './confirm.js';
 import { CliError, closest, fail, fixWith } from './errors.js';
 import { indexHelp, nounHelp, verbHelp } from './help.js';
 import { envelope, request } from './http.js';
@@ -99,7 +99,9 @@ async function executeOnce(argv, opts) {
     // default, which are a sandbox's: --org, or C11R_ORG.
     const liveOrg = live ? (cmd.globals.org ?? (process.env.C11R_ORG || null)) : null;
     if (live && !liveOrg) {
-        fail('missing_value', `${named} --live acts on a claimed organization, named with --org.`, { path: 'org', next_step: fixWith(`${line.replace(/\s--live\b/, '')} --org ORG_SLUG --live`) });
+        // The folder's link is not taken in live mode; named, it is the value to pass when it is the one meant.
+        const linked = org.source === 'link' ? org.org : null;
+        fail('missing_value', `${named} --live acts on a claimed organization, named with --org.${linked ? ` This folder is linked to ${linked}: pass it with --org when it is the one meant.` : ''}`, { path: 'org', next_step: fixWith(`${line.replace(/\s--live\b/, '')} --org ${linked ?? 'ORG_SLUG'} --live`) });
     }
     // The bearer, from the schema (contract section 23). An organization token for the organization
     // nouns, the login for the Provisioning ones; credentials take the login when there is one and
@@ -137,8 +139,8 @@ async function executeOnce(argv, opts) {
     if (live && cmd.globals.yes && verb.method !== 'GET')
         confirmed = true;
     if ((verb.destructive || verb.confirm || confirmFlags.length) && !cmd.globals.dryRun && !apiAsks) {
-        const what = `${verb.name} ${schema.noun}${parsed.id ? ` ${parsed.id}` : ''}${confirmFlags.length ? ` with ${confirmFlags.map(toFlag).join(' ')}` : ''}`;
-        const sentence = what.charAt(0).toUpperCase() + what.slice(1);
+        // The command itself names the action ("c11r markets delete eu"): no verb to inflect.
+        const sentence = `c11r ${schema.noun} ${verb.name}${parsed.id ? ` ${parsed.id}` : ''}${confirmFlags.length ? ` ${confirmFlags.map(toFlag).join(' ')}` : ''}`;
         await confirm(sentence, line, { yes: cmd.globals.yes, prompter: opts.prompter });
         confirmed = true;
     }
@@ -148,7 +150,12 @@ async function executeOnce(argv, opts) {
     }
     // Where a secret goes, checked before the request makes one.
     const secretPlan = verb.secret ? planSecret({ org: org.org, noun: schema.noun, verb: verb.name, id: parsed.id, values: parsed.values, yes: cmd.globals.yes }) : null;
-    const ctx = { live, token: live ? (login ? await loginToken() : null) : bearer === 'login' ? await loginToken() : org.token };
+    // Live without a login: the organization token this machine holds for the organization named,
+    // and no other (never C11R_TOKEN, whose organization is unknown). The API answers a sandbox's
+    // state_required with its claim step, a claimed one's login_required; a slug alone stays
+    // login_required, so no one learns which slugs exist.
+    const liveOwn = live && !login && org.org === liveOrg && (org.source === 'flag' || org.source === 'env') ? org.token : null;
+    const ctx = { live, token: live ? (login ? await loginToken() : liveOwn) : bearer === 'login' ? await loginToken() : org.token };
     const orgQuery = liveOrg ? { org: liveOrg } : bearer === 'login' && loginOrg && schema.noun !== 'organizations' && schema.noun !== 'auth' ? { org: loginOrg } : {};
     const sendOnce = (req) => request({ ...req, query: { ...(req.query ?? {}), ...orgQuery }, dryRun: req.dryRun ?? cmd.globals.dryRun, confirm: confirmed || req.confirm }, ctx);
     const run = {
@@ -169,9 +176,9 @@ async function executeOnce(argv, opts) {
                 // The API's own confirmation, in live: as it is with no terminal; asked with its words in one.
                 if (apiAsks && !confirmed && e instanceof CliError && e.code === 'confirmation_required') {
                     const p = opts.prompter ?? terminal;
-                    // Without a command of the API's, the next step is this one again, without --yes.
+                    // Without a command of the API's, the next step is this one with --yes, under confirm.
                     if (!p.interactive)
-                        throw e.body.next_step?.command ? e : new CliError({ ...e.body, next_step: { action: 'fix_request', command: line, url: null } }, e.kind, e.state);
+                        throw e.body.next_step?.command ? e : new CliError({ ...e.body, next_step: { action: 'confirm', command: withYes(line), url: null } }, e.kind, e.state);
                     await confirm(e.body.message, line, { yes: false, prompter: p, sentence: e.body.message });
                     confirmed = true;
                     return sendOnce(req);

package/dist/help.js

@@ -93,6 +93,7 @@ function flagHelp(key, f, noun) {
         ...(f.required || (f.input?.kind === 'secret' && f.input.required) ? { required: true } : {}),
         ...(f.input ? { reads: f.input.kind === 'secret' ? `${f.input.target}, a secret: never a flag value, never printed` : `${f.input.target}, a JSON document` } : {}),
         ...(f.values ? { values: f.values } : {}),
+        ...(f.bare ? { alone: `${toFlag(key)} with no value sends true` } : {}),
         ...(f.known ? { known: f.known.length <= KNOWN_IN_FULL ? f.known : `one of ${f.known.length} documented values: c11r schema ${noun}` } : {}),
         ...(clearable(f) ? { clear: 'null, or an empty value, takes it off' } : {}),
         ...(f.filter ? { filter: f.filter.op } : {}),

package/dist/schema.js

@@ -155,6 +155,7 @@ function flag(f, to, required) {
         ...(required ? { required: true } : {}),
         ...(f.description ? { description: f.description } : {}),
         ...(typeof f.repeat === 'string' && f.repeat ? { repeat: f.repeat } : {}),
+        ...(f.bare ? { bare: true } : {}),
     };
 }
 function bad(noun, why) {

package/dist/storefront.js

@@ -0,0 +1,280 @@
+// The starter storefront on this machine (contract section 48): the catalogue file of a custom
+// seed, and the look files of scaffold storefront, both checked here before anything is sent.
+//
+// A catalogue is YAML: name, products (name, description, prices in EUR and USD, code) and an
+// optional look. A refusal names the field as the API would (catalogue.products[2].prices.USD) and
+// the line of the file. A look file (--logo ./logo.svg) goes as { type, content_base64, sha256 }:
+// svg, png, jpg or webp, by its name and its first bytes, at most 512 KB, and 2 MB in one call. An
+// https URL goes as it is, and null takes the image off.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML, { LineCounter, isMap, isSeq } from 'yaml';
+import { fail } from './errors.js';
+export const SEED_TYPES = ['coffee', 'tshirts', 'games', 'custom'];
+export const FONTS = ['classic', 'modern', 'rounded', 'mono'];
+export const CORNERS = ['round', 'square'];
+export const TAGLINE_MAX = 120;
+export const BADGE_MAX = 20;
+/** The shop's name in its title and header (scaffold storefront --name), trimmed. */
+export const NAME_MAX = 40;
+export const FILE_MAX = 512 * 1024;
+export const CALL_MAX = 2 * 1024 * 1024;
+const PRODUCTS_MAX = 24;
+const CURRENCIES = ['EUR', 'USD'];
+const LOOK_KEYS = ['color', 'background', 'font', 'corners', 'tagline', 'badge'];
+/** The answer's next with the shop's entry first, and the API's own entry for the same command left out. */
+export function withShop(r, store) {
+    const shop = shopNext(store);
+    if (!shop)
+        return r;
+    return { ...r, data: { ...r.data, shop_url: shop.url }, next: [shop.next, ...r.next.filter((n) => n.command !== shop.next.command)] };
+}
+/** The shop link of an answer's store, and the next entry that hands it to the human. */
+export function shopNext(store) {
+    const host = store && typeof store === 'object' ? store.host : undefined;
+    if (typeof host !== 'string' || !host)
+        return null;
+    const given = store.url;
+    const url = typeof given === 'string' && given ? given : `https://${host}/`;
+    return { url, next: { command: 'c11r scaffold storefront', why: `The shop is at ${url}: give the human the link. Every change to its look goes through this command.` } };
+}
+/** A look value checked as the API checks it; a message, or null when it is right. */
+export function lookProblem(key, v) {
+    if (v === null)
+        return null;
+    switch (key) {
+        case 'color':
+            return typeof v === 'string' && /^#[0-9a-fA-F]{6}$/.test(v) ? null : 'is a colour as #rrggbb';
+        case 'background':
+            return typeof v === 'string' && /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/.test(v) ? null : 'is a colour as #rgb or #rrggbb';
+        case 'font':
+            return typeof v === 'string' && FONTS.includes(v) ? null : `is one of ${FONTS.join(', ')}`;
+        case 'corners':
+            return typeof v === 'string' && CORNERS.includes(v) ? null : `is one of ${CORNERS.join(', ')}`;
+        case 'name':
+            return typeof v === 'string' && v.trim().length >= 1 && [...v.trim()].length <= NAME_MAX ? null : `has 1 to ${NAME_MAX} characters${typeof v === 'string' ? `, not ${[...v.trim()].length}` : ''}`;
+        case 'tagline':
+        case 'badge': {
+            const max = key === 'tagline' ? TAGLINE_MAX : BADGE_MAX;
+            return typeof v === 'string' && v.trim().length >= 1 && [...v].length <= max ? null : `has 1 to ${max} characters${typeof v === 'string' ? `, not ${[...v].length}` : ''}`;
+        }
+    }
+    return null;
+}
+/** The catalogue file read and checked: the object the API takes as body.catalogue. */
+export function readCatalogue(file) {
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch (e) {
+        fail('invalid_value', `--catalogue ${file}: ${e.code === 'ENOENT' ? 'no such file' : e.message}.`, { path: 'catalogue' });
+    }
+    const lines = new LineCounter();
+    const doc = YAML.parseDocument(text, { lineCounter: lines, prettyErrors: false });
+    if (doc.errors.length) {
+        const e = doc.errors[0];
+        const at = lines.linePos(e.pos[0]);
+        fail('invalid_value', `${file} is not YAML${at ? ` (line ${at.line})` : ''}: ${e.message.split('\n')[0]}`, { path: 'catalogue', details: { file, ...(at ? { line: at.line } : {}) } });
+    }
+    const v = doc.toJS();
+    const bad = (at, why) => {
+        const field = ['catalogue', ...at].reduce((acc, k) => (typeof k === 'number' ? `${acc}[${k}]` : acc ? `${acc}.${k}` : String(k)), '');
+        const line = lineOf(doc, lines, at);
+        fail('invalid_value', `${file}${line ? ` line ${line}` : ''}: ${field.replace(/^catalogue\.?/, '') || 'the file'} ${why}. Nothing was sent.`, {
+            path: field,
+            details: { file, ...(line ? { line } : {}) },
+            next_step: { action: 'fix_request', command: null },
+        });
+    };
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        bad([], 'is a mapping with name and products');
+    const c = v;
+    for (const k of Object.keys(c))
+        if (!['name', 'products', 'look'].includes(k))
+            bad([k], 'is not a catalogue field: it takes name, products and look');
+    text1(c.name, ['name'], 40, true, bad);
+    if (!Array.isArray(c.products) || !c.products.length)
+        bad(['products'], `is a list of 1 to ${PRODUCTS_MAX} products`);
+    const products = c.products;
+    if (products.length > PRODUCTS_MAX)
+        bad(['products'], `has ${products.length} products: at most ${PRODUCTS_MAX}`);
+    const names = new Map();
+    const codes = new Map();
+    products.forEach((p, i) => {
+        const at = ['products', i];
+        if (!p || typeof p !== 'object' || Array.isArray(p))
+            bad(at, 'is a product with name and prices');
+        const o = p;
+        for (const k of Object.keys(o))
+            if (!['name', 'description', 'prices', 'code'].includes(k))
+                bad([...at, k], 'is not a product field: it takes name, description, prices and code');
+        text1(o.name, [...at, 'name'], 80, true, bad);
+        const name = o.name.trim().toLowerCase();
+        if (names.has(name))
+            bad([...at, 'name'], `repeats the name of products[${names.get(name)}]: names are unique`);
+        names.set(name, i);
+        if (o.description !== undefined && o.description !== null)
+            text1(o.description, [...at, 'description'], 500, false, bad);
+        if (!o.prices || typeof o.prices !== 'object' || Array.isArray(o.prices))
+            bad([...at, 'prices'], 'has a price in EUR and one in USD, as { EUR: 18, USD: 20 }');
+        const prices = o.prices;
+        for (const k of Object.keys(prices))
+            if (!CURRENCIES.includes(k))
+                bad([...at, 'prices', k], 'is not a currency of the seed: it takes EUR and USD');
+        for (const cur of CURRENCIES) {
+            const given = prices[cur];
+            if (given === undefined)
+                bad([...at, 'prices'], `has no ${cur} price: it needs EUR and USD`);
+            // A quoted amount ("9.50") is taken as the API takes it: digits, a dot, digits.
+            const n = typeof given === 'string' && /^\d+(\.\d+)?$/.test(given.trim()) ? Number(given) : given;
+            if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0 || n > 100000)
+                bad([...at, 'prices', cur], 'is an amount above 0 and at most 100000');
+            if (Math.round(n * 100) !== Number((n * 100).toFixed(6)))
+                bad([...at, 'prices', cur], 'has two decimals at most');
+        }
+        if (o.code !== undefined) {
+            if (typeof o.code !== 'string' || !/^[A-Z0-9-]{2,24}$/.test(o.code))
+                bad([...at, 'code'], 'is 2 to 24 capitals, digits and dashes');
+            if (codes.has(o.code))
+                bad([...at, 'code'], `repeats the code of products[${codes.get(o.code)}]: codes are unique`);
+            codes.set(o.code, i);
+        }
+    });
+    if (c.look !== undefined && c.look !== null) {
+        if (typeof c.look !== 'object' || Array.isArray(c.look))
+            bad(['look'], `is a mapping of ${LOOK_KEYS.join(', ')}`);
+        for (const [k, x] of Object.entries(c.look)) {
+            if (!LOOK_KEYS.includes(k))
+                bad(['look', k], `is not a look field here: it takes ${LOOK_KEYS.join(', ')} (images come with c11r scaffold storefront)`);
+            const why = lookProblem(k, x);
+            if (why)
+                bad(['look', k], why);
+        }
+    }
+    return c;
+}
+function text1(v, at, max, required, bad) {
+    if (v === undefined || v === null) {
+        if (required)
+            bad(at, 'is missing');
+        return;
+    }
+    if (typeof v !== 'string')
+        bad(at, 'is text');
+    const n = [...v].length;
+    if ((required && !v.trim()) || n > max)
+        bad(at, `has ${required ? 1 : 0} to ${max} characters, not ${n}`);
+}
+/** The line of the field at the path: its key's line, or its item's; else the nearest parent's. */
+function lineOf(doc, lines, at) {
+    for (let n = at.length; n > 0; n--) {
+        const parent = n === 1 ? doc.contents : doc.getIn(at.slice(0, n - 1), true);
+        const last = at[n - 1];
+        if (isMap(parent)) {
+            const pair = parent.items.find((p) => p.key?.value === last);
+            const range = pair?.key?.range;
+            if (range)
+                return lines.linePos(range[0]).line;
+        }
+        else if (isSeq(parent) && typeof last === 'number') {
+            const range = parent.items[last]?.range;
+            if (range)
+                return lines.linePos(range[0]).line;
+        }
+    }
+    return null;
+}
+const EXT = { '.svg': 'svg', '.png': 'png', '.jpg': 'jpg', '.jpeg': 'jpg', '.webp': 'webp' };
+/** What the first bytes say the file is, or null. */
+function sniff(b) {
+    if (b.length >= 8 && b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return 'png';
+    if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff)
+        return 'jpg';
+    if (b.length >= 12 && b.subarray(0, 4).toString('latin1') === 'RIFF' && b.subarray(8, 12).toString('latin1') === 'WEBP')
+        return 'webp';
+    const head = b.subarray(0, 1024).toString('utf8').replace(/^/, '').trimStart();
+    if (/^(<\?xml[^>]*>\s*)?(<!--[\s\S]*?-->\s*)*(<!DOCTYPE svg[^>]*>\s*)?<svg[\s>]/i.test(head))
+        return 'svg';
+    return null;
+}
+/**
+ * An image value as the API takes it: null as null, an https URL as it is, else a local file read
+ * into { type, content_base64, sha256 }. field names it in errors (logo, product_images.BB-ETH-250).
+ */
+export function lookImage(field, flag, v) {
+    if (v === null)
+        return { value: null, bytes: 0 };
+    if (typeof v !== 'string' || !v.trim())
+        fail('invalid_value', `${flag} takes a file, an https URL, or null to take the image off.`, { path: field });
+    const s = v.trim();
+    if (/^https:\/\//i.test(s))
+        return { value: s, bytes: 0 };
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(s))
+        fail('invalid_value', `${flag} ${s}: a link is https only. Or give a local file.`, { path: field });
+    const ext = EXT[path.extname(s).toLowerCase()];
+    if (!ext)
+        fail('invalid_value', `${flag} ${s} is not an svg, png, jpg or webp file, by its name.`, { path: field, details: { types: ['svg', 'png', 'jpg', 'webp'] } });
+    let stat;
+    try {
+        stat = fs.statSync(s);
+    }
+    catch (e) {
+        fail('invalid_value', `${flag} ${s}: ${e.code === 'ENOENT' ? 'no such file' : e.message}.`, { path: field });
+    }
+    if (!stat.isFile())
+        fail('invalid_value', `${flag} ${s} is not a file.`, { path: field });
+    if (stat.size > FILE_MAX)
+        fail('invalid_value', `${flag} ${s} has ${kb(stat.size)}: an image is at most 512 KB.`, { path: field, details: { bytes: stat.size, max: FILE_MAX } });
+    if (stat.size === 0)
+        fail('invalid_value', `${flag} ${s} is empty.`, { path: field });
+    const b = fs.readFileSync(s);
+    const is = sniff(b);
+    if (is !== ext)
+        fail('invalid_value', `${flag} ${s} is named ${ext}, but its first bytes ${is ? `are ${is}'s` : 'are none of svg, png, jpg or webp'}.`, { path: field });
+    if (ext === 'svg') {
+        let text = '';
+        try {
+            text = new TextDecoder('utf-8', { fatal: true }).decode(b);
+        }
+        catch {
+            fail('invalid_value', `${flag} ${s} is not UTF-8 text, as an svg file is. Save it again as UTF-8. Nothing was sent.`, { path: field, next_step: { action: 'fix_request', command: null } });
+        }
+        const why = svgRefusal(text);
+        if (why)
+            fail('invalid_value', `${flag} ${s} would be refused by the store: ${why.reason}. ${why.fix} Nothing was sent.`, { path: field, details: { refused: why.reason }, next_step: { action: 'fix_request', command: null } });
+    }
+    return { value: { type: ext, content_base64: b.toString('base64'), sha256: crypto.createHash('sha256').update(b).digest('hex') }, bytes: b.length };
+}
+/**
+ * Why the store would refuse an SVG, and the way out; null when it takes it. The store's rules
+ * (its assets.ts svgRefusal), checked here so the agent learns before the upload.
+ */
+export function svgRefusal(text) {
+    const body = text.replace(/^\uFEFF/, '').replace(/<\?xml[\s\S]*?\?>/, '').replace(/<!--[\s\S]*?-->/g, '').trim();
+    if (/<!DOCTYPE|<!ENTITY/i.test(text))
+        return { reason: 'it declares a DOCTYPE or an entity', fix: 'Remove the DOCTYPE line (and any ENTITY) from the file.' };
+    if (!/^<svg[\s>]/i.test(body))
+        return { reason: 'it is not an <svg> document', fix: 'The file starts with <svg>, after an optional <?xml ...?> line and comments.' };
+    const embedded = body.match(/<\s*(script|foreignObject|iframe|embed|object|audio|video|handler|listener)\b/i);
+    if (embedded)
+        return { reason: `it has a <${embedded[1]}> element`, fix: `Remove the <${embedded[1]}> element: a shop image has no script or embedded content.` };
+    const event = body.match(/\s(on[a-z]+)\s*=/i);
+    if (event)
+        return { reason: `it has the event attribute ${event[1]}`, fix: 'Remove every on... attribute.' };
+    if (/javascript:|vbscript:/i.test(body))
+        return { reason: 'it has a script URL', fix: 'Remove every javascript: or vbscript: link.' };
+    for (const m of body.matchAll(/\b(?:xlink:)?href\s*=\s*(["'])(.*?)\1/gi))
+        if (!allowedRef(m[2]))
+            return { reason: `it links to ${m[2].slice(0, 60)}`, fix: 'Keep only links inside the file (#id) or images embedded as data:image/...;base64.' };
+    for (const m of body.matchAll(/url\(\s*(["']?)(.*?)\1\s*\)/gi))
+        if (!allowedRef(m[2]))
+            return { reason: `it loads ${m[2].slice(0, 60)}`, fix: 'Keep only url(#id) or images embedded as data:image/...;base64.' };
+    if (/@import/i.test(body))
+        return { reason: 'it imports a stylesheet', fix: 'Remove the @import: put the styles in the file.' };
+    return null;
+}
+const allowedRef = (v) => /^#/.test(v.trim()) || /^data:image\/(png|jpe?g|webp|gif);base64,/i.test(v.trim());
+export const kb = (n) => `${Math.ceil(n / 1024)} KB`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "1.0.0-dev.19",
+  "version": "1.0.0-dev.21",
   "description": "c11r: the Commerce Layer CLI for coding agents. One grammar, c11r <noun> <verb>, from a sandbox to a running organization.",
   "homepage": "https://commercelayer.ai",
   "keywords": [