@binaryandthread/cli 0.1.3 → 0.1.5

package/dist/{chunk-IM3HF7NN.js → chunk-AAN4VWP3.js}

@@ -17,7 +17,7 @@ function makePrompts() {
   async function confirm(label) {
     const rl = readline.createInterface({ input, output });
     try {
-      const answer = (await rl.question(`\u26A0  ${label} `)).trim().toLowerCase();
+      const answer = (await rl.question(`   ${label} `)).trim().toLowerCase();
       return answer === "y" || answer === "yes";
     } finally {
       rl.close();
@@ -29,4 +29,4 @@ function makePrompts() {
 export {
   makePrompts
 };
-//# sourceMappingURL=chunk-IM3HF7NN.js.map
+//# sourceMappingURL=chunk-AAN4VWP3.js.map

package/dist/{chunk-IM3HF7NN.js.map → chunk-AAN4VWP3.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/prompts.ts"],"sourcesContent":["// Terminal prompts — the real readline-backed prompter for the interactive flows.\n//\n// Kept tiny + dependency-free (node:readline/promises). The command handlers take a prompts\n// object INJECTED (CheckoutPrompts), so this concrete implementation is only wired by bin.ts;\n// the flows are unit-tested with a fake prompter. NOTE: this prompter NEVER asks for a card —\n// the only PII it collects is an email + shipping address (cards live on the storefront page).\n\nimport * as readline from \"node:readline/promises\"\nimport { stdin as input, stdout as output } from \"node:process\"\n\nexport interface Prompts {\n  ask(label: string, opts?: { default?: string }): Promise<string>\n  confirm(label: string): Promise<boolean>\n}\n\n/** Build a readline-backed prompter. Each call opens + closes its own interface (simple, safe). */\nexport function makePrompts(): Prompts {\n  async function ask(label: string, opts?: { default?: string }): Promise<string> {\n    const rl = readline.createInterface({ input, output })\n    try {\n      const suffix = opts?.default ? ` [${opts.default}]` : \"\"\n      const answer = (await rl.question(`   ${label}${suffix}: `)).trim()\n      return answer || (opts?.default ?? \"\")\n    } finally {\n      rl.close()\n    }\n  }\n\n  async function confirm(label: string): Promise<boolean> {\n    const rl = readline.createInterface({ input, output })\n    try {\n      const answer = (await rl.question(`⚠  ${label} `)).trim().toLowerCase()\n      return answer === \"y\" || answer === \"yes\"\n    } finally {\n      rl.close()\n    }\n  }\n\n  return { ask, confirm }\n}\n"],"mappings":";;;AAOA,YAAY,cAAc;AAC1B,SAAS,SAAS,OAAO,UAAU,cAAc;AAQ1C,SAAS,cAAuB;AACrC,iBAAe,IAAI,OAAe,MAA8C;AAC9E,UAAM,KAAc,yBAAgB,EAAE,OAAO,OAAO,CAAC;AACrD,QAAI;AACF,YAAM,SAAS,MAAM,UAAU,KAAK,KAAK,OAAO,MAAM;AACtD,YAAM,UAAU,MAAM,GAAG,SAAS,MAAM,KAAK,GAAG,MAAM,IAAI,GAAG,KAAK;AAClE,aAAO,WAAW,MAAM,WAAW;AAAA,IACrC,UAAE;AACA,SAAG,MAAM;AAAA,IACX;AAAA,EACF;AAEA,iBAAe,QAAQ,OAAiC;AACtD,UAAM,KAAc,yBAAgB,EAAE,OAAO,OAAO,CAAC;AACrD,QAAI;AACF,YAAM,UAAU,MAAM,GAAG,SAAS,WAAM,KAAK,GAAG,GAAG,KAAK,EAAE,YAAY;AACtE,aAAO,WAAW,OAAO,WAAW;AAAA,IACtC,UAAE;AACA,SAAG,MAAM;AAAA,IACX;AAAA,EACF;AAEA,SAAO,EAAE,KAAK,QAAQ;AACxB;","names":[]}
+{"version":3,"sources":["../src/prompts.ts"],"sourcesContent":["// Terminal prompts — the real readline-backed prompter for the interactive flows.\n//\n// Kept tiny + dependency-free (node:readline/promises). The command handlers take a prompts\n// object INJECTED (CheckoutPrompts), so this concrete implementation is only wired by bin.ts;\n// the flows are unit-tested with a fake prompter. NOTE: this prompter NEVER asks for a card —\n// the only PII it collects is an email + shipping address (cards live on the storefront page).\n\nimport * as readline from \"node:readline/promises\"\nimport { stdin as input, stdout as output } from \"node:process\"\n\nexport interface Prompts {\n  ask(label: string, opts?: { default?: string }): Promise<string>\n  confirm(label: string): Promise<boolean>\n}\n\n/** Build a readline-backed prompter. Each call opens + closes its own interface (simple, safe). */\nexport function makePrompts(): Prompts {\n  async function ask(label: string, opts?: { default?: string }): Promise<string> {\n    const rl = readline.createInterface({ input, output })\n    try {\n      const suffix = opts?.default ? ` [${opts.default}]` : \"\"\n      const answer = (await rl.question(`   ${label}${suffix}: `)).trim()\n      return answer || (opts?.default ?? \"\")\n    } finally {\n      rl.close()\n    }\n  }\n\n  async function confirm(label: string): Promise<boolean> {\n    const rl = readline.createInterface({ input, output })\n    try {\n      // A neutral question marker — NOT ⚠. The confirms we ask (proceed to checkout, send a report)\n      // are benign: nothing is charged, nothing is destroyed. Reserve ⚠ for real warnings so the\n      // voice never cries wolf; a caller that truly needs a warning puts ⚠ in its own label.\n      const answer = (await rl.question(`   ${label} `)).trim().toLowerCase()\n      return answer === \"y\" || answer === \"yes\"\n    } finally {\n      rl.close()\n    }\n  }\n\n  return { ask, confirm }\n}\n"],"mappings":";;;AAOA,YAAY,cAAc;AAC1B,SAAS,SAAS,OAAO,UAAU,cAAc;AAQ1C,SAAS,cAAuB;AACrC,iBAAe,IAAI,OAAe,MAA8C;AAC9E,UAAM,KAAc,yBAAgB,EAAE,OAAO,OAAO,CAAC;AACrD,QAAI;AACF,YAAM,SAAS,MAAM,UAAU,KAAK,KAAK,OAAO,MAAM;AACtD,YAAM,UAAU,MAAM,GAAG,SAAS,MAAM,KAAK,GAAG,MAAM,IAAI,GAAG,KAAK;AAClE,aAAO,WAAW,MAAM,WAAW;AAAA,IACrC,UAAE;AACA,SAAG,MAAM;AAAA,IACX;AAAA,EACF;AAEA,iBAAe,QAAQ,OAAiC;AACtD,UAAM,KAAc,yBAAgB,EAAE,OAAO,OAAO,CAAC;AACrD,QAAI;AAIF,YAAM,UAAU,MAAM,GAAG,SAAS,MAAM,KAAK,GAAG,GAAG,KAAK,EAAE,YAAY;AACtE,aAAO,WAAW,OAAO,WAAW;AAAA,IACtC,UAAE;AACA,SAAG,MAAM;AAAA,IACX;AAAA,EACF;AAEA,SAAO,EAAE,KAAK,QAAQ;AACxB;","names":[]}

package/dist/{chunk-7FH7BZ3I.js → chunk-VRNJLVHX.js}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// ../../../../../../teetime-backend/packages/store-client/dist/index.js
+// ../store-client/dist/index.js
 var SENSITIVE_KEYS = /* @__PURE__ */ new Set([
   "authorization",
   "token",
@@ -44,15 +44,21 @@ function redact(input, _seen) {
   if (typeof input !== "object") {
     return input;
   }
-  const seen = _seen ?? /* @__PURE__ */ new WeakSet();
-  if (seen.has(input)) {
-    return input;
+  const seen = _seen ?? /* @__PURE__ */ new Map();
+  const existing = seen.get(input);
+  if (existing !== void 0) {
+    return existing;
   }
-  seen.add(input);
   if (Array.isArray(input)) {
-    return input.map((v) => redact(v, seen));
+    const out2 = [];
+    seen.set(input, out2);
+    for (const v of input) {
+      out2.push(redact(v, seen));
+    }
+    return out2;
   }
   const out = {};
+  seen.set(input, out);
   for (const [key, value] of Object.entries(input)) {
     if (SENSITIVE_KEYS.has(key.toLowerCase())) {
       out[key] = MASK;
@@ -70,6 +76,7 @@ var DEFAULT_RETRY = {
   maxDelayMs: 2e3
 };
 var RETRY_AFTER_MAX_MS = 1e4;
+var DEFAULT_TIMEOUT_MS = 15e3;
 function parseRetryAfterMs(res) {
   let raw = null;
   try {
@@ -134,6 +141,7 @@ var StoreClient = class {
   logger;
   retry;
   sleepImpl;
+  timeoutMs;
   /** Cached resolved regions (read-only catalog optimisation). */
   regionsCache = null;
   constructor(opts) {
@@ -153,6 +161,7 @@ var StoreClient = class {
     this.logger = opts.logger ?? console;
     this.retry = { ...DEFAULT_RETRY, ...opts.retry ?? {} };
     this.sleepImpl = opts.sleepImpl ?? sleep;
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   }
   // ----- the request engine --------------------------------------------------
   buildUrl(path, query) {
@@ -195,8 +204,10 @@ var StoreClient = class {
     let lastErr;
     for (let attempt = 0; attempt < this.retry.attempts; attempt++) {
       let retryAfterMs = null;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
       try {
-        const res = await this.fetchImpl(url, init);
+        const res = await this.fetchImpl(url, { ...init, signal: controller.signal });
         if (res.ok) {
           const text = await res.text();
           return text ? JSON.parse(text) : {};
@@ -244,6 +255,8 @@ var StoreClient = class {
         }
         lastErr = e;
         this.logWarn("store.request.network_retry", { path, attempt: attempt + 1 });
+      } finally {
+        clearTimeout(timer);
       }
       if (attempt < this.retry.attempts - 1) {
         await this.sleepImpl(retryAfterMs ?? this.backoffMs(attempt));
@@ -294,10 +307,20 @@ var StoreClient = class {
   // ----- products (region resolved BEFORE pricing) ---------------------------
   async listProducts(opts) {
     const region = opts?.region ?? await this.resolveRegion(opts?.countryCode);
-    const data = await this.request("GET", "/store/products", {
-      query: { region_id: region.id, limit: 100 }
-    });
-    return data.products ?? [];
+    const PAGE = 100;
+    const HARD_CAP = 1e3;
+    const all = [];
+    for (let offset = 0; offset < HARD_CAP; offset += PAGE) {
+      const data = await this.request("GET", "/store/products", {
+        query: { region_id: region.id, limit: PAGE, offset }
+      });
+      const page = data.products ?? [];
+      all.push(...page);
+      if (page.length < PAGE) {
+        break;
+      }
+    }
+    return all;
   }
   async getProduct(handle, opts) {
     const region = opts?.region ?? await this.resolveRegion(opts?.countryCode);
@@ -388,7 +411,9 @@ var StoreClient = class {
     return res.cart;
   }
   // ----- headless contract (04.5-01) -----------------------------------------
-  async mintCheckout(cartId, email, channel = "cli") {
+  // `channel` is REQUIRED (L11): a default silently mis-attributes analytics for a future caller that
+  // forgets it. Both current callers (cli, mcp) pass it explicitly.
+  async mintCheckout(cartId, email, channel) {
     return this.request("POST", "/store/headless/checkout", {
       idempotent: true,
       body: { cart_id: cartId, email, channel }
@@ -461,13 +486,15 @@ var StoreClient = class {
     }
   }
   /**
-   * Guest order lookup — requires order display id + EXACT email (F-H1).
-   * The backend returns 404 on a mismatch (no enumeration); the client surfaces null.
+   * Guest order lookup (AUD-8) — POST /store/order-lookup with the order id (display id OR internal
+   * id) + the EXACT email in the BODY (never the query string, so the email is not access-logged).
+   * The backend returns 404 on any mismatch (no enumeration) → the client surfaces null. Rate-limited
+   * server-side; returns minimal status only, never PII (F-H1 / F-H3).
    */
-  async getOrder(displayId, email) {
+  async getOrder(idOrDisplayId, email) {
     try {
-      return await this.request("GET", "/store/orders", {
-        query: { display_id: String(displayId), email }
+      return await this.request("POST", "/store/order-lookup", {
+        body: { id: String(idOrDisplayId), email }
       });
     } catch (e) {
       if (e instanceof StoreApiError && e.status === 404) {
@@ -567,7 +594,7 @@ function findVariant(p, opts = {}) {
     return variants.find((v) => colourMatches(v));
   }
   if (size && !colour) {
-    return variants.find((v) => sizeMatches(v)) ?? variants[0];
+    return variants.find((v) => sizeMatches(v));
   }
   return variants[0];
 }
@@ -604,6 +631,29 @@ function firstImageUrl(images) {
 function escapeRegex(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+function str(v, fallback) {
+  return typeof v === "string" && v.length > 0 ? v : fallback;
+}
+function productSpecs(p) {
+  const md = p.metadata ?? {};
+  return [
+    { key: "material", value: str(md.material, "100% cotton") },
+    { key: "weight", value: str(md.weight, "180 g/m\xB2") },
+    { key: "fit", value: str(md.fit, "Unisex heavyweight crewneck") },
+    { key: "print", value: str(md.print, "Front print") },
+    { key: "delivery", value: str(md.delivery, "Ships in 2\u20135 business days + transit") },
+    { key: "care", value: str(md.care, "Cold wash, line dry") }
+  ];
+}
+function productLore(p) {
+  const md = p.metadata ?? {};
+  const text = typeof md.lore === "string" ? md.lore : "";
+  const raw = Array.isArray(md.lore_sources) ? md.lore_sources : [];
+  const sources = raw.filter(
+    (s) => !!s && typeof s === "object" && typeof s.url === "string" && typeof s.label === "string"
+  ).map((s) => ({ url: s.url, label: s.label }));
+  return { text, sources };
+}
 
 // src/voice.ts
 var GLYPH = {
@@ -646,15 +696,67 @@ var CODENAMES = [
   "tabs-over-spaces",
   "vim-not-emacs",
   "2-space-indent",
-  "trailing-comma"
+  "trailing-comma",
+  "rebase-not-merge",
+  "lf-not-crlf",
+  "semicolons-optional",
+  "dark-mode-only"
 ];
-function codename(_version) {
-  return CODENAMES[0];
+function codename(version) {
+  const minor = Number.parseInt(version.split(".")[1] ?? "", 10);
+  const idx = Number.isFinite(minor) ? Math.abs(minor) % CODENAMES.length : 0;
+  return CODENAMES[idx];
 }
 function versionLine(version) {
   return `bt ${version} "${codename(version)}"`;
 }
 
+// src/errors.ts
+var EXIT = {
+  OK: 0,
+  GENERIC: 1,
+  DATAERR: 65,
+  // EX_DATAERR — bad request / unprocessable / stale cart (400/409/422)
+  UNAVAILABLE: 69,
+  // EX_UNAVAILABLE — not found (404)
+  TEMPFAIL: 75,
+  // EX_TEMPFAIL — temporary: 5xx, network/exhausted, rate-limited (429)
+  NOPERM: 77
+  // EX_NOPERM — auth required / forbidden (401/403)
+};
+function messageOf(e) {
+  if (e instanceof Error && e.message) {
+    return e.message;
+  }
+  const s = String(e ?? "").trim();
+  return s || "unexpected error";
+}
+function classifyError(e) {
+  const message = String(redact(messageOf(e)));
+  if (e instanceof RecoverableCartError) {
+    return { code: EXIT.DATAERR, type: "stale_cart", status: e.status, message };
+  }
+  if (e instanceof StoreApiError) {
+    const s = e.status;
+    if (s === 401 || s === 403) return { code: EXIT.NOPERM, type: "auth", status: s, message };
+    if (s === 404) return { code: EXIT.UNAVAILABLE, type: "not_found", status: s, message };
+    if (s === 429) return { code: EXIT.TEMPFAIL, type: "rate_limited", status: s, message };
+    if (s === 0 || s === 408 || s >= 500) return { code: EXIT.TEMPFAIL, type: "upstream", status: s, message };
+    if (s >= 400) return { code: EXIT.DATAERR, type: "client_error", status: s, message };
+  }
+  return { code: EXIT.GENERIC, type: "error", message };
+}
+function formatFatal(e, json) {
+  const info = classifyError(e);
+  if (json) {
+    const envelope = { error: { code: info.code, type: info.type, message: info.message } };
+    return { out: JSON.stringify(envelope, null, 2), err: null, code: info.code };
+  }
+  const reassurance = "nothing was lost. if a checkout was in flight, your order is safe. file it \u2192 bt report";
+  return { out: null, err: `\u2717  ${info.message}
+   ${reassurance}`, code: info.code };
+}
+
 // src/brand.ts
 var ANSI = {
   reset: "\x1B[0m",
@@ -828,6 +930,53 @@ function resolveLineItemRef(items, ref) {
   );
   return byTitle ?? null;
 }
+function isSubsequence(needle, hay) {
+  let i = 0;
+  for (let j = 0; j < hay.length && i < needle.length; j++) {
+    if (hay[j] === needle[i]) i++;
+  }
+  return i === needle.length;
+}
+function resolveProductSelector(products, selector) {
+  const needle = (selector ?? "").trim();
+  if (!needle || products.length === 0) {
+    return { candidates: [], fuzzy: false };
+  }
+  if (/^\d+$/.test(needle)) {
+    const idx = Number(needle) - 1;
+    if (idx >= 0 && idx < products.length) {
+      return { match: products[idx], candidates: [], fuzzy: true };
+    }
+    return { candidates: [], fuzzy: true };
+  }
+  const lower = needle.toLowerCase();
+  const exact = products.find((p) => (p.handle ?? "").toLowerCase() === lower || p.id === needle);
+  if (exact) {
+    return { match: exact, candidates: [], fuzzy: false };
+  }
+  const hits = products.filter(
+    (p) => isSubsequence(lower, (p.handle ?? "").toLowerCase()) || isSubsequence(lower, (p.title ?? "").toLowerCase())
+  );
+  if (hits.length === 1) {
+    return { match: hits[0], candidates: [], fuzzy: true };
+  }
+  return { candidates: hits, fuzzy: true };
+}
+async function resolveProduct(client, region, selector) {
+  const needle = (selector ?? "").trim();
+  if (needle && !/^\d+$/.test(needle)) {
+    const exact = await client.getProduct(needle, { region });
+    if (exact) {
+      return { product: exact };
+    }
+  }
+  const products = await client.listProducts({ region });
+  const r = resolveProductSelector(products, needle);
+  if (r.match) {
+    return { product: r.match, fuzzy: r.fuzzy };
+  }
+  return { candidates: r.candidates, fuzzy: r.fuzzy };
+}
 function resolveOutput(program) {
   const opts = program.opts();
   const json = Boolean(opts.json);
@@ -835,6 +984,9 @@ function resolveOutput(program) {
   return { json, brand };
 }
 function printResult(res, json) {
+  if (res.exitCode) {
+    process.exitCode = res.exitCode;
+  }
   if (json && res.json !== void 0) {
     process.stdout.write(JSON.stringify(res.json, null, 2) + "\n");
     return;
@@ -912,29 +1064,45 @@ async function defaultRender(url, opts) {
 async function runView(client, config, args) {
   const style = brandOf(args);
   const region = await client.resolveRegion(config.region);
-  const product = await client.getProduct(args.handle, { region });
+  const picked = await resolveProduct(client, region, args.handle);
+  const product = picked.product;
   if (!product) {
+    if (picked.candidates && picked.candidates.length > 1) {
+      return {
+        lines: [
+          fail({ code: EXIT.DATAERR, what: `"${args.handle}" matches ${picked.candidates.length} designs \u2014 pick one:` }),
+          ...picked.candidates.map((p) => `     ${p.handle ?? p.id}`),
+          "   or be exact \u2192 bt view <slug>"
+        ],
+        exitCode: EXIT.DATAERR
+      };
+    }
     return {
       lines: [
         fail({
-          code: 1,
-          what: `variant ${args.handle} not found.`,
+          code: EXIT.UNAVAILABLE,
+          what: `no design here called "${args.handle}".`,
           fix: "bt browse   (to see what's in stock)"
         })
-      ]
+      ],
+      exitCode: EXIT.UNAVAILABLE
     };
   }
   const { title, handle } = displayName(product);
   const colours = productColours(product);
   const lines = [];
+  if (picked.fuzzy && handle !== args.handle.trim()) {
+    lines.push(working(`matched "${handle}" from "${args.handle}"`));
+  }
   lines.push(header(style, title));
   lines.push(`   ${dim(style, handle)}`);
   if (product.description) {
     lines.push(empty(`   ${product.description}`));
   }
   const fabric = product.metadata?.["fabric"] ?? null;
-  if (fabric) {
-    lines.push(`   fabric   ${fabric}`);
+  const specs = productSpecs(product);
+  for (const s of specs) {
+    lines.push(`   ${s.key.padEnd(9)}${s.value}`);
   }
   if (colours.length > 0) {
     lines.push(`   colours  ${colours.map((c) => `${colourSwatch(c)} ${c}`).join(" \xB7 ")}`);
@@ -981,6 +1149,7 @@ async function runView(client, config, args) {
       handle: product.handle,
       title: product.title,
       fabric,
+      specs,
       colours,
       thumbnail: product.thumbnail,
       variants: (product.variants ?? []).map((v) => ({
@@ -993,7 +1162,7 @@ async function runView(client, config, args) {
   };
 }
 function registerView(program, makeClient, loadConfig) {
-  program.command("view").alias("show").argument("<handle>", "the product handle/slug").option("--colour <colour>", "render a specific colour's mockup (e.g. black)").description("render a design: specs + image (always with the link as the floor).").action(async (handle, opts) => {
+  program.command("view").alias("show").argument("<handle>", "the design: a slug, a bt browse number (3), or a fuzzy hint (termnl)").option("--colour <colour>", "render a specific colour's mockup (e.g. black)").description("render a design: specs + image (always with the link as the floor).").action(async (handle, opts) => {
     const { json, brand } = resolveOutput(program);
     const noColor = program.opts().color === false;
     const res = await runView(makeClient(), loadConfig(), {
@@ -1011,14 +1180,29 @@ function registerView(program, makeClient, loadConfig) {
 async function runStage(client, config, args) {
   const style = brandOf(args);
   const region = await client.resolveRegion(config.region);
-  const product = await client.getProduct(args.handle, { region });
-  if (!product) {
+  const resolved = await resolveProduct(client, region, args.handle);
+  if (!resolved.product) {
+    if (resolved.candidates && resolved.candidates.length > 1) {
+      return {
+        lines: [
+          fail({ code: EXIT.DATAERR, what: `"${args.handle}" matches ${resolved.candidates.length} designs \u2014 pick one:` }),
+          ...resolved.candidates.map((p) => `     ${p.handle ?? p.id}`),
+          "   or be exact \u2192 bt stage <slug>"
+        ],
+        exitCode: EXIT.DATAERR
+        // ambiguous input → non-zero so `bt stage x && bt checkout` halts (d10)
+      };
+    }
     return {
       lines: [
-        fail({ code: 1, what: `variant ${args.handle} not found.`, fix: "bt browse" })
-      ]
+        fail({ code: EXIT.UNAVAILABLE, what: `no design here called "${args.handle}".`, fix: "bt browse" })
+      ],
+      exitCode: EXIT.UNAVAILABLE
+      // not-found → non-zero (d10)
     };
   }
+  const product = resolved.product;
+  const matchNote = resolved.fuzzy && (product.handle ?? "") !== args.handle.trim() ? working(`matched "${product.handle}" from "${args.handle}"`) : null;
   const size = args.size ?? config.defaultSize;
   const colours = productColours(product);
   const colour = args.colour ?? config.defaultColour ?? (colours.length > 0 ? colours[0] : void 0);
@@ -1028,17 +1212,20 @@ async function runStage(client, config, args) {
     return {
       lines: [
         fail({
-          code: 1,
+          code: EXIT.DATAERR,
           what: `no variant for ${args.handle}${size ? `#size=${size}` : ""}${colour ? ` (${colour})` : ""}.`,
           fix: `bt view ${args.handle}   (to see available sizes + colours)${have}`
         })
-      ]
+      ],
+      exitCode: EXIT.DATAERR
+      // unprocessable size+colour combo → non-zero (d10)
     };
   }
   if (args.dryRun) {
     const colourSuffix2 = colour ? ` (${colour})` : "";
     return {
       lines: [
+        ...matchNote ? [matchNote] : [],
         ok(`dry-run \u2014 would stage ${product.handle ?? args.handle}${size ? `#${size}` : ""}${colourSuffix2} (nothing staged).`),
         "   run without --dry-run to acquire the inventory lock."
       ],
@@ -1054,6 +1241,9 @@ async function runStage(client, config, args) {
     };
   }
   const lines = [];
+  if (matchNote) {
+    lines.push(matchNote);
+  }
   let cartId = config.cart_id;
   let recovered = false;
   if (!cartId) {
@@ -1099,7 +1289,7 @@ async function runStage(client, config, args) {
   };
 }
 function registerStage(program, makeClient, loadConfig) {
-  program.command("stage").alias("add").argument("<handle>", "the product handle/slug").option("--size <size>", "garment size (default: your last commit's size)").option("--colour <colour>", "colour, e.g. white / black (default: the product's first colour)").option("--dry-run", "resolve the variant + show what would be staged, without staging").description("reserve stock \u2014 acquires an inventory lock, reserves nothing permanent.").action(async (handle, opts) => {
+  program.command("stage").alias("add").argument("<handle>", "the design: a slug (terminal-velocity), a bt browse number (3), or a fuzzy hint (termnl)").option("--size <size>", "garment size (default: your last commit's size)").option("--colour <colour>", "colour, e.g. white / black (default: the product's first colour)").option("--dry-run", "resolve the variant + show what would be staged, without staging").description("reserve stock \u2014 acquires an inventory lock, reserves nothing permanent.").action(async (handle, opts) => {
     const { json, brand } = resolveOutput(program);
     const res = await runStage(makeClient(), loadConfig(), {
       handle,
@@ -1127,6 +1317,7 @@ export {
   productColours,
   sizesForColour,
   findVariant,
+  productLore,
   GLYPH,
   ok,
   warn,
@@ -1134,6 +1325,8 @@ export {
   empty,
   fail,
   versionLine,
+  EXIT,
+  formatFatal,
   cyan,
   dim,
   green,
@@ -1151,6 +1344,7 @@ export {
   lineColour,
   formatCartLine,
   resolveLineItemRef,
+  resolveProduct,
   resolveOutput,
   printResult,
   runView,
@@ -1158,4 +1352,4 @@ export {
   runStage,
   registerStage
 };
-//# sourceMappingURL=chunk-7FH7BZ3I.js.map
+//# sourceMappingURL=chunk-VRNJLVHX.js.map