@commercelayer/agent-cli 1.0.0-dev.1 → 1.0.0-dev.10

package/README.md

@@ -14,7 +14,8 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 - A plain noun has no code in the CLI. Its fields, filters and verbs come from the API's schema, and `c11r schema <noun>` returns that schema.
 - Flags are the schema's fields, in kebab or snake case: `--price-list` and `--price_list` are the same.
 - On `list`, `--<field> <value>` filters by equality and `--<field>.<op> <value>` by another operator: `--placed-at.gte 2026-11-01`, `--status.in placed,approved`. `--waiting` lists what needs a decision now.
-- A dotted flag sets part of an object: `--customer.email ada@example.com`. An array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2`. `--data` takes the fields as one JSON object, or `@` and a file name.
+- A ref flag, or one the schema marks `nullable`, given `null` or an empty value sends `null` and takes it off: `c11r customers update ada@example.com --customer-group null` sends `customer_group: null`, `c11r orders update 1001 --coupon-code null` sends `coupon_code: null`. A ref the schema marks `nullable: false`, and any other field, sends the text.
+- A dotted flag sets part of an object: `--customer.email ada@example.com`. An `in` filter takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it (`--tax-calculator.in "UK VAT, manual"`), and a list that has one is sent as a JSON array. Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes `key=value` pairs, one object per flag: `--items sku=COFFEE,quantity=2`. `--data` takes the fields as one JSON object, or `@` and a file name.
 - Amounts are in major units: `--amount 12.50`.
 - A secret field the schema marks `secret_input` (provider credentials) has no flag of its own: `--credentials-file <file>` reads it, as JSON or `KEY=value` lines, from a plain file only its owner can read (mode 600). Without the file, a terminal asks for it without echo; with neither, the command stops with `secret_required`. It is refused as a flag value or in `--data`, and never printed.
 - A document field the schema marks `file_input` (price rules, rule filters) also reads from a JSON file: `--file <file>`, or `--<field>-file` when a verb has more than one.
@@ -28,13 +29,13 @@ This is the 1.0.0 line, in development on the `clean-slate` branch. It replaces
 | `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 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. 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. 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. |
 | `c11r auth logout`, `auth switch <slug> [--global]` | Forgetting the login; the organization commands act on. |
 
-A loop policy allows verbs: a bare verb is the skill's own noun (`approve`), `<noun>.<verb>` another Manage noun's verb on the same item (`payments.capture`). Verbs that delete or return money are never open to a policy.
+A loop runs a skill a Manage or Report noun's schema names in `loop.skill`, or in `loop.skills` for a noun with several (`manage-orders`, `manage-stock`, `report-sales`, `report-pending`, ...); a report loop allows no verb and only reports. create and update refuse any other skill, and any verb that loop does not list, with the allowed values. A loop policy allows verbs: a bare verb is the skill's own noun (`approve`), `<noun>.<verb>` another Manage noun's verb on the same item (`payments.capture`). Verbs that delete or return money are never open to a policy.
 
 ## Login, organization tokens and secrets
 
@@ -50,7 +51,7 @@ Never from a flag or the environment. c11r exchanges the pair for a two hour tok
 
 `organizations create` and `organizations connect <slug>` answer an organization token once: it is stored like a sandbox token. `connect --revoke-others` also ends every other token of that organization, and asks for confirmation. With a login and no organization token for the organization named, an organization noun stops with `no_credentials` and the next step `c11r organizations connect <slug>`. `members` and `roles` with an organization token and no login are sent with that token, and the API says what is needed: a claim for a sandbox, a login for a claimed organization. `organizations` with no login stops here with `login_required`.
 
-`credentials create` and `credentials token` answer a secret once. c11r writes it to a file with mode 600 and prints the file, the format and a hint, never the value: by default `~/.config/c11r/secrets/<org>/<name>.env` (`<id>-token.env` for a token), or `--out <path>`, as `KEY=value` lines or with `--format json` one JSON object. The file is checked before the request is sent; one there already is replaced only with `--yes`. A file inside a git repository that git does not ignore gets the warning `secret_not_ignored`. With `--dry-run` nothing is written and `secret_file` says where it would go. Each file records the record it belongs to. A `delete` of a record whose noun answers secrets (`credentials`, `webhooks`) removes the files c11r wrote for it in `~/.config/c11r/secrets/<org>/` (a credential's secret and tokens, a webhook's shared secret), found by the id, name or code given, and lists them in `removed_files`; `sandbox destroy` removes the whole folder of that organization and names it in `forgotten.secrets`. A file written with `--out` is not tracked and stays: the warning `out_files_not_tracked` says so, when a secret of that organization was written with `--out` on this machine, or when a delete found nothing to remove. A token file carries `CL_BASE_ENDPOINT` beside the token. `sales-calls book` answers a cancel token once: it is kept in `credentials.json` and `sales-calls cancel <booking>` sends it.
+`credentials create` and `credentials token` answer a secret once. c11r writes it to a file with mode 600 and prints the file, the format and a hint, never the value: by default `~/.config/c11r/secrets/<org>/<name>.env` (`<id>-token.env` for a token; a record with no name, such as a gift card, `gift-card-<id>.env` after the id it is given), or `--out <path>`, as `KEY=value` lines or with `--format json` one JSON object. The file is checked before the request is sent; one there already is replaced only with `--yes`. A file inside a git repository that git does not ignore gets the warning `secret_not_ignored`. With `--dry-run` nothing is written and `secret_file` says where it would go. Each file records the record it belongs to. A `delete` of a record whose noun answers secrets (`credentials`, `webhooks`) removes the files c11r wrote for it in `~/.config/c11r/secrets/<org>/` (a credential's secret and tokens, a webhook's shared secret), found by the id, name or code given, and lists them in `removed_files`; `sandbox destroy` removes the whole folder of that organization and names it in `forgotten.secrets`. A file written with `--out` is not tracked and stays: the warning `out_files_not_tracked` says so on the delete of the record whose secret went to `--out` on this machine, and on `sandbox destroy` of an organization that had one. Any other delete has no such warning. A token file carries `CL_BASE_ENDPOINT` beside the token. `sales-calls book` answers a cancel token once: it is kept in `credentials.json` and `sales-calls cancel <booking>` sends it.
 
 ## Global flags
 
@@ -63,7 +64,7 @@ Never from a flag or the environment. c11r exchanges the pair for a two hour tok
 | `--live` | Live data, on a claimed organization: `?mode=live` on every request. Without it, test mode. |
 | `--help` | Describes the noun or verb it follows, from its schema. |
 
-Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sandbox reset` and `destroy`) 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.
+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.
 
 ## Which organization
 
@@ -73,6 +74,16 @@ Destructive verbs (deletes, `orders cancel`, `payments void` and `refund`, `sand
 - `.c11r.json` holds only `{ "org": "<slug>" }`: no secret, safe to commit. `sandbox create`, `organizations create` and `auth switch` write it, and `organizations connect` when the folder has no link; `reset` follows the new slug; `destroy` removes it when it names the destroyed organization.
 - The project folder is the one with `.c11r.json`, else the nearest with `store.yml` or `loops.yml`, else the current one. `loops.yml` goes there.
 
+## The store's setup in files
+
+`c11r config export` writes the organization's setup into the project folder: `store.yml` (the Configure nouns, refs by key, no ids, no secrets; its first key, `meta`, names the organization and the time) and `price_lists/<code>.csv`. It records what it wrote in `.c11r/export.json`, and never overwrites a file changed since the last export (or one no export wrote) without `--yes`: the answer lists them. A price list file the organization no longer has, unchanged since, goes. `c11r config plan` sends the files and answers what `config apply` would change; `apply` makes the organization match them, and with `--prune` (confirmed) also deletes what the files lack. While imports run, `apply` answers `status: running` with each noun's state and `retry_after`; `--wait` applies again until done or failed.
+
+Records that share a key (two shipping methods with the same name in one market, say) can't be matched to the files. `export` and `plan` list them in `ambiguous` (an empty list when there are none), each with the command that makes its key differ, and `export` puts the first one at the top of `next`. `apply` refuses with `conflict` and the same list in `error.details.ambiguous`, before it writes anything.
+
+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 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.
+
 ## Output, errors and exit codes
 
 Every answer is one JSON object on stdout, the API's envelope:
@@ -124,6 +135,6 @@ The CLI's own answers (help, loops.yml) have the same shape, with `state` null.
 | `C11R_PROVISIONING_TOKEN` | A ready login token, used as is: for CI. Never a client secret. |
 | `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`. |
