@lovinka/vitrinka 1.1.1 → 1.4.0

package/README.md

@@ -25,6 +25,26 @@ npm i -g @lovinka/vitrinka
 claude mcp add --scope user vitrinka -- npx -y --package=@lovinka/vitrinka vitrinka-mcp
 ```
 
+`vitrinka install` also offers (interactive `[Y/n]`, or `--claude`/`--no-claude`)
+to wire the **Claude Code UI** — re-runnable standalone as `vitrinka install-claude`:
+
+- **Footer badge** — a `footerLinksRegexes` entry in `~/.claude/settings.json`
+  renders a clickable **🧷 board** badge in Claude Code's footer whenever a
+  `/boards/` URL appears in the conversation (clickable in every terminal;
+  needs Claude Code ≥ 2.1.176).
+- **Statusline segment** — `~/.claude/vitrinka-statusline.sh` wraps your existing
+  statusline command (recorded on its `VITRINKA_ORIG=` line) and appends a
+  `🧷 board` OSC 8 link when the session's `.screenshots/.vitrinka` descriptor
+  exists; with no statusline configured it renders a minimal
+  `dir │ branch │ 🧷 board │ model` line itself. Needs `jq`; degrades to
+  pass-through without it, and never double-renders a board segment your own
+  statusline already prints.
+
+Both steps are idempotent — re-runs detect the wiring and no-op. To remove:
+delete `~/.claude/vitrinka-statusline.sh`, restore `statusLine.command` in
+`~/.claude/settings.json` to the `VITRINKA_ORIG` value (or drop the key), and
+remove the `footerLinksRegexes` entry whose pattern contains `/boards/`.
+
 For Claude Desktop or any other MCP client, add the equivalent entry by hand:
 
 ```json

package/dist/cli.js

@@ -10,14 +10,14 @@
 // 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 { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync, copyFileSync, mkdtempSync, chmodSync, appendFileSync, statSync, cpSync, openSync, readSync, closeSync, } 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 { readToken, tokenSource, tokenPath, tokenHelp } 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);
@@ -146,6 +146,26 @@ export function shotContext(args) {
     }
     return out;
 }
+// appVersionOf reads the app's version string for capture provenance:
+// app.json (Expo: expo.version, or bare version) first, then package.json.
+// Best-effort — a missing/malformed file just leaves the field off.
+export function appVersionOf(projectDir) {
+    for (const f of ['app.json', 'package.json']) {
+        const p = join(projectDir, f);
+        if (!existsSync(p))
+            continue;
+        try {
+            const j = JSON.parse(readFileSync(p, 'utf8'));
+            const v = j?.expo?.version ?? j?.version;
+            if (typeof v === 'string' && v)
+                return v;
+        }
+        catch {
+            // Malformed JSON is not snap's problem — provenance is best-effort.
+        }
+    }
+    return '';
+}
 function appendShot(root, shot) {
     const m = loadManifest(root);
     m.shots.push(shot);
@@ -470,17 +490,23 @@ function cmdDescription(mdPath) {
  *  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).
+ *  Home entries are tagged `s:"home"` so the board can tier + mark them.
  *  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) => {
+    const add = (segs, mdPath, home) => {
         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 e = { c };
+        if (d)
+            e.d = d;
+        if (home)
+            e.s = 'home';
+        out.set(c, e);
     };
     const list = (dir) => {
         try {
@@ -491,15 +517,16 @@ export function collectCommands(projectDir, homeClaude = join(process.env.HOME |
         }
     };
     for (const root of [join(projectDir, '.claude'), homeClaude]) {
+        const home = root === homeClaude;
         for (const rel of list(join(root, 'commands'))) {
             if (!rel.endsWith('.md'))
                 continue;
-            add(rel.slice(0, -3).split('/'), join(root, 'commands', rel));
+            add(rel.slice(0, -3).split('/'), join(root, 'commands', rel), home);
         }
         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));
+            add(rel.slice(0, -'/SKILL.md'.length).split('/'), join(root, 'skills', rel), home);
         }
     }
     return [...out.values()].sort((a, b) => (a.c < b.c ? -1 : a.c > b.c ? 1 : 0));
