@lovinka/vitrinka 1.17.0 → 1.18.0

package/dist/cli.js

@@ -20,6 +20,7 @@ import { createInterface } from 'node:readline';
 import { readToken, tokenSource, tokenPath, tokenHelp } from "./lib/token.js";
 import { operatorPath, readOperator, actorHeaderValue } from "./lib/operator.js";
 import { resolveBaseUrl } from "./lib/base-url.js";
+import { recordProject } from "./lib/registry.js";
 const CLI_PATH = fileURLToPath(import.meta.url);
 // Cap on the gzipped tarball push streams to the server. spawnSync kills tar (SIGTERM,
 // empty stderr) if its stdout exceeds this, so pushCmd surfaces the size in its error.
@@ -1425,14 +1426,6 @@ async function doctorCmd(args) {
         else
             console.log('✗ mcp        not registered — repair: vitrinka doctor --fix (or vitrinka install)');
     }
-    if (home && existsSync(join(home, '.claude', 'vitrinka-statusline.sh'))) {
-        if (fix)
-            installClaudeCmd(args);
-        else 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)
@@ -1645,8 +1638,16 @@ async function installCmd(args) {
     const mcpOk = haveClaude ? mcpRegistered() : false;
     const tokenSrc = tokenSource();
     const op = readOperator(true);
-    const wrapperP = join(home, '.claude', 'vitrinka-statusline.sh');
-    const uiOk = existsSync(wrapperP);
+    // Prior consent to the Claude UI wiring == the footer badge is already in
+    // settings (the retired statusline wrapper is no longer a signal).
+    const claudeSettingsP = join(home, '.claude', 'settings.json');
+    let uiOk = false;
+    if (existsSync(claudeSettingsP)) {
+        try {
+            uiOk = hasBoardFooterLink(JSON.parse(readFileSync(claudeSettingsP, 'utf8')));
+        }
+        catch { /* malformed settings.json — treat as not-wired; install-claude reports it */ }
+    }
     const row = (ok, label, detail) => {
         console.log(`  ${ok ? '✓' : '✗'} ${label.padEnd(11)}${detail}`);
     };
@@ -1661,7 +1662,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 + session hook wired' : 'not wired');
+    row(uiOk, 'claude ui', uiOk ? 'footer badge wired' : 'not wired');
     console.log('');
     // ---- silent steps: plugins, shim, PATH, completion (reversible, own dirs) ----
     for (const rt of runtimes) {
@@ -1744,13 +1745,16 @@ async function installCmd(args) {
         else
             console.error('⚠ no operator — board writes stay anonymous (set later: vitrinka operator <name>)');
     }
-    // 4. Claude Code UI wiring (edits ~/.claude/settings.json). Already-wired
-    // machines refresh silently (consent was given once); fresh ones are asked.
+    // 4. Claude Code UI wiring (edits ~/.claude/settings.json). The retired
+    // statusline extension is cleaned up on every run (silent when absent); the
+    // footer badge is (re-)wired — already-wired machines refresh silently
+    // (consent was given once), fresh ones are asked.
+    cleanupLegacyStatusline(home);
     if (args['no-claude'] === true) {
         console.log('claude ui: skipped (--no-claude)');
     }
     else if (uiOk || args.claude === true
-        || promptYesNo('Wire Claude Code UI (🧷 board statusline segment + clickable footer badge + session-start board link)? [Y/n] ')) {
+        || promptYesNo('Wire Claude Code UI (clickable 🧷 board footer badge)? [Y/n] ')) {
         installClaudeCmd(args);
     }
     else if (!process.stdin.isTTY) {
@@ -1760,9 +1764,6 @@ async function installCmd(args) {
         console.log('claude ui: skipped (re-run any time: vitrinka install-claude)');
     }
     // ---- environment checks (non-fatal) ----
-    if (spawnSync('jq', ['--version'], { stdio: 'ignore' }).error) {
-        console.error('⚠ jq missing (brew install jq) — the statusline 🧷 board segment won\'t render without it');
-    }
     if (spawnSync('cwebp', ['-version'], { stdio: 'ignore' }).error) {
         console.error('⚠ cwebp missing (brew install webp) — snap falls back to PNG');
     }
@@ -1798,6 +1799,66 @@ export function stripMarkerBlock(content, marker) {
 // 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'];
+// cleanupLegacyStatusline removes the retired Claude Code status-panel extension
+// (docs/specs/2026-07-20-menubar-tray-decisions.md #5): the
+// ~/.claude/vitrinka-statusline.sh wrapper — restoring the user's original
+// statusLine command recorded on its VITRINKA_ORIG line — and the
+// vitrinka-board-link SessionStart hook + its settings entry. The /boards/
+// footer badge is a separate surface and is NOT touched here. Silent when
+// nothing is there; prints one short notice when it removed something. Shared
+// by `install`/`update` (clean existing installs) and `uninstall`.
+export function cleanupLegacyStatusline(home) {
+    const wrapperP = join(home, '.claude', 'vitrinka-statusline.sh');
+    const hookP = join(home, '.claude', 'hooks', 'vitrinka-board-link.sh');
+    const settingsPath = join(home, '.claude', 'settings.json');
+    let removed = false;
+    if (existsSync(settingsPath)) {
+        let settings;
+        try {
+            settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+        }
+        catch (e) {
+            fail(`cleanup: ${settingsPath} is not valid JSON — nothing was changed there; fix it first (${e.message})`);
+        }
+        let changed = false;
+        const sl = settings.statusLine;
+        if (sl?.command && sl.command.replace(/^~(?=\/)/, home) === wrapperP) {
+            const orig = existsSync(wrapperP) ? wrapperOrigCommand(readFileSync(wrapperP, 'utf8')) : '';
+            if (orig)
+                settings.statusLine = { type: 'command', command: orig };
+            else
+                delete settings.statusLine;
+            changed = true;
+        }
+        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;
+        }
+        if (changed) {
+            writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+            removed = true;
+        }
+    }
+    if (existsSync(wrapperP)) {
+        rmSync(wrapperP);
+        removed = true;
+    }
+    if (existsSync(hookP)) {
+        rmSync(hookP);
+        removed = true;
+    }
+    if (removed)
+        console.log('✓ removed legacy statusline extension');
+}
 // 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/
@@ -1862,10 +1923,10 @@ function uninstallCmd(args) {
             console.log(`✓ removed ${marker} block from ${file}`);
         }
     }
-    // Claude UI wiring — restore statusLine from the wrapper's VITRINKA_ORIG,
-    // drop the /boards/ footer entry, delete the wrapper.
+    // Claude UI wiring — drop the /boards/ footer entry, then run the shared
+    // cleanup that removes the retired statusline wrapper + board-link hook and
+    // restores the user's original statusLine command.
     const settingsPath = join(home, '.claude', 'settings.json');
-    const wrapperP = join(home, '.claude', 'vitrinka-statusline.sh');
     if (existsSync(settingsPath)) {
         let settings;
         try {
@@ -1874,17 +1935,6 @@ function uninstallCmd(args) {
         catch (e) {
             fail(`uninstall: ${settingsPath} is not valid JSON — nothing was changed there; fix it first (${e.message})`);
         }
-        let changed = false;
-        const sl = settings.statusLine;
-        if (sl?.command && sl.command.replace(/^~(?=\/)/, home) === wrapperP) {
-            const orig = existsSync(wrapperP) ? wrapperOrigCommand(readFileSync(wrapperP, 'utf8')) : '';
-            if (orig)
-                settings.statusLine = { type: 'command', command: orig };
-            else
-                delete settings.statusLine;
-            changed = true;
-            console.log(`✓ statusline restored${orig ? ` → ${orig}` : ' (removed — none was configured before)'}`);
-        }
         const arr = settings.footerLinksRegexes;
         if (Array.isArray(arr)) {
             const kept = arr.filter((e) => !(typeof e?.pattern === 'string' && e.pattern.replaceAll('\\', '').includes('/boards/')));
@@ -1893,36 +1943,12 @@ function uninstallCmd(args) {
                     settings.footerLinksRegexes = kept;
                 else
                     delete settings.footerLinksRegexes;
-                changed = true;
+                writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
                 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');
-    }
-    if (existsSync(wrapperP)) {
-        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}`);
     }
+    cleanupLegacyStatusline(home);
     if (existsSync(desktopAppFlagPath())) {
         rmSync(desktopAppFlagPath());
         console.log(`✓ removed ${desktopAppFlagPath()}`);
@@ -1949,27 +1975,18 @@ function uninstallCmd(args) {
 }
 // ---------- install-claude: Claude Code UI wiring ----------
 //
-// Wires the three Claude Code surfaces that link to boards (decisions:
+// Wires the Claude Code footer badges 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-url>" plain-text
-//      segment when the session's capture root has a .screenshots/.vitrinka
-//      descriptor. Plain URL on purpose: Claude Code strips OSC 8 from statusline
-//      output in real terminals (anthropics/claude-code#21586, #26356 — closed
-//      "not planned"), but terminals like Warp/iTerm2/Ghostty cmd+click-linkify
-//      visible URLs on their own.
-//      With no original statusline, the wrapper renders a minimal line itself.
-//   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).
+//      conversation (works in every terminal).
+//   2. App badge — a second footer entry whose vitrinka:// deep link opens the
+//      same board in Vitrinka.app, added only where the desktop app is present.
+// The old statusline segment + SessionStart board-link hook were removed for
+// good (docs/specs/2026-07-20-menubar-tray-decisions.md #5): active-board
+// visibility now lives in the desktop app's menu bar tray. Idempotent, never an
+// uninstall: re-runs detect the /boards/ footer pattern and no-op. Removal = drop
+// the footerLinksRegexes entries (documented in pkg/README.md).
 export const BOARD_FOOTER_LINK = {
     type: 'regex',
     pattern: '(?<url>https?:\\/\\/\\S+\\/boards\\/(?<slug>[\\w.-]+))',
@@ -2028,108 +2045,15 @@ export function refreshDesktopAppFlag() {
     }
     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.
-// Board detection mirrors the CLI's capture-root contract: .screenshots/.vitrinka
-// with {base, key[, workspace]} → ${base}[/w/${workspace}]/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-URL segment when
-# the session's capture root has a .screenshots/.vitrinka descriptor. Plain URL,
-# not OSC 8 — Claude Code strips OSC 8 from statusline output; terminals
-# cmd+click-linkify visible URLs themselves.
-VITRINKA_ORIG='${quoted}'
-
-input=$(cat)
-
-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)
-  VWS=$(jq -r '.workspace // empty' "$VJSON" 2>/dev/null)
-  if [ -n "$VBASE" ] && [ -n "$VKEY" ]; then
-    [ -n "$VWS" ] && VBASE="$VBASE/w/$VWS"
-    BOARD=$(printf '\\033[35m🧷\\033[0m \\033[2m%s\\033[0m' "$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
-`;
-}
-// 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.
+// hasBoardLinkHook — a SessionStart entry running the retired vitrinka-board-link
+// hook still exists; used by cleanupLegacyStatusline to find and drop it.
 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.
+// wrapperOrigCommand — recover the original statusline command a legacy wrapper
+// file recorded, so cleanup can restore it when removing the retired extension.
 export function wrapperOrigCommand(content) {
     const line = content.split('\n').find((l) => l.startsWith("VITRINKA_ORIG='"));
     if (!line || !line.endsWith("'"))
@@ -2201,56 +2125,10 @@ export function installClaudeCmd(_args) {
         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';
-    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)`);
-    }
-    // 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)`);
-    }
+    // The retired statusline segment + board-link hook are cleaned up (not wired)
+    // by install/update/uninstall via cleanupLegacyStatusline; nothing to do here.
     if (changed)
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-    // The wrapper reads Claude's stdin JSON with jq; without it the board segment
-    // silently degrades to pass-through — surface that at install time.
-    if (spawnSync('jq', ['--version'], { stdio: 'ignore' }).error) {
-        console.error('⚠ jq not found — the statusline 🧷 board segment needs it (brew install jq); footer badge works regardless');
-    }
     console.log(`install-claude done — restart Claude Code sessions to pick up ${settingsPath}`);
 }
 // ---------- open: jump to the live board ----------
@@ -2293,6 +2171,43 @@ function openCmd(root, args) {
     if (r.error || r.status !== 0)
         console.error(`open: could not launch ${opener} — URL printed above`);
 }
+// ---------- edit: open a file/dir in the resident editor ----------
+// buildEditUrl — the vitrinka:// deep link the desktop app routes to its editor
+// page. PURE (unit-tested): the path is percent-encoded so spaces and unicode
+// survive the URL round-trip.
+export function buildEditUrl(absPath) {
+    return `vitrinka://edit?path=${encodeURIComponent(absPath)}`;
+}
+// editCmd — `vitrinka edit [path]`: focus the resident Vitrinka.app on a file or
+// project (instant-editor decision #4). Records the repo in the project registry
+// as a side effect (#6) so the app's project list stays current, then opens the
+// vitrinka://edit deep link. --print emits only the URL; when the app isn't
+// installed we print a one-line install hint plus the URL (nothing to launch).
+function editCmd(rest, args) {
+    const positional = rest.find((a) => !a.startsWith('--')) || '.';
+    const absPath = resolve(positional);
+    // Inside a git repo → record {project → main worktree top} so the desktop app
+    // discovers this checkout. Same project derivation as statusCmd; the stored
+    // path is the MAIN worktree top (the app enumerates worktrees itself).
+    const top = mainWorktreeTop(absPath);
+    if (top)
+        recordProject(sanitizeSeg(strArg(args.project) || basename(top), 64), top);
+    const url = buildEditUrl(absPath);
+    if (args.print === true) {
+        console.log(url);
+        return;
+    }
+    // Only the resident macOS app can handle vitrinka://edit. When it's absent,
+    // there's nothing to launch — surface the install hint alongside the URL.
+    if (process.platform !== 'darwin' || !existsSync(desktopAppFlagPath())) {
+        console.log(url);
+        console.error('edit: Vitrinka.app not installed — install it with: cd apps/desktop && make install');
+        return;
+    }
+    const r = spawnSync('open', [url], { stdio: 'ignore' });
+    if (r.error || r.status !== 0)
+        console.error(`edit: could not launch open — URL: ${url}`);
+}
 // ---------- status: the session dashboard ----------
 // statusCmd — one glance at this repo+branch's vitrinka world: the live board,
 // the open work queue (same scope derivation as `watch`), and who holds the
@@ -2300,8 +2215,11 @@ function openCmd(root, args) {
 async function statusCmd(root, args) {
     const base = resolveBaseUrl(strArg(args.base));
     const cwd = resolve('.');
-    const project = sanitizeSeg(strArg(args.project) || basename(mainWorktreeTop(cwd) || cwd), 64);
+    const top = mainWorktreeTop(cwd);
+    const project = sanitizeSeg(strArg(args.project) || basename(top || cwd), 64);
     const branch = sanitizeSeg(strArg(args.branch) || git(['branch', '--show-current'], cwd) || 'main', 100);
+    if (top)
+        recordProject(project, top); // feed the desktop app's project registry
     console.log(`vitrinka status — ${project}/${branch}`);
     const board = boardUrlOf(root);
     console.log(board ? `  board      ${board}` : '  board      none yet (publish one: vitrinka board-from-set)');
@@ -2583,17 +2501,27 @@ async function updateCmd(_args) {
         }
     }
     // Refresh installed surfaces from the NEW code — plugins where installed,
-    // Claude wiring only if the wrapper shows prior consent.
+    // Claude wiring only where the footer badge shows prior consent.
     const rerun = (sub) => spawnSync(process.execPath, [CLI_PATH, ...sub], { stdio: 'inherit' }).status === 0;
     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)) {
-        if (!rerun(['install-claude']))
-            console.error('⚠ update: Claude UI refresh failed — re-run: vitrinka install-claude');
+    // Remove the retired statusline extension from existing installs, then refresh
+    // the footer badge where it was already wired.
+    const home = process.env.HOME || '';
+    cleanupLegacyStatusline(home);
+    const settingsP = join(home, '.claude', 'settings.json');
+    let consented = false;
+    if (existsSync(settingsP)) {
+        try {
+            consented = hasBoardFooterLink(JSON.parse(readFileSync(settingsP, 'utf8')));
+        }
+        catch { /* malformed settings.json — treat as not-wired; install-claude reports it */ }
+    }
+    if (consented && !rerun(['install-claude'])) {
+        console.error('⚠ update: Claude UI refresh failed — re-run: vitrinka install-claude');
     }
     console.log('update done — try: vitrinka --help');
 }
@@ -3315,7 +3243,7 @@ export const COMMANDS = [
         examples: ['vitrinka uninstall', 'vitrinka uninstall --purge --yes'],
     },
     {
-        name: 'install-claude', summary: 'Wire the Claude Code UI: 🧷 board statusline segment + clickable footer badge',
+        name: 'install-claude', summary: 'Wire the Claude Code UI: clickable 🧷 board footer badge',
         usage: '', flags: [],
         examples: ['vitrinka install-claude'],
     },
@@ -3338,6 +3266,14 @@ export const COMMANDS = [
             { f: '--browser', d: 'force the browser even when Vitrinka.app is installed' }],
         examples: ['vitrinka open', 'vitrinka open --qr'],
     },
+    {
+        name: 'edit', summary: 'Open a file or project in the resident Vitrinka.app editor (records the repo for the app\'s project list)',
+        usage: '[<path>] [--print] [--project <p>]',
+        positional: '[<path>]',
+        flags: [{ f: '--print', d: 'only print the vitrinka://edit URL' },
+            { f: '--project', arg: '<p>', d: 'override the recorded project name' }],
+        examples: ['vitrinka edit', 'vitrinka edit src/cli.ts', 'vitrinka edit --print'],
+    },
     {
         name: 'status', summary: 'Session dashboard: live board, open work queue, and listener lease for this repo+branch',
         usage: '[--root <dir>] [--project <p>] [--branch <b>] [--base <url>]',
@@ -3947,6 +3883,11 @@ async function boardFromSetCmd(root, args, journey = false) {
         process.exit(2);
     }
     const cfg = loadVitrinkaCfg(root);
+    // The .vitrinka descriptor names the project — record its main worktree top so
+    // the desktop app can discover this checkout (instant-editor decision #6).
+    const projTop = mainWorktreeTop(dirname(root));
+    if (cfg.project && projTop)
+        recordProject(sanitizeSeg(cfg.project, 64), projTop);
     const slug = (strArg(args.slug) || cfg.key).toLowerCase();
     const title = strArg(args.btitle) || strArg(args.title) || '';
     const headers = { 'Content-Type': 'application/json' };
@@ -4096,7 +4037,9 @@ export function detectImportKind(explicit, file, content) {
         return 'openapi';
     return '';
 }
-// postImport sends a raw source to the board import endpoint and prints the card.
+// postImport sends a raw source to the board import endpoint and prints the
+// server's summary ({id, elemNo, title, counts…}) — or the full card JSON with
+// --verbose (mcp-token-economy #3: the geo boxes are noise by default).
 async function postImport(board, body, args) {
     const base = resolveBaseUrl(strArg(args.base));
     const headers = { 'Content-Type': 'application/json' };
@@ -4106,7 +4049,8 @@ async function postImport(board, body, args) {
     const actor = actorFor(args);
     if (actor)
         headers['X-Board-Actor'] = actor;
-    const res = await fetch(`${base}/api/v1/boards/${encodeURIComponent(board)}/import`, {
+    const verbose = args.verbose === true ? '?verbose=1' : '';
+    const res = await fetch(`${base}/api/v1/boards/${encodeURIComponent(board)}/import${verbose}`, {
         method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(120_000),
     });
     const text = await res.text();
@@ -4120,7 +4064,7 @@ async function importCmd(rest, args) {
     const file = rest.find((a) => !a.startsWith('--'));
     const board = strArg(args.board);
     if (!file || !board) {
-        console.error('usage: vitrinka import <file> --board <slug> [--kind auto|openapi|sqlddl|compose] [--title "…"]');
+        console.error('usage: vitrinka import <file> --board <slug> [--kind auto|openapi|sqlddl|compose] [--title "…"] [--verbose]');
         process.exit(2);
     }
     if (!existsSync(file)) {
@@ -4385,8 +4329,11 @@ async function watchCmd(args) {
     // Repo context for scope inference (main worktree basename = project; current
     // branch). '.' cwd is where the session runs (the app repo).
     const cwd = resolve('.');
-    const repoProject = basename(mainWorktreeTop(cwd) || cwd);
+    const repoTop = mainWorktreeTop(cwd);
+    const repoProject = basename(repoTop || cwd);
     const repoBranch = git(['branch', '--show-current'], cwd);
+    if (repoTop)
+        recordProject(sanitizeSeg(repoProject, 64), repoTop); // register the repo for the desktop app
     const scope = deriveWatchScope(args, { repoProject, repoBranch });
     const sq = scopeQuery(scope);
     const listUrl = () => {
@@ -4621,6 +4568,8 @@ async function runSub(argv) {
         versionCmd(false);
     else if (cmd === 'open')
         openCmd(root, args);
+    else if (cmd === 'edit')
+        editCmd(rest, args);
     else if (cmd === 'status')
         await statusCmd(root, args);
     else if (cmd === 'snap')