@lovinka/vitrinka 1.4.0 → 1.6.0

package/dist/cli.js

@@ -111,6 +111,10 @@ function buildIndex(root) {
     const m = loadManifest(root);
     const project = basename(dirname(root)) || 'project';
     const htmlPath = htmlPathOf(root);
+    // A fresh/nonexistent root builds an empty gallery — mirror saveManifest's
+    // dir creation instead of crashing with a raw ENOENT.
+    mkdirSync(root, { recursive: true });
+    ensureRootSelfIgnored(root);
     writeFileSync(htmlPath, renderHtml(m.shots, project));
     return { count: m.shots.length, htmlPath };
 }
@@ -1100,6 +1104,53 @@ async function doctorCmd(args) {
         console.log(`✓ operator   ${op}`);
     else
         console.log('✗ operator   unset — board writes stay anonymous (fix: vitrinka operator <name>)');
+    // Setup surfaces (skills / shim / MCP / Claude UI) — informational rows, and
+    // `--fix` repairs everything repairable in place. Token/operator stay manual
+    // (they're credentials/identity, not installation).
+    const fix = args.fix === true;
+    const home = process.env.HOME || '';
+    const bundle = bundledSkillsDir(CLI_PATH);
+    if (bundle && home) {
+        const st = skillsStateOf(bundle, join(home, '.claude', 'skills'));
+        if (st === 'current')
+            console.log('✓ skills     current');
+        else if (fix)
+            installSkillsCmd(args);
+        else
+            console.log(`✗ skills     ${st} — repair: vitrinka doctor --fix`);
+    }
+    if (home) {
+        const shimP = shimPathOf(home);
+        const shimOk = existsSync(shimP) && readFileSync(shimP, 'utf8') === SHIM_CONTENT;
+        if (shimOk)
+            console.log(`✓ shim       ${shimP}`);
+        else if (fix) {
+            mkdirSync(dirname(shimP), { recursive: true });
+            writeFileSync(shimP, SHIM_CONTENT);
+            chmodSync(shimP, 0o755);
+            console.log(`✓ shim       rewritten → ${shimP}`);
+        }
+        else
+            console.log(`✗ shim       ${existsSync(shimP) ? 'stale (points at another CLI copy)' : 'missing'} — repair: vitrinka doctor --fix`);
+    }
+    if (claudeCliPresent()) {
+        if (mcpRegistered())
+            console.log('✓ mcp        registered');
+        else if (fix) {
+            if (registerMcp('user'))
+                console.log('✓ mcp        re-registered (--scope user)');
+            else
+                console.log('✗ mcp        re-registration failed — see output above');
+        }
+        else
+            console.log('✗ mcp        not registered — repair: vitrinka doctor --fix (or vitrinka install)');
+    }
+    if (home && existsSync(join(home, '.claude', 'vitrinka-statusline.sh'))) {
+        if (fix)
+            installClaudeCmd(args);
+        else
+            console.log('✓ claude ui  wired (refresh: vitrinka doctor --fix)');
+    }
     if (failed)
         process.exit(1);
 }
@@ -1116,9 +1167,9 @@ export function bundledSkillsDir(cliPath) {
 }
 // installSkillsCmd copies the packaged skills bundle (vitrinka + listen,
 // screenshot, artifact, brainstorming) into the Claude skills directory —
-// ~/.claude/skills by default, ./.claude/skills with --local. This is the
-// npm-package twin of install.sh's skills step, so `npm i -g @lovinka/vitrinka
-// && vitrinka install-skills` fully equips a machine without a repo checkout.
+// ~/.claude/skills by default, ./.claude/skills with --local. `npm i -g
+// @lovinka/vitrinka && vitrinka install-skills` fully equips a machine
+// without a repo checkout.
 function installSkillsCmd(args) {
     const bundle = bundledSkillsDir(CLI_PATH);
     if (!bundle)
@@ -1129,8 +1180,8 @@ function installSkillsCmd(args) {
         fail('install-skills: $HOME is not set (or pass --local)');
     const target = local ? resolve('.claude', 'skills') : join(home, '.claude', 'skills');
     mkdirSync(target, { recursive: true });
-    // Whole directories, like install.sh: a skill may nest its SKILL.md (the
-    // vitrinka skill keeps it under listen/ next to its CLI + tests).
+    // Whole directories: a skill may nest its SKILL.md (the vitrinka skill
+    // keeps it under listen/ next to its CLI + tests).
     const names = readdirSync(bundle).filter((n) => !n.startsWith('.') && statSync(join(bundle, n)).isDirectory());
     if (!names.length)
         fail(`install-skills: no skills found in ${bundle}`);
@@ -1148,75 +1199,398 @@ function installSkillsCmd(args) {
         }
         console.log(`✓ ${n} → ${join(target, n)}`);
     }
+    // /vitrinka:listen command stub — nested SKILL.md files (skills/vitrinka/listen/)
+    // never register as invocable skills; only a stub under commands/vitrinka/ makes
+    // the slash command callable.
+    const stub = join(bundle, 'vitrinka', 'commands', 'listen.md');
+    if (existsSync(stub)) {
+        const commandsDir = local ? resolve('.claude', 'commands', 'vitrinka') : join(home, '.claude', 'commands', 'vitrinka');
+        mkdirSync(commandsDir, { recursive: true });
+        let content = readFileSync(stub, 'utf8');
+        if (local)
+            content = content.replaceAll('~/.claude/skills/vitrinka/listen/SKILL.md', '.claude/skills/vitrinka/listen/SKILL.md');
+        writeFileSync(join(commandsDir, 'listen.md'), content);
+        console.log(`✓ /vitrinka:listen command → ${join(commandsDir, 'listen.md')}`);
+    }
     console.log(`${names.length} skill${names.length === 1 ? '' : 's'} installed (${names.sort().join(', ')})`);
 }
