@lovinka/vitrinka 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -3,6 +3,53 @@
 `vitrinka update` prints the sections newer than your previous version after
 updating — keep entries short and user-facing.
 
+## 1.10.0 — 2026-07-13
+
+### Added
+- `compose_board` question options accept `cardId` — the board draws a trace
+  wire from the option to the card it names, hovering glows it, and picking
+  flies the camera there. Pair it with the new `POST /artifact` params
+  (`section`, `device`, `anchor`/`side`): mockups land inside their take's
+  section frame, sized by device intent, and scale to fit their card
+  automatically (server-measured natural size).
+
+## 1.9.0 — 2026-07-12
+
+### Changed
+- MCP registration moved to the remote `/mcp` endpoint (streamable HTTP) —
+  no local stdio process per session; `vitrinka install`/`doctor --fix`
+  re-register automatically. The old stdio bin is deprecated.
+
+## 1.8.3 — 2026-07-11
+
+### Fixed
+- Interactive prompts (`install`'s operator question, any `promptLine`) strip
+  ANSI escape sequences and control characters — arrow-key edits no longer
+  persist raw `ESC[D`/`ESC[C` bytes into the operator name (which every fresh
+  browser adopted as its board identity). `vitrinka operator <name>` sanitizes
+  the same way, and the server now rejects control characters with 422.
+
+## 1.8.2 — 2026-07-11
+
+### Added
+- Desktop-app flag: `~/.config/vitrinka/desktop-app` is the one canonical
+  "is Vitrinka.app installed" answer (content = app path). Stamped by
+  `apps/desktop make install`, re-synced by `install-claude` and `doctor`.
+- `install-claude` adds a second **⧉ app** footer badge (only when the app is
+  installed) whose `vitrinka://` deep link opens the board in Vitrinka.app.
+- `vitrinka open` opens the board in Vitrinka.app when installed;
+  `--browser` forces the browser.
+
+## 1.8.1 — 2026-07-11
+
+### Added
+- `install-claude` now also wires a `SessionStart` hook
+  (`~/.claude/hooks/vitrinka-board-link.sh`) that puts the repo's live board
+  URL into session context at start — the clickable 🧷 footer badge exists
+  from message one instead of waiting for a board URL to be mentioned.
+  `vitrinka doctor` reports (and `--fix` repairs) the hook; `uninstall`
+  removes it.
+
 ## 1.8.0 — 2026-07-11
 
 ### Changed

package/README.md

@@ -60,11 +60,28 @@ to wire the **Claude Code UI** — re-runnable standalone as `vitrinka install-c
   `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/`.
+- **Session-start board link** — `~/.claude/hooks/vitrinka-board-link.sh`, a
+  `SessionStart` hook that prints the repo's live board URL into session
+  context at start, so the clickable footer badge exists from message one
+  (the statusline URL isn't clickable in every terminal). Silent no-op in
+  repos without a `.screenshots/.vitrinka` descriptor; needs `jq`.
+- **App badge** (only when Vitrinka.app is installed) — a second
+  `footerLinksRegexes` entry that renders **⧉ app** next to the board badge;
+  its `vitrinka://` deep link opens the same board in the desktop app
+  (which registers only the custom scheme — https stays in the browser).
+
+**Desktop-app flag** — `~/.config/vitrinka/desktop-app` is the ONE canonical
+"is Vitrinka.app installed here" answer (content = the app path). `apps/desktop`'s
+`make install` stamps it; `install-claude` and `doctor` re-sync it to reality
+(and add/remove the app badge accordingly). Skills and tools should test this
+flag file instead of probing `/Applications` themselves — `vitrinka open` uses
+it to open boards in the app (pass `--browser` to force the browser).
+
+All steps are idempotent — re-runs detect the wiring and no-op. To remove:
+delete `~/.claude/vitrinka-statusline.sh` and `~/.claude/hooks/vitrinka-board-link.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/` plus the `hooks.SessionStart` entry running `vitrinka-board-link`.
 
 For Claude Desktop or any other MCP client, add the equivalent entry by hand:
 

package/dist/bin-mcp.js

@@ -13,14 +13,18 @@ const sub = process.argv[2];
 if (sub === '--help' || sub === '-h') {
     process.stdout.write('vitrinka-mcp — Model Context Protocol server for vitrinka\n\n' +
         'USAGE\n' +
-        '  vitrinka-mcp            Start the MCP server over stdio (default).\n' +
+        '  vitrinka-mcp            Start the MCP server over stdio (DEPRECATED — see below).\n' +
         '  vitrinka-mcp work …     Run the unattended annotation worker (--repo <dir>).\n\n' +
         'ENV\n' +
         '  VITRINKA_BASE_URL  default https://vitrinka.lovinka.com\n' +
         '  VITRINKA_TOKEN     bearer token; falls back to ~/.config/vitrinka/token\n' +
         '                     (required only by mutating tools; reads work without it)\n\n' +
+        'DEPRECATED: the stdio server is replaced by the remote streamable-HTTP\n' +
+        'endpoint the Go server hosts at /mcp — same tools, zero local processes.\n\n' +
         'REGISTER (Claude Code, user scope)\n' +
-        '  claude mcp add --scope user vitrinka -- npx -y --package=@lovinka/vitrinka vitrinka-mcp\n');
+        '  claude mcp add --scope user --transport http vitrinka \\\n' +
+        '    https://vitrinka.lovinka.com/mcp \\\n' +
+        '    --header "Authorization: Bearer $(cat ~/.config/vitrinka/token)"\n');
     process.exit(0);
 }
 if (sub === 'work') {

package/dist/bin-mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin-mcp.js","sourceRoot":"","sources":["../src/bin-mcp.ts"],"names":[],"mappings":";AACA,gFAAgF;AAChF,8CAA8C;AAC9C,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,+EAA+E;AAC/E,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,8CAA8C;AAE9C,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE5B,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;IACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+DAA+D;QAC7D,SAAS;QACT,wEAAwE;QACxE,oFAAoF;QACpF,OAAO;QACP,6DAA6D;QAC7D,6EAA6E;QAC7E,mFAAmF;QACnF,sCAAsC;QACtC,6FAA6F,CAChG,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;IACnB,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;AAC5B,CAAC;KAAM,CAAC;IACN,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"bin-mcp.js","sourceRoot":"","sources":["../src/bin-mcp.ts"],"names":[],"mappings":";AACA,gFAAgF;AAChF,8CAA8C;AAC9C,EAAE;AACF,8EAA8E;AAC9E,2EAA2E;AAC3E,+EAA+E;AAC/E,EAAE;AACF,gFAAgF;AAChF,0EAA0E;AAC1E,8CAA8C;AAE9C,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAE5B,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;IACrC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,+DAA+D;QAC7D,SAAS;QACT,uFAAuF;QACvF,oFAAoF;QACpF,OAAO;QACP,6DAA6D;QAC7D,6EAA6E;QAC7E,mFAAmF;QACnF,0EAA0E;QAC1E,8EAA8E;QAC9E,sCAAsC;QACtC,8DAA8D;QAC9D,2CAA2C;QAC3C,wEAAwE,CAC3E,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,IAAI,GAAG,KAAK,MAAM,EAAE,CAAC;IACnB,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;AAC5B,CAAC;KAAM,CAAC;IACN,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;AAC3B,CAAC"}

package/dist/cli.js

@@ -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)'}`);
@@ -1262,9 +1264,13 @@ 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);
 }
@@ -1334,9 +1340,12 @@ 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;
 }
@@ -1345,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).
@@ -1366,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) {
@@ -1427,7 +1452,7 @@ 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: plugins, shim, PATH, completion (reversible, own dirs) ----
     for (const rt of runtimes) {
@@ -1457,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}`);
     }
@@ -1514,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) {
@@ -1661,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');
     }
@@ -1668,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']) {
@@ -1690,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
@@ -1703,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) {
@@ -1720,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.
@@ -1785,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) {
@@ -1840,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';
@@ -1865,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
@@ -1901,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`);
 }
@@ -2844,10 +3023,11 @@ export const COMMANDS = [
         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'],
     },
     {