+| `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_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

@@ -3,6 +3,7 @@
 // verb's flags, which say whether a flag takes a value, what type it is and where it goes.
 import fs from 'node:fs';
 import { closest, fail, fixWith } from './errors.js';
+import { clearable } from './schema.js';
 const BOOLEAN_GLOBALS = {
     '--json': 'json',
     '--dry-run': 'dryRun',
@@ -60,7 +61,11 @@ export function parseFields(noun, verb, rest) {
                 id = a;
                 continue;
             }
-            fail('unexpected_argument', `${cmd} does not take ${a}${verb.id ? `: it already has the id ${id}` : ''}. A value goes after its flag.`, { next_step: fixWith(`${cmd} --help`) });
+            // A verb with no id (stock set): say which flags it does take, as --sku for the sku.
+            const sent = Object.entries(verb.flags).filter(([, f]) => f.to !== 'local');
+            const required = sent.filter(([, f]) => f.required);
+            const takes = (required.length ? required : sent).map(([k]) => toFlag(k));
+            fail('unexpected_argument', `${cmd} does not take ${a}${verb.id ? `: it already has the id ${id}` : takes.length ? `: it takes no id, only flags (${takes.join(', ')})` : ': it takes no id, only flags'}. A value goes after its flag.`, { next_step: fixWith(`${cmd} --help`) });
         }
         const [flag, inline] = splitInline(a);
         const key = toKey(flag);
@@ -104,7 +109,7 @@ export function parseFields(noun, verb, rest) {
             for (const k of sub.slice(0, -1))
                 target = (target[k] ??= {});
             const part = sub.join('.');
-            target[sub[sub.length - 1]] = part in (spec.properties ?? {}) ? coerce(key, { type: spec.properties[part] }, raw) : raw;
+            target[sub[sub.length - 1]] = part in (spec.properties ?? {}) ? coerce(key, spec.properties[part], raw) : raw;
             continue;
         }
         const value = coerce(key, spec, raw);
@@ -122,6 +127,13 @@ function secretAsValue(cmd, key) {
 /** A value as its flag's type says, or invalid_value with the reason. */
 export function coerce(key, spec, raw) {
     const invalid = (why) => fail('invalid_value', `${toFlag(key)} ${JSON.stringify(raw)} ${why}.`, { path: key, ...(spec.values ? { details: { values: spec.values } } : {}) });
+    // The schema's fault, not the command's: said so before any value is checked against nothing.
+    if ((spec.type === 'enum' || (spec.type === 'array' && spec.items === 'enum')) && !spec.values?.length) {
+        fail('invalid_response', `The API's schema gives ${toFlag(key)} as an enum with no values, so c11r cannot check ${JSON.stringify(raw)}. It was not sent.`, { path: key, next_step: { action: 'none' } });
+    }
+    // null, or an empty value, clears what the schema lets null clear (--customer-group null, --coupon-code "").
+    if (clearable(spec) && (raw === 'null' || raw.trim() === ''))
+        return null;
     switch (spec.type) {
         case 'string':
         case 'ref':
@@ -156,7 +168,7 @@ export function coerce(key, spec, raw) {
             const v = raw.trim().startsWith('{') ? json(raw, invalid) : pairs(key, raw, spec.properties ?? {}, invalid);
             if (!v || typeof v !== 'object' || Array.isArray(v))
                 invalid('is not a JSON object');
-            return v;
+            return enumParts(key, spec.properties, v);
         }
         case 'array': {
             const item = spec.items ?? 'string';
@@ -164,11 +176,15 @@ export function coerce(key, spec, raw) {
                 const list = json(raw, invalid);
                 if (!Array.isArray(list))
                     invalid('is not a list');
-                return list.map((x) => (typeof x === 'string' && item !== 'string' ? coerce(key, { type: item, values: spec.values }, x) : x));
+                return list.map((x) => (typeof x === 'string' && item !== 'string' ? coerce(key, { type: item, values: spec.values }, x) : item === 'object' ? enumParts(key, spec.properties, x) : x));
             }
             // One object per flag (--items sku=A,quantity=2, repeated), or scalars separated by commas.
             if (item === 'object')
                 return [coerce(key, { type: 'object', properties: spec.properties }, raw)];
+            // An in filter on names or text takes the value whole: a name may have a comma ("UK VAT, manual").
+            // Several are the flag repeated, or a JSON array. Enums, numbers and dates still split on commas.
+            if (spec.filter?.op === 'in' && (item === 'string' || item === 'ref'))
+                return [raw];
             return raw
                 .split(',')
                 .map((s) => s.trim())
@@ -177,6 +193,17 @@ export function coerce(key, spec, raw) {
         }
     }
 }