-// 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) {
+// ---------- setup state probing (shared by install / doctor / uninstall) ----------
+// dirsEqual — recursive byte comparison, the node twin of install.sh's `diff -rq`.
+function dirsEqual(a, b) {
+    const names = new Set([...readdirSync(a), ...readdirSync(b)]);
+    for (const n of names) {
+        const pa = join(a, n), pb = join(b, n);
+        if (!existsSync(pa) || !existsSync(pb))
+            return false;
+        const da = statSync(pa).isDirectory(), db = statSync(pb).isDirectory();
+        if (da !== db)
+            return false;
+        if (da) {
+            if (!dirsEqual(pa, pb))
+                return false;
+        }
+        else if (!readFileSync(pa).equals(readFileSync(pb)))
+            return false;
+    }
+    return true;
+}
+// skillsStateOf — the bundled skills' freshness at a target skills dir. Local
+// installs rewrite CLI paths after copy, so a fresh local copy reads "outdated"
+// against the bundle — harmless (refresh is idempotent), same as install.sh.
+function skillsStateOf(bundle, target) {
+    const names = readdirSync(bundle).filter((n) => !n.startsWith('.') && statSync(join(bundle, n)).isDirectory());
+    if (names.some((n) => !existsSync(join(target, n))))
+        return 'missing';
+    return names.every((n) => dirsEqual(join(bundle, n), join(target, n))) ? 'current' : 'outdated';
+}
+const SHIM_CONTENT = `#!/bin/sh\nexec node "${CLI_PATH}" "$@"\n`;
+function shimPathOf(home) { return join(home, '.local', 'bin', 'vitrinka'); }
+function rcPathOf(home) {
+    return join(home, (process.env.SHELL || '').includes('bash') ? '.bashrc' : '.zshrc');
+}
+// claudeCliPresent / mcpRegistered / registerMcp — the `claude mcp` touchpoints.
+// The MCP target mirrors updateCmd's repo-vs-npm detection: a checkout registers
+// the repo's stdio shim (a `git pull` IS the update), an npm install registers
+// the published package via npx.
+function claudeCliPresent() {
+    return !spawnSync('claude', ['--version'], { stdio: 'ignore' }).error;
+}
+function mcpRegistered() {
+    const r = spawnSync('claude', ['mcp', 'list'], { encoding: 'utf8' });
+    return r.status === 0 && /\bvitrinka\b/.test(r.stdout);
+}
+function mcpTarget() {
+    const repoTop = git(['rev-parse', '--show-toplevel'], dirname(CLI_PATH));
+    const shim = repoTop ? join(repoTop, 'mcp', 'server.ts') : '';
+    if (shim && existsSync(shim))
+        return ['node', shim];
+    return ['npx', '-y', '--package=@lovinka/vitrinka', 'vitrinka-mcp'];
+}
+function registerMcp(scope) {
+    spawnSync('claude', ['mcp', 'remove', '--scope', scope, 'vitrinka'], { stdio: 'ignore' });
+    return spawnSync('claude', ['mcp', 'add', '--scope', scope, 'vitrinka', '--', ...mcpTarget()], { stdio: 'inherit' }).status === 0;
+}
+// promptLine — visible one-line read from the controlling TTY ('' when
+// non-interactive, like promptYesNo).
+function promptLine(question) {
+    if (!process.stdin.isTTY)
+        return '';
+    process.stdout.write(question);
+    try {
+        const fd = openSync('/dev/tty', 'r');
+        const buf = Buffer.alloc(512);
+        const n = readSync(fd, buf, 0, 512, null);
+        closeSync(fd);
+        return buf.toString('utf8', 0, n).trim();
+    }
+    catch {
+        return ''; // no controlling TTY — treat as non-interactive, never block
+    }
+}
+// promptSecret — promptLine with terminal echo off (token input, the old
+// install.sh's `read -rs`). Degrades to a visible read if stty is unavailable.
+function promptSecret(question) {
+    if (!process.stdin.isTTY)
+        return '';
+    const echoOff = spawnSync('stty', ['-echo'], { stdio: 'inherit' }).status === 0;
+    const val = promptLine(question);
+    if (echoOff) {
+        spawnSync('stty', ['echo'], { stdio: 'inherit' });
+        process.stdout.write('\n'); // the suppressed Enter
+    }
+    return val;
+}
+// ---------- install: status-first onboarding ----------
+//
+// The one-command machine setup (decisions: docs/specs/2026-07-08-cli-onboarding-
+// decisions.md — this replaced the deleted install.sh). Status-first: print a
+// ✓/✗ table of every component, silently install the harmless ones (skills,
+// shim, PATH, completion — own dirs, fully reversible), then ask ONLY for the
+// missing config-touchers (MCP registration, write token, operator persona,
+// Claude UI wiring). Re-runs are near-silent. Non-interactive runs (CI,
+// curl|bash) skip every prompt and print the manual command instead.
+async 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}`);
+    const local = args.local === true;
+    const base = resolveBaseUrl(strArg(args.base));
+    const mcpScope = local ? 'project' : 'user';
+    // ---- probe (before touching anything) ----
+    const bundle = bundledSkillsDir(CLI_PATH);
+    const skillsTarget = local ? resolve('.claude', 'skills') : join(home, '.claude', 'skills');
+    const skills = bundle ? skillsStateOf(bundle, skillsTarget) : 'no-bundle';
+    const shimP = shimPathOf(home);
+    const shimOk = existsSync(shimP) && readFileSync(shimP, 'utf8') === SHIM_CONTENT;
+    const rc = rcPathOf(home);
+    const completionOk = existsSync(rc) && readFileSync(rc, 'utf8').includes('# vitrinka-completion');
+    const haveClaude = claudeCliPresent();
+    const mcpOk = haveClaude ? mcpRegistered() : false;
+    const tokenSrc = tokenSource();
+    const op = readOperator(true);
+    const wrapperP = join(home, '.claude', 'vitrinka-statusline.sh');
+    const uiOk = existsSync(wrapperP);
+    const row = (ok, label, detail) => {
+        console.log(`  ${ok ? '✓' : '✗'} ${label.padEnd(11)}${detail}`);
+    };
+    console.log(`vitrinka setup — ${base}${local ? '  (local scope)' : ''}`);
+    row(skills === 'current', 'skills', skills === 'no-bundle' ? 'bundle not found next to the CLI (reinstall the package)'
+        : skills === 'current' ? `current → ${skillsTarget}` : `${skills} → will refresh`);
+    if (!local)
+        row(shimOk, 'shim', shimOk ? shimP : 'will install');
+    if (!local)
+        row(completionOk, 'completion', completionOk ? rc : args['no-completion'] === true ? 'skipped (--no-completion)' : 'will enable');
+    row(mcpOk, 'mcp', mcpOk ? 'registered' : haveClaude ? `not registered (scope ${mcpScope})` : 'claude CLI not found');
+    row(tokenSrc !== 'missing', 'token', tokenSrc === 'missing' ? 'missing — writes will 401' : `present (${tokenSrc === 'env' ? '$VITRINKA_TOKEN' : tokenPath()})`);
+    row(!!op, 'operator', op || 'unset — board writes stay anonymous');
+    row(uiOk, 'claude ui', uiOk ? 'statusline + footer wired' : 'not wired');
+    console.log('');
+    // ---- silent steps: skills, shim, PATH, completion (reversible, own dirs) ----
+    if (bundle && skills !== 'current')
+        installSkillsCmd(args);
+    if (!local) {
+        if (!shimOk) {
+            mkdirSync(dirname(shimP), { recursive: true });
+            writeFileSync(shimP, SHIM_CONTENT);
+            chmodSync(shimP, 0o755);
+            console.log(`✓ shim → ${shimP}`);
+        }
+        const binDir = dirname(shimP);
+        const marker = '# vitrinka-cli';
+        const zshrc = join(home, '.zshrc');
+        const zshrcContent = existsSync(zshrc) ? readFileSync(zshrc, 'utf8') : '';
+        if (!zshrcContent.includes(marker) && !(process.env.PATH || '').split(':').includes(binDir)) {
+            appendFileSync(zshrc, `\n${marker}\nexport PATH="$HOME/.local/bin:$PATH"\n`);
+            console.log(`✓ PATH block → ${zshrc} (open a new shell, or: source ${zshrc})`);
+        }
+        if (args['no-completion'] !== true && !completionOk) {
+            const shellName = rc.endsWith('.bashrc') ? 'bash' : 'zsh';
+            appendFileSync(rc, `\n# vitrinka-completion\neval "$(vitrinka completion ${shellName})"\n`);
+            console.log(`✓ ${shellName} completion → ${rc}`);
+        }
+    }
+    // ---- asked steps: the config-touchers ----
+    // 1. MCP registration (claude's registry).
+    const mcpCmdHint = `claude mcp add --scope ${mcpScope} vitrinka -- ${mcpTarget().join(' ')}`;
+    if (!haveClaude) {
+        console.error(`⚠ claude CLI not found — register the MCP later with:\n  ${mcpCmdHint}`);
+    }
+    else if (!mcpOk) {
+        if (args['no-mcp'] === true)
+            console.log('mcp: skipped (--no-mcp)');
+        else if (args.mcp === true || promptYesNo(`Register the vitrinka MCP for Claude Code (scope ${mcpScope})? [Y/n] `)) {
+            if (registerMcp(mcpScope))
+                console.log(`✓ mcp registered (--scope ${mcpScope})`);
+            else
+                console.error(`⚠ mcp registration failed — retry with:\n  ${mcpCmdHint}`);
+        }
+        else {
+            console.log(`mcp: skipped — register later with:\n  ${mcpCmdHint}`);
+        }
+    }
+    // 2. Write token (reads work without one; pushes/board writes 401).
+    if (tokenSrc === 'missing') {
+        if (process.stdin.isTTY) {
+            console.log('No write token yet — reads work without one, writes 401. It is the');
+            console.log('server\'s VITRINKA_TOKEN (one shared secret — copy it from a configured');
+            console.log('machine or the server admin; details: vitrinka doctor).');
+            const tok = promptSecret('Write token (Enter to skip): ');
+            if (tok) {
+                mkdirSync(dirname(tokenPath()), { recursive: true });
+                writeFileSync(tokenPath(), tok + '\n');
+                chmodSync(tokenPath(), 0o600);
+                console.log(`✓ token → ${tokenPath()}`);
+            }
+            else {
+                console.error(`⚠ no token — writes will 401 until you add one (${tokenPath()})`);
+            }
+        }
+        else {
+            console.error('⚠ no token and non-interactive — writes will 401 until you add one:');
+            console.error(tokenHelp());
+        }
     }