@@ -523,7 +550,9 @@ export function buildProjectIndex(projectDir) {
         files = files.slice(0, 50_000);
     }
     const routes = extractRoutes(files);
-    const cmds = collectCommands(projectDir);
+    // The palette lives at the repo root's .claude — resolve from `top`, not the
+    // raw cwd, or a push from a subdir silently indexes only ~/.claude.
+    const cmds = collectCommands(top);
     // 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 {
@@ -612,6 +641,111 @@ async function indexCmd(root, args) {
     if (!(await pushProjectIndex(projectDir, base, project, true)))
         process.exit(1);
 }
+const COMPONENT_SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.next', '.expo', 'coverage', '.git', '__tests__', '__mocks__']);
+function scanComponentFiles(dir, out) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // a listed default dir simply doesn't exist in this repo
+    }
+    for (const e of entries) {
+        if (e.isDirectory()) {
+            if (!COMPONENT_SKIP_DIRS.has(e.name) && !e.name.startsWith('.'))
+                scanComponentFiles(join(dir, e.name), out);
+        }
+        else if (/\.(tsx|jsx)$/.test(e.name) && !/\.(test|spec|stories)\./.test(e.name)) {
+            out.push(join(dir, e.name));
+        }
+    }
+}
+function extractProps(src, comp) {
+    const m = src.match(new RegExp(`(?:interface\\s+${comp}Props\\s*(?:extends [^{]+)?|type\\s+${comp}Props\\s*=\\s*)\\{`));
+    if (!m || m.index === undefined)
+        return { props: [], variants: [] };
+    // Balance braces from the block open so nested object types don't truncate.
+    let depth = 0, i = src.indexOf('{', m.index), start = i;
+    for (; i < src.length; i++) {
+        if (src[i] === '{')
+            depth++;
+        else if (src[i] === '}' && --depth === 0)
+            break;
+    }
+    const block = src.slice(start + 1, i);
+    const props = [];
+    const variants = [];
+    for (const line of block.split('\n')) {
+        const pm = line.match(/^\s*(\w+)(\?)?\s*:\s*([^;]+)/);
+        if (!pm)
+            continue;
+        const type = pm[3].trim().replace(/\s+/g, ' ').slice(0, 120);
+        props.push({ name: pm[1], type, required: !pm[2] });
+        const lits = type.match(/'[^']+'/g);
+        if (lits && lits.length > 1)
+            variants.push(`${pm[1]}=${lits.map((l) => l.slice(1, -1)).join('|')}`);
+    }
+    return { props, variants };
+}
+function scanComponents(projectDir, srcDirs) {
+    const files = [];
+    for (const d of srcDirs)
+        scanComponentFiles(resolve(projectDir, d), files);
+    const seen = new Map();
+    for (const file of files) {
+        const src = readFileSync(file, 'utf8');
+        const names = new Set();
+        for (const m of src.matchAll(/export\s+(?:default\s+)?function\s+([A-Z]\w+)\s*[(<]/g))
+            names.add(m[1]);
+        for (const m of src.matchAll(/export\s+const\s+([A-Z]\w+)\s*(?::[^=]+)?=\s*(?:React\.)?(?:memo|forwardRef)?\s*[(<]/g))
+            names.add(m[1]);
+        for (const name of names) {
+            if (seen.has(name))
+                continue; // first definition wins; dupes are re-exports
+            const { props, variants } = extractProps(src, name);
+            seen.set(name, { name, kind: 'component', sourcePath: relative(projectDir, file), props, variants });
+        }
+    }
+    return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+async function indexComponentsCmd(root, args) {
+    const projectDir = dirname(root);
+    const library = strArg(args.library);
+    if (!library)
+        throw new Error('index-components: --library <kit> is required (one per UI library, e.g. "web" or "expo")');
+    const base = (strArg(args.base) || process.env.VITRINKA_URL || 'https://vitrinka.lovinka.com').replace(/\/+$/, '');
+    const project = sanitizeSeg(strArg(args.project) || basename(mainWorktreeTop(projectDir) || projectDir), 64);
+    let components;
+    if (strArg(args.from)) {
+        const raw = JSON.parse(readFileSync(String(args.from), 'utf8'));
+        components = Array.isArray(raw) ? raw : raw.components;
+        if (!Array.isArray(components))
+            throw new Error('index-components: --from file must be a components array or {components:[…]}');
+    }
+    else {
+        const dirs = (strArg(args.src) || 'src/components,components,src').split(',').map((d) => d.trim()).filter(Boolean);
+        components = scanComponents(projectDir, dirs);
+        if (!components.length) {
+            throw new Error(`index-components: no exported components under ${dirs.join(', ')} — pass --src or check the library root`);
+        }
+    }
+    if (args.dry) {
+        console.log(JSON.stringify({ project, library, components }, null, 2));
+        return;
+    }
+    const token = readToken();
+    const headers = { 'Content-Type': 'application/json' };
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    const res = await fetch(`${base}/api/v1/projects/${encodeURIComponent(project)}/components`, {
+        method: 'PUT', headers,
+        body: JSON.stringify({ library, components }),
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!res.ok)
+        throw new Error(`index-components: push rejected (HTTP ${res.status}): ${(await res.text()).slice(0, 200)}`);
+    console.log(`components ↑ ${project}/${library}: ${components.length} indexed`);
+}
 function loadVitrinkaCfg(root) {
     const raw = readFileSync(vitrinkaCfgPath(root), 'utf8'); // caller checks existsSync
     try {
@@ -904,7 +1038,118 @@ async function operatorCmd(rest, args) {
         console.error(`operator: server unreachable (${e instanceof Error ? e.message : String(e)}) — local name is set; re-run to publish`);
     }
 }
+// ---------- doctor: setup health check ----------
+// doctorCmd checks this machine's vitrinka setup: server reachable, write
+// token present AND accepted by the server, operator persona set. The token
+// probe is `PUT /api/v1/operator` with an empty JSON body — auth runs before
+// body validation, so 401 = bad token and 422 = token accepted, with nothing
+// ever written. Exit 1 when the server is unreachable or the token is
+// missing/rejected (reads still work; writes would 401).
+async function doctorCmd(args) {
+    const base = resolveBaseUrl(strArg(args.base));
+    let failed = false;
+    let reachable = false;
+    try {
+        const res = await fetch(`${base}/healthz`, { signal: AbortSignal.timeout(10_000) });
+        reachable = res.ok;
+        console.log(res.ok ? `✓ server     ${base}` : `✗ server     ${base} (HTTP ${res.status})`);
+        if (!res.ok)
+            failed = true;
+    }
+    catch (e) {
+        console.log(`✗ server     ${base} unreachable (${e instanceof Error ? e.message : String(e)}) — vitrinka is WireGuard-mesh-only; bring the VPN up`);
+        failed = true;
+    }
+    const src = tokenSource();
+    const token = readToken();
+    if (!token) {
+        console.log(`✗ token      missing ($VITRINKA_TOKEN unset, no ${tokenPath()}) — writes will 401`);
+        console.log('');
+        console.log(tokenHelp());
+        console.log('');
+        failed = true;
+    }
+    else if (reachable) {
+        try {
+            const res = await fetch(`${base}/api/v1/operator`, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+                body: '{}',
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (res.status === 401) {
+                console.log(`✗ token      REJECTED by ${base} (from ${src === 'env' ? '$VITRINKA_TOKEN' : tokenPath()}) — stale or mistyped`);
+                console.log('');
+                console.log(tokenHelp());
+                console.log('');
+                failed = true;
+            }
+            else {
+                console.log(`✓ token      valid (from ${src === 'env' ? '$VITRINKA_TOKEN' : tokenPath()})`);
+            }
+        }
+        catch (e) {
+            console.log(`? token      present (from ${src === 'env' ? '$VITRINKA_TOKEN' : tokenPath()}) — validity check failed (${e instanceof Error ? e.message : String(e)})`);
+        }
+    }
+    else {
+        console.log(`? token      present (from ${src === 'env' ? '$VITRINKA_TOKEN' : tokenPath()}) — server unreachable, validity unknown`);
+    }
+    const op = readOperator(true);
+    if (op)
+        console.log(`✓ operator   ${op}`);
+    else
+        console.log('✗ operator   unset — board writes stay anonymous (fix: vitrinka operator <name>)');
+    if (failed)
+        process.exit(1);
+}
 // ---------- install: PATH shim ----------
+// bundledSkillsDir locates the skills bundle shipped inside the npm package
+// (dist/cli.js → ../skills) or, when running from a repo checkout
+// (pkg/src/cli.ts), the repo-root skills/ directory.
+export function bundledSkillsDir(cliPath) {
+    for (const cand of [join(dirname(cliPath), '..', 'skills'), join(dirname(cliPath), '..', '..', 'skills')]) {
+        if (existsSync(join(cand, 'vitrinka')))
+            return cand;
+    }
+    return '';
+}
+// 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.
+function installSkillsCmd(args) {
+    const bundle = bundledSkillsDir(CLI_PATH);
+    if (!bundle)
+        fail('install-skills: bundled skills not found next to the CLI — reinstall the package');
+    const home = process.env.HOME;
+    const local = args.local === true;
+    if (!local && !home)
+        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).
+    const names = readdirSync(bundle).filter((n) => !n.startsWith('.') && statSync(join(bundle, n)).isDirectory());
+    if (!names.length)
+        fail(`install-skills: no skills found in ${bundle}`);
+    for (const n of names) {
+        rmSync(join(target, n), { recursive: true, force: true });
+        cpSync(join(bundle, n), join(target, n), { recursive: true });
+        // Local installs live at ./.claude/skills — keep referenced CLI paths copy-pasteable.
+        if (local) {
+            for (const doc of [join(target, n, 'SKILL.md'), join(target, n, 'listen', 'SKILL.md')]) {
+                if (!existsSync(doc))
+                    continue;
+                writeFileSync(doc, readFileSync(doc, 'utf8')
+                    .replaceAll('~/.claude/skills/vitrinka/cli.ts', '.claude/skills/vitrinka/cli.ts'));
+            }
+        }
+        console.log(`✓ ${n} → ${join(target, n)}`);
+    }
+    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
@@ -956,8 +1201,195 @@ function installCmd(args) {
             console.log(`added ${shellName} completion to ${rc} (open a new shell, or: source ${rc})`);
         }
     }
+    // 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)');
+    }
+    else if (args.claude === true || promptYesNo('Wire Claude Code UI (🧷 board statusline segment + clickable footer badge)? [Y/n] ')) {
+        installClaudeCmd(args);
+    }
+    else if (!process.stdin.isTTY) {
+        console.log('claude wiring: skipped (non-interactive — run `vitrinka install-claude`, or pass --claude)');
+    }
+    else {
+        console.log('claude wiring: skipped (re-run any time: vitrinka install-claude)');
+    }
     console.log('done — try: vitrinka --help');
 }
+// ---------- install-claude: Claude Code UI wiring ----------
+//
+// Wires the two Claude Code surfaces that link to boards (decisions:
+// docs/specs/2026-07-07-claude-install-decisions.md):
+//   1. footerLinksRegexes in ~/.claude/settings.json — Claude renders its own
+//      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.
+//      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
+// statusLine.command (recorded in the wrapper's VITRINKA_ORIG line) + drop the
+// footerLinksRegexes entry (documented in pkg/README.md).
+export const BOARD_FOOTER_LINK = {
+    type: 'regex',
+    pattern: '(?<url>https?:\\/\\/\\S+\\/boards\\/(?<slug>[\\w.-]+))',
+    url: '{url}',
+    label: 'vitrinka/b/{slug}',
+};
+// hasBoardFooterLink — an entry whose pattern targets /boards/ URLs already
+// exists (ours or hand-written); the marker that makes the settings edit idempotent.
+export function hasBoardFooterLink(settings) {
+    const arr = settings.footerLinksRegexes;
+    // Strip regex escaping first — patterns write the path as \/boards\/ as often as /boards/.
+    return Array.isArray(arr) && arr.some((e) => typeof e?.pattern === 'string' && e.pattern.replaceAll('\\', '').includes('/boards/'));
+}
+// buildStatuslineWrapper — the ~/.claude/vitrinka-statusline.sh content. The
+// original command is recorded on the VITRINKA_ORIG line (single-quoted), both
+// to run it and so a re-run can recover it instead of wrapping the wrapper.
+// Board detection mirrors the CLI's capture-root contract: .screenshots/.vitrinka
+// with {base, key} → ${base}/boards/${key}. Needs jq (like the statusline
+// examples in Claude's own docs); without jq it degrades to pass-through.
+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.
+VITRINKA_ORIG='${quoted}'
+
+input=$(cat)
+
+out=""
+if [ -n "$VITRINKA_ORIG" ]; then
+  out=$(printf '%s' "$input" | /bin/sh -c "$VITRINKA_ORIG")
+fi
+
+# The original already renders a board segment → pass through untouched.
+case "$out" in *'/boards/'*|*'🧷'*) printf '%s\\n' "$out"; exit 0 ;; esac
+
+if ! command -v jq >/dev/null 2>&1; then printf '%s\\n' "$out"; exit 0; fi
+
+DIR=$(printf '%s' "$input" | jq -r '.workspace.current_dir // empty')
+PROJECT_DIR=$(printf '%s' "$input" | jq -r '.workspace.project_dir // empty')
+
+BOARD=""
+for VJSON in "$DIR/.screenshots/.vitrinka" "$PROJECT_DIR/.screenshots/.vitrinka"; do
+  [ -f "$VJSON" ] || continue
+  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")
+  fi
+  break
+done
+
+DIM=$(printf '\\033[2m'); RESET=$(printf '\\033[0m')
+
+if [ -n "$VITRINKA_ORIG" ]; then
+  # Append to the FIRST line only (extra statusline lines stay untouched).
+  first=\${out%%$'\\n'*}; rest=\${out#"$first"}
+  [ -n "$BOARD" ] && first="$first \${DIM}│\${RESET} $BOARD"
+  printf '%s%s\\n' "$first" "$rest"
+else
+  # No original statusline — minimal line: dir │ branch │ board │ model.
+  MODEL=$(printf '%s' "$input" | jq -r '.model.display_name // empty')
+  BRANCH=$(git -C "\${DIR:-.}" branch --show-current 2>/dev/null)
+  GREEN=$(printf '\\033[32m'); CYAN=$(printf '\\033[36m')
+  line="\${DIR/#$HOME/~}"
+  [ -n "$BRANCH" ] && line="$line \${DIM}│\${RESET} \${GREEN}\${BRANCH}\${RESET}"
+  [ -n "$BOARD" ] && line="$line \${DIM}│\${RESET} $BOARD"
+  [ -n "$MODEL" ] && line="$line \${DIM}│\${RESET} \${CYAN}\${MODEL}\${RESET}"
+  printf '%s\\n' "$line"
+fi
+`;
+}
+// wrapperOrigCommand — recover the original statusline command a wrapper file
+// recorded, so re-runs refresh the wrapper without wrapping it around itself.
+export function wrapperOrigCommand(content) {
+    const line = content.split('\n').find((l) => l.startsWith("VITRINKA_ORIG='"));
+    if (!line || !line.endsWith("'"))
+        return '';
+    return line.slice("VITRINKA_ORIG='".length, -1).replaceAll(`'\\''`, "'");
+}
+// promptYesNo — synchronous [Y/n] on the controlling TTY (Enter = yes). False on
+// any non-interactive stdin or when /dev/tty can't be opened (CI, curl|bash).
+function promptYesNo(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    process.stdout.write(question);
+    try {
+        const fd = openSync('/dev/tty', 'r');
+        const buf = Buffer.alloc(64);
+        const n = readSync(fd, buf, 0, 64, null);
+        closeSync(fd);
+        const ans = buf.toString('utf8', 0, n).trim().toLowerCase();
+        return ans === '' || ans === 'y' || ans === 'yes';
+    }
+    catch {
+        return false; // no controlling TTY — treat as non-interactive, never block
+    }
+}
+export function installClaudeCmd(_args) {
+    const home = process.env.HOME;
+    if (!home)
+        fail('install-claude: $HOME is not set');
+    const claudeDir = join(home, '.claude');
+    if (!existsSync(claudeDir)) {
+        console.log('install-claude: ~/.claude not found — Claude Code is not set up on this machine; skipping');
+        return;
+    }
+    const settingsPath = join(claudeDir, 'settings.json');
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        }
+        catch (e) {
+            fail(`install-claude: ${settingsPath} is not valid JSON — nothing was changed; fix it first (${e.message})`);
+        }
+    }
+    let changed = false;
+    // 1. Footer badge — clickable in every terminal (requires Claude Code ≥ 2.1.176).
+    if (hasBoardFooterLink(settings)) {
+        console.log('✓ footer badge already configured (footerLinksRegexes /boards/ entry)');
+    }
+    else {
+        settings.footerLinksRegexes = [...(Array.isArray(settings.footerLinksRegexes) ? settings.footerLinksRegexes : []), BOARD_FOOTER_LINK];
+        changed = true;
+        console.log('✓ footer badge → footerLinksRegexes (clickable "🧷 board" whenever a board URL appears in conversation)');
+    }
+    // 2. Statusline wrapper.
+    const wrapperPath = join(claudeDir, 'vitrinka-statusline.sh');
+    const wrapperCmd = '~/.claude/vitrinka-statusline.sh';
+    const sl = settings.statusLine;
+    if (sl && sl.type !== undefined && sl.type !== 'command') {
+        console.error(`⚠ statusLine.type is ${JSON.stringify(sl.type)} — don't know how to wrap it; statusline left untouched (footer badge still works)`);
+    }
+    else {
+        const current = sl?.command ?? '';
+        const isWrapper = current.replace(/^~(?=\/)/, home) === wrapperPath;
+        // Re-runs recover the original from the existing wrapper file — never wrap the wrapper.
+        const orig = isWrapper && existsSync(wrapperPath) ? wrapperOrigCommand(readFileSync(wrapperPath, 'utf8')) : current;
+        writeFileSync(wrapperPath, buildStatuslineWrapper(orig));
+        chmodSync(wrapperPath, 0o755);
+        if (!isWrapper) {
+            settings.statusLine = { type: 'command', command: wrapperCmd };
+            changed = true;
+        }
+        if (isWrapper)
+            console.log(`✓ statusline wrapper refreshed (${wrapperPath}${orig ? `, wraps: ${orig}` : ', minimal line'})`);
+        else if (orig)
+            console.log(`✓ statusline wrapped → ${wrapperPath} (appends 🧷 board to: ${orig})`);
+        else
+            console.log(`✓ statusline installed → ${wrapperPath} (minimal: dir │ branch │ 🧷 board │ model)`);
+    }
+    if (changed)
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    console.log(`install-claude done — restart Claude Code sessions to pick up ${settingsPath}`);
+}
 // ---------- snap: one-shot capture → manifest → detached push ----------
 // Filename slug: diacritics folded (Přihlášení → prihlaseni), non-alnum → '-', capped.
 export function kebab(s) {
@@ -1258,6 +1690,13 @@ async function snapCmd(surface, args) {
     if (surface === 'ios' && iosSimName && !ctx.device?.device) {
         ctx.device = { ...ctx.device, device: iosSimName };
     }
+    // Capture provenance: the mechanism that produced the pixels, the URL/deep
+    // link the screen was opened at (--url wins over --open), and the app build.
+    const tool = adopt ? 'adopted'
+        : surface === 'ios' ? 'simctl'
+            : surface === 'android' ? 'adb-screencap'
+                : 'screencapture';
+    const url = strArg(args.url) || openUrl;
     const { count } = appendShot(root, {
         file: `${day}/${name}`,
         surface,
@@ -1268,6 +1707,9 @@ async function snapCmd(surface, args) {
         action: strArg(args.action) || undefined,
         hq: hq || undefined,
         ts: new Date().toISOString(),
+        tool,
+        url: url || undefined,
+        appVersion: appVersionOf(projectDir) || undefined,
         ...ctx,
     });
     maybeWarnOffline(root);
@@ -1629,10 +2071,28 @@ export const COMMANDS = [
         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' }],
+        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: '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' },
+            { 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'],
     },
+    {
+        name: 'install-claude', summary: 'Wire the Claude Code UI: 🧷 board statusline segment + clickable footer badge',
+        usage: '', flags: [],
+        examples: ['vitrinka install-claude'],
+    },
+    {
+        name: 'install-skills', summary: 'Install the bundled Claude skills (vitrinka, screenshot, artifact, brainstorming)',
+        usage: '[--local]', flags: [{ f: '--local', d: 'install into ./.claude/skills of the current project instead of ~/.claude/skills' }],
+        examples: ['vitrinka install-skills'],
+    },
     {
         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]',
@@ -1642,6 +2102,7 @@ export const COMMANDS = [
             { 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: '--url', arg: '<url>', d: 'exact URL the shot was taken at (provenance; defaults to --open)' },
             { 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'],
     },
@@ -1673,6 +2134,20 @@ export const COMMANDS = [
         dynamic: 'projects',
         examples: ['vitrinka index --root .screenshots'],
     },
+    {
+        name: 'index-components', summary: 'Scan a UI library for exported components + push the component index',
+        usage: '--library <kit> [--src <dirs>] [--project <p>] [--from <file.json>] [--dry] [--base <url>]',
+        flags: [
+            { f: '--library', arg: '<kit>', d: 'UI kit name, one per library in a monorepo (e.g. "web", "expo") — required' },
+            { f: '--src', arg: '<dirs>', d: 'comma-separated dirs to scan (default "src/components,components,src")' },
+            { f: '--project', arg: '<p>', d: 'project slug (default: worktree name)' },
+            { f: '--from', arg: '<file>', d: 'push a prepared components JSON (the AI pre-index output) instead of scanning' },
+            { f: '--dry', d: 'print the scan as JSON, push nothing (feed this to the AI pre-index pass)' },
+            BASE_FLAG
+        ],
+        examples: ['vitrinka index-components --library web --dry > components.json',
+            'vitrinka index-components --library web --from components.json'],
+    },
     {
         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',
@@ -2180,7 +2655,7 @@ async function boardFromSetCmd(root, 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 }),
+        method: 'POST', headers, body: JSON.stringify({ slug, title, project: cfg.project }),
         signal: AbortSignal.timeout(30_000),
     });
     if (!create.ok && create.status !== 409) { // 409 = board exists → reuse
@@ -2468,8 +2943,14 @@ async function runSub(argv) {
         await nameCmd(argv, args);
     else if (cmd === 'operator')
         await operatorCmd(argv, args);
+    else if (cmd === 'doctor')
+        await doctorCmd(args);
     else if (cmd === 'install')
         installCmd(args);
+    else if (cmd === 'install-claude')
+        installClaudeCmd(args);
+    else if (cmd === 'install-skills')
+        installSkillsCmd(args);
     else if (cmd === 'snap')
         await snapCmd(rest[0] && !rest[0].startsWith('--') ? rest[0] : '', args);
     else if (cmd === 'board-from-set')
@@ -2478,6 +2959,8 @@ async function runSub(argv) {
         await watchCmd(args);
     else if (cmd === 'index')
         await indexCmd(root, args);
+    else if (cmd === 'index-components')
+        await indexComponentsCmd(root, args);
     else if (cmd === 'embed-shots')
         embedShotsCmd(root, args);
     else if (cmd === 'artifact-init')