+/** In JSON too, an enum part of an object is one of its values. */
+function enumParts(key, props, v) {
+    if (!v || typeof v !== 'object')
+        return v;
+    for (const [name, p] of Object.entries(props ?? {})) {
+        const part = v[name];
+        if (p.type === 'enum' && typeof part === 'string')
+            coerce(`${key}.${name}`, p, part);
+    }
+    return v;
+}
 function json(raw, invalid) {
     try {
         return JSON.parse(raw);
@@ -187,7 +214,7 @@ function json(raw, invalid) {
 }
 /**
  * sku=A,quantity=2 as { sku: 'A', quantity: 2 }, each part typed by the schema's properties.
- * A part the schema does not type stays text: a postal code or a phone is never made a number.
+ * A part the schema does not type stays text: a zip code or a phone is never made a number.
  */
 function pairs(key, raw, props, invalid) {
     const out = {};
@@ -197,7 +224,7 @@ function pairs(key, raw, props, invalid) {
             invalid('is not JSON nor key=value pairs separated by commas');
         const name = part.slice(0, eq).trim();
         const value = part.slice(eq + 1).trim();
-        out[name] = props[name] ? coerce(`${key}.${name}`, { type: props[name] }, value) : value;
+        out[name] = props[name] ? coerce(`${key}.${name}`, props[name], value) : value;
     }
     return out;
 }

package/dist/builtins/extensions.js

@@ -8,10 +8,14 @@
 // sales-calls book answers a cancel token once (section 20): stored the same way, by booking id,
 // and sent by sales-calls cancel <booking> without the agent ever holding it.
 import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
 import { credentialsFile, hintOf, readLink, storeBooking, storedBooking, storeOrg, writeLink } from '../config.js';
 import { confirm, terminal } from '../confirm.js';
 import { fail } from '../errors.js';
 import { apiUrl } from '../http.js';
+import { clearDrift, driftWarning, readDrift, readStoreFiles, storeFileOrg, writeStoreFiles } from '../project.js';
 import { resourceRequest } from '../resources.js';
 const NAME_MAX = 25;
 export const organizations = {
@@ -104,4 +108,151 @@ export const salesCalls = {
         return undefined;
     },
 };
-export const extensions = { organizations, 'sales-calls': salesCalls };
+// config (contract section 45.2): the API answers and applies documents; the files are the CLI's.
+//   export  writes store.yml and price_lists/<code>.csv, never over a file changed since the last
+//           export without --yes, and clears the drift note.
+//   plan    sends the folder's files and says what apply would change, and since when the
+//           folder is behind when Configure writes were made here.
+//   apply   sends them; while imports run (202, running) it shows each noun's state, and with
+//           --wait applies again until done or failed. prune is confirmed by the schema.
+const WAIT_MAX_MS = 15 * 60_000;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const waitMs = (data) => {
+    const s = Number(data?.retry_after);
+    const test = process.env.C11R_WAIT_MS;
+    if (test !== undefined)
+        return Number(test);
+    return (Number.isFinite(s) && s > 0 ? Math.min(s, 60) : 5) * 1000;
+};
+export const config = {
+    flags: {
+        apply: { wait: { type: 'boolean', to: 'local', description: 'While imports run, apply again every retry_after seconds until done or failed (15 minutes at most).' } },
+    },
+    prepare(verb, parsed) {
+        if (verb.name !== 'plan' && verb.name !== 'apply')
+            return;
+        if (parsed.values.store !== undefined)
+            return;
+        const files = readStoreFiles();
+        parsed.values.store = files.store;
+        parsed.values.price_lists = files.price_lists;
+    },
+    async run(run) {
+        const name = run.verb.name;
+        if (name === 'export') {
+            const r = await run.send(resourceRequest('config', run.verb, undefined, run.parsed.values));
+            if (run.globals.dryRun)
+                return r;
+            const data = r.data ?? {};
+            if (!data.store || typeof data.store !== 'object')
+                fail('invalid_response', 'config export answered without store.', { next_step: { action: 'none' } });
+            const out = writeStoreFiles({ store: data.store, price_lists: data.price_lists ?? {}, meta: { org: data.meta?.org ?? run.org.org ?? undefined, exported_at: data.meta?.exported_at } }, { overwrite: run.globals.yes });
+            const ambiguous = Array.isArray(data.ambiguous) ? data.ambiguous : [];
+            const counts = Object.fromEntries(Object.entries(data.store).map(([k, v]) => [k, Array.isArray(v) ? v.length : 0]));
+            return {
+                ...r,
+                data: {
+                    org: data.meta?.org ?? run.org.org,
+                    exported_at: data.meta?.exported_at ?? null,
+                    folder: out.dir,
+                    files: out.written,
+                    removed: out.removed,
+                    records: counts,
+                    price_lists: Object.keys(data.price_lists ?? {}),
+                    // Keys several records share (45.9): apply refuses them until they differ.
+                    ambiguous,
+                },
+                next: [
+                    ...(ambiguous[0]?.command ? [{ command: String(ambiguous[0].command), why: 'records share a key: plan and apply cannot match them until it differs' }] : []),
+                    { command: 'c11r config plan', why: 'what the files would change in an organization, after you edit them or for another one (--org)' },
+                ],
+            };
+        }
+        if (name === 'plan' || name === 'apply') {
+            const req = resourceRequest('config', run.verb, undefined, run.parsed.values);
+            let r = await run.send(req);
+            const started = Date.now();
+            while (name === 'apply' && run.parsed.values.wait && r.data?.status === 'running' && Date.now() - started < WAIT_MAX_MS) {
+                const ms = waitMs(r.data);
+                process.stderr.write(JSON.stringify({ running: { nouns: states(r.data), next_in_ms: ms } }) + '\n');
+                await sleep(ms);
+                r = await run.send(req);
+            }
+            const warnings = [...r.warnings];
+            const here = storeFileOrg();
+            const drift = readDrift();
+            if (name === 'plan' && drift.length && here === run.org.org)
+                warnings.push(driftWarning(drift));
+            // The organization now matches the files: the folder is no longer behind.
+            if (name === 'apply' && !run.globals.dryRun && r.data?.status === 'done' && here === run.org.org)
+                clearDrift();
+            const data = r.data ?? {};
+            const running = name === 'apply' && data.status === 'running';
+            return {
+                ...r,
+                data: running ? { ...data, retry_after: waitMs(data) / 1000, states: states(data) } : data,
+                warnings,
+                next: running && !run.parsed.values.wait ? [{ command: `${run.line} --wait`, why: 'carry on, and wait until every noun is done or failed' }, ...r.next] : r.next,
+            };
+        }
+        return undefined;
+    },
+};
+/** Each noun's state while apply runs: done, running (with its import), waiting, failed or unchanged. */
+function states(data) {
+    const out = {};
+    for (const n of Array.isArray(data?.nouns) ? data.nouns : [])
+        out[n.noun] = n.import?.id && n.status === 'running' ? `running (import ${n.import.id})` : String(n.status);
+    return out;
+}
+// exports (45.3): get --out downloads the file while its link is good (5 minutes), unzipped unless
+// the name ends in .gz; --wait polls a job not completed yet.
+export const exports = {
+    flags: {
+        get: {
+            out: { type: 'string', to: 'local', description: 'Download the export to this file once completed (its link lasts 5 minutes). Unzipped, unless the name ends in .gz.' },
+            wait: { type: 'boolean', to: 'local', description: 'Until the export is completed, failed or interrupted, read it again every few seconds (15 minutes at most).' },
+        },
+    },
+    async run(run) {
+        if (run.verb.name !== 'get' || (!run.parsed.values.out && !run.parsed.values.wait))
+            return undefined;
+        const req = resourceRequest('exports', run.verb, run.parsed.id, run.parsed.values);
+        let r = await run.send(req);
+        const started = Date.now();
+        const busy = (s) => s === 'pending' || s === 'in_progress';
+        while (run.parsed.values.wait && busy(r.data?.status) && Date.now() - started < WAIT_MAX_MS) {
+            const ms = waitMs(null);
+            process.stderr.write(JSON.stringify({ waiting: { export: run.parsed.id, status: r.data?.status, next_in_ms: ms } }) + '\n');
+            await sleep(ms);
+            r = await run.send(req);
+        }
+        const out = run.parsed.values.out;
+        if (!out)
+            return r;
+        const data = r.data ?? {};
+        if (data.status !== 'completed' || typeof data.url !== 'string') {
+            fail('conflict', `Export ${run.parsed.id} is ${data.status ?? 'not completed'}: there is no file to download yet.`, { path: 'out', details: { status: data.status ?? null }, next_step: { action: 'fix_request', command: `${run.line} --wait` } }, 'rejected');
+        }
+        const file = path.resolve(out);
+        let res;
+        try {
+            res = await fetch(data.url, { signal: AbortSignal.timeout(120_000) });
+        }
+        catch (e) {
+            fail('api_unreachable', `The export's file could not be downloaded: ${e.message}.`, { path: 'out', next_step: { action: 'fix_request', command: run.line } });
+        }
+        // An expired link: get the export again for a new one.
+        if (!res.ok)
+            fail('expired', `The export's link answered ${res.status}: it lasts 5 minutes. Get the export again for a new one.`, { path: 'out', next_step: { action: 'fix_request', command: run.line } }, 'rejected');
+        let bytes = Buffer.from(await res.arrayBuffer());
+        const zipped = bytes[0] === 0x1f && bytes[1] === 0x8b;
+        if (zipped && !file.endsWith('.gz'))
+            bytes = zlib.gunzipSync(bytes);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, bytes);
+        const { url: _url, ...rest } = data;
+        return { ...r, data: { ...rest, file, bytes: bytes.length, unzipped: zipped && !file.endsWith('.gz') } };
+    },
+};
+export const extensions = { organizations, 'sales-calls': salesCalls, config, exports };

package/dist/builtins/loops.js

@@ -4,8 +4,9 @@
 // schedules the agent repeats it every `every`.
 //
 // A policy allows verbs: a bare verb is the skill's own noun (approve), <noun>.<verb> another
-// Manage noun's verb on the same item (payments.capture). Each must be in the noun's schema
-// loop.verbs; the API checks again on every pass.
+// Manage noun's verb on the same item (payments.capture). The skill must be one a Manage or Report
+// noun's schema names in loop.skill or loop.skills, and each verb in that loop.verbs; the API checks
+// again on every pass.
 import fs from 'node:fs';
 import path from 'node:path';
 import YAML from 'yaml';
@@ -13,13 +14,13 @@ import { projectDir } from '../config.js';
 import { CliError, closest, fail, fixWith } from '../errors.js';
 import { envelope } from '../http.js';
 import { parseSchema } from '../schema.js';
-import { apiSchema } from '../schemas.js';
+import { apiNouns, apiSchema } from '../schemas.js';
 const NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
 const EVERY = /^[1-9]\d*(m|h|d)$/;
 const policyFlags = (required) => [
-    { name: 'skill', type: 'string', required, description: 'The Manage skill or playbook the loop runs, as in manage-orders.' },
+    { name: 'skill', type: 'string', required, description: 'The skill the loop runs, as in manage-orders or report-sales: one a noun\'s schema names in loop.skill or loop.skills.' },
     { name: 'every', type: 'string', required, description: 'How often a pass should run, as in 15m, 2h or 1d. The scheduler reads it; the CLI does not wait.' },
-    { name: 'allow', type: 'array', required, description: 'A verb the policy allows, repeated: approve, payments.capture. Only verbs the noun\'s schema lists in loop.verbs.' },
+    { name: 'allow', type: 'array', description: 'A verb the policy allows, repeated: approve, payments.capture. Only verbs the noun\'s schema lists in loop.verbs. Without it the loop only reports what is waiting.' },
     { name: 'max_total', type: 'array', description: 'The largest order total acted on, in major units: 500 for every currency, or EUR=500, repeated per currency. Above it, the item waits for the human.' },
     { name: 'market', type: 'array', description: 'A market code the loop acts in, repeated. Items in other markets wait. Without it, every market.' },
 ];
@@ -77,9 +78,11 @@ export function readLoops(file) {
     const out = {};
     for (const [name, d] of Object.entries(raw.loops ?? {})) {
         const def = d;
-        if (!def || typeof def.skill !== 'string' || !Array.isArray(def.policy?.allow))
-            fail('invalid_config', `${file}: loop ${name} needs a skill and a policy with allow.`, { path: `loops.${name}` });
-        out[name] = def;
+        // allow may be left out, or empty: the loop only reports.
+        const allow = def?.policy?.allow ?? [];
+        if (!def || typeof def.skill !== 'string' || !Array.isArray(allow))
+            fail('invalid_config', `${file}: loop ${name} needs a skill, and its policy.allow is a list of verbs.`, { path: `loops.${name}` });
+        out[name] = { ...def, policy: { ...(def.policy ?? {}), allow } };
     }
     return out;
 }
@@ -118,7 +121,7 @@ async function write(run, name, file) {
         skill: v.skill ?? existing.skill,
         every: v.every ?? existing.every,
         policy: {
-            allow: v.allow ?? existing.policy.allow,
+            allow: v.allow ?? existing?.policy.allow ?? [],
             ...(v.max_total !== undefined ? { max_total: maxTotal(v.max_total) } : existing?.policy.max_total !== undefined ? { max_total: existing.policy.max_total } : {}),
             ...(v.market !== undefined ? { markets: v.market } : existing?.policy.markets ? { markets: existing.policy.markets } : {}),
         },
@@ -166,24 +169,50 @@ function maxTotal(items) {
         return [ccy, amount(n)];
     }));
 }