-    else {
-        mkdirSync(binDir, { recursive: true });
-        writeFileSync(shimPath, shim);
-        chmodSync(shimPath, 0o755);
-        console.log(`installed shim: ${shimPath} → node ${CLI_PATH}`);
+    // 3. Operator persona (board attribution) — same engine as `vitrinka operator`.
+    const opArg = strArg(args.operator);
+    if (opArg) {
+        await operatorCmd(['operator', opArg], args);
+    }
+    else if (!op) {
+        const name = promptLine('Operator name — how should vitrinka credit you on boards? (Enter to skip): ');
+        if (name)
+            await operatorCmd(['operator', name], args);
+        else
+            console.error('⚠ no operator — board writes stay anonymous (set later: vitrinka operator <name>)');
+    }
+    // 4. Claude Code UI wiring (edits ~/.claude/settings.json). Already-wired
+    // machines refresh silently (consent was given once); fresh ones are asked.
+    if (args['no-claude'] === true) {
+        console.log('claude ui: skipped (--no-claude)');
     }
-    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 (uiOk || args.claude === true
+        || promptYesNo('Wire Claude Code UI (🧷 board statusline segment + clickable footer badge)? [Y/n] ')) {
+        installClaudeCmd(args);
     }
-    else if ((process.env.PATH || '').split(':').includes(binDir)) {
-        console.log(`${binDir} already on PATH — ${zshrc} left untouched`);
+    else if (!process.stdin.isTTY) {
+        console.log('claude ui: skipped (non-interactive — run `vitrinka install-claude`, or pass --claude)');
     }
     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})`);
+        console.log('claude ui: skipped (re-run any time: vitrinka install-claude)');
     }
-    // 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)');
+    // ---- environment checks (non-fatal) ----
+    if (spawnSync('jq', ['--version'], { stdio: 'ignore' }).error) {
+        console.error('⚠ jq missing (brew install jq) — the statusline 🧷 board segment won\'t render without it');
     }
-    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}`);
+    if (spawnSync('cwebp', ['-version'], { stdio: 'ignore' }).error) {
+        console.error('⚠ cwebp missing (brew install webp) — snap falls back to PNG');
+    }
+    try {
+        const res = await fetch(`${base}/healthz`, { signal: AbortSignal.timeout(5_000) });
+        if (!res.ok)
+            console.error(`⚠ ${base} answered HTTP ${res.status}`);
+    }
+    catch {
+        console.error(`⚠ ${base} unreachable — vitrinka is WireGuard-mesh-only; bring the VPN up`);
+    }
+    console.log('');
+    console.log('done — health check any time with: vitrinka doctor');
+}
+// ---------- uninstall: clean offboarding ----------
+// stripMarkerBlock removes a marker comment line AND the single payload line
+// after it (the exact shape install writes), plus the blank separator install
+// prepended. PURE — unit-tested.
+export function stripMarkerBlock(content, marker) {
+    const lines = content.split('\n');
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === marker) {
+            if (out.length && out[out.length - 1] === '')
+                out.pop(); // the blank install added
+            i++; // skip the payload line too
+            continue;
         }
