@lovinka/vitrinka 1.1.0

package/dist/cli.js

@@ -0,0 +1,2543 @@
+#!/usr/bin/env node
+// cli.ts — the unified vitrinka CLI. Maintains `.screenshots/manifest.json` + a self-contained,
+// clickable `index.html` gallery, publishes sets to vitrinka (the internal artifacts app), and
+// one-shots capture (`snap`) + artifact scaffolding (`artifact-init`, `artifact-from-set`).
+//
+// Zero dependencies (node: builtins only). Erasable TypeScript only — Node 24 type-stripping
+// and bun both run it directly: `node cli.ts <cmd>`.
+//
+// add / build / meta / remote-init / push are ported verbatim in behavior from
+// skills/screenshot/gallery.mjs (offline marker, COPYFILE_DISABLE, control-file excludes,
+// `--key`, repeatable `--chip`). gallery.mjs is now a passthrough shim to this file.
+// Design: vitrinka/docs/plans/2026-07-03-hand-in-hand-tooling-design.md
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync, copyFileSync, mkdtempSync, chmodSync, appendFileSync, statSync, } from 'node:fs';
+import { join, resolve, basename, dirname, extname, relative, sep } from 'node:path';
+import { tmpdir, hostname } from 'node:os';
+import { spawnSync, spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createInterface } from 'node:readline';
+import { readToken } from "./lib/token.js";
+import { operatorPath, readOperator, actorHeaderValue } from "./lib/operator.js";
+import { resolveBaseUrl } from "./lib/base-url.js";
+const CLI_PATH = fileURLToPath(import.meta.url);
+export function parseArgs(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (!a.startsWith('--'))
+            continue;
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        const val = next === undefined || next.startsWith('--') ? true : argv[++i];
+        const cur = out[key];
+        if (cur === undefined)
+            out[key] = val; // repeated flags (e.g. --chip) accumulate
+        else if (Array.isArray(cur))
+            cur.push(val);
+        else
+            out[key] = [cur, val];
+    }
+    return out;
+}
+// Last-wins string extraction for the new commands (ported commands keep their original
+// inline `args.x && args.x !== true` expressions so behavior stays verbatim).
+function strArg(v) {
+    if (v === undefined || v === true)
+        return '';
+    if (Array.isArray(v)) {
+        const last = v[v.length - 1];
+        return last === true ? '' : String(last);
+    }
+    return String(v);
+}
+function numArg(v, dflt, flag) {
+    const s = strArg(v);
+    if (!s)
+        return dflt;
+    const n = Number(s);
+    if (!Number.isFinite(n) || n <= 0) {
+        console.error(`${flag}: expected a positive number, got ${JSON.stringify(s)}`);
+        process.exit(2);
+    }
+    return n;
+}
+function fail(msg, code = 1) {
+    console.error(msg);
+    process.exit(code);
+}
+// positionals extracts the non-flag arguments, honoring parseArgs's
+// flag-value consumption (a non-"--" token right after a flag is its value).
+export function positionals(argv) {
+    const out = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--'))
+                i++;
+            continue;
+        }
+        out.push(a);
+    }
+    return out;
+}
+function manifestPathOf(root) { return join(root, 'manifest.json'); }
+function htmlPathOf(root) { return join(root, 'index.html'); }
+function loadManifest(root) {
+    const manifestPath = manifestPathOf(root);
+    if (!existsSync(manifestPath))
+        return { version: 1, shots: [] };
+    const raw = readFileSync(manifestPath, 'utf8'); // ENOENT handled above; other read errors surface loudly
+    let m;
+    try {
+        m = JSON.parse(raw);
+    }
+    catch (e) {
+        // Corrupt existing manifest is unexpected — never silently overwrite (would lose history).
+        throw new Error(`Corrupt manifest ${manifestPath} (${e.message}). Fix or delete it manually; refusing to overwrite.`);
+    }
+    if (!m || !Array.isArray(m.shots)) {
+        throw new Error(`Malformed manifest ${manifestPath}: missing shots[]. Fix or delete it manually.`);
+    }
+    return m;
+}
+function saveManifest(root, m) {
+    mkdirSync(root, { recursive: true });
+    ensureRootSelfIgnored(root);
+    writeFileSync(manifestPathOf(root), JSON.stringify(m, null, 2) + '\n');
+}
+function buildIndex(root) {
+    const m = loadManifest(root);
+    const project = basename(dirname(root)) || 'project';
+    const htmlPath = htmlPathOf(root);
+    writeFileSync(htmlPath, renderHtml(m.shots, project));
+    return { count: m.shots.length, htmlPath };
+}
+// shotContext builds the v2 capture-context fields from CLI flags:
+// --src (repeatable or comma-separated), --state, --device <name>,
+// --viewport WxH[@scale]. Empty object stays off the manifest entirely.
+export function shotContext(args) {
+    const out = {};
+    const rawSrc = args.src === undefined ? [] : Array.isArray(args.src) ? args.src : [args.src];
+    const src = rawSrc.filter((v) => typeof v === 'string')
+        .flatMap((v) => v.split(',')).map((v) => v.trim()).filter(Boolean);
+    if (src.length)
+        out.src = src;
+    const state = strArg(args.state);
+    if (state)
+        out.state = state;
+    const deviceName = strArg(args.device);
+    const vp = strArg(args.viewport);
+    if (deviceName || vp) {
+        const device = {};
+        if (deviceName)
+            device.device = deviceName;
+        const m = vp ? /^(\d+)x(\d+)(?:@(\d+(?:\.\d+)?))?$/.exec(vp) : null;
+        if (vp && !m)
+            fail(`invalid --viewport ${JSON.stringify(vp)} — expected WxH or WxH@scale (e.g. 393x852@3)`, 2);
+        if (m) {
+            device.w = Number(m[1]);
+            device.h = Number(m[2]);
+            if (m[3])
+                device.scale = Number(m[3]);
+        }
+        out.device = device;
+    }
+    return out;
+}
+function appendShot(root, shot) {
+    const m = loadManifest(root);
+    m.shots.push(shot);
+    // v2: stamp the session's code identity (last append wins — the freshest
+    // commit is the one the newest pixels came from).
+    m.version = Math.max(m.version || 1, 2);
+    const projectDir = dirname(root);
+    const commit = git(['rev-parse', '--short', 'HEAD'], projectDir);
+    const branch = git(['branch', '--show-current'], projectDir);
+    if (commit)
+        m.commit = commit;
+    if (branch)
+        m.branch = branch;
+    saveManifest(root, m);
+    const project = basename(dirname(root)) || 'project';
+    const htmlPath = htmlPathOf(root);
+    writeFileSync(htmlPath, renderHtml(m.shots, project));
+    return { count: m.shots.length, htmlPath };
+}
+function addCmd(root, args) {
+    const file = args.file;
+    if (!file || file === true) {
+        console.error('cli.ts add: --file <rel-path> is required');
+        process.exit(2);
+    }
+    const shot = {
+        file: String(file),
+        surface: args.surface && args.surface !== true ? String(args.surface) : 'other',
+        route: args.route && args.route !== true ? String(args.route) : '',
+        note: args.note && args.note !== true ? String(args.note) : '',
+        // journey fields (vitrinka editorial viewer): stage label + short human title
+        label: args.label && args.label !== true ? String(args.label) : undefined,
+        title: args.title && args.title !== true ? String(args.title) : undefined,
+        action: args.action && args.action !== true ? String(args.action) : undefined,
+        ts: new Date().toISOString(),
+        ...shotContext(args),
+    };
+    const { count, htmlPath } = appendShot(root, shot);
+    console.log(`+ ${file}  (${count} shots) → ${htmlPath}`);
+}
+export function esc(s) {
+    return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function renderHtml(shots, project) {
+    // Data is inlined and rendered client-side via textContent/setAttribute → XSS-safe by construction.
+    // Escape </script> so the JSON payload can't break out of the <script> tag.
+    const data = JSON.stringify(shots).replace(/</g, '\\u003c');
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Screenshots — ${esc(project)}</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+         background: #0d1117; color: #e6edf3; }
+  header { position: sticky; top: 0; z-index: 5; display: flex; align-items: baseline; gap: 12px;
+           padding: 14px 22px; background: #161b22ee; backdrop-filter: blur(8px);
+           border-bottom: 1px solid #30363d; }
+  header h1 { font-size: 15px; margin: 0; font-weight: 600; }
+  header .sub { color: #8b949e; font-size: 12px; }
+  main { max-width: 1080px; margin: 0 auto; padding: 8px 22px 80px; }
+  .day { margin-top: 28px; }
+  .day-h { display: flex; align-items: baseline; gap: 10px; position: sticky; top: 49px;
+           background: #0d1117; padding: 8px 0; border-bottom: 1px solid #21262d; z-index: 2; }
+  .day-h .date { font-size: 13px; font-weight: 600; color: #58a6ff; }
+  .day-h .count { font-size: 11px; color: #8b949e; }
+  .card { display: flex; gap: 18px; padding: 18px 0; border-bottom: 1px solid #21262d; }
+  .card a.shot { flex: 0 0 auto; }
+  .card img { display: block; width: 360px; max-width: 42vw; height: auto; border-radius: 8px;
+              border: 1px solid #30363d; background: #010409; }
+  .meta { min-width: 0; display: flex; flex-direction: column; gap: 8px; padding-top: 2px; }
+  .row { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+  .badge { font-size: 10px; letter-spacing: .04em; text-transform: uppercase; font-weight: 700;
+           padding: 2px 7px; border-radius: 999px; color: #0d1117; background: #8b949e; }
+  .badge.ios { background: #58a6ff; } .badge.android { background: #3fb950; }
+  .badge.web { background: #d29922; } .badge.macos { background: #bc8cff; }
+  .route { font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace; color: #e6edf3;
+           background: #161b22; border: 1px solid #30363d; border-radius: 6px; padding: 2px 7px; }
+  .note { margin: 0; color: #c9d1d9; }
+  .foot { display: flex; gap: 12px; align-items: center; margin-top: auto; color: #6e7681; font-size: 11px; }
+  .foot .file { font-family: ui-monospace, monospace; }
+  .empty { color: #8b949e; padding: 40px 0; text-align: center; }
+  @media (max-width: 620px) { .card { flex-direction: column; } .card img { width: 100%; max-width: 100%; } }
+</style>
+</head>
+<body>
+<header><h1>📸 ${esc(project)}</h1><span class="sub" id="sub"></span></header>
+<main id="app"></main>
+<script>
+const SHOTS = ${data};
+const app = document.getElementById('app');
+const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
+SHOTS.sort((a, b) => String(a.ts || '').localeCompare(String(b.ts || '')));
+document.getElementById('sub').textContent = SHOTS.length + (SHOTS.length === 1 ? ' shot' : ' shots');
+const dayOf = (s) => {
+  const seg = String(s.file || '').split('/')[0];
+  if (/^\\d{4}-\\d{2}-\\d{2}$/.test(seg)) return seg;
+  return String(s.ts || '').slice(0, 10) || 'undated';
+};
+const groups = {};
+for (const s of SHOTS) (groups[dayOf(s)] ||= []).push(s);
+const days = Object.keys(groups).sort();
+if (!SHOTS.length) app.appendChild(el('p', 'empty', 'No screenshots captured yet.'));
+for (const day of days) {
+  const sec = el('section', 'day');
+  const h = el('div', 'day-h');
+  h.appendChild(el('span', 'date', day));
+  h.appendChild(el('span', 'count', groups[day].length + (groups[day].length === 1 ? ' shot' : ' shots')));
+  sec.appendChild(h);
+  for (const s of groups[day]) {
+    const card = el('div', 'card');
+    const a = el('a', 'shot'); a.href = s.file; a.target = '_blank'; a.rel = 'noopener';
+    const img = el('img'); img.src = s.file; img.loading = 'lazy'; img.alt = s.route || s.file;
+    a.appendChild(img); card.appendChild(a);
+    const meta = el('div', 'meta');
+    const row = el('div', 'row');
+    row.appendChild(el('span', 'badge ' + (s.surface || 'other'), s.surface || 'other'));
+    if (s.route) row.appendChild(el('code', 'route', s.route));
+    meta.appendChild(row);
+    if (s.note) meta.appendChild(el('p', 'note', s.note));
+    const foot = el('div', 'foot');
+    foot.appendChild(el('span', 'file', s.file));
+    if (s.ts) { const t = new Date(s.ts); if (!isNaN(t)) foot.appendChild(el('time', 'ts', t.toLocaleString())); }
+    meta.appendChild(foot);
+    card.appendChild(meta);
+    sec.appendChild(card);
+  }
+  app.appendChild(sec);
+}
+</script>
+</body>
+</html>
+`;
+}
+// Set/update the manifest's journey header (vitrinka editorial viewer): kicker,
+// display title (+ red accent substring), intro paragraph, and meta chips.
+function metaCmd(root, args) {
+    const m = loadManifest(root);
+    m.version = 2;
+    const j = m.journey && typeof m.journey === 'object' ? m.journey : {};
+    for (const k of ['kicker', 'title', 'accent', 'intro']) {
+        const v = args[k];
+        if (v && v !== true)
+            j[k] = String(Array.isArray(v) ? v[v.length - 1] : v);
+    }
+    if (args.chip) {
+        const chips = (Array.isArray(args.chip) ? args.chip : [args.chip]).filter((c) => c !== true);
+        j.chips = chips.map((c) => {
+            const idx = String(c).indexOf('=');
+            if (idx < 1) {
+                console.error(`meta: --chip expects "Key=Value", got ${JSON.stringify(String(c))}`);
+                process.exit(2);
+            }
+            return { k: String(c).slice(0, idx).trim(), v: String(c).slice(idx + 1).trim() };
+        });
+    }
+    m.journey = j;
+    saveManifest(root, m);
+    buildIndex(root);
+    console.log(`journey meta set (${Object.keys(j).join(', ')}) → ${manifestPathOf(root)}`);
+}
+function vitrinkaCfgPath(root) { return join(root, '.vitrinka'); }
+function offlineMarkerPath(root) { return join(root, '.vitrinka-offline'); }
+// Mirrors vitrinka's server-side slug rules (contract: [a-z0-9._-], collapse '-', trim).
+export function sanitizeSeg(s, max) {
+    const out = String(s).toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/-+/g, '-').replace(/^[-.]+|[-.]+$/g, '');
+    return out.slice(0, max) || 'x';
+}
+// Mirrors the server's validKey (internal/web/validate.go): within GET
+// /{project}/{branch}/{selector} a key shares the path slot with versions, "latest" and
+// "{version}.zip", so the server rejects such keys at PUT time. Fail fast at mint time
+// instead of printing a share URL whose first push can only 400.
+export function validKey(k) {
+    if (k === 'latest' || k.endsWith('.zip'))
+        return false;
+    return /[^0-9]/.test(k); // purely numeric keys resolve as version selectors
+}
+function assertValidKey(key, cmd) {
+    if (validKey(key))
+        return;
+    fail(`${cmd}: invalid set key ${JSON.stringify(key)} — a key must not be purely numeric, "latest", or end in .zip (those collide with the server's version selectors)`, 2);
+}
+function git(gitArgs, cwd) {
+    const r = spawnSync('git', gitArgs, { cwd, encoding: 'utf8' });
+    return r.status === 0 ? r.stdout.trim() : '';
+}
+// Capture roots must never enter a repo's history — agents sometimes invent
+// non-standard roots (".screenshots4") that repo .gitignore globs don't cover,
+// and a later `git add -A` sweeps the set metadata into a commit. Self-ignore
+// every root via .git/info/exclude (local-only, shared across worktrees, never
+// dirties the repo). Memoized per-root; a no-op outside a git repo.
+const selfIgnoredRoots = new Set();
+function ensureRootSelfIgnored(root) {
+    const abs = resolve(root);
+    if (selfIgnoredRoots.has(abs))
+        return;
+    selfIgnoredRoots.add(abs);
+    try {
+        const top = git(['rev-parse', '--show-toplevel'], abs);
+        if (!top)
+            return; // not inside a git repo
+        const rel = relative(top, abs).split(sep).join('/');
+        if (!rel || rel.startsWith('..'))
+            return; // never ignore the repo root itself
+        const excl = git(['rev-parse', '--path-format=absolute', '--git-path', 'info/exclude'], abs);
+        if (!excl)
+            return;
+        const entry = `/${rel}/`;
+        const cur = existsSync(excl) ? readFileSync(excl, 'utf8') : '';
+        if (cur.split(/\r?\n/).some((l) => l.trim() === entry))
+            return;
+        mkdirSync(dirname(excl), { recursive: true });
+        writeFileSync(excl, cur + (cur && !cur.endsWith('\n') ? '\n' : '') + entry + '\n');
+    }
+    catch (e) {
+        // Best-effort (read-only .git etc.) — warn, never block a capture.
+        console.error(`warn: could not self-ignore ${root}: ${e.message}`);
+    }
+}
+// mainWorktreeTop resolves the MAIN worktree's root for a checkout. Linked
+// worktrees are typically named after their branch (repo-branch dirs), so
+// deriving the project from their toplevel forks every branch into its own
+// "project" on vitrinka. The common git dir always lives at <main>/.git.
+export function mainWorktreeTop(cwd) {
+    const common = git(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
+    if (common && basename(common) === '.git')
+        return dirname(common);
+    return git(['rev-parse', '--show-toplevel'], cwd);
+}
+// originRepo normalizes the origin remote to a schemeless slug, e.g.
+// "github.com/LEFTEQ/fixit". "" outside a repo / without a remote.
+function originRepo(dir) {
+    return git(['remote', 'get-url', 'origin'], dir)
+        .replace(/^git@([^:]+):/, '$1/').replace(/^[a-z+]+:\/\//, '').replace(/\.git$/, '');
+}
+// Binary/asset blobs the autocomplete should never offer — they only bloat
+// the index (the server caps entries at 50k).
+const INDEX_EXCLUDE = /\.(png|jpe?g|gif|webp|avif|heic|ico|icns|svgz|pdf|zip|tar|gz|tgz|bz2|7z|jar|mp[34]|mov|avi|webm|wav|ogg|flac|ttf|otf|woff2?|eot|keystore|jks|p8|p12|mobileprovision|dylib|so|a|o|node|wasm|pyc|class|min\.js|min\.css|map|lock|lockb)$|(^|\/)(package-lock\.json|bun\.lock|yarn\.lock|pnpm-lock\.yaml|go\.sum)$/i;
+const ROUTE_EXTS = /\.(tsx|jsx|ts|js)$/;
+/** extractRoutes derives route paths from file-based routing conventions.
+ *  Router roots are found at the repo root AND inside workspace containers
+ *  (`apps/<name>/`, `packages/<name>/`, each with optional `src/`) — FixIt-style
+ *  monorepos keep Expo Router at apps/client/app/**. Per ROOT: Next.js
+ *  app-router mode (any app/**\/page.* under THAT root) makes ONLY page.*
+ *  files routes; otherwise app/** screens follow Expo Router rules (groups
+ *  "(tabs)" stripped, trailing "index" collapsed, "_layout"/"+not-found"
+ *  skipped). pages/** always follows the Next pages-router rules. Route paths
+ *  stay plain, so two roots CAN produce the same path (e.g. apps/web/app/
+ *  index.tsx and apps/client/app/index.tsx both yield "/") — the first file
+ *  in input order keeps the path, later duplicates are dropped. Unrecognized
+ *  layouts yield [] — the files tier still carries the index. */
+const APP_ROOT_RE = /^(?:(?:apps|packages)\/[^/]+\/)?(?:src\/)?app\/(.+)$/;
+const PAGES_ROOT_RE = /^(?:(?:apps|packages)\/[^/]+\/)?(?:src\/)?pages\/(.+)$/;
+export function extractRoutes(files) {
+    const routes = new Map();
+    // Next-mode is PER router root, not global: a monorepo can hold a Next app
+    // (apps/web) and an Expo app (apps/client) side by side. One exec per file:
+    // the root is derived from the match already in hand.
+    const rootOfMatch = (f, rel) => f.slice(0, f.length - rel.length);
+    const nextRoots = new Set();
+    for (const f of files) {
+        const m = APP_ROOT_RE.exec(f);
+        if (m && /\/page\.(tsx|jsx|ts|js)$/.test(f))
+            nextRoots.add(rootOfMatch(f, m[1]));
+    }
+    const add = (rel, file) => {
+        const segs = rel.split('/').filter((s) => s && !(s.startsWith('(') && s.endsWith(')')));
+        if (segs[segs.length - 1] === 'index')
+            segs.pop();
+        const p = '/' + segs.join('/');
+        if (!routes.has(p))
+            routes.set(p, file);
+    };
+    for (const f of files) {
+        if (!ROUTE_EXTS.test(f))
+            continue;
+        const app = APP_ROOT_RE.exec(f);
+        if (app) {
+            const rel = app[1].replace(ROUTE_EXTS, '');
+            const base = rel.split('/').pop();
+            if (nextRoots.has(rootOfMatch(f, app[1]))) {
+                if (base === 'page')
+                    add(rel.replace(/\/?page$/, ''), f);
+            }
+            else if (!base.startsWith('_') && !base.startsWith('+')) {
+                add(rel, f);
+            }
+            continue;
+        }
+        const pages = PAGES_ROOT_RE.exec(f);
+        if (pages) {
+            const rel = pages[1].replace(ROUTE_EXTS, '');
+            const base = rel.split('/').pop();
+            if (base.startsWith('_') || rel === 'api' || rel.startsWith('api/'))
+                continue;
+            add(rel, f);
+        }
+    }
+    return [...routes.entries()].map(([p, f]) => ({ p, f }))
+        .sort((a, b) => (a.p < b.p ? -1 : a.p > b.p ? 1 : 0));
+}
+// cmdDescription pulls the one-line `description:` out of a command/skill
+// md frontmatter — the popover hint. "" when absent/unreadable.
+function cmdDescription(mdPath) {
+    let head;
+    try {
+        head = readFileSync(mdPath, 'utf8').slice(0, 2048);
+    }
+    catch {
+        return ''; // vanished/unreadable between readdir and read — hint only, skip
+    }
+    const m = /^description:\s*["']?(.+?)["']?\s*$/m.exec(head);
+    if (!m)
+        return '';
+    const d = m[1].replace(/\s+/g, ' ').trim();
+    return d.length > 80 ? d.slice(0, 79) + '…' : d;
+}
+/** collectCommands indexes the slash-command palette exactly as Claude Code
+ *  resolves it: `<root>/commands/**\/*.md` → `/ns:name` (dirs join with ":"),
+ *  `<root>/skills/<ns…>/<name>/SKILL.md` → `/ns:name` — from the PROJECT's
+ *  .claude first, then the HOME ~/.claude (project wins name collisions).
+ *  Underscore-prefixed files/dirs (e.g. skills/git/_shared) are internals. */
+export function collectCommands(projectDir, homeClaude = join(process.env.HOME || '', '.claude')) {
+    const out = new Map();
+    const add = (segs, mdPath) => {
+        if (segs.some((s) => !s || s.startsWith('_') || s.startsWith('.')))
+            return;
+        const c = '/' + segs.join(':');
+        if (out.has(c) || out.size >= 1000)
+            return;
+        const d = cmdDescription(mdPath);
+        out.set(c, d ? { c, d } : { c });
+    };
+    const list = (dir) => {
+        try {
+            return readdirSync(dir, { recursive: true, encoding: 'utf8' });
+        }
+        catch {
+            return []; // root absent (no .claude here) — normal, not an error
+        }
+    };
+    for (const root of [join(projectDir, '.claude'), homeClaude]) {
+        for (const rel of list(join(root, 'commands'))) {
+            if (!rel.endsWith('.md'))
+                continue;
+            add(rel.slice(0, -3).split('/'), join(root, 'commands', rel));
+        }
+        for (const rel of list(join(root, 'skills'))) {
+            if (!rel.endsWith('/SKILL.md'))
+                continue;
+            add(rel.slice(0, -'/SKILL.md'.length).split('/'), join(root, 'skills', rel));
+        }
+    }
+    return [...out.values()].sort((a, b) => (a.c < b.c ? -1 : a.c > b.c ? 1 : 0));
+}
+/** buildProjectIndex lists the ACTUAL checkout's non-gitignored files
+ *  (tracked + untracked-unignored — a just-created screen completes before
+ *  its first commit), derives routes, and indexes the slash-command palette.
+ *  null outside a git repo. */
+export function buildProjectIndex(projectDir) {
+    const top = git(['rev-parse', '--show-toplevel'], projectDir);
+    if (!top)
+        return null;
+    const ls = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard'], { cwd: top, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (ls.status !== 0) {
+        console.error(`index: git ls-files failed: ${String(ls.stderr).trim()}`);
+        return null;
+    }
+    let files = ls.stdout.split('\n').filter((f) => f && !INDEX_EXCLUDE.test(f)).sort();
+    if (files.length > 50_000) {
+        console.error(`index: ${files.length} files exceeds the 50k server cap — keeping the first 50k (tune INDEX_EXCLUDE)`);
+        files = files.slice(0, 50_000);
+    }
+    const routes = extractRoutes(files);
+    const cmds = collectCommands(projectDir);
+    // Key order mirrors the server's canonical marshal (v, repo, routes, files, cmds).
+    const body = JSON.stringify({ v: 1, repo: originRepo(projectDir) || undefined, routes, files, cmds });
+    return {
+        body, hash: createHash('sha256').update(body).digest('hex'),
+        routes: routes.length, files: files.length, cmds: cmds.length,
+    };
+}
+// The last successfully pushed index (base+project+hash) is remembered inside
+// the repo's common .git dir — per-repo, never committed, shared by worktrees.
+function indexCachePath(projectDir) {
+    return join(git(['rev-parse', '--path-format=absolute', '--git-common-dir'], projectDir), 'vitrinka-index.cache');
+}
+/** pushProjectIndex builds + pushes the index unless nothing changed since
+ *  the last successful push. Never throws and never exits — every caller is
+ *  a touchpoint where index freshness must not fail the primary job.
+ *
+ *  `verify` (the explicit `vitrinka index` / daemon path): a matching local
+ *  stamp alone must not claim success — the server row may have been wiped
+ *  (DB reset). On a stamp hit it confirms with one conditional GET against
+ *  the server's own hash (304 = in sync, zero body); a 404 or a diverged
+ *  ETag invalidates the stamp and falls through to a re-PUT. Piggybacked
+ *  callers keep verify=false — an unchanged repo costs zero requests there. */
+export async function pushProjectIndex(projectDir, base, project, verify = false) {
+    const built = buildProjectIndex(projectDir);
+    if (!built)
+        return false;
+    const cachePath = indexCachePath(projectDir);
+    const endpoint = `${base}/api/v1/projects/${encodeURIComponent(project)}/index`;
+    const cached = existsSync(cachePath) ? readFileSync(cachePath, 'utf8').trim().split(' ') : [];
+    const stampHit = cached[0] === base && cached[1] === project && cached[2] === built.hash;
+    let serverHash = cached[3] || ''; // the server's canonical hash from the last PUT's response
+    if (stampHit && !verify)
+        return true;
+    if (stampHit && verify) {
+        try {
+            const res = await fetch(endpoint, {
+                headers: serverHash ? { 'If-None-Match': `"${serverHash}"` } : {},
+                signal: AbortSignal.timeout(30_000),
+            });
+            if (res.status === 304 || (res.ok && !serverHash))
+                return true; // in sync / present
+            // 404 (row wiped) or a diverged ETag → the stamp lied; re-push below.
+        }
+        catch (e) {
+            console.error(`index: vitrinka unreachable (${e instanceof Error ? e.message : e}) — next touchpoint retries`);
+            return false;
+        }
+    }
+    const headers = { 'Content-Type': 'application/json' };
+    const token = readToken();
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    try {
+        const res = await fetch(endpoint, {
+            method: 'PUT', headers, body: built.body, signal: AbortSignal.timeout(30_000),
+        });
+        if (!res.ok && res.status !== 204) {
+            console.error(`index: push rejected (HTTP ${res.status}): ${(await res.text()).slice(0, 200)}`);
+            return false;
+        }
+        if (res.status !== 204) {
+            try {
+                serverHash = String((await res.json()).hash || serverHash);
+            }
+            catch {
+                // 2xx without the JSON hash (older server): keep the previous serverHash.
+            }
+        }
+    }
+    catch (e) {
+        console.error(`index: vitrinka unreachable (${e instanceof Error ? e.message : e}) — next touchpoint retries`);
+        return false;
+    }
+    writeFileSync(cachePath, `${base} ${project} ${built.hash} ${serverHash}`.trimEnd() + '\n');
+    console.log(`index ↑ ${project}: ${built.routes} routes, ${built.files} files, ${built.cmds} commands`);
+    return true;
+}
+// indexCmd — the explicit `vitrinka index` touchpoint. Exits non-zero on
+// failure (unlike the piggybacked pushes) so scripts can rely on it; verifies
+// the server actually holds the index rather than trusting the local stamp.
+async function indexCmd(root, args) {
+    const projectDir = dirname(root);
+    const cfg = existsSync(vitrinkaCfgPath(root)) ? loadVitrinkaCfg(root) : null;
+    const base = (strArg(args.base) || cfg?.base || process.env.VITRINKA_URL || 'https://vitrinka.lovinka.com').replace(/\/+$/, '');
+    const project = sanitizeSeg(strArg(args.project) || cfg?.project || basename(mainWorktreeTop(projectDir) || projectDir), 64);
+    if (!(await pushProjectIndex(projectDir, base, project, true)))
+        process.exit(1);
+}
+function loadVitrinkaCfg(root) {
+    const raw = readFileSync(vitrinkaCfgPath(root), 'utf8'); // caller checks existsSync
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Corrupt ${vitrinkaCfgPath(root)} (${e.message}). Delete it and re-run remote-init.`);
+    }
+}
+function shareUrl(cfg) {
+    return `${cfg.base}/${cfg.project}/${cfg.slug}/${cfg.key}`;
+}
+function remoteInitCmd(root, args) {
+    if (existsSync(vitrinkaCfgPath(root))) {
+        // Sticky per session dir — reuse, so re-activation never forks the set.
+        const cfg = loadVitrinkaCfg(root);
+        console.log(`vitrinka set (existing) → ${shareUrl(cfg)}`);
+        return cfg;
+    }
+    const projectDir = dirname(root);
+    const base = (args.base && args.base !== true ? String(args.base) : process.env.VITRINKA_URL || 'https://vitrinka.lovinka.com').replace(/\/+$/, '');
+    // Project identity comes from the MAIN worktree (a linked worktree's dir is
+    // named after its branch — using it would fork each branch into its own
+    // project; the branch already lives in cfg.branch).
+    const gitTop = mainWorktreeTop(projectDir);
+    // Artifact roots live at <project>/.artifacts/<slug> — outside a git repo the project
+    // fallback must be the real project dir, not the '.artifacts' container itself.
+    const fallbackDir = basename(projectDir) === '.artifacts' ? dirname(projectDir) : projectDir;
+    const project = sanitizeSeg(args.project && args.project !== true ? String(args.project) : basename(gitTop || fallbackDir), 64);
+    const branch = (args.branch && args.branch !== true ? String(args.branch) : git(['branch', '--show-current'], projectDir)) || 'main';
+    const d = new Date();
+    const p2 = (n) => String(n).padStart(2, '0');
+    const key = args.key && args.key !== true
+        ? String(args.key).replace(/[^a-zA-Z0-9._-]+/g, '-').slice(0, 64) // meaningful keys, e.g. artifact slugs
+        : `s-${d.getFullYear()}${p2(d.getMonth() + 1)}${p2(d.getDate())}-${p2(d.getHours())}${p2(d.getMinutes())}`;
+    assertValidKey(key, 'remote-init');
+    const cfg = {
+        base,
+        project,
+        branch,
+        slug: sanitizeSeg(branch, 100),
+        key,
+        kind: args.kind && args.kind !== true ? String(args.kind) : 'screenshots',
+        issue: args.issue && args.issue !== true ? String(args.issue) : '',
+    };
+    mkdirSync(root, { recursive: true });
+    ensureRootSelfIgnored(root);
+    writeFileSync(vitrinkaCfgPath(root), JSON.stringify(cfg, null, 2) + '\n');
+    console.log(`vitrinka set → ${shareUrl(cfg)}`);
+    return cfg;
+}
+// Token / operator resolution + the X-Board-Actor latin-1 encoder are shared
+// with the MCP server — single-sourced in ./lib (readToken, readOperator,
+// operatorPath, actorHeaderValue are imported at the top).
+// actorFor resolves the X-Board-Actor header value for a board write: an
+// explicit --actor flag wins, else the configured operator name, else ''
+// (anonymous). The CLI uses the truthiness operator semantics (a SET-but-empty
+// $VITRINKA_OPERATOR falls through to the operator file).
+function actorFor(args) {
+    return actorHeaderValue((strArg(args.actor) || readOperator(true)).trim());
+}
+function markOffline(root, error) {
+    const p = offlineMarkerPath(root);
+    // Merge with any existing marker: a repeated push failure inside one offline episode
+    // must not clear the `warned` flag snap set (or snap would warn on every shot).
+    // A successful push deletes the marker, so a NEW episode still warns exactly once.
+    let warned = false;
+    if (existsSync(p)) {
+        try {
+            warned = JSON.parse(readFileSync(p, 'utf8')).warned === true;
+        }
+        catch {
+            // Malformed marker (half-written by a killed push) — treat as not-yet-warned.
+        }
+    }
+    writeFileSync(p, JSON.stringify({ ts: new Date().toISOString(), error, ...(warned ? { warned } : {}) }) + '\n');
+}
+async function pushCmd(root, args) {
+    if (!existsSync(vitrinkaCfgPath(root))) {
+        console.error(`push: no ${vitrinkaCfgPath(root)} — run \`node ${CLI_PATH} remote-init --root ${root}\` first`);
+        process.exit(2);
+    }
+    const cfg = loadVitrinkaCfg(root);
+    const projectDir = dirname(root);
+    // Control files are excluded here AND skipped server-side (belt and suspenders).
+    // COPYFILE_DISABLE stops macOS bsdtar from emitting AppleDouble (._*) junk entries.
+    const tar = spawnSync('tar', [
+        '-czf', '-',
+        '--exclude', '.vitrinka*', '--exclude', './.vitrinka*',
+        '--exclude', '.active', '--exclude', './.active',
+        '--exclude', '._*', '--exclude', './._*', '--exclude', '.DS_Store',
+        '-C', root, '.',
+    ], { maxBuffer: 512 * 1024 * 1024, env: { ...process.env, COPYFILE_DISABLE: '1' } });
+    if (tar.status !== 0) {
+        console.error(`push: tar failed: ${String(tar.stderr)}`);
+        process.exit(1);
+    }
+    const commit = git(['rev-parse', '--short', 'HEAD'], projectDir);
+    const repo = originRepo(projectDir);
+    const q = new URLSearchParams();
+    q.set('kind', cfg.kind || 'screenshots');
+    if (cfg.branch)
+        q.set('branch', cfg.branch);
+    if (commit)
+        q.set('commit', commit);
+    if (repo)
+        q.set('repo', repo);
+    if (cfg.issue)
+        q.set('issue', cfg.issue);
+    // Source set cross-link: --source flag wins, else the ref recorded in .vitrinka
+    // (by artifact-from-set, or persisted from an earlier explicit push). Same for --title.
+    // The server clears omitted ?source=/?title= on every re-sync, so both must be re-sent.
+    const source = (args.source && args.source !== true ? String(args.source) : '') || cfg.source || '';
+    if (source)
+        q.set('source', source);
+    const title = (args.title && args.title !== true ? String(args.title) : '') || cfg.title || '';
+    if (title)
+        q.set('title', title);
+    const endpoint = `${cfg.base}/api/v1/sets/${encodeURIComponent(cfg.project)}/${encodeURIComponent(cfg.slug)}/${encodeURIComponent(cfg.key)}/content?${q}`;
+    const headers = { 'Content-Type': 'application/gzip' };
+    const token = readToken();
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    let res;
+    try {
+        res = await fetch(endpoint, { method: 'PUT', headers, body: tar.stdout, signal: AbortSignal.timeout(120_000) });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        markOffline(root, msg);
+        console.error(`push: vitrinka unreachable (${msg}) — shots stay local; any later push backfills the whole set`);
+        process.exit(1);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        markOffline(root, `HTTP ${res.status}: ${text.slice(0, 200)}`);
+        console.error(`push: server rejected (HTTP ${res.status}): ${text.slice(0, 300)}`);
+        // Additive AI hint for a 4xx (client-side) rejection — never blocks the exit.
+        if (res.status >= 400 && res.status < 500) {
+            await emitHint(`vitrinka push --root ${root}`, `HTTP ${res.status}: ${text.slice(0, 300)}`, renderCmdHelp('push'));
+        }
+        process.exit(1);
+    }
+    let out = {};
+    try {
+        out = JSON.parse(text);
+    }
+    catch (e) {
+        // 2xx with a non-JSON body is unexpected — log it, but the sync itself succeeded.
+        console.error(`push: warning — success response was not JSON (${e.message}); using alias URL`);
+    }
+    if (existsSync(offlineMarkerPath(root)))
+        rmSync(offlineMarkerPath(root));
+    // Persist explicitly-passed --source/--title (on success only, so a server-rejected
+    // value never sticks) — the next plain `push` re-sends them instead of silently
+    // clearing the cross-link chip / human title server-side.
+    const explicitSource = args.source && args.source !== true ? String(args.source) : '';
+    const explicitTitle = args.title && args.title !== true ? String(args.title) : '';
+    if ((explicitSource && explicitSource !== cfg.source) || (explicitTitle && explicitTitle !== cfg.title)) {
+        if (explicitSource)
+            cfg.source = explicitSource;
+        if (explicitTitle)
+            cfg.title = explicitTitle;
+        writeFileSync(vitrinkaCfgPath(root), JSON.stringify(cfg, null, 2) + '\n');
+    }
+    console.log(`↑ synced ${out.files ?? '?'} files → ${out.url || shareUrl(cfg)}`);
+    // Touchpoint refresh of the project's file/route index (autocomplete
+    // source) — hash-gated both ends, never fails the set push.
+    await pushProjectIndex(projectDir, cfg.base, cfg.project);
+    // --name: name the set right after publish (PATCH; names are sticky
+    // server-side, so unlike --title it is never re-sent on later pushes).
+    // A naming failure warns loudly but exits 0 — the content itself is up.
+    const name = strArg(args.name);
+    if (name) {
+        const nameRes = await patchSetMeta(cfg.base, cfg.project, cfg.slug, cfg.key, { name: name.toLowerCase() });
+        if (nameRes.ok)
+            console.log(`  name → ${cfg.base}/${cfg.project}/${cfg.slug}/${encodeURIComponent(name.toLowerCase())}`);
+        else
+            console.error(`push: warning — naming failed (${nameRes.error}); content is up, retry with: node ${CLI_PATH} name ${cfg.project}/${cfg.slug}/${cfg.key} ${name}`);
+    }
+}
+// ---------- set metadata (name/title) ----------
+// patchSetMeta PATCHes /api/v1/sets/{project}/{slug}/{selector}; never throws.
+async function patchSetMeta(base, project, slug, selector, body) {
+    const endpoint = `${base}/api/v1/sets/${encodeURIComponent(project)}/${encodeURIComponent(slug)}/${encodeURIComponent(selector)}`;
+    const headers = { 'Content-Type': 'application/json' };
+    const token = readToken();
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    let res;
+    try {
+        res = await fetch(endpoint, {
+            method: 'PATCH', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+    const text = await res.text();
+    if (!res.ok)
+        return { ok: false, error: `HTTP ${res.status}: ${text.slice(0, 200)}` };
+    try {
+        return { ok: true, json: JSON.parse(text) };
+    }
+    catch {
+        return { ok: true, json: {} }; // 2xx with non-JSON body — the PATCH itself succeeded
+    }
+}
+// nameCmd: `name <project/branch/selector> <new-name>` (or `--clear`) — set or
+// clear the custom, URL-addressable name of an existing set.
+async function nameCmd(rest, args) {
+    const pos = positionals(rest).slice(1); // drop the command word itself
+    const ref = pos[0] || '';
+    const segs = ref.split('/');
+    if (segs.length !== 3 || segs.some((s) => !s)) {
+        fail(`name: expected <project>/<branchSlug>/<selector> (selector = version, key, or current name), got ${JSON.stringify(ref)}`, 2);
+    }
+    const clear = args.clear === true;
+    const newName = (pos[1] || '').toLowerCase();
+    if (!clear && !newName)
+        fail('name: expected a new name (or --clear)', 2);
+    if (clear && newName)
+        fail('name: pass either a new name or --clear, not both', 2);
+    const base = (strArg(args.base) || process.env.VITRINKA_URL || 'https://vitrinka.lovinka.com').replace(/\/+$/, '');
+    const res = await patchSetMeta(base, segs[0], segs[1], segs[2], { name: clear ? '' : newName });
+    if (!res.ok)
+        fail(`name: ${res.error}`);
+    if (clear)
+        console.log(`cleared name of ${segs[0]}/${segs[1]}/${segs[2]} → ${res.json?.url || ''}`);
+    else
+        console.log(`named ${segs[0]}/${segs[1]}/${segs[2]} → ${base}/${segs[0]}/${segs[1]}/${encodeURIComponent(newName)}`);
+}
+// ---------- operator: the board-attribution persona ----------
+// operatorCmd manages the operator persona name — how vitrinka credits this
+// machine's writes on boards.
+//   operator            → print the current local + server values
+//   operator <name>     → write ~/.config/vitrinka/operator AND PUT the server
+//                         default (needs the write token; server errors are
+//                         reported but never fail the local write).
+async function operatorCmd(rest, args) {
+    const pos = positionals(rest).slice(1); // drop the command word itself
+    const base = (strArg(args.base) || process.env.VITRINKA_URL || process.env.VITRINKA_BASE_URL
+        || 'https://vitrinka.lovinka.com').replace(/\/+$/, '');
+    const name = pos.join(' ').trim();
+    if (!name) {
+        const local = readOperator(true);
+        console.log(`operator (local): ${local || '(unset)'}`);
+        try {
+            const res = await fetch(`${base}/api/v1/operator`, { signal: AbortSignal.timeout(15_000) });
+            if (res.ok) {
+                const d = await res.json();
+                console.log(`operator (server): ${d.operator || '(unset)'}`);
+            }
+            else {
+                console.log(`operator (server): unavailable (HTTP ${res.status})`);
+            }
+        }
+        catch (e) {
+            console.log(`operator (server): unreachable (${e instanceof Error ? e.message : String(e)})`);
+        }
+        return;
+    }
+    if (name.length > 64)
+        fail('operator: name too long (max 64 chars)', 2);
+    // Local write first — it never needs the network.
+    const p = operatorPath();
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, name + '\n');
+    console.log(`operator (local): ${name} → ${p}`);
+    // Then publish the server default (Bearer). Reachability/auth problems are
+    // reported but do not undo the local write.
+    const token = readToken();
+    if (!token) {
+        console.error('operator: no write token — server default NOT set (add ~/.config/vitrinka/token or $VITRINKA_TOKEN, then re-run)');
+        return;
+    }
+    try {
+        const res = await fetch(`${base}/api/v1/operator`, {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+            body: JSON.stringify({ operator: name }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (res.ok)
+            console.log(`operator (server): ${name} → ${base}`);
+        else
+            console.error(`operator: server rejected (HTTP ${res.status}): ${(await res.text()).slice(0, 200)}`);
+    }
+    catch (e) {
+        console.error(`operator: server unreachable (${e instanceof Error ? e.message : String(e)}) — local name is set; re-run to publish`);
+    }
+}
+// ---------- install: PATH shim ----------
+// installCmd writes an executable shim `vitrinka` into ~/.local/bin (so the
+// CLI works in interactive shells AND non-interactive AI/tool shells, which a
+// zshrc alias would not) and makes sure ~/.local/bin is on PATH via a
+// marker-guarded ~/.zshrc block. Idempotent: re-running reports and no-ops.
+function installCmd(args) {
+    const home = process.env.HOME;
+    if (!home)
+        fail('install: $HOME is not set');
+    const binDir = join(home, '.local', 'bin');
+    const shimPath = join(binDir, 'vitrinka');
+    const shim = `#!/bin/sh\nexec node "${CLI_PATH}" "$@"\n`;
+    if (existsSync(shimPath) && readFileSync(shimPath, 'utf8') === shim) {
+        console.log(`shim already installed: ${shimPath}`);
+    }
+    else {
+        mkdirSync(binDir, { recursive: true });
+        writeFileSync(shimPath, shim);
+        chmodSync(shimPath, 0o755);
+        console.log(`installed shim: ${shimPath} → node ${CLI_PATH}`);
+    }
+    const marker = '# vitrinka-cli';
+    const zshrc = join(home, '.zshrc');
+    const zshrcContent = existsSync(zshrc) ? readFileSync(zshrc, 'utf8') : '';
+    if (zshrcContent.includes(marker)) {
+        console.log(`PATH block already in ${zshrc}`);
+    }
+    else if ((process.env.PATH || '').split(':').includes(binDir)) {
+        console.log(`${binDir} already on PATH — ${zshrc} left untouched`);
+    }
+    else {
+        appendFileSync(zshrc, `\n${marker}\nexport PATH="$HOME/.local/bin:$PATH"\n`);
+        console.log(`added PATH block to ${zshrc} (open a new shell, or: source ${zshrc})`);
+    }
+    // Shell completion — state-aware, opt-out via --no-completion. Appends a
+    // single guarded `eval "$(vitrinka completion zsh)"` line (skipped if present).
+    if (args['no-completion'] === true) {
+        console.log('completion: skipped (--no-completion)');
+    }
+    else {
+        const compMarker = '# vitrinka-completion';
+        const shellName = (process.env.SHELL || '').includes('bash') ? 'bash' : 'zsh';
+        const rc = join(home, shellName === 'bash' ? '.bashrc' : '.zshrc');
+        const rcContent = existsSync(rc) ? readFileSync(rc, 'utf8') : '';
+        if (rcContent.includes(compMarker)) {
+            console.log(`completion already enabled in ${rc}`);
+        }
+        else {
+            appendFileSync(rc, `\n${compMarker}\neval "$(vitrinka completion ${shellName})"\n`);
+            console.log(`added ${shellName} completion to ${rc} (open a new shell, or: source ${rc})`);
+        }
+    }
+    console.log('done — try: vitrinka --help');
+}
+// ---------- snap: one-shot capture → manifest → detached push ----------
+// Filename slug: diacritics folded (Přihlášení → prihlaseni), non-alnum → '-', capped.
+export function kebab(s) {
+    const out = String(s)
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60)
+        .replace(/-+$/, '');
+    return out || 'shot';
+}
+// NN sequence = max already-used prefix in the dated dir + 1 (ignores index.html etc.).
+// Max-based, not count-based: after a manual shot deletion a count would re-issue a
+// surviving file's number and the next snap would silently overwrite it.
+export function nextSeq(dir) {
+    let max = 0;
+    if (existsSync(dir)) {
+        for (const f of readdirSync(dir)) {
+            const m = /^(\d{2,})-/.exec(f);
+            if (m)
+                max = Math.max(max, Number(m[1]));
+        }
+    }
+    return String(max + 1).padStart(2, '0');
+}
+export function deriveShotName(seq, surface, titleOrRoute, ext = '.png') {
+    return `${seq}-${surface}-${kebab(titleOrRoute)}${ext}`;
+}
+const UDID_RE = /^[0-9A-Fa-f]{8}-([0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$/;
+// BFS for a UUID-shaped string; keys containing "udid" win over any other UUID-shaped value.
+export function findUdid(v) {
+    const queue = [v];
+    const preferred = [];
+    const fallback = [];
+    while (queue.length) {
+        const cur = queue.shift();
+        if (!cur || typeof cur !== 'object')
+            continue;
+        for (const [k, val] of Object.entries(cur)) {
+            if (typeof val === 'string' && UDID_RE.test(val.trim())) {
+                (/udid/i.test(k) ? preferred : fallback).push(val.trim());
+            }
+            else if (val && typeof val === 'object') {
+                queue.push(val);
+            }
+        }
+    }
+    return preferred[0] || fallback[0] || '';
+}
+function udidFromWorktreeFile(projectDir) {
+    const p = join(projectDir, '.fixit-worktree.json');
+    if (!existsSync(p))
+        return '';
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        // Defensive read by design: a malformed worktree file must not block capture — note it, fall through.
+        console.error(`snap: ignoring malformed ${p} (${e.message})`);
+        return '';
+    }
+    return findUdid(parsed);
+}
+function bootedSims() {
+    const r = spawnSync('xcrun', ['simctl', 'list', 'devices', 'booted', '-j'], { encoding: 'utf8' });
+    if (r.error)
+        fail(`snap ios: xcrun unavailable: ${r.error.message}`);
+    if (r.status !== 0)
+        fail(`snap ios: simctl list failed: ${(r.stderr || '').trim()}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(r.stdout);
+    }
+    catch (e) {
+        fail(`snap ios: could not parse simctl list output (${e.message})`);
+    }
+    const out = [];
+    for (const list of Object.values(parsed.devices || {})) {
+        for (const d of list) {
+            if (d.state === 'Booted' && d.udid)
+                out.push({ udid: d.udid, name: d.name || '' });
+        }
+    }
+    return out;
+}
+// Also carries the simulator NAME when the resolution path already listed
+// sims — the v2 device field fills for free, with no extra xcrun call and no
+// new failure mode on the --udid / worktree-file fast paths.
+function resolveIosUdid(args, projectDir) {
+    const flag = strArg(args.udid);
+    if (flag)
+        return { udid: flag };
+    const fromFile = udidFromWorktreeFile(projectDir);
+    if (fromFile)
+        return { udid: fromFile };
+    const booted = bootedSims();
+    if (booted.length === 1)
+        return booted[0];
+    if (booted.length === 0)
+        fail('snap ios: no booted simulator (and no --udid / .fixit-worktree.json)');
+    fail(`snap ios: ${booted.length} booted simulators — pass --udid. Booted:\n`
+        + booted.map((b) => `  ${b.udid}  ${b.name}`).join('\n'));
+}
+// The detached push means push failures are invisible to the caller — so snap surfaces a
+// pre-existing offline marker instead, exactly once (the marker records that it was shown;
+// markOffline carries the flag across repeated failures, and a successful push deletes the
+// marker, re-arming the warning for the next offline episode).
+function maybeWarnOffline(root) {
+    const p = offlineMarkerPath(root);
+    if (!existsSync(p))
+        return;
+    let marker = {};
+    try {
+        marker = JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        // Malformed marker (half-written by a killed push) is recoverable: still warn, then rewrite it.
+    }
+    if (marker.warned)
+        return;
+    console.error(`vitrinka unreachable on a previous push (${marker.error || 'unknown error'}) — shots stay local; any later successful push backfills the whole set`);
+    writeFileSync(p, JSON.stringify({ ...marker, warned: true }) + '\n');
+}
+// safeSize returns a file's byte size, or undefined if it can't be stat'd
+// (missing/racing) — the encoding decision then degrades to "keep original".
+function safeSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return undefined;
+    }
+}
+// chooseEncoding is the pure decision behind snap's WebP normalization:
+//   - no cwebp                → keep the original (PNG/JPEG untouched).
+//   - normal                 → lossy q85 WebP (small review-page assets).
+//   - --hq                   → lossless WebP ONLY when it's smaller than the
+//                              original (pixel-identical, fewer bytes); else
+//                              keep the original PNG. NEVER lossy, NEVER resize.
+export function chooseEncoding(i) {
+    if (!i.cwebpAvailable)
+        return 'original';
+    if (!i.hq)
+        return 'lossy';
+    if (i.losslessSize !== undefined && i.pngSize !== undefined && i.losslessSize < i.pngSize) {
+        return 'lossless';
+    }
+    return 'original';
+}
+async function snapCmd(surface, args) {
+    if (!['ios', 'android', 'macos', 'web'].includes(surface)) {
+        console.error(`snap: surface must be ios|android|macos|web, got ${JSON.stringify(surface)}`);
+        process.exit(2);
+    }
+    const root = resolve(strArg(args.root) || '.screenshots');
+    const projectDir = dirname(root);
+    const route = strArg(args.route);
+    const note = strArg(args.note);
+    if (!route) {
+        console.error('snap: --route is required');
+        process.exit(2);
+    }
+    if (!note) {
+        console.error('snap: --note is required');
+        process.exit(2);
+    }
+    const adopt = strArg(args.file);
+    if (surface === 'web' && !adopt) {
+        console.error('snap web: --file <path> is required (capture via the browser MCP, then adopt the file)');
+        process.exit(2);
+    }
+    // --open + --settle: navigate-and-wait live INSIDE the tool, so a capture is
+    // ONE command — never a shell `sleep N; openurl; sleep M; snap` chain (which
+    // agent harnesses rightly block). --settle defaults to 4 s when --open is
+    // used (deep-link → render time), 0 otherwise; both are overridable.
+    const openUrl = strArg(args.open);
+    if (openUrl && surface === 'web')
+        fail('snap web: --open is not supported (drive the browser via the MCP, then adopt with --file)', 2);
+    if (openUrl && adopt)
+        fail('snap: --open cannot be combined with --file (adopt captures nothing)', 2);
+    const settle = numArg(args.settle, openUrl ? 4 : 0, '--settle');
+    let iosUdid = '';
+    let iosSimName = '';
+    if (surface === 'ios' && !adopt) {
+        const sim = resolveIosUdid(args, projectDir);
+        iosUdid = sim.udid;
+        iosSimName = sim.name || '';
+    }
+    if (openUrl) {
+        if (surface === 'ios') {
+            const r = spawnSync('xcrun', ['simctl', 'openurl', iosUdid, openUrl], { encoding: 'utf8' });
+            if (r.error)
+                fail(`snap ios: xcrun unavailable: ${r.error.message}`);
+            if (r.status !== 0)
+                fail(`snap ios: simctl openurl failed: ${(r.stderr || '').trim()}`);
+        }
+        else if (surface === 'android') {
+            const r = spawnSync('adb', ['shell', 'am', 'start', '-a', 'android.intent.action.VIEW', '-d', openUrl], { encoding: 'utf8' });
+            if (r.error)
+                fail(`snap android: adb unavailable: ${r.error.message}`);
+            if (r.status !== 0)
+                fail(`snap android: am start failed: ${(r.stderr || '').trim()}`);
+        }
+        else { // macos
+            const r = spawnSync('open', [openUrl], { encoding: 'utf8' });
+            if (r.error)
+                fail(`snap macos: open unavailable: ${r.error.message}`);
+            if (r.status !== 0)
+                fail(`snap macos: open failed: ${(r.stderr || '').trim()}`);
+        }
+    }
+    if (settle > 0)
+        await new Promise((r) => setTimeout(r, settle * 1000));
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    const day = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+    const dir = join(root, day);
+    mkdirSync(dir, { recursive: true });
+    const ext = adopt ? (extname(adopt).toLowerCase() || '.png') : '.png';
+    let name = deriveShotName(nextSeq(dir), surface, strArg(args.title) || route, ext);
+    let dest = join(dir, name);
+    if (adopt) {
+        const src = resolve(adopt);
+        if (!existsSync(src)) {
+            console.error(`snap: --file ${src} does not exist`);
+            process.exit(2);
+        }
+        copyFileSync(src, dest);
+    }
+    else if (surface === 'ios') {
+        const r = spawnSync('xcrun', ['simctl', 'io', iosUdid, 'screenshot', dest], { encoding: 'utf8' });
+        if (r.error)
+            fail(`snap ios: xcrun unavailable: ${r.error.message}`);
+        if (r.status !== 0)
+            fail(`snap ios: simctl screenshot failed: ${(r.stderr || '').trim()}`);
+    }
+    else if (surface === 'android') {
+        const r = spawnSync('adb', ['exec-out', 'screencap', '-p'], { maxBuffer: 64 * 1024 * 1024 });
+        if (r.error)
+            fail(`snap android: adb unavailable: ${r.error.message}`);
+        if (r.status !== 0)
+            fail(`snap android: screencap failed: ${String(r.stderr || '').trim()}`);
+        writeFileSync(dest, r.stdout);
+    }
+    else { // macos
+        const region = strArg(args.region);
+        const scArgs = ['-x', ...(region ? ['-R', region] : []), dest];
+        const r = spawnSync('screencapture', scArgs, { encoding: 'utf8' });
+        if (r.error)
+            fail(`snap macos: screencapture unavailable: ${r.error.message}`);
+        if (r.status !== 0)
+            fail(`snap macos: screencapture failed: ${(r.stderr || '').trim()}`);
+    }
+    // ---------- WebP normalization ----------
+    // Native captures are lossless PNG (a 3x sim frame is 2–5 MB); the review
+    // page doesn't need lossless, and `push` re-uploads the WHOLE set as one
+    // PUT — full-res PNGs blow the proxy body cap once a set spans sessions
+    // (2026-07-03: 317 MB set → HTTP 413, silently, on every detached push).
+    // WebP q85 keeps native resolution at ~5–10% of the PNG bytes. cwebp is a
+    // soft dependency (brew install webp): when missing, keep the original.
+    //
+    // `--hq` (marketing / full-fidelity): NEVER lossy-re-encode, NEVER resize —
+    // keep the original PNG, but if cwebp is present try `-lossless` and keep it
+    // only when it comes out smaller than the PNG (pixel-identical, fewer bytes).
+    const hq = args.hq === true;
+    if (/\.(png|jpe?g)$/i.test(name)) {
+        const webpName = name.replace(/\.(png|jpe?g)$/i, '.webp');
+        const webpDest = join(dir, webpName);
+        const cwebpArgs = hq
+            ? ['-quiet', '-lossless', dest, '-o', webpDest]
+            : ['-quiet', '-q', '85', dest, '-o', webpDest];
+        const w = spawnSync('cwebp', cwebpArgs, { encoding: 'utf8' });
+        const cwebpOk = !w.error && w.status === 0 && existsSync(webpDest);
+        const choice = chooseEncoding({
+            hq,
+            cwebpAvailable: cwebpOk,
+            pngSize: safeSize(dest),
+            losslessSize: hq && cwebpOk ? safeSize(webpDest) : undefined,
+        });
+        if (choice === 'original') {
+            rmSync(webpDest, { force: true });
+            if (!hq && !cwebpOk) {
+                console.error('snap: cwebp unavailable/failed — keeping the original (brew install webp for q85 WebP sets)');
+            }
+        }
+        else {
+            rmSync(dest);
+            name = webpName;
+            dest = webpDest;
+        }
+    }
+    const ctx = shotContext(args);
+    // iOS knows its simulator — auto-fill the device name when the resolution
+    // path already learned it (zero extra xcrun calls).
+    if (surface === 'ios' && iosSimName && !ctx.device?.device) {
+        ctx.device = { ...ctx.device, device: iosSimName };
+    }
+    const { count } = appendShot(root, {
+        file: `${day}/${name}`,
+        surface,
+        route,
+        note,
+        label: strArg(args.label) || undefined,
+        title: strArg(args.title) || undefined,
+        action: strArg(args.action) || undefined,
+        hq: hq || undefined,
+        ts: new Date().toISOString(),
+        ...ctx,
+    });
+    maybeWarnOffline(root);
+    // (shot N) = 1-based manifest position — what embed-shots/artifact-from-set --select
+    // addresses. The filename NN restarts per dated dir; the position never does.
+    console.log(`saved ${dest}  (shot ${count})`);
+    if (existsSync(vitrinkaCfgPath(root))) {
+        // Detached, fire-and-forget: the harness gets no background task; the next snap/push backfills.
+        spawn(process.execPath, [CLI_PATH, 'push', '--root', root], { detached: true, stdio: 'ignore' }).unref();
+        console.log(`share ${shareUrl(loadVitrinkaCfg(root))}`);
+    }
+    else {
+        console.log(`(no ${vitrinkaCfgPath(root)} — run remote-init to publish; shot saved locally)`);
+    }
+    console.log('NOW READ THE IMAGE TO VERIFY');
+}
+// ---------- embed-shots: manifest shots → resized JPEG data URIs in one data.json ----------
+// "1,3-5" → [1,3,4,5] — 1-based manifest positions, deduped, ascending.
+export function parseSelect(spec, count) {
+    const picked = new Set();
+    for (const tok of String(spec).split(',')) {
+        const t = tok.trim();
+        if (!t)
+            continue;
+        const m = t.match(/^(\d+)(?:-(\d+))?$/);
+        if (!m)
+            throw new Error(`--select: bad token ${JSON.stringify(t)} (expected N or A-B)`);
+        const a = Number(m[1]);
+        const b = m[2] === undefined ? a : Number(m[2]);
+        if (a < 1 || b < a)
+            throw new Error(`--select: bad range "${t}"`);
+        if (b > count)
+            throw new Error(`--select: ${b} out of range (set has ${count} shots)`);
+        for (let i = a; i <= b; i++)
+            picked.add(i);
+    }
+    if (!picked.size)
+        throw new Error('--select: empty selection');
+    return [...picked].sort((x, y) => x - y);
+}
+export function mimeFor(file) {
+    const e = extname(String(file)).toLowerCase();
+    if (e === '.png')
+        return 'image/png';
+    if (e === '.jpg' || e === '.jpeg')
+        return 'image/jpeg';
+    if (e === '.webp')
+        return 'image/webp';
+    if (e === '.gif')
+        return 'image/gif';
+    return 'application/octet-stream';
+}
+function embedShots(root, opts) {
+    const m = loadManifest(root);
+    if (!m.shots.length)
+        fail(`embed-shots: no shots in ${manifestPathOf(root)}`, 2);
+    let indices;
+    try {
+        indices = opts.select ? parseSelect(opts.select, m.shots.length) : m.shots.map((_, i) => i + 1);
+    }
+    catch (e) {
+        fail(`embed-shots: ${e.message}`, 2);
+    }
+    const tmp = mkdtempSync(join(tmpdir(), 'vitrinka-embed-'));
+    let sipsMissing = false;
+    const shots = [];
+    try {
+        for (const i of indices) {
+            const s = m.shots[i - 1];
+            const srcPath = join(root, s.file);
+            if (!existsSync(srcPath))
+                fail(`embed-shots: shot ${i} file missing: ${srcPath} (manifest and folder out of sync)`);
+            let src = '';
+            if (!sipsMissing) {
+                const outPath = join(tmp, `${i}.jpg`);
+                const r = spawnSync('sips', [
+                    '-Z', String(opts.size),
+                    '-s', 'format', 'jpeg',
+                    '-s', 'formatOptions', String(opts.quality),
+                    srcPath, '--out', outPath,
+                ], { encoding: 'utf8' });
+                if (r.error && r.error.code === 'ENOENT') {
+                    sipsMissing = true; // no sips (non-macOS): embed originals, warn once
+                    console.error('embed-shots: sips not found — embedding original files unresized');
+                }
+                else if (r.error) {
+                    throw new Error(`embed-shots: sips failed: ${r.error.message}`);
+                }
+                else if (r.status !== 0) {
+                    throw new Error(`embed-shots: sips failed on ${srcPath}: ${(r.stderr || '').trim()}`);
+                }
+                else {
+                    src = `data:image/jpeg;base64,${readFileSync(outPath).toString('base64')}`;
+                }
+            }
+            if (sipsMissing) {
+                src = `data:${mimeFor(s.file)};base64,${readFileSync(srcPath).toString('base64')}`;
+            }
+            shots.push({ label: s.label, title: s.title, route: s.route, note: s.note, ts: s.ts, src });
+        }
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+    const data = { journey: m.journey && typeof m.journey === 'object' ? m.journey : {}, shots };
+    const outAbs = resolve(opts.out);
+    mkdirSync(dirname(outAbs), { recursive: true });
+    writeFileSync(outAbs, JSON.stringify(data, null, 2) + '\n');
+    return { out: outAbs, count: shots.length, sipsMissing };
+}
+function embedShotsCmd(root, args) {
+    const out = strArg(args.out);
+    if (!out) {
+        console.error('embed-shots: --out <dir>/data.json is required');
+        process.exit(2);
+    }
+    const res = embedShots(root, {
+        select: strArg(args.select) || undefined,
+        size: numArg(args.size, 720, '--size'),
+        quality: numArg(args.quality, 85, '--quality'),
+        out,
+    });
+    console.log(`embedded ${res.count} shots → ${res.out}${res.sipsMissing ? ' (originals — sips unavailable)' : ''}`);
+}
+// ---------- artifact scaffolding ----------
+function ensureGitIgnored(projectDir, entry) {
+    const top = git(['rev-parse', '--show-toplevel'], projectDir) || projectDir;
+    const gi = join(top, '.gitignore');
+    const cur = existsSync(gi) ? readFileSync(gi, 'utf8') : '';
+    const bare = entry.replace(/\/$/, '');
+    const has = cur.split(/\r?\n/).some((l) => {
+        const t = l.trim();
+        return t === entry || t === bare || t === `/${entry}` || t === `/${bare}`;
+    });
+    if (!has)
+        writeFileSync(gi, cur + (cur && !cur.endsWith('\n') ? '\n' : '') + entry + '\n');
+}
+// Shared <head> + module prologue: pinned import map (kit-1 / zipstore-1 are versioned,
+// immutable vendor files), tailwind, htm binding. xyflow stays commented until needed.
+function scaffoldHead(title) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<script type="importmap">
+{ "imports": {
+    "react": "/vendor/react.mjs",
+    "react-dom/client": "/vendor/react-dom-client.mjs",
+    "htm": "/vendor/htm.mjs",
+    "kit-1": "/vendor/kit-1.mjs",
+    "zipstore-1": "/vendor/zipstore-1.mjs"
+} }
+</script>
+<!-- Flow diagram? Add inside "imports" above:
+       "@xyflow/react": "/vendor/xyflow-react.mjs"
+     and add to <head>:
+       <link rel="stylesheet" href="/vendor/xyflow-react.css">
+-->
+<script src="/vendor/tailwind.js"></script>
+</head>
+<body class="bg-[#f6f2ee] text-[#101113] antialiased">
+<div id="root"></div>
+<script type="module">
+import React from 'react';
+import { createRoot } from 'react-dom/client';
+import htm from 'htm';
+import { Hero, Chips, Section, ShotCard, StatRow, DownloadAllButton } from 'kit-1';
+const html = htm.bind(React.createElement);
+`;
+}
+const DATA_FETCH = `
+const res = await fetch('./data.json');
+if (!res.ok) throw new Error('data.json: HTTP ' + res.status);
+const DATA = await res.json();
+`;
+// The authored title is emitted as an htm interpolation (title=\${"…"}), never as a quoted
+// attribute — htm has no escape for an inner '"', which would truncate the Hero prop.
+function blankScaffold(title, hasData) {
+    return scaffoldHead(title) + (hasData ? DATA_FETCH : `
+// TODO: inline your data here (or write a sibling ./data.json and fetch it)
+const DATA = {};
+`) + `
+function App() {
+  return html\`<main class="mx-auto max-w-5xl px-8 py-12">
+    <\${Hero} kicker="TODO" title=\${${JSON.stringify(title)}} accent="TODO accent phrase" intro="TODO 1-2 sentence intro" />
+    <!-- TODO: compose the report from kit-1: Section, ShotCard, StatRow, Chips, DownloadAllButton -->
+  </main>\`;
+}
+createRoot(document.getElementById('root')).render(html\`<\${App} />\`);
+</script>
+</body>
+</html>
+`;
+}
+function composedScaffold(title, zipName) {
+    return scaffoldHead(title) + DATA_FETCH + `
+const kebab = (s) => String(s || 'shot').normalize('NFKD').replace(/[\\u0300-\\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'shot';
+const extOf = (src) => String(src).startsWith('data:image/png') ? '.png' : '.jpg';
+const files = DATA.shots.map((s, i) => ({
+  name: String(i + 1).padStart(2, '0') + '-' + kebab(s.title || s.route) + extOf(s.src),
+  dataUri: s.src,
+}));
+
+function App() {
+  const j = DATA.journey || {};
+  return html\`<main class="mx-auto max-w-5xl px-8 py-12">
+    <\${Hero} kicker=\${j.kicker} title=\${j.title} accent=\${j.accent} intro=\${j.intro} chips=\${j.chips} />
+
+    <!-- TODO: opening narrative — what this session shipped and why it matters -->
+
+    \${DATA.shots.map((s, i) => html\`
+      <\${Section} key=\${i} label=\${s.label} title=\${s.title} note=\${s.note}>
+        <\${ShotCard} src=\${s.src} alt=\${s.title || s.route || 'screenshot'} caption=\${s.note} />
+      <//>
+    \`)}
+
+    <!-- TODO: closing narrative / findings (StatRow and Chips from kit-1 are available) -->
+
+    <div class="mt-12">
+      <\${DownloadAllButton} files=\${files} zipName=${JSON.stringify(zipName)} />
+    </div>
+  </main>\`;
+}
+createRoot(document.getElementById('root')).render(html\`<\${App} />\`);
+</script>
+</body>
+</html>
+`;
+}
+function artifactInitCmd(args) {
+    const slugRaw = strArg(args.slug);
+    if (!slugRaw) {
+        console.error('artifact-init: --slug <slug> is required');
+        process.exit(2);
+    }
+    const slug = sanitizeSeg(slugRaw, 64);
+    assertValidKey(slug, 'artifact-init'); // the slug becomes the set key — fail before any writes
+    const kind = strArg(args.kind) || 'report';
+    const title = strArg(args.title) || slug;
+    const dir = resolve('.artifacts', slug);
+    const indexPath = join(dir, 'index.html');
+    if (existsSync(indexPath)) {
+        console.error(`artifact-init: ${indexPath} already exists — edit it in place (or remove the dir to re-scaffold)`);
+        process.exit(2);
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(indexPath, blankScaffold(title, existsSync(join(dir, 'data.json'))));
+    ensureGitIgnored(process.cwd(), '.artifacts/');
+    remoteInitCmd(dir, { ...args, key: slug, kind });
+    console.log(`scaffolded ${indexPath}`);
+    console.log(`author the App, then: node ${CLI_PATH} push --root ${dir} --title "<Human title>"`);
+}
+function artifactFromSetCmd(args) {
+    const slugRaw = strArg(args.slug);
+    if (!slugRaw) {
+        console.error('artifact-from-set: --slug <slug> is required');
+        process.exit(2);
+    }
+    const slug = sanitizeSeg(slugRaw, 64);
+    assertValidKey(slug, 'artifact-from-set'); // the slug becomes the set key — fail before any writes
+    const from = resolve(strArg(args.from) || '.screenshots');
+    const dir = resolve('.artifacts', slug);
+    const indexPath = join(dir, 'index.html');
+    if (existsSync(indexPath)) {
+        console.error(`artifact-from-set: ${indexPath} already exists — edit it in place (or remove the dir to re-scaffold)`);
+        process.exit(2);
+    }
+    mkdirSync(dir, { recursive: true });
+    const res = embedShots(from, {
+        select: strArg(args.select) || undefined,
+        size: numArg(args.size, 720, '--size'),
+        quality: numArg(args.quality, 85, '--quality'),
+        out: join(dir, 'data.json'),
+    });
+    const fromManifest = loadManifest(from);
+    const title = strArg(args.title) || (fromManifest.journey && fromManifest.journey.title) || slug;
+    writeFileSync(indexPath, composedScaffold(title, `${slug}.zip`));
+    ensureGitIgnored(process.cwd(), '.artifacts/');
+    remoteInitCmd(dir, { ...args, key: slug, kind: strArg(args.kind) || 'report' });
+    // Record the source screenshot set (project/branchSlug/key) so push sends ?source= and
+    // vitrinka can cross-link set ↔ artifact both ways.
+    let source = strArg(args.source);
+    if (!source) {
+        if (existsSync(vitrinkaCfgPath(from))) {
+            const c = loadVitrinkaCfg(from);
+            source = `${c.project}/${c.slug}/${c.key}`;
+        }
+        else {
+            console.error(`artifact-from-set: no ${vitrinkaCfgPath(from)} — source set not recorded (pass --source project/branchSlug/key to cross-link)`);
+        }
+    }
+    if (source) {
+        const cfg = loadVitrinkaCfg(dir);
+        cfg.source = source;
+        writeFileSync(vitrinkaCfgPath(dir), JSON.stringify(cfg, null, 2) + '\n');
+    }
+    console.log(`scaffolded ${indexPath} (${res.count} shots embedded${source ? `, source ${source}` : ''})`);
+    console.log(`write the narrative sections, then \`push\`: node ${CLI_PATH} push --root ${dir} --title "<Human title>"`);
+}
+const ROOT_FLAG = { f: '--root', arg: '<dir>', d: 'capture root (default .screenshots)' };
+const BASE_FLAG = { f: '--base', arg: '<url>', d: 'vitrinka base URL (default $VITRINKA_URL or the mesh host)' };
+const CTX_FLAGS = [
+    { f: '--label', arg: '<STAGE>', d: 'journey stage label' },
+    { f: '--title', arg: '<t>', d: 'short human title' },
+    { f: '--action', arg: '<a>', d: 'edge label — the action leading to the NEXT shot' },
+    { f: '--src', arg: '<file>', d: "implementing source file(s) (repeatable or comma-list)" },
+    { f: '--state', arg: '<s>', d: 'app/auth state note' },
+    { f: '--device', arg: '<name>', d: 'device name' },
+    { f: '--viewport', arg: 'WxH[@scale]', d: 'viewport, e.g. 393x852@3' },
+];
+export const COMMANDS = [
+    {
+        name: 'add', summary: 'Append a screenshot to the manifest, rebuild index.html',
+        usage: '--root <dir> --file <rel> --surface <ios|android|web|macos> --route <r> --note <n> [ctx flags]',
+        flags: [ROOT_FLAG, { f: '--file', arg: '<rel>', d: 'screenshot path relative to root (required)' },
+            { f: '--surface', arg: '<ios|android|web|macos>', d: 'platform (default other)' },
+            { f: '--route', arg: '<r>', d: 'app route' }, { f: '--note', arg: '<n>', d: 'caption' }, ...CTX_FLAGS],
+        examples: ['vitrinka add --root .screenshots --file 2026-07-06/01-web-home.png --surface web --route /home --note "landing"'],
+    },
+    { name: 'build', summary: 'Rebuild index.html from the manifest', usage: '--root <dir>', flags: [ROOT_FLAG],
+        examples: ['vitrinka build --root .screenshots'] },
+    {
+        name: 'meta', summary: 'Set the journey header (kicker/title/accent/intro/chips)',
+        usage: '--root <dir> [--kicker <k>] [--title <t>] [--accent <substr>] [--intro <p>] [--chip "K=V" ...]',
+        flags: [ROOT_FLAG, { f: '--kicker', arg: '<k>', d: 'eyebrow kicker' }, { f: '--title', arg: '<t>', d: 'display title' },
+            { f: '--accent', arg: '<substr>', d: 'substring of the title to accent' }, { f: '--intro', arg: '<p>', d: 'intro paragraph' },
+            { f: '--chip', arg: '"K=V"', d: 'meta chip (repeatable)' }],
+        examples: ['vitrinka meta --root .screenshots --kicker "FLOW" --title "Payout flow" --accent "Payout"'],
+    },
+    {
+        name: 'remote-init', summary: 'Create a .vitrinka set config for publishing',
+        usage: '--root <dir> [--base <url>] [--project <p>] [--branch <b>] [--kind <k>] [--key <k>] [--issue <ref>]',
+        flags: [ROOT_FLAG, BASE_FLAG, { f: '--project', arg: '<p>', d: 'project slug (default: main worktree name)' },
+            { f: '--branch', arg: '<b>', d: 'branch (default: current)' }, { f: '--kind', arg: '<k>', d: 'set kind (default screenshots)' },
+            { f: '--key', arg: '<k>', d: 'set key (default: timestamped)' }, { f: '--issue', arg: '<ref>', d: 'linked issue ref' }],
+        dynamic: 'projects',
+        examples: ['vitrinka remote-init --root .screenshots --project fixit --branch main'],
+    },
+    {
+        name: 'push', summary: 'Publish the set to vitrinka (tar+PUT), refresh the index',
+        usage: '--root <dir> [--title <t>] [--name <slug>] [--source <project/branchSlug/key>]',
+        flags: [ROOT_FLAG, { f: '--title', arg: '<t>', d: 'human title (re-sent every push)' },
+            { f: '--name', arg: '<slug>', d: 'name the set after publish (sticky)' },
+            { f: '--source', arg: '<ref>', d: 'cross-link source set project/branchSlug/key' }],
+        examples: ['vitrinka push --root .screenshots --title "Payout flow"'],
+    },
+    {
+        name: 'name', summary: "Set or clear a set's custom URL name",
+        usage: '<project/branchSlug/selector> <new-name> [--base <url>]   (or --clear)',
+        positional: '<project/branchSlug/selector>', dynamic: 'projects', write: true,
+        flags: [BASE_FLAG, { f: '--clear', d: 'clear the custom name instead of setting one' }],
+        examples: ['vitrinka name fixit/main/2 payout-flow', 'vitrinka name fixit/main/payout-flow --clear'],
+    },
+    {
+        name: 'operator', summary: 'Show or set the board-attribution operator persona',
+        usage: '[<name>] [--base <url>]', positional: '[<name>]', flags: [BASE_FLAG],
+        examples: ['vitrinka operator', 'vitrinka operator "Lukáš"'],
+    },
+    {
+        name: 'install', summary: 'Install the PATH shim (+ optional shell completion)',
+        usage: '[--no-completion]', flags: [{ f: '--no-completion', d: 'skip appending the shell-completion line' }],
+        examples: ['vitrinka install'],
+    },
+    {
+        name: 'snap', summary: 'Capture a screenshot → manifest → detached push',
+        usage: '<ios|android|macos|web> [--root <dir>] [--file <path>] --route <r> --note <n> [ctx flags] [--udid <u>] [--region x,y,w,h] [--open <deeplink>] [--settle <seconds>] [--hq]',
+        positional: '<ios|android|macos|web>',
+        flags: [ROOT_FLAG, { f: '--file', arg: '<path>', d: 'adopt an existing image instead of capturing' },
+            { f: '--route', arg: '<r>', d: 'app route (required)' }, { f: '--note', arg: '<n>', d: 'caption (required)' }, ...CTX_FLAGS,
+            { f: '--udid', arg: '<u>', d: 'iOS simulator UDID' }, { f: '--region', arg: 'x,y,w,h', d: 'macOS capture region' },
+            { f: '--open', arg: '<deeplink>', d: 'open a deep link, then settle before capturing' },
+            { f: '--settle', arg: '<seconds>', d: 'wait after --open (default 4)' },
+            { f: '--hq', d: 'full-fidelity marketing asset: no lossy re-encode, no resize (lossless WebP only if smaller)' }],
+        examples: ['vitrinka snap ios --route /home --note "landing"', 'vitrinka snap web --route / --note "hero" --hq'],
+    },
+    {
+        name: 'board-from-set', summary: 'Turn the set into an annotation flow board',
+        usage: '[--root <dir>] [--slug <board>] [--btitle <t>] [--actor <name>]',
+        flags: [ROOT_FLAG, { f: '--slug', arg: '<board>', d: 'board slug (default: set key)' },
+            { f: '--btitle', arg: '<t>', d: 'board title' }, { f: '--actor', arg: '<name>', d: 'override the operator attribution' }],
+        dynamic: 'boards',
+        examples: ['vitrinka board-from-set --root .screenshots'],
+    },
+    {
+        name: 'watch', summary: 'Monitor the work queue (listen v2); auto-scopes to repo+branch, leases the scope (one listener each), one line per new item',
+        usage: '[--board <slug>|--project <p> --branch <b>|--all] [--takeover] [--quiet-grace <sec>] [--once] [--base <url>]',
+        flags: [{ f: '--board', arg: '<slug>', d: 'lease one board (else the repo project+branch is inferred)' },
+            { f: '--project', arg: '<p>', d: 'override the inferred project scope' },
+            { f: '--branch', arg: '<b>', d: 'override the inferred branch scope (with --project)' },
+            { f: '--all', d: 'firehose: observe every board (leases a conflict-free scope, claims nothing)' },
+            { f: '--takeover', d: 'steal an EXPIRED lease (a dead session); never steals a live one' },
+            { f: '--quiet-grace', arg: '<sec>', d: 'drain poll interval (default 5)' },
+            { f: '--once', d: 'single deterministic poll (exit 0 = work, 3 = idle)' }, BASE_FLAG],
+        dynamic: 'boards',
+        examples: ['vitrinka watch', 'vitrinka watch --board payout-flow', 'vitrinka watch --takeover'],
+    },
+    {
+        name: 'index', summary: 'Build + push the file/route autocomplete index',
+        usage: '[--root <dir>] [--base <url>] [--project <p>]',
+        flags: [ROOT_FLAG, BASE_FLAG, { f: '--project', arg: '<p>', d: 'project slug (default: worktree name)' }],
+        dynamic: 'projects',
+        examples: ['vitrinka index --root .screenshots'],
+    },
+    {
+        name: 'embed-shots', summary: 'Embed manifest shots as resized JPEG data URIs → data.json',
+        usage: '[--root <dir>] [--select 1,3-5] [--size 720] [--quality 85] --out <dir>/data.json',
+        flags: [ROOT_FLAG, { f: '--select', arg: '1,3-5', d: '1-based shot selection' }, { f: '--size', arg: '<px>', d: 'longest edge (default 720)' },
+            { f: '--quality', arg: '<q>', d: 'JPEG quality (default 85)' }, { f: '--out', arg: '<file>', d: 'output data.json (required)' }],
+        examples: ['vitrinka embed-shots --root .screenshots --out .artifacts/x/data.json'],
+    },
+    {
+        name: 'artifact-init', summary: 'Scaffold a blank artifact report + set config',
+        usage: '--slug <s> [--kind report] [--title <t>] [--base <url>]',
+        flags: [{ f: '--slug', arg: '<s>', d: 'artifact slug (= set key, required)' }, { f: '--kind', arg: '<k>', d: 'set kind (default report)' },
+            { f: '--title', arg: '<t>', d: 'artifact title' }, BASE_FLAG],
+        examples: ['vitrinka artifact-init --slug payout-report --title "Payout report"'],
+    },
+    {
+        name: 'artifact-from-set', summary: 'Scaffold an artifact report from a screenshot set',
+        usage: '--slug <s> [--from .screenshots] [--select 1,3-5] [--title <t>] [--kind report] [--source <ref>]',
+        flags: [{ f: '--slug', arg: '<s>', d: 'artifact slug (= set key, required)' }, { f: '--from', arg: '<dir>', d: 'source set root (default .screenshots)' },
+            { f: '--select', arg: '1,3-5', d: '1-based shot selection' }, { f: '--title', arg: '<t>', d: 'artifact title' },
+            { f: '--kind', arg: '<k>', d: 'set kind (default report)' }, { f: '--source', arg: '<ref>', d: 'source set ref for cross-linking' }, BASE_FLAG],
+        examples: ['vitrinka artifact-from-set --slug payout-report --from .screenshots'],
+    },
+    // Meta commands — documented + completable, kept out of the compact usage grid.
+    { name: 'help', summary: 'Show help (all commands, or one command in detail)', usage: '[<command>]', positional: '[<command>]', hidden: true,
+        examples: ['vitrinka help', 'vitrinka help snap'] },
+    { name: 'completion', summary: 'Print a shell-completion script (zsh|bash)', usage: '<zsh|bash>', positional: '<zsh|bash>', hidden: true,
+        examples: ['vitrinka completion zsh >> ~/.zshrc'] },
+    { name: 'ai', summary: 'Ask claude for a vitrinka command in natural language', usage: '"<ask>" [--yes]', positional: '"<ask>"', hidden: true,
+        flags: [{ f: '--yes', d: 'run the proposed command without a confirm prompt' }],
+        examples: ['vitrinka ai "publish the current screenshots as a flow board"'] },
+];
+const COMMAND_MAP = Object.fromEntries(COMMANDS.map((c) => [c.name, c]));
+export const COMMAND_NAMES = COMMANDS.map((c) => c.name);
+// ---------- help rendering (man-page-ish; respects NO_COLOR) ----------
+function useColor() {
+    return !process.env.NO_COLOR && !!process.stdout.isTTY;
+}
+function bold(s) { return useColor() ? `\x1b[1m${s}\x1b[0m` : s; }
+function dim(s) { return useColor() ? `\x1b[2m${s}\x1b[0m` : s; }
+// renderCompactUsage — the fallback shown on unknown command / bad args.
+export function renderCompactUsage() {
+    const rows = COMMANDS.filter((c) => !c.hidden).map((c) => `  vitrinka ${c.name} ${c.usage}`);
+    return `Usage:\n${rows.join('\n')}\n\nRun "vitrinka help <command>" for details, or "vitrinka ai \"<ask>\"".`;
+}
+// Backwards-compatible binding: dispatch fallback + the gallery.mjs shim test
+// still reference a `Usage:`-headed string that names every command.
+const USAGE = renderCompactUsage();
+export function renderFullHelp() {
+    const lines = [];
+    lines.push(bold('vitrinka') + ' — screenshot sets, artifacts, flow boards, and the work queue.');
+    lines.push('');
+    lines.push(bold('USAGE'));
+    lines.push('  vitrinka <command> [flags]');
+    lines.push('');
+    lines.push(bold('COMMANDS'));
+    const width = Math.max(...COMMANDS.filter((c) => !c.hidden).map((c) => c.name.length));
+    for (const c of COMMANDS.filter((c) => !c.hidden)) {
+        lines.push(`  ${c.name.padEnd(width)}  ${c.summary}`);
+    }
+    lines.push('');
+    lines.push(bold('MORE'));
+    const meta = COMMANDS.filter((c) => c.hidden);
+    const mw = Math.max(...meta.map((c) => c.name.length));
+    for (const c of meta)
+        lines.push(`  ${c.name.padEnd(mw)}  ${c.summary}`);
+    lines.push('');
+    lines.push(dim('  Env: VITRINKA_URL, VITRINKA_TOKEN, VITRINKA_OPERATOR, NO_COLOR, VITRINKA_NO_AI=1, CLAUDE_BIN'));
+    return lines.join('\n');
+}
+export function renderCmdHelp(name) {
+    const c = COMMAND_MAP[name];
+    if (!c)
+        return renderCompactUsage();
+    const lines = [];
+    lines.push(`${bold('vitrinka ' + c.name)} — ${c.summary}`);
+    lines.push('');
+    lines.push(bold('USAGE'));
+    lines.push(`  vitrinka ${c.name} ${c.usage}`);
+    if (c.flags && c.flags.length) {
+        lines.push('');
+        lines.push(bold('FLAGS'));
+        const rows = c.flags.map((f) => ({ left: `${f.f}${f.arg ? ' ' + f.arg : ''}`, d: f.d }));
+        const w = Math.max(...rows.map((r) => r.left.length));
+        for (const r of rows)
+            lines.push(`  ${r.left.padEnd(w)}  ${r.d}`);
+    }
+    if (c.examples && c.examples.length) {
+        lines.push('');
+        lines.push(bold('EXAMPLES'));
+        for (const e of c.examples)
+            lines.push(`  ${e}`);
+    }
+    return lines.join('\n');
+}
+// nearestCommand — plain edit-distance "did you mean" (no AI). Returns '' when
+// nothing is within a small threshold.
+export function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    const dp = Array.from({ length: m + 1 }, (_, i) => [i, ...Array(n).fill(0)]);
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1]
+                : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+export function nearestCommand(input) {
+    let best = '', bestD = Infinity;
+    for (const name of COMMAND_NAMES) {
+        const d = levenshtein(input, name);
+        if (d < bestD) {
+            bestD = d;
+            best = name;
+        }
+    }
+    // Suggest only a genuinely-close miss (≤ a third of the name length, min 2).
+    return bestD <= Math.max(2, Math.ceil(best.length / 3)) ? best : '';
+}
+// ---------- shell completion ----------
+// completionScript embeds the command names + per-command flags at generation
+// time; slug-shaped positionals shell out to the hidden `vitrinka __complete`.
+export function completionScript(shell) {
+    const names = COMMANDS.filter((c) => !c.hidden || c.name === 'help').map((c) => c.name).concat(['help', 'completion', 'ai']);
+    const uniqNames = [...new Set(names)];
+    const flagsFor = (c) => (c.flags || []).map((f) => f.f).join(' ');
+    const dynamicCmds = COMMANDS.filter((c) => c.dynamic).map((c) => c.name);
+    if (shell === 'bash') {
+        const cases = COMMANDS.filter((c) => c.flags && c.flags.length)
+            .map((c) => `      ${c.name}) __vitrinka_flags="${flagsFor(c)}" ;;`).join('\n');
+        return `# vitrinka bash completion — add to ~/.bashrc:
+#   eval "$(vitrinka completion bash)"
+_vitrinka() {
+  local cur prev cmd
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  local cmds="${uniqNames.join(' ')}"
+  if [ "$COMP_CWORD" -eq 1 ]; then
+    COMPREPLY=( $(compgen -W "$cmds" -- "$cur") ); return
+  fi
+  cmd="\${COMP_WORDS[1]}"
+  if [[ "$cur" == -* ]]; then
+    local __vitrinka_flags=""
+    case "$cmd" in
+${cases}
+    esac
+    COMPREPLY=( $(compgen -W "$__vitrinka_flags" -- "$cur") ); return
+  fi
+  case " ${dynamicCmds.join(' ')} " in
+    *" $cmd "*)
+      local dyn; dyn="$(vitrinka __complete "$cmd" "$cur" 2>/dev/null)"
+      COMPREPLY=( $(compgen -W "$dyn" -- "$cur") ) ;;
+  esac
+}
+complete -F _vitrinka vitrinka
+`;
+    }
+    if (shell === 'zsh') {
+        const cases = COMMANDS.filter((c) => c.flags && c.flags.length)
+            .map((c) => `      ${c.name}) flags="${flagsFor(c)}" ;;`).join('\n');
+        return `# vitrinka zsh completion — add to ~/.zshrc:
+#   eval "$(vitrinka completion zsh)"
+_vitrinka() {
+  local cmds=(${uniqNames.join(' ')})
+  if (( CURRENT == 2 )); then
+    compadd -- $cmds; return
+  fi
+  local cmd="\${words[2]}"
+  local cur="\${words[CURRENT]}"
+  if [[ "$cur" == -* ]]; then
+    local flags=""
+    case "$cmd" in
+${cases}
+    esac
+    compadd -- \${=flags}; return
+  fi
+  case " ${dynamicCmds.join(' ')} " in
+    *" $cmd "*)
+      local dyn; dyn=("\${(f)$(vitrinka __complete "$cmd" "$cur" 2>/dev/null)}")
+      compadd -- $dyn ;;
+  esac
+}
+compdef _vitrinka vitrinka
+`;
+    }
+    fail(`completion: unsupported shell ${JSON.stringify(shell)} — expected zsh or bash`, 2);
+}
+function completionCmd(rest) {
+    const shell = rest.find((a) => !a.startsWith('--')) || '';
+    if (!shell)
+        fail('completion: expected a shell — zsh or bash', 2);
+    process.stdout.write(completionScript(shell));
+}
+function resolveBase(args) {
+    return resolveBaseUrl(strArg(args.base));
+}
+// fetchCandidates lists slug candidates of `kind` from the server. Silent [] on
+// any failure — completion and fuzzy resolution must never hang or error.
+export async function fetchCandidates(base, kind, timeoutMs = 1500) {
+    const url = kind === 'boards' ? `${base}/api/v1/boards` : `${base}/api/v1/projects`;
+    let data;
+    try {
+        data = await watchFetchJson(url, timeoutMs);
+    }
+    catch {
+        return []; // unreachable / non-2xx — completion stays empty (expected, by design)
+    }
+    const rows = kind === 'boards' ? data?.boards : data?.projects;
+    if (!Array.isArray(rows))
+        return [];
+    return rows.map((r) => String(kind === 'boards' ? r?.slug : r?.project)).filter(Boolean);
+}
+// __complete — the hidden dynamic-candidate endpoint the shell scripts call.
+// Prints newline-separated matches; ALWAYS exits 0 with no output on any
+// failure so a shell completion never blocks.
+async function completeDynamicCmd(rest) {
+    const cmd = rest[0] || '';
+    const partial = rest[1] || '';
+    const spec = COMMAND_MAP[cmd];
+    if (!spec?.dynamic)
+        return; // nothing dynamic for this command → silent
+    const cands = await fetchCandidates(resolveBase({}), spec.dynamic);
+    for (const c of cands)
+        if (c.startsWith(partial))
+            process.stdout.write(c + '\n');
+}
+// ---------- AI assistance (local claude CLI; degrades gracefully) ----------
+// aiEnabled — the single kill switch for all three AI paths.
+function aiEnabled() { return process.env.VITRINKA_NO_AI !== '1'; }
+// askClaude runs the LOCAL claude binary ($CLAUDE_BIN then PATH) in print mode
+// with --model haiku, feeding `prompt` on stdin. Returns the trimmed stdout on a
+// clean exit, or null on ANY failure (disabled, no binary, non-zero, timeout) —
+// every caller degrades to a single clear line, never a crash.
+export function askClaude(prompt, opts = {}) {
+    if (!aiEnabled())
+        return Promise.resolve(null);
+    const bin = process.env.CLAUDE_BIN || 'claude';
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        const done = (v) => { if (!settled) {
+            settled = true;
+            resolvePromise(v);
+        } };
+        let child;
+        try {
+            child = spawn(bin, ['-p', '--model', 'haiku'], { stdio: ['pipe', 'pipe', 'ignore'] });
+        }
+        catch {
+            return done(null); // spawn threw synchronously (e.g. bad bin) — degrade
+        }
+        const timer = setTimeout(() => { try {
+            child.kill('SIGKILL');
+        }
+        catch { /* already gone */ } done(null); }, opts.timeoutMs ?? 6000);
+        let out = '';
+        child.stdout?.setEncoding('utf8');
+        child.stdout?.on('data', (d) => { out += d; });
+        child.on('error', () => { clearTimeout(timer); done(null); }); // ENOENT: no claude on PATH
+        child.on('close', (code) => { clearTimeout(timer); done(code === 0 ? out.trim() : null); });
+        child.stdin?.on('error', () => { });
+        child.stdin?.end(prompt);
+    });
+}
+// extractCommandLine pulls a single proposed command out of claude's reply:
+// the first non-empty line of the first fenced block, else the first line that
+// starts with "vitrinka". A leading shell prompt ("$ ") is stripped.
+export function extractCommandLine(reply) {
+    const fence = /```[a-zA-Z]*\n([\s\S]*?)```/.exec(reply);
+    const scan = (text) => {
+        for (const raw of text.split('\n')) {
+            const line = raw.trim().replace(/^\$\s+/, '');
+            if (line)
+                return line;
+        }
+        return '';
+    };
+    if (fence) {
+        const inside = scan(fence[1]);
+        if (inside)
+            return inside;
+    }
+    for (const raw of reply.split('\n')) {
+        const line = raw.trim().replace(/^\$\s+/, '');
+        if (/^vitrinka\b/.test(line))
+            return line;
+    }
+    return scan(reply);
+}
+// SHELL_META rejects any command line carrying shell control operators — the
+// proposal must be a plain argv, never a pipeline/chain/substitution.
+const SHELL_META = /[|;&><`]|\$\(|\$\{|\n/;
+// tokenizeArgv splits a command line into argv honoring single/double quotes but
+// interpreting NO shell metacharacters. Returns null on an unbalanced quote.
+export function tokenizeArgv(line) {
+    const out = [];
+    let cur = '', quote = '', started = false;
+    for (const c of line) {
+        if (quote) {
+            if (c === quote)
+                quote = '';
+            else
+                cur += c;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(c)) {
+            if (started || cur) {
+                out.push(cur);
+                cur = '';
+                started = false;
+            }
+            continue;
+        }
+        cur += c;
+        started = true;
+    }
+    if (quote)
+        return null;
+    if (started || cur)
+        out.push(cur);
+    return out;
+}
+// validateProposal turns claude's UNTRUSTED command line into a safe, internally
+// dispatchable argv, or rejects it. The ONLY accepted shape is
+// `vitrinka <known-subcommand> …` with no shell metacharacters; `ai` is refused
+// to prevent recursion. The command is never shell-eval'd — the caller dispatches
+// the returned argv through the same in-process switch.
+export function validateProposal(line) {
+    if (!line)
+        return { ok: false, reason: 'empty proposal' };
+    if (SHELL_META.test(line))
+        return { ok: false, reason: 'contains shell metacharacters' };
+    const argv = tokenizeArgv(line);
+    if (!argv || argv.length === 0)
+        return { ok: false, reason: 'unparseable command line' };
+    if (argv[0] !== 'vitrinka')
+        return { ok: false, reason: `argv[0] is not "vitrinka" (got ${JSON.stringify(argv[0])})` };
+    const sub = argv[1] || '';
+    if (!COMMAND_NAMES.includes(sub))
+        return { ok: false, reason: `unknown subcommand ${JSON.stringify(sub)}` };
+    if (sub === 'ai')
+        return { ok: false, reason: 'refusing to recurse into `ai`' };
+    // Registry-validate the FLAGS too: a hallucinated flag must be rejected
+    // here, not silently ignored (or misread) by the command at runtime.
+    const spec = COMMANDS.find((c) => c.name === sub);
+    const known = new Set((spec?.flags ?? []).map((fl) => fl.f));
+    for (const tok of argv.slice(2)) {
+        if (!tok.startsWith('--'))
+            continue; // positional / flag value
+        const flag = tok.includes('=') ? tok.slice(0, tok.indexOf('=')) : tok;
+        if (!known.has(flag))
+            return { ok: false, reason: `unknown flag ${JSON.stringify(flag)} for ${sub}` };
+    }
+    return { ok: true, sub, argv };
+}
+// confirmYN prompts on stderr and reads one line from stdin. Non-interactive
+// (no TTY) without an explicit --yes defaults to NO — never auto-runs.
+async function confirmYN(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const ans = await new Promise((res) => rl.question(`${question} [y/N] `, res));
+    rl.close();
+    return /^y(es)?$/i.test(ans.trim());
+}
+// aiCmd: natural-language → ONE proposed vitrinka command → confirm → dispatch
+// INTERNALLY (never a shell). claude's output is untrusted: parsed, registry-
+// validated, and only then run through the same in-process switch.
+async function aiCmd(rest, args) {
+    if (!aiEnabled())
+        fail('ai: disabled (VITRINKA_NO_AI=1)', 1);
+    const ask = positionals(rest).slice(1).join(' ').trim() || strArg(args.ask);
+    if (!ask)
+        fail('ai: expected a natural-language request, e.g. vitrinka ai "publish these as a flow board"', 2);
+    const cwd = process.cwd();
+    const repo = originRepo(cwd) || basename(mainWorktreeTop(cwd) || cwd);
+    const base = resolveBase(args);
+    const operator = readOperator(true) || '(unset)';
+    const prompt = [
+        'You translate a natural-language request into ONE vitrinka CLI command.',
+        'Output ONLY the command, on a single line, inside a ```sh fenced block. No prose, no explanation.',
+        'The command MUST start with "vitrinka " and use only the documented subcommands and flags below.',
+        '',
+        '# Context',
+        `cwd repo: ${repo}`,
+        `base URL: ${base}`,
+        `operator: ${operator}`,
+        '',
+        '# vitrinka help',
+        renderFullHelpPlain(),
+        '',
+        '# Request',
+        ask,
+    ].join('\n');
+    const reply = await askClaude(prompt, { timeoutMs: 20_000 });
+    if (reply == null) {
+        fail('ai: claude unavailable (no `claude` on PATH, or non-zero exit). Set $CLAUDE_BIN, or run the command yourself.', 1);
+    }
+    const line = extractCommandLine(reply);
+    const proposal = validateProposal(line);
+    if (!proposal.ok) {
+        console.error(`ai: rejected claude's suggestion (${proposal.reason}). Raw suggestion:`);
+        console.error(`  ${line || '(none)'}`);
+        process.exit(1);
+    }
+    console.log(`proposed: ${proposal.argv.join(' ')}`);
+    if (args.yes !== true) {
+        const ok = await confirmYN('run it?');
+        if (!ok) {
+            console.error('ai: cancelled');
+            process.exit(0);
+        }
+    }
+    // Dispatch the vetted argv through the SAME in-process switch (no shell eval).
+    await runSub(proposal.argv.slice(1));
+}
+// renderFullHelpPlain — the full help with color forced off (for the AI prompt).
+function renderFullHelpPlain() {
+    const rows = COMMANDS.map((c) => `  vitrinka ${c.name} ${c.usage}`);
+    const detail = COMMANDS.filter((c) => c.flags && c.flags.length).map((c) => {
+        const fl = (c.flags || []).map((f) => `    ${f.f}${f.arg ? ' ' + f.arg : ''}  ${f.d}`).join('\n');
+        return `${c.name}:\n${fl}`;
+    }).join('\n');
+    return `Commands:\n${rows.join('\n')}\n\nFlags:\n${detail}`;
+}
+// ---------- AI fuzzy slug resolution (read: auto; write: confirm) ----------
+// resolveFuzzy maps a possibly-fuzzy slug to a real one of `kind`. Exact match →
+// returned as-is. Otherwise the live candidate list is fetched and claude picks
+// the intended slug; for READ commands the resolution is applied automatically
+// (announced on stderr), for WRITE commands it is confirmed first (unless --yes).
+// No candidates / ambiguous / AI unavailable → the top candidates are listed and
+// the process exits 1.
+export async function resolveFuzzy(input, kind, opts) {
+    const cands = await fetchCandidates(opts.base, kind);
+    if (cands.includes(input))
+        return input;
+    if (cands.length === 0) {
+        fail(`no matching ${kind.replace(/s$/, '')} for ${JSON.stringify(input)} (server returned no candidates)`, 1);
+    }
+    const prompt = [
+        `From this list of ${kind}, pick the ONE that best matches the user's fuzzy input.`,
+        'Output ONLY the exact chosen value on a single line, nothing else. If none is a clear match, output NONE.',
+        '', `Input: ${input}`, '', 'Candidates:', ...cands.map((c) => `- ${c}`),
+    ].join('\n');
+    const reply = await askClaude(prompt, { timeoutMs: 8000 });
+    const picked = (reply || '').split('\n').map((s) => s.trim()).find(Boolean) || '';
+    if (!picked || picked === 'NONE' || !cands.includes(picked)) {
+        console.error(`could not confidently resolve ${JSON.stringify(input)} — candidates:`);
+        for (const c of cands.slice(0, 10))
+            console.error(`  ${c}`);
+        process.exit(1);
+    }
+    console.error(`resolved "${input}" → ${picked}`);
+    if (opts.write && !opts.yes) {
+        const ok = await confirmYN(`use "${picked}"?`);
+        if (!ok) {
+            console.error('cancelled');
+            process.exit(0);
+        }
+    }
+    return picked;
+}
+// emitHint prints ONE claude-authored `hint:` line AFTER a command's own error
+// output (usage error / 4xx). Capped short; prints nothing on timeout / no
+// claude / AI disabled — the hint is strictly additive, never blocking.
+async function emitHint(cmdline, errorText, helpSection) {
+    if (!aiEnabled())
+        return;
+    const prompt = [
+        'A vitrinka CLI command just failed. In ONE short line, suggest the single most likely fix.',
+        'Output ONLY that line, prefixed with "hint: ". No other prose.',
+        '', '# Command', cmdline, '', '# Error', errorText, '', '# Relevant help', helpSection,
+    ].join('\n');
+    const reply = await askClaude(prompt, { timeoutMs: 6000 });
+    if (!reply)
+        return;
+    const line = reply.split('\n').map((s) => s.trim()).find(Boolean) || '';
+    if (!line)
+        return;
+    process.stderr.write((line.startsWith('hint:') ? line : `hint: ${line}`) + '\n');
+}
+// board-from-set — the flow-visualizer one-shot: turn THIS session's set into a
+// board where shots are laid out as the user flow (serpentine, action-labeled
+// arrows). Board slug defaults to the set key; re-running appends the newest
+// import below the existing content (server behavior).
+async function boardFromSetCmd(root, args) {
+    if (!existsSync(vitrinkaCfgPath(root))) {
+        console.error(`board-from-set: no ${vitrinkaCfgPath(root)} — run remote-init first`);
+        process.exit(2);
+    }
+    const cfg = loadVitrinkaCfg(root);
+    const slug = (strArg(args.slug) || cfg.key).toLowerCase();
+    const title = strArg(args.btitle) || strArg(args.title) || '';
+    const headers = { 'Content-Type': 'application/json' };
+    const token = readToken();
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    // Attribute the board + its imported cards to the operator (or --actor).
+    const actor = actorFor(args);
+    if (actor)
+        headers['X-Board-Actor'] = actor;
+    const create = await fetch(`${cfg.base}/api/v1/boards`, {
+        method: 'POST', headers, body: JSON.stringify({ slug, title }),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!create.ok && create.status !== 409) { // 409 = board exists → reuse
+        console.error(`board-from-set: create board failed: ${create.status} ${await create.text()}`);
+        process.exit(1);
+    }
+    const imp = await fetch(`${cfg.base}/api/v1/boards/${encodeURIComponent(slug)}/import-set`, {
+        method: 'POST', headers,
+        body: JSON.stringify({ project: cfg.project, branch: cfg.slug, selector: cfg.key }),
+        signal: AbortSignal.timeout(60_000),
+    });
+    if (!imp.ok) {
+        console.error(`board-from-set: import failed: ${imp.status} ${await imp.text()}`);
+        process.exit(1);
+    }
+    const out = await imp.json();
+    console.log(`flow board: ${cfg.base}/boards/${slug}  (${out.cards.length} cards, ${out.edges.length} edges)`);
+    // The board is about to be annotated — make sure its autocomplete index is fresh.
+    await pushProjectIndex(dirname(root), cfg.base, cfg.project);
+}
+// announceLine renders the single stdout line for one work item:
+//   №<id> [<intent>] <board>: <prompt, single line, ≤100 chars>
+export function announceLine(it) {
+    const intent = it.intent === 'other' && it.intentOther ? it.intentOther : (it.intent || 'other');
+    const board = it.board || '?';
+    const prompt = String(it.prompt ?? '').replace(/\s+/g, ' ').trim();
+    const short = prompt.length > 100 ? prompt.slice(0, 100) + '…' : prompt;
+    return `№${it.id} [${intent}] ${board}: ${short}`;
+}
+// computeAnnouncements is the watermark/diff core (PURE — unit-tested without
+// HTTP). Given the previously-announced OPEN items (id → last status/updatedAt)
+// and the CURRENT open queue, it returns the lines to print for genuinely-new
+// work plus the next watermark map. An item is "new" when it wasn't announced
+// before, OR its status/updatedAt changed (re-queue / prompt revision). An item
+// that LEFT the open queue simply drops from nextMap — so if it reopens later
+// it is announced again. Feeding the CURRENT open queue every poll makes the
+// "left then reappeared" case fall out for free (it was absent → present).
+export function computeAnnouncements(prev, currentQueue) {
+    const nextMap = {};
+    const lines = [];
+    for (const it of currentQueue) {
+        if (it == null || it.id === undefined || it.id === null)
+            continue;
+        const key = String(it.id);
+        const cur = { status: it.status, updatedAt: it.updatedAt };
+        const before = prev[key];
+        if (!before || before.status !== cur.status || before.updatedAt !== cur.updatedAt) {
+            lines.push(announceLine(it));
+        }
+        nextMap[key] = cur;
+    }
+    return { lines, nextMap };
+}
+const watchEmit = (line) => { process.stdout.write(line + '\n'); };
+const watchSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function watchBaseUrl(args) {
+    return (strArg(args.base) || process.env.VITRINKA_URL || process.env.VITRINKA_BASE_URL
+        || 'https://vitrinka.lovinka.com').replace(/\/+$/, '');
+}
+// deriveWatchScope resolves the listener scope from flags + the repo context
+// (PURE — unit-tested). Priority: --all (firehose) → --board <slug> → the repo's
+// project (main-worktree basename, push's derivation) + current git branch.
+// --project / --branch override the inferred project scope.
+export function deriveWatchScope(args, ctx) {
+    if (args.all === true)
+        return { kind: 'all', label: 'all boards' };
+    const board = strArg(args.board);
+    if (board)
+        return { kind: 'board', board, label: `board ${board}` };
+    const project = sanitizeSeg(strArg(args.project) || ctx.repoProject || 'project', 64);
+    const branch = sanitizeSeg(strArg(args.branch) || ctx.repoBranch || 'main', 100);
+    return { kind: 'project', project, branch, label: `${project}/${branch}` };
+}
+// scopeQuery renders the scope's server query params (shared by the wait lease
+// and the plain work list).
+function scopeQuery(scope) {
+    switch (scope.kind) {
+        case 'all': return { all: '1' };
+        case 'board': return { board: scope.board };
+        case 'project': return { project: scope.project, branch: scope.branch };
+    }
+}
+// watchFetchResp — a work-API read that returns status + parsed body (does NOT
+// throw on non-2xx, so the caller can branch on 409/holder). Throws only on a
+// transport failure so the resilience layer backs off.
+async function watchFetchResp(url, timeoutMs) {
+    const headers = {};
+    const token = readToken();
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(timeoutMs) });
+    let body = null;
+    try {
+        body = await res.json();
+    }
+    catch { /* empty/non-JSON */ }
+    return { status: res.status, body };
+}
+// watchFetchJson — as above but throws on non-2xx (used by the plain list).
+async function watchFetchJson(url, timeoutMs) {
+    const { status, body } = await watchFetchResp(url, timeoutMs);
+    if (status < 200 || status >= 300)
+        throw new Error(`HTTP ${status}`);
+    return body;
+}
+async function watchCmd(args) {
+    const base = watchBaseUrl(args);
+    const graceSec = numArg(args['quiet-grace'], 5, '--quiet-grace');
+    const once = args.once === true;
+    // Repo context for scope inference (main worktree basename = project; current
+    // branch). '.' cwd is where the session runs (the app repo).
+    const cwd = resolve('.');
+    const repoProject = basename(mainWorktreeTop(cwd) || cwd);
+    const repoBranch = git(['branch', '--show-current'], cwd);
+    const scope = deriveWatchScope(args, { repoProject, repoBranch });
+    const sq = scopeQuery(scope);
+    const listUrl = () => {
+        const q = new URLSearchParams({ status: 'open', ...sq });
+        return `${base}/api/v1/work?${q}`;
+    };
+    // --once: a single deterministic probe (tests). Lease-free (no session), so it
+    // never claims scope. Returns exit 0 with announcements, else 3 (idle).
+    if (once) {
+        const waitUrl = `${base}/api/v1/work/wait?${new URLSearchParams({ timeout: '2', ...sq })}`;
+        let waited;
+        try {
+            waited = await watchFetchJson(waitUrl, 12_000);
+        }
+        catch (e) {
+            console.error(`watch --once: vitrinka unreachable: ${e instanceof Error ? e.message : e}`);
+            process.exit(3);
+        }
+        if (!waited || waited.idle || !Array.isArray(waited.work) || waited.work.length === 0) {
+            process.exit(3);
+        }
+        let list;
+        try {
+            list = await watchFetchJson(listUrl(), 30_000);
+        }
+        catch (e) {
+            console.error(`watch --once: list failed: ${e instanceof Error ? e.message : e}`);
+            process.exit(3);
+        }
+        const items = Array.isArray(list?.work) ? list.work : [];
+        const { lines } = computeAnnouncements({}, items);
+        for (const l of lines)
+            watchEmit(l);
+        process.exit(lines.length > 0 ? 0 : 3);
+    }
+    // Persistent leased loop. Identity: operator persona + host:pid — the process
+    // that must stay alive. The long-poll IS the lease heartbeat; on graceful stop
+    // we DELETE the lease so its unfinished work reverts immediately.
+    const actor = readOperator(true);
+    const session = `${hostname()}:${process.pid}`;
+    const takeover = args.takeover === true;
+    const leasedWaitUrl = (secs) => {
+        const q = new URLSearchParams({ timeout: String(secs), session, ...sq });
+        if (actor)
+            q.set('actor', actor);
+        if (takeover)
+            q.set('takeover', '1');
+        return `${base}/api/v1/work/wait?${q}`;
+    };
+    let stopping = false;
+    let releasing = false;
+    let leaseId = null;
+    const shutdown = async (code) => {
+        if (releasing)
+            return;
+        releasing = true;
+        stopping = true;
+        if (leaseId != null) {
+            try {
+                const headers = {};
+                const token = readToken();
+                if (token)
+                    headers.Authorization = `Bearer ${token}`;
+                await fetch(`${base}/api/v1/work/listeners/${leaseId}`, { method: 'DELETE', headers, signal: AbortSignal.timeout(5_000) });
+            }
+            catch { /* best effort — the TTL reaps it anyway */ }
+        }
+        process.exit(code);
+    };
+    process.on('SIGINT', () => { void shutdown(0); });
+    process.on('SIGTERM', () => { void shutdown(0); });
+    let announced = {};
+    let downSince = null;
+    let degradedAt = null;
+    let backoff = 1000;
+    const noteSuccess = () => {
+        if (degradedAt !== null)
+            watchEmit('✓ vitrinka reachable again');
+        downSince = null;
+        degradedAt = null;
+        backoff = 1000;
+    };
+    const noteFailure = async () => {
+        const now = Date.now();
+        if (downSince === null)
+            downSince = now;
+        const downMs = now - downSince;
+        if (downMs >= 120_000 && (degradedAt === null || now - degradedAt >= 600_000)) {
+            watchEmit(`⚠ vitrinka unreachable for ${Math.round(downMs / 1000)}s — listener degraded`);
+            degradedAt = now;
+        }
+        const wait = backoff;
+        backoff = Math.min(backoff * 2, 30_000);
+        await watchSleep(wait);
+    };
+    while (!stopping) {
+        // Leased long-poll: claims/renews the scope, blocks until work exists. The
+        // instant the queue is non-empty it returns immediately (busy) so graceSec
+        // below throttles the diff loop.
+        let resp;
+        try {
+            resp = await watchFetchResp(leasedWaitUrl(55), 70_000);
+        }
+        catch {
+            await noteFailure();
+            continue;
+        }
+        if (resp.status === 409) {
+            // Scope already held by another session. Live → cannot steal; expired →
+            // retry with --takeover. Either way surface it and exit (the skill reads
+            // exit 2 as "another session owns this scope").
+            const h = resp.body?.holder ?? {};
+            const live = resp.body?.live ? 'live' : 'expired';
+            const scopeStr = h.scopeKind === 'project' ? `${h.scope}/${h.branch}` : (h.scope || h.scopeKind || scope.label);
+            const since = h.lastSeen ? ` (since ${h.lastSeen})` : '';
+            watchEmit(`⚠ listener already active (${live}): ${h.actor || '?'}@${h.session || '?'} on ${scopeStr}${since}`);
+            if (!resp.body?.live)
+                watchEmit('  → retry with --takeover to steal the expired lease');
+            process.exit(2);
+        }
+        if (resp.status < 200 || resp.status >= 300) {
+            await noteFailure();
+            continue;
+        }
+        noteSuccess();
+        if (typeof resp.body?.listener === 'number')
+            leaseId = resp.body.listener;
+        const waited = resp.body;
+        if (!waited || waited.idle || !Array.isArray(waited.work) || waited.work.length === 0) {
+            announced = {};
+            continue;
+        }
+        // Queue non-empty → diff the full open list and announce new items. The next
+        // loop iteration re-waits (renewing the lease); graceSec throttles.
+        try {
+            const list = await watchFetchJson(listUrl(), 30_000);
+            const items = Array.isArray(list.work) ? list.work : [];
+            const { lines, nextMap } = computeAnnouncements(announced, items);
+            announced = nextMap;
+            for (const l of lines)
+                watchEmit(l);
+        }
+        catch {
+            await noteFailure();
+            continue;
+        }
+        await watchSleep(graceSec * 1000);
+    }
+}
+// runSub — the single command switch, reused by the CLI entrypoint AND the `ai`
+// command's internal dispatch (no shell eval anywhere). `argv` is [command,
+// ...rest] exactly as process.argv.slice(2). Every case here MUST have a
+// COMMANDS registry entry (the registry-completeness test enforces it).
+async function runSub(argv) {
+    const [cmd, ...rest] = argv;
+    const args = parseArgs(rest);
+    const root = resolve(strArg(args.root) || '.screenshots');
+    if (cmd === 'add')
+        addCmd(root, args);
+    else if (cmd === 'build') {
+        const { count, htmlPath } = buildIndex(root);
+        console.log(`built ${htmlPath} (${count} shots)`);
+    }
+    else if (cmd === 'meta')
+        metaCmd(root, args);
+    else if (cmd === 'remote-init')
+        remoteInitCmd(root, args);
+    else if (cmd === 'push')
+        await pushCmd(root, args);
+    else if (cmd === 'name')
+        await nameCmd(argv, args);
+    else if (cmd === 'operator')
+        await operatorCmd(argv, args);
+    else if (cmd === 'install')
+        installCmd(args);
+    else if (cmd === 'snap')
+        await snapCmd(rest[0] && !rest[0].startsWith('--') ? rest[0] : '', args);
+    else if (cmd === 'board-from-set')
+        await boardFromSetCmd(root, args);
+    else if (cmd === 'watch')
+        await watchCmd(args);
+    else if (cmd === 'index')
+        await indexCmd(root, args);
+    else if (cmd === 'embed-shots')
+        embedShotsCmd(root, args);
+    else if (cmd === 'artifact-init')
+        artifactInitCmd(args);
+    else if (cmd === 'artifact-from-set')
+        artifactFromSetCmd(args);
+    else
+        throw new Error(`runSub: unhandled command ${JSON.stringify(cmd)}`); // guarded by the caller
+}
+// IS_MAIN self-run: fires only when THIS file is the process entry (direct
+// `node cli.ts`, or the dist bin). `main` is a hoisted function declaration, so
+// calling it here — before its definition below — is fine, and keeping the
+// entry block adjacent to runSub keeps the help/completion cases out of the
+// runSub-vs-registry source scan in dx.test.ts.
+const IS_MAIN = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href === import.meta.url : false;
+if (IS_MAIN) {
+    await main(process.argv.slice(2));
+}
+// main is the CLI entry, exported so the thin skills/vitrinka/cli.ts delegator
+// (kept for backward-compat with already-armed Monitors + the PATH shim) can
+// run the unified CLI by importing it.
+export async function main(argv) {
+    const [cmd, ...rest] = argv;
+    const args = parseArgs(rest);
+    const wantsHelp = args.help === true || rest.includes('-h') || rest.includes('--help');
+    if (cmd === undefined) {
+        // Bare invocation — the compact usage grid (exit 2, like the gallery shim).
+        console.error(USAGE);
+        process.exit(2);
+    }
+    else if (cmd === 'help' || cmd === '--help' || cmd === '-h') {
+        const topic = argv.slice(1).find((a) => !a.startsWith('-')) || '';
+        console.log(topic && COMMAND_MAP[topic] ? renderCmdHelp(topic) : renderFullHelp());
+        process.exit(0);
+    }
+    else if (COMMAND_MAP[cmd] && wantsHelp) {
+        // `vitrinka <cmd> --help` / `-h` → that command's detail page.
+        console.log(renderCmdHelp(cmd));
+        process.exit(0);
+    }
+    else if (cmd === 'completion') {
+        completionCmd(rest);
+    }
+    else if (cmd === '__complete') {
+        await completeDynamicCmd(rest);
+    }
+    else if (cmd === 'ai') {
+        await aiCmd(argv, args);
+    }
+    else if (!COMMAND_MAP[cmd]) {
+        // Unknown command → "did you mean" (plain edit-distance, no AI) + usage,
+        // then one additive AI hint. Exit 2.
+        const near = nearestCommand(cmd);
+        console.error(`unknown command ${JSON.stringify(cmd)}${near ? ` — did you mean "${near}"?` : ''}`);
+        console.error(USAGE);
+        await emitHint(`vitrinka ${argv.join(' ')}`, `unknown command ${JSON.stringify(cmd)}`, USAGE);
+        process.exit(2);
+    }
+    else {
+        await runSub(argv);
+    }
+}
+//# sourceMappingURL=cli.js.map