-/** The policy's verbs against the skill noun's schema; a playbook is checked by the API at the first pass. */
+/**
+ * The skill and the policy's verbs against the same source loops run uses: each noun schema's loop,
+ * { skill, verbs }. A skill no schema's loop names is refused with the ones that are, and so is a
+ * verb its loop does not list.
+ */
 async function checkPolicy(def) {
-    if (!def.policy.allow.length)
-        fail('missing_argument', 'A loop needs at least one --allow.', { path: 'allow' });
-    if (!def.skill.startsWith('manage-'))
-        return [{ code: 'policy_unchecked', message: `${def.skill} is not a Manage skill: the API checks its policy at the first pass.` }];
-    const noun = def.skill.slice('manage-'.length);
-    const schema = await apiSchema(noun, []);
-    const allowed = schema.loop?.verbs ?? [];
-    if (!allowed.length)
-        fail('policy_forbidden', `No loop acts on ${noun}: its schema has no loop.`, { path: 'skill' });
+    const skills = await loopSkills();
+    const allowed = skills.get(def.skill);
+    if (!allowed) {
+        const names = [...skills.keys()].sort();
+        fail('invalid_value', `--skill ${def.skill} runs no loop. A loop runs ${names.length ? names.join(', ') : 'no skill yet'}.`, {
+            path: 'skill',
+            did_you_mean: closest(def.skill, names),
+            details: { values: names },
+            next_step: fixWith('c11r loops create --help'),
+        });
+    }
     for (const verb of def.policy.allow) {
-        if (!allowed.includes(verb)) {
-            fail('policy_forbidden', `A ${def.skill} loop may not allow ${verb}. It may allow ${allowed.join(', ')}.`, { path: 'allow', did_you_mean: closest(verb, allowed), details: { loopable: allowed }, next_step: fixWith(`c11r schema ${noun}`) });
+        if (!allowed.verbs.includes(verb)) {
+            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 [];
 }
+/**
+ * The skills a loop can run, from the schemas of the nouns that have a loop (Manage and Report):
+ * each skill to its noun and the verbs its policy may allow. loop.skills, when given, lists every
+ * skill of the noun's loop (a report loop per report); else loop.skill is the one.
+ */
+async function loopSkills() {
+    const nouns = (await apiNouns()).filter((n) => (n.group === 'manage' || n.group === 'report') && n.served !== false);
+    const schemas = await Promise.all(nouns.map((n) => apiSchema(n.noun, []).catch(() => null)));
+    const out = new Map();
+    for (const s of schemas) {
+        if (!s?.loop)
+            continue;
+        const names = Array.isArray(s.loop.skills) && s.loop.skills.length ? s.loop.skills : s.loop.skill ? [s.loop.skill] : [];
+        for (const skill of names) {
+            const seen = out.get(skill);
+            out.set(skill, { noun: seen?.noun ?? s.noun, verbs: [...new Set([...(seen?.verbs ?? []), ...(s.loop.verbs ?? [])])] });
+        }
+    }
+    return out;
+}
 async function remove(run, name, file) {
     one(file, name);
     if (run.globals.dryRun)

package/dist/builtins/sandbox.js

@@ -4,7 +4,7 @@
 // reset moves both to the new organization; destroy forgets them. The token is printed never,
 // not even by create: only its hint.
 import crypto from 'node:crypto';
-import { credentialsFile, defaultOrg, markOutWritten, outWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
+import { credentialsFile, defaultOrg, forgetOutWritten, storedLogin, forgetOrg, LINK_FILE, readLink, removeLink, renameOrg, storedOrgs, storeOrg, writeLink, hintOf } from '../config.js';
 import { CliError, fail } from '../errors.js';
 import { apiUrl, envelope, request } from '../http.js';
 import { parseSchema } from '../schema.js';
@@ -28,9 +28,9 @@ 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 test payment method, enough to place a test order at once.' },
+                    { 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.' },
                 ],
-                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 20 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 is applied, in about 10 seconds.',
             },
             { 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.' },
             {
@@ -124,8 +124,7 @@ async function destroy(run) {
         // here. The sandbox is gone either way, so this machine forgets it too.
         if (!(e instanceof CliError && e.code === 'unauthorized') || run.globals.dryRun || !run.org.org)
             throw e;
-        const out = outWritten(run.org.org);
-        markOutWritten(run.org.org, false);
+        const out = forgetOutWritten(run.org.org);
         forgetOrg(run.org.org);
         const link = removeLink(run.org.org);
         const secrets = removeOrgSecrets(run.org.org);
@@ -136,8 +135,7 @@ async function destroy(run) {
     const org = r.data?.org ?? run.org.org;
     if (!org)
         return r;
-    const out = outWritten(org);
-    markOutWritten(org, false);
+    const out = forgetOutWritten(org);
     forgetOrg(org);
     const link = removeLink(org);
     const secrets = removeOrgSecrets(org);

package/dist/config.js

@@ -110,20 +110,37 @@ export function setDefaultOrg(org) {
         delete c.default_org;
     writeCredentials(c);
 }
-export function outWritten(org) {
-    return Boolean(readCredentials().out_written?.[org]);
+/** A record's secret went to an --out file: remembered so its delete can say that file stays. */
+export function markOutWritten(org, record) {
+    const keys = record.keys.filter(Boolean);
+    if (!keys.length)
+        return;
+    const c = readCredentials();
+    const all = { ...(c.out_written ?? {}) };
+    const list = (all[org] ?? []).filter((r) => !(r.noun === record.noun && r.keys.some((k) => keys.includes(k))));
+    all[org] = [...list, { noun: record.noun, keys }];
+    c.out_written = all;
+    writeCredentials(c);
 }
-export function markOutWritten(org, written) {
+/**
+ * After a delete: whether that record had a secret written with --out, which is then forgotten.
+ * With no record named, the organization goes (sandbox destroy).
+ */
+export function forgetOutWritten(org, record) {
     const c = readCredentials();
+    const list = c.out_written?.[org] ?? [];
+    const hit = (r) => !record || (r.noun === record.noun && r.keys.some((k) => record.keys.includes(k)));
+    if (!list.some(hit))
+        return false;
+    const rest = list.filter((r) => !hit(r));
     const all = { ...(c.out_written ?? {}) };
-    if (written === Boolean(all[org]))
-        return;
-    if (written)
-        all[org] = true;
+    if (rest.length)
+        all[org] = rest;
     else
         delete all[org];
     c.out_written = all;
     writeCredentials(c);
+    return true;
 }
 export function storedBooking(id) {
     const b = readCredentials().bookings?.[id];

package/dist/engine.js

@@ -4,7 +4,7 @@
 // destructive verb, then the request. A plain noun needs no code here: its schema says
 // everything. Every answer is the API's envelope, { data, state, warnings, next }.
 import { parseCommand, parseFields, toFlag } from './argv.js';
-import { outWritten, raiseProblem, resolveOrg } from './config.js';
+import { forgetOutWritten, raiseProblem, resolveOrg } from './config.js';
 import { confirm, terminal } from './confirm.js';
 import { CliError, closest, fail, fixWith } from './errors.js';
 import { indexHelp, nounHelp, verbHelp } from './help.js';
@@ -12,11 +12,37 @@ import { envelope, request } from './http.js';
 import { readInputs } from './inputs.js';
 import { hasLogin, loginToken } from './login.js';
 import { resourceRequest } from './resources.js';
+import { markDrift } from './project.js';
 import { describePlan, OUT_NOT_TRACKED, planSecret, removeRecordFiles, writeSecret } from './secrets.js';
 import { verbOf } from './schema.js';
-import { apiNouns, apiSchema } from './schemas.js';
+import { apiNouns, apiSchema, refreshSchemas, refusedBySchema } from './schemas.js';
 import { VERSION } from './version.js';
+/**
+ * One command. When it was read against a cached schema the API has since changed (a deploy), and
+ * the refusal is one that explains (refusedBySchema), it runs once more on fresh schemas. The API
+ * refused, so nothing happened; the second run asks again what the fresh schema asks, and never
+ * adds confirm=true on its own.
+ */
 export async function execute(argv, opts = {}) {
+    try {
+        return await executeOnce(argv, opts);
+    }
+    catch (e) {
+        if (!(e instanceof CliError) || !refusedBySchema(e.code) || !refusedBeforeEffect(e))
+            throw e;
+        refreshSchemas();
+        process.stderr.write(JSON.stringify({ retrying: { code: e.code, why: 'the schema changed on the API: read again' } }) + '\n');
+        return executeOnce(argv, opts);
+    }
+}
+/** A refusal the API answered (4xx), or a flag or verb the cached schema did not know: nothing was done. */
+function refusedBeforeEffect(e) {
+    const status = e.body.details?.status;
+    if (typeof status === 'number')
+        return status >= 400 && status < 500;
+    return e.code === 'unknown_field' || e.code === 'unknown_verb';
+}
+async function executeOnce(argv, opts) {
     const cmd = parseCommand(argv);
     const builtins = opts.builtins ?? {};
     if (cmd.globals.version && !cmd.noun)
@@ -28,7 +54,10 @@ export async function execute(argv, opts = {}) {
     const schema = builtins[cmd.noun]?.schema ?? (await apiSchema(cmd.noun, Object.keys(builtins)));
     if (cmd.globals.help && !cmd.verb && !builtins[cmd.noun]?.defaultVerb)
         return envelope(nounHelp(schema));
-    const verb = verbOf(schema, cmd.verb ?? builtins[cmd.noun]?.defaultVerb);
+    const ext = opts.extensions?.[schema.noun];
+    const found = verbOf(schema, cmd.verb ?? builtins[cmd.noun]?.defaultVerb);
+    const local = ext?.flags?.[found.name];
+    const verb = local ? { ...found, flags: { ...found.flags, ...local } } : found;
     if (cmd.globals.help)
         return envelope(verbHelp(schema, verb));
     // A verb the schema lists as refused: no request, no confirmation for something that cannot happen.
@@ -36,7 +65,6 @@ export async function execute(argv, opts = {}) {
         const by = verb.refused.by === 'commercelayer' ? 'Commerce Layer' : verb.refused.by;
         fail('not_supported', `c11r ${schema.noun} ${verb.name} is refused by ${by}: ${verb.description || 'it cannot be done through the API.'}`, { details: { refused_by: verb.refused.by }, next_step: { action: 'none' } });
     }
-    const ext = opts.extensions?.[schema.noun];
     const positional = ext?.positional?.[verb.name];
     const rest = positional && !verb.id && cmd.rest[0] !== undefined && !cmd.rest[0].startsWith('-') ? [`--${positional}`, ...cmd.rest] : cmd.rest;
     const parsed = parseFields(schema.noun, verb, rest);
@@ -73,13 +101,13 @@ export async function execute(argv, opts = {}) {
     }
     let confirmed = false;
     const confirmFlags = verb.confirmIf.filter((k) => parsed.values[k] !== undefined && parsed.values[k] !== false);
-    if ((verb.destructive || confirmFlags.length) && !cmd.globals.dryRun) {
+    if ((verb.destructive || verb.confirm || confirmFlags.length) && !cmd.globals.dryRun) {
         const what = `${verb.name} ${schema.noun}${parsed.id ? ` ${parsed.id}` : ''}${confirmFlags.length ? ` with ${confirmFlags.map(toFlag).join(' ')}` : ''}`;
         await confirm(what.charAt(0).toUpperCase() + what.slice(1), line, { yes: cmd.globals.yes, prompter: opts.prompter });
         confirmed = true;
     }
     // Where a secret goes, checked before the request makes one.
-    const secretPlan = verb.secret ? planSecret({ org: org.org, verb: verb.name, id: parsed.id, values: parsed.values, yes: cmd.globals.yes }) : null;
+    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: cmd.globals.live, token: bearer === 'login' ? await loginToken() : org.token };
     const orgQuery = 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);
@@ -115,12 +143,26 @@ export async function execute(argv, opts = {}) {
     };
     const own = (await builtins[schema.noun]?.run?.(run)) ?? (await ext?.run?.(run));
     const r = own ?? (await run.send(resourceRequest(schema.noun, verb, parsed.id, parsed.values)));
-    return filesGone(secretOf(r, run, secretPlan), run);
+    return drifted(filesGone(secretOf(r, run, secretPlan), run), run);
+}
+/**
+ * A Configure write that went through, in a folder whose store.yml names this organization: the
+ * file is now behind it. Noted in .c11r/drift, with the warning config_drift.
+ */
+function drifted(r, run) {
+    if (run.globals.dryRun || !run.org.org || run.verb.method === 'GET')
+        return r;
+    if (run.schema.doc?.group !== 'configure')
+        return r;
+    const data = (r.data && typeof r.data === 'object' ? r.data : {});
+    const id = [run.parsed.id, data.code, data.name, data.id].find((k) => typeof k === 'string' && k !== '');
+    const warning = markDrift(run.org.org, { noun: run.schema.noun, verb: run.verb.name, id: id ?? null });
+    return warning ? { ...r, warnings: [...r.warnings, warning] } : r;
 }
 /**
- * A delete of a record whose verbs answer secrets (credentials, webhooks): the files c11r wrote
- * for it go with it, listed in removed_files. out_files_not_tracked only when it may apply:
- * nothing found here, or a secret of this organization written with --out on this machine.
+ * A delete on a noun that answers secrets: the files c11r wrote for that record in the secrets
+ * folder go with it, listed in removed_files. out_files_not_tracked only when that record's secret
+ * was written with --out on this machine: that file stays where it was written.
  */
 function filesGone(r, run) {
     if (run.verb.name !== 'delete' || run.globals.dryRun || !run.org.org)
@@ -128,8 +170,9 @@ function filesGone(r, run) {
     if (!Object.values(run.schema.verbs).some((v) => v.secret))
         return r;
     const data = (r.data && typeof r.data === 'object' ? r.data : {});
-    const removed = removeRecordFiles(run.org.org, run.schema.noun, [run.parsed.id, data.id, data.name, data.code]);
-    const warn = removed.length === 0 || outWritten(run.org.org);
+    const keys = [run.parsed.id, data.id, data.name, data.code].filter((k) => typeof k === 'string' && k !== '');
+    const removed = removeRecordFiles(run.org.org, run.schema.noun, keys);
+    const warn = forgetOutWritten(run.org.org, { noun: run.schema.noun, keys });
     return { ...r, data: { ...data, removed_files: removed }, warnings: [...r.warnings, ...(warn ? [OUT_NOT_TRACKED] : [])] };
 }
 /** A secret in the answer goes to its file; a dry run says where it would go. */
@@ -138,7 +181,7 @@ function secretOf(r, run, plan) {
     const secret = data && typeof data === 'object' ? data.secret : undefined;
     if (secret && typeof secret === 'object' && 'value' in secret) {
         // A verb the schema did not mark: still never printed.
-        const p = plan ?? planSecret({ org: run.org.org, verb: run.verb.name, id: run.parsed.id, values: run.parsed.values, yes: true });
+        const p = plan ?? planSecret({ org: run.org.org, noun: run.schema.noun, verb: run.verb.name, id: run.parsed.id, values: run.parsed.values, yes: true });
         return writeSecret(r, p, { org: run.org.org, noun: run.schema.noun, verb: run.verb.name, id: run.parsed.id });
     }
     if (plan && run.globals.dryRun)

package/dist/help.js

@@ -3,6 +3,7 @@
 // reads it and offers to do the work.
 import { toFlag } from './argv.js';
 import { EXIT } from './errors.js';
+import { clearable } from './schema.js';
 export const USAGE = 'c11r <noun> <verb> [id] [--field value ...]';
 export const GLOBAL_FLAG_HELP = {
     '--json': 'Output as JSON. The default, and the only format: one object on stdout, { data, state, warnings, next } or { error, state }.',
@@ -21,7 +22,7 @@ export const EXIT_CODE_HELP = {
     [EXIT.not_found]: 'no such resource',
     [EXIT.rejected]: 'the API or Commerce Layer refused the request as it is',
     [EXIT.unavailable]: 'the API did not answer, is busy, or answered with an error of its own',
-    [EXIT.auth]: 'a wrong or revoked token, or no token stored for the organization named',
+    [EXIT.auth]: 'a wrong or revoked token, no token stored for the organization named, or no login (login_required)',
 };
 export function indexHelp(builtins, api) {
     return {
@@ -29,7 +30,7 @@ export function indexHelp(builtins, api) {
         description: 'c11r is the Commerce Layer CLI for coding agents. Every answer, errors included, is one JSON object on stdout.',
         nouns: [...builtins, ...(api ?? [])].sort((a, b) => (a.noun < b.noun ? -1 : 1)),
         standard_verbs: 'list, get, create, update, delete. Nouns with a state machine add their own verbs.',
-        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01; in takes values separated by commas). A dotted flag sets part of an object (--customer.email). An array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
+        flags: 'Fields in kebab or snake case (--price-list, --price_list). On list, --<field> <value> filters by equality and --<field>.<op> <value> by another operator (--created-at.gte 2026-11-01). in takes several values as the flag repeated or a JSON array; on enums, numbers and dates also separated by commas, while a name or text is one value even with a comma in it, and a list that has one is sent as a JSON array. A ref flag, or a flag the schema marks nullable, given null or an empty value sends null and takes it off (--customer-group null, --coupon-code null). A dotted flag sets part of an object (--customer.email). Any other array takes a JSON array, values separated by commas, or the flag repeated; an array of objects takes key=value pairs (--items sku=COFFEE,quantity=2). --data takes the fields as one JSON object, or @ and a file name.',
         global_flags: GLOBAL_FLAG_HELP,
         exit_codes: EXIT_CODE_HELP,
         more: 'c11r <noun> --help describes a noun and its verbs; c11r <noun> <verb> --help a verb and its flags; c11r schema <noun> returns the full schema.',
@@ -53,7 +54,8 @@ export function verbHelp(s, v) {
         state: v.state,
         ...(v.plan ? { plan: v.plan } : {}),
         ...(v.refused ? { served: false, refused_by: v.refused.by } : {}),
-        ...(v.destructive ? { destructive: true, confirmation: 'Asks for confirmation unless --yes; with no terminal and no --yes it stops with confirmation_required.' } : {}),
+        ...(v.destructive ? { destructive: true } : {}),
+        ...(v.confirm ? { confirmation: 'Asks for confirmation unless --yes; with no terminal and no --yes it stops with confirmation_required.' } : {}),
         ...(v.loopable ? { loopable: 'A loop policy may allow this verb.' } : {}),
         ...(v.live ? {} : { live: 'Not in live mode.' }),
         flags: Object.entries(v.flags).map(([key, f]) => flagHelp(key, f)),
@@ -66,6 +68,7 @@ function flagHelp(key, f) {
         ...(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 } : {}),
+        ...(clearable(f) ? { clear: 'null, or an empty value, takes it off' } : {}),
         ...(f.filter ? { filter: f.filter.op } : {}),
         ...(f.description ? { description: f.description } : {}),
     };
@@ -74,7 +77,7 @@ export function usageOf(noun, v) {
     const needed = (f) => f.required || (f.input?.kind === 'secret' && f.input.required);
     const required = Object.entries(v.flags)
         .filter(([, f]) => needed(f))
-        .map(([k, f]) => `${toFlag(k)} <${f.input ? 'file' : f.type === 'enum' ? f.values?.join('|') : f.type}>`);
+        .map(([k, f]) => `${toFlag(k)} <${f.input ? 'file' : f.type === 'enum' && f.values?.length ? f.values.join('|') : f.type}>`);
     const optional = Object.entries(v.flags).some(([k, f]) => !needed(f) && !v.idAlternative.includes(k));
     const id = v.id ? (v.idAlternative.length ? `<id | ${v.idAlternative.map((k) => `${toFlag(k)} <${v.flags[k].type}>`).join(' ')}>` : '<id>') : '';
     return [`c11r ${noun} ${v.name}`, id, ...required, optional ? '[--field value ...]' : ''].filter(Boolean).join(' ');

package/dist/http.js

@@ -33,6 +33,13 @@ export function urlOf(req, ctx) {
     const qs = q.toString();
     return `${apiUrl()}${req.path}${qs ? `?${qs}` : ''}`;
 }
+/** The header with the hash of the schemas the API serves: it changes with a deploy that changes them. */
+export const SCHEMA_HEADER = 'c11r-schema';
+let schemaWatcher = null;
+/** Called with the header's value on every answer that has it (the schema cache listens). */
+export function watchSchemaHeader(fn) {
+    schemaWatcher = fn;
+}
 /** Sends the request: the envelope, or the API's error as a CliError. */
 export async function request(req, ctx) {
     for (let attempt = 1;; attempt++) {
@@ -76,6 +83,9 @@ async function once(req, ctx) {
             next_step: req.method === 'GET' ? { action: 'retry_later' } : { action: 'none' },
         });
     }
+    const version = res.headers.get(SCHEMA_HEADER);
+    if (version && schemaWatcher)
+        schemaWatcher(version);
     const text = await res.text();
     let data;
     try {

package/dist/project.js

@@ -0,0 +1,175 @@
+// The project folder's configuration files (contract section 45.2): store.yml and
+// price_lists/<code>.csv, written by config export and read by config plan and apply, and the
+// CLI's own notes about them in .c11r/:
+//
+//   .c11r/export.json  what the last export wrote: the organization, when, and each file's hash,
+//                      so the next export never overwrites a file changed since without --yes.
+//   .c11r/drift        the Configure writes made since, in a folder whose store.yml names the
+//                      same organization: config plan mentions them, config export clears them.
+//
+// store.yml carries the export's meta ({ org, exported_at }) as its first key; the CLI takes it
+// off before it sends the file, so the API sees { <noun>: [records] } only.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import YAML from 'yaml';
+import { projectDir } from './config.js';
+import { fail } from './errors.js';
+export const STORE_FILE = 'store.yml';
+export const PRICE_LISTS_DIR = 'price_lists';
+const NOTES_DIR = '.c11r';
+const EXPORT_FILE = 'export.json';
+const DRIFT_FILE = 'drift';
+const hashOf = (text) => `sha256-${crypto.createHash('sha256').update(text).digest('hex')}`;
+const notes = (dir) => path.join(dir, NOTES_DIR);
+/** store.yml and the price list CSVs of the project folder, or store_not_found. */
+export function readStoreFiles(dir = projectDir()) {
+    const file = path.join(dir, STORE_FILE);
+    let text;
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        fail('not_found', `There is no ${STORE_FILE} in ${dir}. c11r config export writes one from the organization.`, { path: 'store', next_step: { action: 'fix_request', command: 'c11r config export' } });
+    }
+    let doc;
+    try {
+        doc = YAML.parse(text) ?? {};
+    }
+    catch (e) {
+        fail('invalid_config', `${file} is not YAML: ${e.message}`, { path: 'store' });
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        fail('invalid_config', `${file} holds no nouns: it is { <noun>: [records] }.`, { path: 'store' });
+    const { meta, ...store } = doc;
+    const org = meta && typeof meta === 'object' && typeof meta.org === 'string' ? meta.org : null;
+    const price_lists = {};
+    const csvDir = path.join(dir, PRICE_LISTS_DIR);
+    let names = [];
+    try {
+        names = fs.readdirSync(csvDir);
+    }
+    catch {
+        // No price lists: fine.
+    }
+    for (const n of names.sort())
+        if (n.endsWith('.csv'))
+            price_lists[n.slice(0, -4)] = fs.readFileSync(path.join(csvDir, n), 'utf8');
+    return { store, price_lists, org };
+}
+/** The organization the folder's store.yml names, or null without one. */
+export function storeFileOrg(dir = projectDir()) {
+    try {
+        const doc = YAML.parse(fs.readFileSync(path.join(dir, STORE_FILE), 'utf8'));
+        return typeof doc?.meta?.org === 'string' ? doc.meta.org : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Writes an export: store.yml (meta first) and price_lists/<code>.csv. A file there that differs
+ * from what the last export wrote (or that no export wrote) is the user's: without overwrite,
+ * nothing is written and the answer lists them. Price list files the last export wrote, unchanged
+ * since, and no longer in the organization, go.
+ */
+export function writeStoreFiles(data, opts) {
+    const dir = opts.dir ?? projectDir();
+    const last = readRecord(dir);
+    const meta = { org: data.meta?.org ?? null, exported_at: data.meta?.exported_at ?? new Date().toISOString() };
+    const yaml = `# The organization's setup, written by c11r config export. Edit it, then c11r config plan and c11r config apply.\n${YAML.stringify({ meta, ...data.store }, { lineWidth: 0 })}`;
+    const files = { [STORE_FILE]: yaml };
+    for (const [code, csv] of Object.entries(data.price_lists ?? {}))
+        files[path.join(PRICE_LISTS_DIR, `${safeName(code)}.csv`)] = csv;
+    const changed = (rel) => {
+        const abs = path.join(dir, rel);
+        if (!fs.existsSync(abs))
+            return false;
+        const now = hashOf(fs.readFileSync(abs, 'utf8'));
+        return last.files[rel] !== now;
+    };
+    const stale = Object.keys(last.files).filter((rel) => rel.startsWith(`${PRICE_LISTS_DIR}${path.sep}`) && !(rel in files) && fs.existsSync(path.join(dir, rel)));
+    const mine = [...Object.keys(files).filter((rel) => files[rel] !== readOr(path.join(dir, rel))), ...stale].filter(changed);
+    if (mine.length && !opts.overwrite) {
+        fail('conflict', `${mine.join(', ')} changed since the last export${last.exported_at ? ` (${last.exported_at})` : ''}, or no export wrote ${mine.length === 1 ? 'it' : 'them'}. c11r replaces ${mine.length === 1 ? 'it' : 'them'} only with --yes; c11r config plan shows what the files would change in the organization.`, {
+            path: 'store',
+            details: { files: mine.map((rel) => path.join(dir, rel)) },
+            next_step: { action: 'fix_request', command: 'c11r config plan' },
+        }, 'rejected');
+    }
+    const written = [];
+    for (const [rel, text] of Object.entries(files)) {
+        const abs = path.join(dir, rel);
+        fs.mkdirSync(path.dirname(abs), { recursive: true });
+        if (readOr(abs) !== text)
+            fs.writeFileSync(abs, text);
+        written.push(abs);
+    }
+    const removed = [];
+    for (const rel of stale) {
+        fs.rmSync(path.join(dir, rel), { force: true });
+        removed.push(path.join(dir, rel));
+    }
+    writeRecord(dir, { org: meta.org, exported_at: meta.exported_at, files: Object.fromEntries(Object.entries(files).map(([rel, text]) => [rel, hashOf(text)])) });
+    clearDrift(dir);
+    return { written, removed, dir };
+}
+/**
+ * After a Configure write: in a folder whose store.yml names this organization, notes it in
+ * .c11r/drift and answers the warning. Elsewhere, nothing.
+ */
+export function markDrift(org, entry, dir = projectDir()) {
+    if (storeFileOrg(dir) !== org)
+        return null;
+    const list = readDrift(dir);
+    list.push({ ...entry, at: new Date().toISOString() });
+    fs.mkdirSync(notes(dir), { recursive: true });
+    // The first ones say since when; the last 50 say what.
+    const kept = list.length > 50 ? [list[0], ...list.slice(-49)] : list;
+    fs.writeFileSync(path.join(notes(dir), DRIFT_FILE), JSON.stringify(kept, null, 2) + '\n');
+    return driftWarning(kept);
+}
+/** The writes noted since the last export, oldest first. */
+export function readDrift(dir = projectDir()) {
+    try {
+        const v = JSON.parse(fs.readFileSync(path.join(notes(dir), DRIFT_FILE), 'utf8'));
+        return Array.isArray(v) ? v : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function clearDrift(dir = projectDir()) {
+    fs.rmSync(path.join(notes(dir), DRIFT_FILE), { force: true });
+}
+export function driftWarning(list) {
+    const first = list[0];
+    const what = (e) => `${e.noun} ${e.verb}${e.id ? ` ${e.id}` : ''}`;
+    return {
+        code: 'config_drift',
+        message: `store.yml is now behind the organization, since ${first.at} (${what(first)}${list.length > 1 ? ` and ${list.length - 1} more` : ''}): c11r config export refreshes it.`,
+    };
+}
+function readRecord(dir) {
+    try {
+        const v = JSON.parse(fs.readFileSync(path.join(notes(dir), EXPORT_FILE), 'utf8'));
+        return { org: v.org ?? null, exported_at: v.exported_at ?? null, files: v.files && typeof v.files === 'object' ? v.files : {} };
+    }
+    catch {
+        return { org: null, exported_at: null, files: {} };
+    }
+}
+function writeRecord(dir, r) {
+    fs.mkdirSync(notes(dir), { recursive: true });
+    fs.writeFileSync(path.join(notes(dir), EXPORT_FILE), JSON.stringify(r, null, 2) + '\n');
+}
+function readOr(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** A price list code as a file name: letters, digits, dot, dash and underscore. */
+const safeName = (code) => code.replace(/[^A-Za-z0-9._-]+/g, '-');

package/dist/resources.js

@@ -21,7 +21,7 @@ export function resourceRequest(noun, verb, id, values) {
         else if (flag.to === 'local')
             continue;
         else if (flag.to === 'filter')
-            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = text(value);
+            query[`filter[${flag.filter.field}][${flag.filter.op}]`] = flag.filter.op === 'in' ? inList(value) : text(value);
         else
             query[key] = text(value);
     }
@@ -39,4 +39,7 @@ export function resourceRequest(noun, verb, id, values) {
         req.body = body;
     return req;
 }
+// An in list is joined by commas, or sent as a JSON array of strings when a value has a comma of its
+// own ("UK VAT, manual"), so the API keeps each value whole (contract 28.4).
+const inList = (v) => (Array.isArray(v) && v.some((x) => typeof x === 'string' && x.includes(',')) ? JSON.stringify(v.map(String)) : text(v));
 const text = (v) => (Array.isArray(v) ? v.join(',') : typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v));

package/dist/schema.js

@@ -1,6 +1,6 @@
 // The schema of a noun, as the contract's schema document has it (section 5.1), and what the
 // engine makes of it: for every verb, the flags it takes and where each one goes (body, query or
-// filter). A plain noun (markets, orders, carts, about 60 of them) has no code in the CLI: its
+// filter). A plain noun (markets, orders, payments, about 60 of them) has no code in the CLI: its
 // schema is read from GET /v1/schema/<noun>. Built-in nouns (sandbox, loops, report) write theirs
 // in the same document format, so one reader serves both.
 import { closest, fail, fixWith } from './errors.js';
@@ -53,6 +53,7 @@ export function parseSchema(raw, expected) {
             method,
             id: v.path ? /\{[^}]+\}/.test(v.path) : !['list', 'create'].includes(name),
             destructive,
+            confirm: destructive || v.confirm === true,
             // A policy never deletes nor returns money, whatever else the document says.
             loopable: Boolean(v.loopable) && !v.deletes && !v.returns_money && name !== 'delete',
             live: v.live !== false,
@@ -145,8 +146,9 @@ function flag(f, to, required) {
         to,
         ...(f.values ? { values: f.values } : {}),
         ...(f.items ? { items: f.items } : {}),
-        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, p.type])) } : {}),
+        ...(f.properties?.length ? { properties: Object.fromEntries(f.properties.map((p) => [p.name, { type: p.type, ...(p.values ? { values: p.values } : {}) }])) } : {}),
         ...(f.noun ? { noun: f.noun } : {}),
+        ...(f.nullable !== undefined ? { nullable: f.nullable } : {}),
         ...(required ? { required: true } : {}),
         ...(f.description ? { description: f.description } : {}),
     };
@@ -180,3 +182,7 @@ export function verbOf(schema, verb) {
     }
     return v;
 }
+/** A body flag that null clears: a field marked nullable, or a ref unless marked nullable: false. */
+export function clearable(f) {
+    return f.to === 'body' && (f.nullable === true || (f.type === 'ref' && f.nullable !== false));
+}

package/dist/schemas.js

@@ -2,28 +2,91 @@
 // one (contract section 5), cached on disk for a few minutes so a command costs one request, not
 // two. Schemas are the same at every state, so no token is sent. C11R_SCHEMA_CACHE=0 turns the
 // cache off.
+//
+// A deploy can change a schema inside those minutes. Every answer carries C11R-Schema, the hash of
+// the schemas served: an entry records the one it was loaded with, and an answer with another
+// drops the cache. The engine then runs the command once more on fresh schemas when the API
+// refused it (refusedBySchema). Without the header, a refusal that a stale schema explains
+// (confirmation_required, unknown_field, unknown_verb) does the same.
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { CliError, closest, fail, fixWith } from './errors.js';
-import { apiUrl, request } from './http.js';
+import { apiUrl, request, watchSchemaHeader } from './http.js';
 import { parseSchema } from './schema.js';
 import { VERSION } from './version.js';
 const TTL_MS = 10 * 60_000;
-function cacheFile(key) {
+function cacheDir() {
     if (process.env.C11R_SCHEMA_CACHE === '0')
         return null;
     const base = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
     const host = crypto.createHash('sha256').update(apiUrl()).digest('hex').slice(0, 12);
-    return path.join(base, 'c11r', `schema-${VERSION}-${host}`, `${key}.json`);
+    return path.join(base, 'c11r', `schema-${VERSION}-${host}`);
+}
+/** This process: the header last seen, the versions of the cache entries used, and whether to skip the cache. */
+const seen = { header: null, used: new Set(), fromCache: false, stale: false, fresh: false, written: null };
+/** The hash the cache on disk was written under, in its own file: any answer can check it, whatever the command read. */
+const HASH_FILE = '_hash';
+watchSchemaHeader((version) => {
+    seen.header = version;
+    // Schemas this command read from the cache, under another hash: the refusal may be theirs.
+    if (seen.fromCache && [...seen.used].some((v) => v !== version))
+        seen.stale = true;
+    // The cache on disk, under another hash (or none recorded): gone, whatever this command read.
+    const dir = cacheDir();
+    if (!dir || seen.written === version)
+        return;
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    const hash = names.includes(HASH_FILE) ? fs.readFileSync(path.join(dir, HASH_FILE), 'utf8').trim() : null;
+    if (hash !== version && names.some((n) => n.endsWith('.json')))
+        dropSchemaCache();
+});
+/** Every cached schema of this API, gone: the next command loads them again. */
+export function dropSchemaCache() {
+    const dir = cacheDir();
+    if (dir)
+        fs.rmSync(dir, { recursive: true, force: true });
+}
+/**
+ * Whether a refusal may come from a schema older than the API's: one was served from the cache,
+ * and the API's header says the schemas changed, or, with no header, the refusal is one a stale
+ * schema explains. The caller then refreshes (refreshSchemas) and runs the command once more.
+ */
+export function refusedBySchema(code) {
+    if (!seen.fromCache || seen.fresh)
+        return false;
+    if (seen.stale)
+        return true;
+    return seen.header === null && STALE_CODES.has(code);
+}
+const STALE_CODES = new Set(['confirmation_required', 'unknown_field', 'unknown_verb']);
+/** From now on, in this process, schemas come from the API, and the cache is rewritten. */
+export function refreshSchemas() {
+    dropSchemaCache();
+    seen.fresh = true;
+    seen.fromCache = false;
+    seen.used.clear();
 }
 async function cached(key, load) {
-    const file = cacheFile(key);
-    if (file) {
+    const dir = cacheDir();
+    const file = dir ? path.join(dir, `${key}.json`) : null;
+    if (file && !seen.fresh) {
         try {
-            if (Date.now() - fs.statSync(file).mtimeMs < TTL_MS)
-                return JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (Date.now() - fs.statSync(file).mtimeMs < TTL_MS) {
+                const entry = JSON.parse(fs.readFileSync(file, 'utf8'));
+                if (entry && typeof entry === 'object' && 'value' in entry) {
+                    seen.fromCache = true;
+                    seen.used.add(entry.version ?? null);
+                    return entry.value;
+                }
+            }
         }
         catch {
             // Not cached, or unreadable: load it.
@@ -33,7 +96,18 @@ async function cached(key, load) {
     if (file) {
         try {
             fs.mkdirSync(path.dirname(file), { recursive: true });
-            fs.writeFileSync(file, JSON.stringify(value));
+            // Written under another hash than the files there: those go first, so the cache is one hash.
+            if (seen.header && seen.written !== seen.header) {
+                const hashFile = path.join(path.dirname(file), HASH_FILE);
+                const hash = fs.existsSync(hashFile) ? fs.readFileSync(hashFile, 'utf8').trim() : null;
+                if (hash !== seen.header) {
+                    dropSchemaCache();
+                    fs.mkdirSync(path.dirname(file), { recursive: true });
+                    fs.writeFileSync(hashFile, seen.header);
+                }
+                seen.written = seen.header;
+            }
+            fs.writeFileSync(file, JSON.stringify({ version: seen.header, value }));
         }
         catch {
             // A read-only home is fine: no cache.

package/dist/secrets.js

@@ -14,6 +14,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { markOutWritten } from './config.js';
 import { fail } from './errors.js';
+/** Where the record's id goes in a file named after it, once the answer gives the id. */
+const ID_SLOT = '<id>';
 export function secretsDir() {
     const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
     return path.join(base, 'c11r', 'secrets');
@@ -23,10 +25,14 @@ const safe = (s) => s.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|
 export function planSecret(opts) {
     const out = opts.values.out;
     const format = opts.values.format ?? null;
-    const base = opts.verb === 'token' ? `${safe(opts.id ?? 'credential')}-token` : safe(String(opts.values.name ?? opts.id ?? 'credential'));
+    // By the name given, else the id given; a record with neither (a gift card) by the id it is
+    // given, so each has a file of its own: gift-card-<id>.env.
+    const named = opts.values.name ?? opts.id;
+    const byRecord = !out && opts.verb !== 'token' && (named === undefined || named === null || named === '');
+    const base = opts.verb === 'token' ? `${safe(opts.id ?? 'credential')}-token` : byRecord ? `${safe(opts.noun.replace(/s$/, ''))}-${ID_SLOT}` : safe(String(named));
     const file = out ? path.resolve(out) : path.join(secretsDir(), safe(opts.org ?? 'default'), base);
-    const plan = { file: out || !format ? file : `${file}.${format}`, format, fixed: Boolean(out), overwrite: opts.yes };
-    const candidates = plan.fixed || format ? [plan.file] : [`${file}.env`, `${file}.json`];
+    const plan = { file: out || !format ? file : `${file}.${format}`, format, fixed: Boolean(out), overwrite: opts.yes, byRecord };
+    const candidates = byRecord ? [] : plan.fixed || format ? [plan.file] : [`${file}.env`, `${file}.json`];
     for (const c of candidates) {
         let st = null;
         try {
@@ -43,7 +49,7 @@ export function planSecret(opts) {
             fail('conflict', `${c} exists. c11r replaces it only with --yes, or writes the secret elsewhere with --out.`, { path: 'out', next_step: { action: 'fix_request', command: null }, details: { file: c } }, 'rejected');
         }
     }
-    const dir = path.dirname(candidates[0]);
+    const dir = path.dirname(plan.file);
     const existing = nearestExisting(dir);
     try {
         fs.accessSync(existing, fs.constants.W_OK);
@@ -74,7 +80,7 @@ export function writeSecret(r, plan, ctx) {
     const credentialId = str(rec.id) ?? ctx.id;
     const record = { noun: ctx.noun, id: credentialId ?? null, name: str(rec.name), code: str(rec.code) };
     const format = plan.format ?? (secret.format === 'json' ? 'json' : 'env');
-    const file = plan.fixed || plan.format ? plan.file : `${plan.file}.${format}`;
+    const file = byRecordFile(plan.fixed || plan.format ? plan.file : `${plan.file}.${format}`, plan, credentialId);
     const env = secret.env && Object.keys(secret.env).length ? { ...secret.env } : { [`CL_${(secret.kind ?? 'secret').toUpperCase()}`]: String(secret.value ?? '') };
     // The endpoint goes with every secret, so the file is enough to call Commerce Layer.
     if (!env.CL_BASE_ENDPOINT && typeof data.base_endpoint === 'string')
@@ -97,9 +103,9 @@ export function writeSecret(r, plan, ctx) {
         const created = ctx.verb === 'create';
         fail('secret_not_written', `The API answered the ${secret.kind ?? 'secret'} of credential ${id} once, and c11r could not write it to ${file}: ${e.message}. It was not printed, and the API cannot show it again. ${created ? `c11r credentials token ${id} gives a working token now; for a new secret, create another credential and delete ${id}.` : `c11r credentials token ${id} gives another token.`}`, { path: 'out', next_step: { action: 'fix_request', command: `c11r credentials token ${id}` }, details: { credential_id: credentialId ?? null, file } });
     }
-    // An --out file is not removed with its credential: remember that one exists, for the warning.
+    // An --out file is not removed with its record: remember which record has one, for the warning.
     if (plan.fixed && ctx.org)
-        markOutWritten(ctx.org, true);
+        markOutWritten(ctx.org, { noun: ctx.noun, keys: [record.id, record.name, record.code, ctx.id].filter((k) => typeof k === 'string' && k !== '') });
     // The API says the secret is shown once: c11r kept it in the file, and printed none of it.
     const warnings = r.warnings.filter((w) => w.code !== 'secret_shown_once' && w.code !== 'token_shown_once');
     if (!ignoredByGit(file))
@@ -111,6 +117,18 @@ export function writeSecret(r, plan, ctx) {
         warnings,
     };
 }
+/** A file named after its record: the id in its slot, and a file there already left alone. */
+function byRecordFile(file, plan, id) {
+    if (!plan.byRecord)
+        return file;
+    // The id as the API gives it, case kept: ids are case-sensitive (lqgwUkXlBw).
+    const slot = (id ?? crypto.randomBytes(4).toString('hex')).replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+/, '') || crypto.randomBytes(4).toString('hex');
+    const named = file.replace(ID_SLOT, slot);
+    if (plan.overwrite || !fs.existsSync(named))
+        return named;
+    const ext = path.extname(named);
+    return `${named.slice(0, -ext.length || undefined)}-${crypto.randomBytes(3).toString('hex')}${ext}`;
+}
 /** What a dry run says about the file: where it would go and whether one is there. */
 export function describePlan(plan) {
     const files = plan.fixed || plan.format ? [plan.file] : [`${plan.file}.env`, `${plan.file}.json`];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commercelayer/agent-cli",
-  "version": "1.0.0-dev.1",
+  "version": "1.0.0-dev.10",
   "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": [