-        else {
-            appendFileSync(rc, `\n${compMarker}\neval "$(vitrinka completion ${shellName})"\n`);
-            console.log(`added ${shellName} completion to ${rc} (open a new shell, or: source ${rc})`);
+        out.push(lines[i]);
+    }
+    return out.join('\n');
+}
+// The bundled skill names — used by uninstall when the bundle isn't next to the
+// CLI anymore (e.g. the package was removed first).
+const BUNDLED_SKILLS = ['artifact', 'brainstorming', 'screenshot', 'vitrinka'];
+// uninstallCmd removes everything install put on the machine — the exact
+// inverse: bundled skills + the /vitrinka:listen stub, shim, rc marker blocks,
+// statusline wrapper (restoring the original statusLine command), the /boards/
+// footer badge entry, and the MCP registration. ~/.config/vitrinka (token +
+// operator) survives by default; --purge removes it too.
+function uninstallCmd(args) {
+    const home = process.env.HOME;
+    if (!home)
+        fail('uninstall: $HOME is not set');
+    const local = args.local === true;
+    if (args.yes !== true && !promptYesNo(`Remove vitrinka from this machine (skills, shim, completion, Claude wiring, MCP${args.purge === true ? ', token+operator' : ''})? [Y/n] `)) {
+        fail('uninstall: aborted (non-interactive runs need --yes)', 2);
+    }
+    // Skills + the /vitrinka:listen command stub.
+    const bundle = bundledSkillsDir(CLI_PATH);
+    const names = bundle
+        ? readdirSync(bundle).filter((n) => !n.startsWith('.') && statSync(join(bundle, n)).isDirectory())
+        : BUNDLED_SKILLS;
+    const skillsDir = local ? resolve('.claude', 'skills') : join(home, '.claude', 'skills');
+    const commandsDir = local ? resolve('.claude', 'commands', 'vitrinka') : join(home, '.claude', 'commands', 'vitrinka');
+    for (const n of names) {
+        if (!existsSync(join(skillsDir, n)))
+            continue;
+        rmSync(join(skillsDir, n), { recursive: true, force: true });
+        console.log(`✓ removed skill ${n}`);
+    }
+    if (existsSync(join(commandsDir, 'listen.md'))) {
+        rmSync(join(commandsDir, 'listen.md'));
+        try {
+            rmSync(commandsDir, { recursive: false });
+        }
+        catch { /* not empty — other files live there */ }
+        console.log('✓ removed /vitrinka:listen command stub');
+    }
+    // Shim + rc marker blocks (global installs only — local never wrote them).
+    const shimP = shimPathOf(home);
+    if (existsSync(shimP)) {
+        rmSync(shimP);
+        console.log(`✓ removed shim ${shimP}`);
+    }
+    for (const [file, marker] of [
+        [join(home, '.zshrc'), '# vitrinka-cli'],
+        [join(home, '.zshrc'), '# vitrinka-completion'],
+        [join(home, '.bashrc'), '# vitrinka-completion'],
+    ]) {
+        if (!existsSync(file))
+            continue;
+        const cur = readFileSync(file, 'utf8');
+        const next = stripMarkerBlock(cur, marker);
+        if (next !== cur) {
+            writeFileSync(file, next);
+            console.log(`✓ removed ${marker} block from ${file}`);
         }
     }
-    // Claude Code UI wiring — consent-gated (it edits ~/.claude/settings.json):
-    // --claude / --no-claude decide outright; otherwise ask on a TTY, skip with a
-    // hint when non-interactive (curl|bash, CI).
-    if (args['no-claude'] === true) {
-        console.log('claude wiring: skipped (--no-claude)');
+    // Claude UI wiring — restore statusLine from the wrapper's VITRINKA_ORIG,
+    // drop the /boards/ footer entry, delete the wrapper.
+    const settingsPath = join(home, '.claude', 'settings.json');
+    const wrapperP = join(home, '.claude', 'vitrinka-statusline.sh');
+    if (existsSync(settingsPath)) {
+        let settings;
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        }
+        catch (e) {
+            fail(`uninstall: ${settingsPath} is not valid JSON — nothing was changed there; fix it first (${e.message})`);
+        }
+        let changed = false;
+        const sl = settings.statusLine;
+        if (sl?.command && sl.command.replace(/^~(?=\/)/, home) === wrapperP) {
+            const orig = existsSync(wrapperP) ? wrapperOrigCommand(readFileSync(wrapperP, 'utf8')) : '';
+            if (orig)
+                settings.statusLine = { type: 'command', command: orig };
+            else
+                delete settings.statusLine;
+            changed = true;
+            console.log(`✓ statusline restored${orig ? ` → ${orig}` : ' (removed — none was configured before)'}`);
+        }
+        const arr = settings.footerLinksRegexes;
+        if (Array.isArray(arr)) {
+            const kept = arr.filter((e) => !(typeof e?.pattern === 'string' && e.pattern.replaceAll('\\', '').includes('/boards/')));
+            if (kept.length !== arr.length) {
+                if (kept.length)
+                    settings.footerLinksRegexes = kept;
+                else
+                    delete settings.footerLinksRegexes;
+                changed = true;
+                console.log('✓ footer badge entry removed');
+            }
+        }
+        if (changed)
+            writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     }
-    else if (args.claude === true || promptYesNo('Wire Claude Code UI (🧷 board statusline segment + clickable footer badge)? [Y/n] ')) {
-        installClaudeCmd(args);
+    if (existsSync(wrapperP)) {
+        rmSync(wrapperP);
+        console.log(`✓ removed ${wrapperP}`);
     }
-    else if (!process.stdin.isTTY) {
-        console.log('claude wiring: skipped (non-interactive — run `vitrinka install-claude`, or pass --claude)');
+    // MCP registration (both scopes — cheap, and remove is idempotent).
+    if (claudeCliPresent()) {
+        for (const scope of local ? ['project', 'user'] : ['user', 'project']) {
+            spawnSync('claude', ['mcp', 'remove', '--scope', scope, 'vitrinka'], { stdio: 'ignore' });
+        }
+        console.log('✓ MCP registration removed');
     }
-    else {
-        console.log('claude wiring: skipped (re-run any time: vitrinka install-claude)');
+    // Token + operator only with --purge — they're credentials, not installation.
+    const cfgDir = join(home, '.config', 'vitrinka');
+    if (args.purge === true) {
+        if (existsSync(cfgDir)) {
+            rmSync(cfgDir, { recursive: true, force: true });
+            console.log(`✓ purged ${cfgDir}`);
+        }
     }
-    console.log('done — try: vitrinka --help');
+    else if (existsSync(cfgDir)) {
+        console.log(`token/operator kept at ${cfgDir} (remove with --purge)`);
+    }
+    console.log('uninstall done');
 }
 // ---------- install-claude: Claude Code UI wiring ----------
 //
@@ -1226,8 +1600,12 @@ function installCmd(args) {
 //      clickable "🧷 board" footer badge whenever a /boards/ URL appears in the
 //      conversation (works in every terminal, unlike statusline OSC 8).
 //   2. statusLine — a wrapper script that pipes the same stdin JSON to the
-//      user's ORIGINAL statusline command and appends a "🧷 board" OSC 8 link
-//      when the session's capture root has a .screenshots/.vitrinka descriptor.
+//      user's ORIGINAL statusline command and appends a "🧷 <board-url>" plain-text
+//      segment when the session's capture root has a .screenshots/.vitrinka
+//      descriptor. Plain URL on purpose: Claude Code strips OSC 8 from statusline
+//      output in real terminals (anthropics/claude-code#21586, #26356 — closed
+//      "not planned"), but terminals like Warp/iTerm2/Ghostty cmd+click-linkify
+//      visible URLs on their own.
 //      With no original statusline, the wrapper renders a minimal line itself.
 // Idempotent, never an uninstall: re-runs detect the /boards/ footer pattern and
 // the wrapper registration and no-op. Removal = delete the wrapper + restore
@@ -1256,8 +1634,10 @@ export function buildStatuslineWrapper(origCmd) {
     const quoted = origCmd.replaceAll("'", `'\\''`);
     return `#!/bin/bash
 # vitrinka-statusline — managed by \`vitrinka install-claude\` (re-runs rewrite it).
-# Wraps the original Claude Code statusline and appends a 🧷 board OSC 8 link when
-# the session's capture root has a .screenshots/.vitrinka descriptor.
+# Wraps the original Claude Code statusline and appends a 🧷 board-URL segment when
+# the session's capture root has a .screenshots/.vitrinka descriptor. Plain URL,
+# not OSC 8 — Claude Code strips OSC 8 from statusline output; terminals
+# cmd+click-linkify visible URLs themselves.
 VITRINKA_ORIG='${quoted}'
 
 input=$(cat)
@@ -1281,7 +1661,7 @@ for VJSON in "$DIR/.screenshots/.vitrinka" "$PROJECT_DIR/.screenshots/.vitrinka"
   VBASE=$(jq -r '.base // empty' "$VJSON" 2>/dev/null)
   VKEY=$(jq -r '.key // empty' "$VJSON" 2>/dev/null)
   if [ -n "$VBASE" ] && [ -n "$VKEY" ]; then
-    BOARD=$(printf '\\033]8;;%s\\a\\033[35m🧷 board\\033[0m\\033]8;;\\a' "$VBASE/boards/$VKEY")
+    BOARD=$(printf '\\033[35m🧷\\033[0m \\033[2m%s\\033[0m' "$VBASE/boards/$VKEY")
   fi
   break
 done
@@ -1388,8 +1768,257 @@ export function installClaudeCmd(_args) {
     }
     if (changed)
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    // The wrapper reads Claude's stdin JSON with jq; without it the board segment
+    // silently degrades to pass-through — surface that at install time.
+    if (spawnSync('jq', ['--version'], { stdio: 'ignore' }).error) {
+        console.error('⚠ jq not found — the statusline 🧷 board segment needs it (brew install jq); footer badge works regardless');
+    }
     console.log(`install-claude done — restart Claude Code sessions to pick up ${settingsPath}`);
 }
+// ---------- open: jump to the live board ----------
+// boardUrlOf — the current capture root's live board URL ('' when the root has
+// no .vitrinka descriptor yet). Board slug == set key (board-from-set contract).
+function boardUrlOf(root) {
+    if (!existsSync(vitrinkaCfgPath(root)))
+        return '';
+    const cfg = loadVitrinkaCfg(root);
+    return `${cfg.base}/boards/${cfg.key}`;
+}
+// openCmd opens the thing you're working on: the capture root's live board when
+// one exists, else the vitrinka home. --qr renders the URL as a terminal QR
+// (scan with the iPad → annotate with the Pencil) and skips the local browser;
+// --print only prints.
+function openCmd(root, args) {
+    const url = boardUrlOf(root) || resolveBaseUrl(strArg(args.base));
+    console.log(url);
+    if (args.qr === true) {
+        // Zero-dep rule: we shell to qrencode rather than hand-roll a QR encoder.
+        const r = spawnSync('qrencode', ['-t', 'ANSIUTF8', url], { stdio: 'inherit' });
+        if (r.error)
+            console.error('open: qrencode not found (brew install qrencode) — URL printed above');
+        return; // QR targets another device — don't also grab the local browser
+    }
+    if (args.print === true)
+        return;
+    const opener = process.platform === 'darwin' ? 'open' : 'xdg-open';
+    const r = spawnSync(opener, [url], { stdio: 'ignore' });
+    if (r.error || r.status !== 0)
+        console.error(`open: could not launch ${opener} — URL printed above`);
+}
+// ---------- status: the session dashboard ----------
+// statusCmd — one glance at this repo+branch's vitrinka world: the live board,
+// the open work queue (same scope derivation as `watch`), and who holds the
+// listener lease. Degrades row-by-row when the server is unreachable.
+async function statusCmd(root, args) {
+    const base = resolveBaseUrl(strArg(args.base));
+    const cwd = resolve('.');
+    const project = sanitizeSeg(strArg(args.project) || basename(mainWorktreeTop(cwd) || cwd), 64);
+    const branch = sanitizeSeg(strArg(args.branch) || git(['branch', '--show-current'], cwd) || 'main', 100);
+    console.log(`vitrinka status — ${project}/${branch}`);
+    const board = boardUrlOf(root);
+    console.log(board ? `  board      ${board}` : '  board      none yet (publish one: vitrinka board-from-set)');
+    try {
+        const q = new URLSearchParams({ status: 'open', project, branch });
+        const d = await watchFetchJson(`${base}/api/v1/work?${q}`, 15_000);
+        const items = Array.isArray(d?.work) ? d.work : [];
+        console.log(`  queue      ${items.length} open item${items.length === 1 ? '' : 's'}`);
+        for (const it of items.slice(0, 10))
+            console.log(`             ${announceLine(it)}`);
+        if (items.length > 10)
+            console.log(`             … ${items.length - 10} more`);
+    }
+    catch (e) {
+        console.log(`  queue      unreachable (${e instanceof Error ? e.message : e})`);
+    }
+    try {
+        const d = await watchFetchJson(`${base}/api/v1/work/listeners`, 15_000);
+        const ls = Array.isArray(d?.listeners) ? d.listeners : [];
+        const boardSlug = board ? board.slice(board.lastIndexOf('/') + 1) : '';
+        const mine = ls.filter((l) => l.scopeKind === 'all'
+            || (l.scopeKind === 'project' && l.scope === project && (!l.branch || l.branch === branch))
+            || (l.scopeKind === 'board' && !!boardSlug && l.scope === boardSlug));
+        if (!mine.length)
+            console.log('  listener   none — arm one with /vitrinka:listen (or: vitrinka watch)');
+        for (const l of mine) {
+            console.log(`  listener   ${l.actor || 'anonymous'} @ ${l.session || '?'} (${l.scopeKind}${l.scope ? ` ${l.scope}` : ''}${l.branch ? `/${l.branch}` : ''})`);
+        }
+    }
+    catch (e) {
+        console.log(`  listener   unreachable (${e instanceof Error ? e.message : e})`);
+    }
+}
+// ---------- passive update notifier + first-run hint ----------
+// cmpSemver — numeric dotted-version compare (>0: a newer). PURE — unit-tested.
+export function cmpSemver(a, b) {
+    const pa = a.split('.').map(Number), pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] || 0) - (pb[i] || 0);
+        if (d)
+            return d;
+    }
+    return 0;
+}
+// Commands that must never carry the notifier/hint noise (setup and meta paths).
+const HINT_SKIP = new Set(['install', 'install-claude', 'install-skills', 'update', 'uninstall',
+    'doctor', 'help', 'completion', '__complete', 'ai']);
+function updateCheckPath() {
+    return join(process.env.HOME || '', '.config', 'vitrinka', 'update-check');
+}
+// maybeNotifyUpdate — one dim stderr line when a newer published version is
+// known, npm installs only (a repo checkout is a dev seat that pulls itself).
+// The registry check runs DETACHED at most once a day and writes a cache file;
+// the hot path only ever reads it — a command never waits on the network.
+function maybeNotifyUpdate(cmd) {
+    if (HINT_SKIP.has(cmd) || !process.stderr.isTTY || !process.env.HOME)
+        return;
+    if (git(['rev-parse', '--show-toplevel'], dirname(CLI_PATH)))
+        return;
+    const p = updateCheckPath();
+    let cache = {};
+    try {
+        cache = JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch {
+        // Absent or corrupt cache — the background refresh below rewrites it.
+    }
+    const current = pkgVersion();
+    if (cache.latest && current && cmpSemver(cache.latest, current) > 0) {
+        console.error(`\x1b[2mupdate available ${current} → ${cache.latest} · run: vitrinka update\x1b[0m`);
+    }
+    if (Date.now() - (cache.ts || 0) < 24 * 3600 * 1000)
+        return;
+    const script = `const fs=require('fs'),path=require('path'),f=${JSON.stringify(p)};`
+        + `fetch('https://registry.npmjs.org/@lovinka/vitrinka/latest',{signal:AbortSignal.timeout(10000)})`
+        + `.then(r=>r.json()).then(d=>{fs.mkdirSync(path.dirname(f),{recursive:true});`
+        + `fs.writeFileSync(f,JSON.stringify({ts:Date.now(),latest:String(d.version||'')}))}).catch(()=>{})`;
+    try {
+        spawn(process.execPath, ['-e', script], { detached: true, stdio: 'ignore' }).unref();
+    }
+    catch {
+        // A notifier must never break the actual command.
+    }
+}
+// maybeHintFirstRun — one stderr line on a machine with zero vitrinka setup
+// (no skills, no token, no shim). All three must be absent, so a configured
+// machine (or a local-scope one with a token) is never nagged.
+function maybeHintFirstRun(cmd) {
+    if (HINT_SKIP.has(cmd))
+        return;
+    const home = process.env.HOME;
+    if (!home)
+        return;
+    if (existsSync(join(home, '.claude', 'skills', 'vitrinka')))
+        return;
+    if (readToken())
+        return;
+    if (existsSync(shimPathOf(home)))
+        return;
+    console.error('\x1b[2mhint: this machine has no vitrinka setup yet — run: vitrinka install\x1b[0m');
+}
+// ---------- what's new (changelog) ----------
+// changelogSince — the `## x.y.z` sections newer than `since`, verbatim.
+// '' when nothing is newer or the file has no versioned headings. PURE.
+export function changelogSince(md, since) {
+    const out = [];
+    let taking = false;
+    for (const line of md.split('\n')) {
+        const m = /^##\s+\[?(\d+(?:\.\d+)*)\]?/.exec(line);
+        if (m) {
+            if (since && cmpSemver(m[1], since) <= 0)
+                break;
+            taking = true;
+        }
+        if (taking)
+            out.push(line);
+    }
+    return out.join('\n').trim();
+}
+// ---------- update: bring the CLI + installed surfaces to the latest ----------
+// pkgVersion reads the version of the package the running CLI belongs to.
+// dirname(CLI_PATH) is pkg/src (repo checkout) or <pkg>/dist (npm install) —
+// package.json sits one level up in both layouts.
+function pkgVersion() {
+    try {
+        return String(JSON.parse(readFileSync(join(dirname(CLI_PATH), '..', 'package.json'), 'utf8')).version || '');
+    }
+    catch {
+        return ''; // no package.json next to the CLI (odd layout) — version is cosmetic here
+    }
+}
+// updateCmd updates the CLI source (git pull in a repo checkout, `npm i -g` for
+// a global npm install — detected from where the running file lives), then
+// refreshes every surface a previous install put on this machine: the skills
+// bundle (+ /vitrinka:listen command stub) and, ONLY where it was consented to
+// before, the Claude Code UI wiring. It never asks new consent questions —
+// that stays `vitrinka install`'s job. The refresh steps re-exec the (possibly
+// just replaced) CLI file so they run the NEW code, not this stale process.
+async function updateCmd(args) {
+    const repoTop = git(['rev-parse', '--show-toplevel'], dirname(CLI_PATH));
+    if (repoTop) {
+        // Repo checkout — the shim/MCP run the source directly, so a pull IS the update.
+        const before = git(['rev-parse', '--short', 'HEAD'], repoTop);
+        console.log(`repo checkout ${repoTop} (${before || '?'}) — git pull --ff-only…`);
+        const pull = spawnSync('git', ['-C', repoTop, 'pull', '--ff-only'], { stdio: 'inherit' });
+        if (pull.status !== 0)
+            fail('update: git pull --ff-only failed — fix the repo state (dirty tree / diverged branch) and re-run');
+        const after = git(['rev-parse', '--short', 'HEAD'], repoTop);
+        if (after === before)
+            console.log(`✓ already up to date (${after})`);
+        else {
+            console.log(`✓ updated ${before} → ${after}`);
+            // What's new — the pulled commits, capped so a long-idle machine doesn't scroll.
+            const log = git(['log', '--oneline', '--no-decorate', `${before}..${after}`], repoTop);
+            if (log) {
+                const lines = log.split('\n');
+                for (const l of lines.slice(0, 30))
+                    console.log(`  ${l}`);
+                if (lines.length > 30)
+                    console.log(`  … ${lines.length - 30} more`);
+            }
+        }
+    }
+    else {
+        // Global npm install — compare against the registry, update when behind.
+        const current = pkgVersion();
+        const view = spawnSync('npm', ['view', '@lovinka/vitrinka', 'version'], { encoding: 'utf8' });
+        const latest = view.status === 0 ? view.stdout.trim() : '';
+        if (!latest) {
+            fail(`update: could not read the registry version (npm view @lovinka/vitrinka version): ${String(view.stderr || view.error || '').trim().slice(0, 200) || 'unknown error'}`);
+        }
+        if (latest === current) {
+            console.log(`✓ already at the latest version (${current})`);
+        }
+        else {
+            console.log(`updating @lovinka/vitrinka ${current || '?'} → ${latest}…`);
+            const inst = spawnSync('npm', ['install', '-g', '@lovinka/vitrinka@latest'], { stdio: 'inherit' });
+            if (inst.status !== 0)
+                fail('update: npm install -g @lovinka/vitrinka@latest failed (see npm output above)');
+            console.log(`✓ @lovinka/vitrinka ${latest}`);
+            // What's new — npm just replaced the package files in place, so the
+            // CHANGELOG next to the CLI is the NEW one; print its sections > current.
+            try {
+                const news = changelogSince(readFileSync(join(dirname(CLI_PATH), '..', 'CHANGELOG.md'), 'utf8'), current);
+                if (news)
+                    console.log(`\n${news}\n`);
+            }
+            catch {
+                // Older packages ship no CHANGELOG.md — nothing to show.
+            }
+        }
+    }
+    // Refresh installed surfaces from the NEW code — skills always (an install
+    // implies them), Claude wiring only if the wrapper shows prior consent.
+    const rerun = (sub) => spawnSync(process.execPath, [CLI_PATH, ...sub], { stdio: 'inherit' }).status === 0;
+    if (!rerun(['install-skills', ...(args.local === true ? ['--local'] : [])])) {
+        fail('update: skills refresh failed — re-run: vitrinka install-skills');
+    }
+    const wrapper = join(process.env.HOME || '', '.claude', 'vitrinka-statusline.sh');
+    if (existsSync(wrapper)) {
+        if (!rerun(['install-claude']))
+            console.error('⚠ update: Claude UI refresh failed — re-run: vitrinka install-claude');
+    }
+    console.log('update 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) {
@@ -2071,17 +2700,30 @@ export const COMMANDS = [
         examples: ['vitrinka operator', 'vitrinka operator "Lukáš"'],
     },
     {
-        name: 'doctor', summary: 'Check this machine\'s setup: server reachable, write token valid, operator set',
-        usage: '[--base <url>]', flags: [BASE_FLAG],
-        examples: ['vitrinka doctor'],
+        name: 'doctor', summary: 'Check this machine\'s setup (server, token, operator, skills, shim, MCP); --fix repairs it',
+        usage: '[--fix] [--base <url>]',
+        flags: [{ f: '--fix', d: 'repair everything repairable: refresh skills, rewrite the shim, re-register the MCP, refresh the Claude UI wiring' }, BASE_FLAG],
+        examples: ['vitrinka doctor', 'vitrinka doctor --fix'],
     },
     {
-        name: 'install', summary: 'Install the PATH shim (+ optional shell completion + Claude Code UI wiring)',
-        usage: '[--no-completion] [--claude|--no-claude]',
-        flags: [{ f: '--no-completion', d: 'skip appending the shell-completion line' },
+        name: 'install', summary: 'Onboard this machine: status table, then skills + shim + completion + MCP + token + operator + Claude UI',
+        usage: '[--local] [--operator <name>] [--mcp|--no-mcp] [--claude|--no-claude] [--no-completion]',
+        flags: [{ f: '--local', d: 'project scope: skills → ./.claude, MCP --scope project; skips shim/completion' },
+            { f: '--operator', arg: '<name>', d: 'set the board-attribution persona without prompting' },
+            { f: '--mcp', d: 'register the MCP without asking' },
+            { f: '--no-mcp', d: 'skip the MCP registration' },
             { f: '--claude', d: 'wire the Claude Code UI without asking' },
-            { f: '--no-claude', d: 'skip the Claude Code UI wiring (default when non-interactive)' }],
-        examples: ['vitrinka install'],
+            { f: '--no-claude', d: 'skip the Claude Code UI wiring' },
+            { f: '--no-completion', d: 'skip appending the shell-completion line' }],
+        examples: ['vitrinka install', 'vitrinka install --local', 'vitrinka install --operator "Lukáš" --mcp --claude'],
+    },
+    {
+        name: 'uninstall', summary: 'Remove everything install put here (skills, shim, completion, Claude wiring, MCP); token/operator survive',
+        usage: '[--purge] [--yes] [--local]',
+        flags: [{ f: '--purge', d: 'also remove ~/.config/vitrinka (token + operator)' },
+            { f: '--yes', d: 'skip the confirmation (required when non-interactive)' },
+            { f: '--local', d: 'remove the project-local install (./.claude) instead' }],
+        examples: ['vitrinka uninstall', 'vitrinka uninstall --purge --yes'],
     },
     {
         name: 'install-claude', summary: 'Wire the Claude Code UI: 🧷 board statusline segment + clickable footer badge',
@@ -2093,6 +2735,27 @@ export const COMMANDS = [
         usage: '[--local]', flags: [{ f: '--local', d: 'install into ./.claude/skills of the current project instead of ~/.claude/skills' }],
         examples: ['vitrinka install-skills'],
     },
+    {
+        name: 'update', summary: 'Update the CLI (git pull / npm -g), show what\'s new, refresh the installed skills + Claude wiring',
+        usage: '[--local]',
+        flags: [{ f: '--local', d: 'refresh skills into ./.claude/skills of the current project instead of ~/.claude/skills' }],
+        examples: ['vitrinka update'],
+    },
+    {
+        name: 'open', summary: 'Open the capture root\'s live board in the browser (--qr renders a terminal QR for the iPad)',
+        usage: '[--root <dir>] [--qr] [--print]',
+        flags: [ROOT_FLAG, { f: '--qr', d: 'print an ANSI QR code of the URL instead of opening the browser (needs qrencode)' },
+            { f: '--print', d: 'only print the URL' }],
+        examples: ['vitrinka open', 'vitrinka open --qr'],
+    },
+    {
+        name: 'status', summary: 'Session dashboard: live board, open work queue, and listener lease for this repo+branch',
+        usage: '[--root <dir>] [--project <p>] [--branch <b>] [--base <url>]',
+        flags: [ROOT_FLAG, { f: '--project', arg: '<p>', d: 'override the inferred project scope' },
+            { f: '--branch', arg: '<b>', d: 'override the inferred branch scope' }, BASE_FLAG],
+        dynamic: 'projects',
+        examples: ['vitrinka status'],
+    },
     {
         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]',
@@ -2946,11 +3609,19 @@ async function runSub(argv) {
     else if (cmd === 'doctor')
         await doctorCmd(args);
     else if (cmd === 'install')
-        installCmd(args);
+        await installCmd(args);
     else if (cmd === 'install-claude')
         installClaudeCmd(args);
     else if (cmd === 'install-skills')
         installSkillsCmd(args);
+    else if (cmd === 'uninstall')
+        uninstallCmd(args);
+    else if (cmd === 'update')
+        await updateCmd(args);
+    else if (cmd === 'open')
+        openCmd(root, args);
+    else if (cmd === 'status')
+        await statusCmd(root, args);
     else if (cmd === 'snap')
         await snapCmd(rest[0] && !rest[0].startsWith('--') ? rest[0] : '', args);
     else if (cmd === 'board-from-set')
@@ -3013,6 +3684,7 @@ export async function main(argv) {
     else if (!COMMAND_MAP[cmd]) {
         // Unknown command → "did you mean" (plain edit-distance, no AI) + usage,
         // then one additive AI hint. Exit 2.
+        maybeHintFirstRun(cmd);
         const near = nearestCommand(cmd);
         console.error(`unknown command ${JSON.stringify(cmd)}${near ? ` — did you mean "${near}"?` : ''}`);
         console.error(USAGE);
@@ -3020,6 +3692,9 @@ export async function main(argv) {
         process.exit(2);
     }
     else {
+        // Passive DX layer — one dim stderr line each, never blocking, never fatal.
+        maybeHintFirstRun(cmd);
+        maybeNotifyUpdate(cmd);
         await runSub(argv);
     }
 }