@lovinka/vitrinka 1.7.1 → 1.9.0

package/dist/cli.js

@@ -10,7 +10,7 @@
 // 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, cpSync, openSync, readSync, closeSync, realpathSync, } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync, copyFileSync, mkdtempSync, chmodSync, appendFileSync, statSync, openSync, readSync, closeSync, realpathSync, } 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';
@@ -1107,7 +1107,9 @@ 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();
+    // stripControl mirrors the server's 422 on control characters — an
+    // arrow-edited or paste-polluted name must never reach the settings key.
+    const name = stripControl(pos.join(' '));
     if (!name) {
         const local = readOperator(true);
         console.log(`operator (local): ${local || '(unset)'}`);
@@ -1218,20 +1220,20 @@ 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
+    // Setup surfaces (plugin / 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);
+    for (const rt of pluginRuntimes()) {
+        if (!rt.present)
+            continue; // no runtime, nothing to wire
+        if (rt.installed)
+            console.log(`✓ plugin     ${rt.name}: vitrinka installed`);
+        else if (fix && installPluginInto(rt))
+            console.log(`✓ plugin     ${rt.name}: vitrinka installed`);
         else
-            console.log(`✗ skills     ${st} — repair: vitrinka doctor --fix`);
+            console.log(`✗ plugin     ${rt.name}: not installed — repair: vitrinka doctor --fix`);
     }
     if (home) {
         const shimP = shimPathOf(home);
@@ -1262,110 +1264,88 @@ async function doctorCmd(args) {
     if (home && existsSync(join(home, '.claude', 'vitrinka-statusline.sh'))) {
         if (fix)
             installClaudeCmd(args);
-        else
+        else if (existsSync(join(home, '.claude', 'hooks', 'vitrinka-board-link.sh')))
             console.log('✓ claude ui  wired (refresh: vitrinka doctor --fix)');
+        else
+            console.log('✗ claude ui  session-start hook missing — repair: vitrinka doctor --fix');
     }
+    const appPath = refreshDesktopAppFlag();
+    console.log(appPath ? `✓ app        ${appPath} (flag: ${desktopAppFlagPath()})` : `- app        Vitrinka.app not installed (no flag)`);
     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. `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: 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'));
-            }
+// ---------- plugin distribution (skills ship via the runtimes' plugin systems) ----------
+// The skills bundle used to be copied into ~/.claude/skills (install-skills,
+// REMOVED 2026-07-11). Skills now distribute exclusively as the `vitrinka`
+// plugin from the `lovinka` marketplace (this repo), installable into BOTH
+// Claude Code and Codex — one distribution per machine per runtime.
+const MARKETPLACE_REPO = 'LEFTEQ/vitrinka';
+// pluginRuntimes probes which agent CLIs exist and whether the vitrinka
+// plugin is installed in each. Claude records installs in
+// ~/.claude/plugins/installed_plugins.json; Codex is asked directly
+// (`codex plugin list` is fast and authoritative across its versions).
+function pluginRuntimes() {
+    const home = process.env.HOME || '';
+    const out = [];
+    const claudePresent = claudeCliPresent();
+    let claudeInstalled = false;
+    if (claudePresent && home) {
+        try {
+            claudeInstalled = readFileSync(join(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf8')
+                .includes('vitrinka@lovinka');
+        }
+        catch {
+            claudeInstalled = false; // no plugins file yet — nothing installed
         }
-        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')}`);
+    out.push({ name: 'claude', present: claudePresent, installed: claudeInstalled });
+    const codexPresent = !spawnSync('codex', ['--version'], { stdio: 'ignore' }).error;
+    let codexInstalled = false;
+    if (codexPresent) {
+        const r = spawnSync('codex', ['plugin', 'list'], { encoding: 'utf8' });
+        codexInstalled = r.status === 0 && /\bvitrinka\b/.test(r.stdout || '');
     }
-    console.log(`${names.length} skill${names.length === 1 ? '' : 's'} installed (${names.sort().join(', ')})`);
+    out.push({ name: 'codex', present: codexPresent, installed: codexInstalled });
+    return out;
 }
-// ---------- 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)
+// installPluginInto registers the lovinka marketplace and installs the
+// vitrinka plugin for one runtime. Both runtimes' commands are idempotent
+// enough for our purposes (marketplace add on an existing source errors —
+// tolerated; install/add on an installed plugin re-snapshots).
+function installPluginInto(rt) {
+    const cmds = rt.name === 'claude'
+        ? [['claude', 'plugin', 'marketplace', 'add', MARKETPLACE_REPO], ['claude', 'plugin', 'install', 'vitrinka@lovinka']]
+        : [['codex', 'plugin', 'marketplace', 'add', MARKETPLACE_REPO], ['codex', 'plugin', 'add', 'vitrinka@lovinka']];
+    for (const [bin, ...rest] of cmds) {
+        const r = spawnSync(bin, rest, { encoding: 'utf8' });
+        if (r.status !== 0 && !/already|exists/i.test((r.stderr || '') + (r.stdout || ''))) {
+            console.error(`⚠ ${rt.name}: \`${[bin, ...rest].join(' ')}\` failed${r.stderr ? ` — ${r.stderr.trim().split('\n').pop()}` : ''}`);
             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';
+// updatePluginIn refreshes an installed plugin to the marketplace's latest.
+function updatePluginIn(rt) {
+    const cmd = rt.name === 'claude'
+        ? ['claude', 'plugin', 'update', 'vitrinka@lovinka']
+        : ['codex', 'plugin', 'marketplace', 'upgrade'];
+    return spawnSync(cmd[0], cmd.slice(1), { stdio: 'inherit' }).status === 0;
 }
+// ---------- setup state probing (shared by install / doctor / uninstall) ----------
 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.
+// The registration is the REMOTE streamable-HTTP endpoint the Go server hosts
+// at {base}/mcp (remote-mcp decisions 2026-07-12) — no local process per
+// session; the old stdio bin is deprecated. The bearer token is required on
+// every /mcp request, so registration without a token is refused with the
+// token help. X-Board-Actor rides along when an operator persona exists
+// (UTF-8 bytes latin-1-encoded — header values are ByteStrings).
 function claudeCliPresent() {
     return !spawnSync('claude', ['--version'], { stdio: 'ignore' }).error;
 }
@@ -1374,15 +1354,22 @@ function mcpRegistered() {
     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'];
+    const args = ['--transport', 'http', 'vitrinka', `${resolveBaseUrl()}/mcp`];
+    const token = readToken();
+    if (token)
+        args.push('--header', `Authorization: Bearer ${token}`);
+    const actor = actorHeaderValue(readOperator(true));
+    if (actor)
+        args.push('--header', `X-Board-Actor: ${actor}`);
+    return args;
 }
 function registerMcp(scope) {
+    if (!readToken()) {
+        console.log(`✗ mcp not registered — /mcp requires a bearer token on every request.\n${tokenHelp()}`);
+        return false;
+    }
     spawnSync('claude', ['mcp', 'remove', '--scope', scope, 'vitrinka'], { stdio: 'ignore' });
-    return spawnSync('claude', ['mcp', 'add', '--scope', scope, 'vitrinka', '--', ...mcpTarget()], { stdio: 'inherit' }).status === 0;
+    return spawnSync('claude', ['mcp', 'add', '--scope', scope, ...mcpTarget()], { stdio: 'inherit' }).status === 0;
 }
 // promptLine — visible one-line read from the controlling TTY ('' when
 // non-interactive, like promptYesNo).
@@ -1395,12 +1382,21 @@ function promptLine(question) {
         const buf = Buffer.alloc(512);
         const n = readSync(fd, buf, 0, 512, null);
         closeSync(fd);
-        return buf.toString('utf8', 0, n).trim();
+        // A cooked-mode tty read line-edits backspace but NOT arrow keys — those
+        // arrive as raw ESC[D/ESC[C sequences that LOOK like cursor movement while
+        // typing. Strip ANSI sequences and control chars so an arrow-edited answer
+        // never persists escape bytes (the ␛[D␛[D␛[C operator-name incident).
+        return stripControl(buf.toString('utf8', 0, n));
     }
     catch {
         return ''; // no controlling TTY — treat as non-interactive, never block
     }
 }
+// stripControl — remove ANSI escape sequences and control characters from a
+// line of user input, then trim.
+export function stripControl(s) {
+    return s.replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '').replace(/[\x00-\x1f\x7f]/g, '').trim();
+}
 // 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) {
@@ -1431,9 +1427,7 @@ async function installCmd(args) {
     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 runtimes = pluginRuntimes();
     const shimP = shimPathOf(home);
     const shimOk = existsSync(shimP) && readFileSync(shimP, 'utf8') === SHIM_CONTENT;
     const rc = rcPathOf(home);
@@ -1448,8 +1442,9 @@ async function installCmd(args) {
         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`);
+    for (const rt of runtimes) {
+        row(rt.installed, `plugin·${rt.name}`, rt.installed ? 'vitrinka installed' : rt.present ? 'will install (skills ship as the plugin)' : `${rt.name} CLI not found`);
+    }
     if (!local)
         row(shimOk, 'shim', shimOk ? shimP : 'will install');
     if (!local)
@@ -1457,11 +1452,13 @@ async function installCmd(args) {
     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');
+    row(uiOk, 'claude ui', uiOk ? 'statusline + footer + session hook wired' : 'not wired');
     console.log('');
-    // ---- silent steps: skills, shim, PATH, completion (reversible, own dirs) ----
-    if (bundle && skills !== 'current')
-        installSkillsCmd(args);
+    // ---- silent steps: plugins, shim, PATH, completion (reversible, own dirs) ----
+    for (const rt of runtimes) {
+        if (rt.present && !rt.installed && installPluginInto(rt))
+            console.log(`✓ plugin (${rt.name}) → vitrinka@lovinka`);
+    }
     if (!local) {
         if (!shimOk) {
             mkdirSync(dirname(shimP), { recursive: true });
@@ -1485,7 +1482,9 @@ async function installCmd(args) {
     }
     // ---- asked steps: the config-touchers ----
     // 1. MCP registration (claude's registry).
-    const mcpCmdHint = `claude mcp add --scope ${mcpScope} vitrinka -- ${mcpTarget().join(' ')}`;
+    // Hint never inlines the token — the shell substitution reads it at run time.
+    const mcpCmdHint = `claude mcp add --scope ${mcpScope} --transport http vitrinka ${resolveBaseUrl()}/mcp `
+        + `--header "Authorization: Bearer $(cat ${tokenPath()})"`;
     if (!haveClaude) {
         console.error(`⚠ claude CLI not found — register the MCP later with:\n  ${mcpCmdHint}`);
     }
@@ -1542,7 +1541,7 @@ async function installCmd(args) {
         console.log('claude ui: skipped (--no-claude)');
     }
     else if (uiOk || args.claude === true
-        || promptYesNo('Wire Claude Code UI (🧷 board statusline segment + clickable footer badge)? [Y/n] ')) {
+        || promptYesNo('Wire Claude Code UI (🧷 board statusline segment + clickable footer badge + session-start board link)? [Y/n] ')) {
         installClaudeCmd(args);
     }
     else if (!process.stdin.isTTY) {
@@ -1587,9 +1586,9 @@ export function stripMarkerBlock(content, marker) {
     }
     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'];
+// Legacy ~/.claude/skills copy names — removed by uninstall on machines set
+// up before the plugin distribution (install-skills, removed 2026-07-11).
+const LEGACY_SKILLS = ['artifact', 'brainstorming', 'screenshot', 'vitrinka', 'listen'];
 // 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/
@@ -1600,21 +1599,31 @@ function uninstallCmd(args) {
     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] `)) {
+    if (args.yes !== true && !promptYesNo(`Remove vitrinka from this machine (plugins, legacy skill copies, 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;
+    // Plugins (the current distribution) + legacy ~/.claude/skills copies +
+    // the old /vitrinka:listen command stub, from machines set up pre-plugin.
+    for (const rt of pluginRuntimes()) {
+        if (!rt.installed)
+            continue;
+        const cmd = rt.name === 'claude'
+            ? ['claude', 'plugin', 'uninstall', 'vitrinka@lovinka']
+            : ['codex', 'plugin', 'remove', 'vitrinka@lovinka'];
+        if (spawnSync(cmd[0], cmd.slice(1), { stdio: 'inherit' }).status === 0) {
+            console.log(`✓ removed ${rt.name} plugin`);
+        }
+        else {
+            console.error(`⚠ ${rt.name} plugin removal failed — run: ${cmd.join(' ')}`);
+        }
+    }
     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) {
+    for (const n of LEGACY_SKILLS) {
         if (!existsSync(join(skillsDir, n)))
             continue;
         rmSync(join(skillsDir, n), { recursive: true, force: true });
-        console.log(`✓ removed skill ${n}`);
+        console.log(`✓ removed legacy skill copy ${n}`);
     }
     if (existsSync(join(commandsDir, 'listen.md'))) {
         rmSync(join(commandsDir, 'listen.md'));
@@ -1679,6 +1688,20 @@ function uninstallCmd(args) {
                 console.log('✓ footer badge entry removed');
             }
         }
+        if (hasBoardLinkHook(settings)) {
+            const hooks = settings.hooks;
+            const ss = hooks.SessionStart
+                .map((m) => (Array.isArray(m?.hooks)
+                ? { ...m, hooks: m.hooks.filter((h) => !(typeof h?.command === 'string' && h.command.includes('vitrinka-board-link'))) }
+                : m))
+                .filter((m) => !Array.isArray(m?.hooks) || m.hooks.length > 0);
+            if (ss.length)
+                hooks.SessionStart = ss;
+            else
+                delete hooks.SessionStart;
+            changed = true;
+            console.log('✓ session-start hook entry removed');
+        }
         if (changed)
             writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     }
@@ -1686,6 +1709,15 @@ function uninstallCmd(args) {
         rmSync(wrapperP);
         console.log(`✓ removed ${wrapperP}`);
     }
+    const hookP = join(home, '.claude', 'hooks', 'vitrinka-board-link.sh');
+    if (existsSync(hookP)) {
+        rmSync(hookP);
+        console.log(`✓ removed ${hookP}`);
+    }
+    if (existsSync(desktopAppFlagPath())) {
+        rmSync(desktopAppFlagPath());
+        console.log(`✓ removed ${desktopAppFlagPath()}`);
+    }
     // MCP registration (both scopes — cheap, and remove is idempotent).
     if (claudeCliPresent()) {
         for (const scope of local ? ['project', 'user'] : ['user', 'project']) {
@@ -1708,7 +1740,7 @@ function uninstallCmd(args) {
 }
 // ---------- install-claude: Claude Code UI wiring ----------
 //
-// Wires the two Claude Code surfaces that link to boards (decisions:
+// Wires the three 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
@@ -1721,16 +1753,30 @@ function uninstallCmd(args) {
 //      "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
-// statusLine.command (recorded in the wrapper's VITRINKA_ORIG line) + drop the
-// footerLinksRegexes entry (documented in pkg/README.md).
+//   3. SessionStart hook — ~/.claude/hooks/vitrinka-board-link.sh prints the
+//      capture root's board URL into session context at start, so the footer
+//      badge is clickable from message one (the statusline URL isn't).
+// Idempotent, never an uninstall: re-runs detect the /boards/ footer pattern,
+// the wrapper registration, and the SessionStart entry and no-op. Removal =
+// delete the wrapper + hook + restore statusLine.command (recorded in the
+// wrapper's VITRINKA_ORIG line) + drop the footerLinksRegexes and SessionStart
+// entries (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}',
 };
+// Second badge on the same board URLs: a vitrinka:// deep link that opens the
+// Tauri desktop app (which registers ONLY the custom scheme — https stays in
+// the browser by design, see apps/desktop). Captures the path after the host
+// so `vitrinka://w/<ws>/boards/<slug>` lands on the same board in-app.
+export const BOARD_APP_FOOTER_LINK = {
+    type: 'regex',
+    pattern: 'https?:\\/\\/[^\\/\\s]+\\/(?<path>(?:w\\/[\\w.-]+\\/)?boards\\/[\\w.-]+)',
+    url: 'vitrinka://{path}',
+    label: '⧉ app',
+};
 // 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) {
@@ -1738,6 +1784,41 @@ export function hasBoardFooterLink(settings) {
     // 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/'));
 }
+// hasBoardAppFooterLink — the vitrinka:// deep-link badge already exists.
+export function hasBoardAppFooterLink(settings) {
+    const arr = settings.footerLinksRegexes;
+    return Array.isArray(arr) && arr.some((e) => typeof e?.url === 'string' && e.url.startsWith('vitrinka://'));
+}
+// ---------- desktop-app flag ----------
+// ONE canonical "is Vitrinka.app installed here" answer, so skills (and the
+// Claude wiring) never probe /Applications themselves: install-claude and
+// doctor refresh ~/.config/vitrinka/desktop-app to hold the app path, or
+// delete it when the app is gone. Skills just test the file.
+export function desktopAppFlagPath() {
+    return join(process.env.HOME || '', '.config', 'vitrinka', 'desktop-app');
+}
+// desktopAppPath — where Vitrinka.app actually is right now ('' when absent).
+export function desktopAppPath() {
+    for (const p of [join(process.env.HOME || '', 'Applications', 'Vitrinka.app'), '/Applications/Vitrinka.app']) {
+        if (existsSync(p))
+            return p;
+    }
+    return '';
+}
+// refreshDesktopAppFlag — sync the flag file to reality; returns the app path
+// ('' when absent). Called from install-claude and doctor.
+export function refreshDesktopAppFlag() {
+    const app = desktopAppPath();
+    const flag = desktopAppFlagPath();
+    if (app) {
+        mkdirSync(dirname(flag), { recursive: true });
+        writeFileSync(flag, app + '\n');
+    }
+    else if (existsSync(flag)) {
+        rmSync(flag);
+    }
+    return app;
+}
 // 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.
@@ -1803,6 +1884,41 @@ else
 fi
 `;
 }
+// SessionStart hook — the third Claude UI surface. Statusline URLs aren't
+// clickable in every terminal (and never OSC 8), so this puts the board URL
+// into the session context at start: the footer badge renders from message
+// one and Claude knows the live board without asking. Silent no-op when the
+// repo has no .screenshots/.vitrinka descriptor.
+export const BOARD_LINK_HOOK_CMD = '~/.claude/hooks/vitrinka-board-link.sh';
+export const BOARD_LINK_HOOK_SCRIPT = `#!/bin/bash
+# vitrinka-board-link — SessionStart hook, managed by \`vitrinka install-claude\`
+# (re-runs rewrite it). Emits the repo's live board URL into session context so
+# the clickable footer badge (footerLinksRegexes /boards/ entry) exists from
+# message one. Silent no-op without a .screenshots/.vitrinka descriptor.
+command -v jq >/dev/null 2>&1 || exit 0
+input=$(cat)
+dir=$(printf '%s' "$input" | jq -r '.cwd // ""')
+dir="\${dir:-$PWD}"
+root=$(git -C "$dir" rev-parse --show-toplevel 2>/dev/null)
+vjson=""
+for c in "$dir/.screenshots/.vitrinka" \${root:+"$root/.screenshots/.vitrinka"}; do
+  [ -f "$c" ] && { vjson=$c; break; }
+done
+[ -n "$vjson" ] || exit 0
+base=$(jq -r '.base // empty' "$vjson" 2>/dev/null)
+key=$(jq -r '.key // empty' "$vjson" 2>/dev/null)
+ws=$(jq -r '.workspace // empty' "$vjson" 2>/dev/null)
+[ -n "$base" ] && [ -n "$key" ] || exit 0
+[ -n "$ws" ] && base="$base/w/$ws"
+printf 'Live vitrinka board for this repo: %s/boards/%s\\n' "$base" "$key"
+`;
+// hasBoardLinkHook — a SessionStart entry running vitrinka-board-link already
+// exists; the marker that makes the settings edit idempotent.
+export function hasBoardLinkHook(settings) {
+    const arr = settings.hooks?.SessionStart;
+    return Array.isArray(arr) && arr.some((m) => Array.isArray(m?.hooks)
+        && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('vitrinka-board-link')));
+}
 // 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) {
@@ -1858,6 +1974,24 @@ export function installClaudeCmd(_args) {
         changed = true;
         console.log('✓ footer badge → footerLinksRegexes (clickable "🧷 board" whenever a board URL appears in conversation)');
     }
+    // 1b. App badge — only on machines with the desktop app: a second badge per
+    // board URL whose vitrinka:// deep link opens the same board in Vitrinka.app.
+    // The flag is refreshed here (see desktopAppPath); skills read the flag file,
+    // never probe /Applications themselves.
+    const appPath = refreshDesktopAppFlag();
+    if (appPath && !hasBoardAppFooterLink(settings)) {
+        settings.footerLinksRegexes = [...settings.footerLinksRegexes, BOARD_APP_FOOTER_LINK];
+        changed = true;
+        console.log(`✓ app badge → footerLinksRegexes ("⧉ app" opens boards in ${appPath})`);
+    }
+    else if (appPath) {
+        console.log('✓ app badge already configured (vitrinka:// footer entry)');
+    }
+    else if (hasBoardAppFooterLink(settings)) {
+        settings.footerLinksRegexes = settings.footerLinksRegexes.filter((e) => !(typeof e?.url === 'string' && e.url.startsWith('vitrinka://')));
+        changed = true;
+        console.log('✓ app badge removed (Vitrinka.app not installed on this machine)');
+    }
     // 2. Statusline wrapper.
     const wrapperPath = join(claudeDir, 'vitrinka-statusline.sh');
     const wrapperCmd = '~/.claude/vitrinka-statusline.sh';
@@ -1883,6 +2017,24 @@ export function installClaudeCmd(_args) {
         else
             console.log(`✓ statusline installed → ${wrapperPath} (minimal: dir │ branch │ 🧷 board │ model)`);
     }
+    // 3. SessionStart hook — board URL into context at session start, so the
+    // footer badge is clickable from message one.
+    const hooksDir = join(claudeDir, 'hooks');
+    const hookPath = join(hooksDir, 'vitrinka-board-link.sh');
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(hookPath, BOARD_LINK_HOOK_SCRIPT);
+    chmodSync(hookPath, 0o755);
+    if (hasBoardLinkHook(settings)) {
+        console.log(`✓ session-start hook refreshed (${hookPath})`);
+    }
+    else {
+        const hooks = (settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {});
+        const arr = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+        hooks.SessionStart = [...arr, { hooks: [{ type: 'command', command: BOARD_LINK_HOOK_CMD, timeout: 10 }] }];
+        settings.hooks = hooks;
+        changed = true;
+        console.log(`✓ session-start hook → ${hookPath} (board URL in context from message one)`);
+    }
     if (changed)
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
     // The wrapper reads Claude's stdin JSON with jq; without it the board segment
@@ -1919,7 +2071,16 @@ function openCmd(root, args) {
     if (args.print === true)
         return;
     const opener = process.platform === 'darwin' ? 'open' : 'xdg-open';
-    const r = spawnSync(opener, [url], { stdio: 'ignore' });
+    // Desktop app installed (the ~/.config/vitrinka/desktop-app flag) → open the
+    // board in Vitrinka.app via its vitrinka:// scheme instead of the browser.
+    // --browser forces the https URL.
+    let target = url;
+    if (args.browser !== true && process.platform === 'darwin' && existsSync(desktopAppFlagPath())) {
+        target = url.replace(/^https?:\/\/[^/]+\//, 'vitrinka://');
+        if (target === url)
+            target = 'vitrinka://'; // bare base URL — just focus the app
+    }
+    const r = spawnSync(opener, [target], { stdio: 'ignore' });
     if (r.error || r.status !== 0)
         console.error(`open: could not launch ${opener} — URL printed above`);
 }
@@ -1977,7 +2138,7 @@ export function cmpSemver(a, b) {
     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',
+const HINT_SKIP = new Set(['install', 'install-claude', 'update', 'uninstall',
     'doctor', 'help', 'completion', '__complete', 'ai']);
 function updateCheckPath() {
     return join(process.env.HOME || '', '.config', 'vitrinka', 'update-check');
@@ -2070,7 +2231,7 @@ function pkgVersion() {
 // 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) {
+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.
@@ -2124,11 +2285,13 @@ async function updateCmd(args) {
             }
         }
     }
-    // Refresh installed surfaces from the NEW code — skills always (an install
-    // implies them), Claude wiring only if the wrapper shows prior consent.
+    // Refresh installed surfaces from the NEW code — plugins where installed,
+    // 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');
+    for (const rt of pluginRuntimes()) {
+        if (rt.installed && !updatePluginIn(rt)) {
+            console.error(`⚠ update: ${rt.name} plugin refresh failed — re-run its plugin update manually`);
+        }
     }
     const wrapper = join(process.env.HOME || '', '.claude', 'vitrinka-statusline.sh');
     if (existsSync(wrapper)) {
@@ -2854,21 +3017,17 @@ export const COMMANDS = [
         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: 'update', summary: 'Update the CLI (git pull / npm -g), show what\'s new, refresh the installed skills + Claude wiring',
+        name: 'update', summary: 'Update the CLI (git pull / npm -g), show what\'s new, refresh the installed plugins + 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]',
+        name: 'open', summary: 'Open the capture root\'s live board — in Vitrinka.app when installed, else the browser (--qr renders a terminal QR for the iPad)',
+        usage: '[--root <dir>] [--qr] [--print] [--browser]',
         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' }],
+            { f: '--print', d: 'only print the URL' },
+            { f: '--browser', d: 'force the browser even when Vitrinka.app is installed' }],
         examples: ['vitrinka open', 'vitrinka open --qr'],
     },
     {
@@ -3741,8 +3900,6 @@ async function runSub(argv) {
         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')