@lovinka/vitrinka 1.17.0 → 1.20.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// cli.ts — the unified vitrinka CLI. Maintains `.screenshots/manifest.json` + a self-contained,
+// cli.ts — the unified vitrinka CLI. Maintains `.vitrinka/screenshots/manifest.json` + a self-contained,
 // clickable `index.html` gallery, publishes sets to vitrinka (the internal artifacts app), and
 // one-shots capture (`snap`) + artifact scaffolding (`artifact-init`, `artifact-from-set`).
 //
@@ -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, openSync, readSync, closeSync, realpathSync, openAsBlob, lstatSync, constants as fsConstants, } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, renameSync, readdirSync, copyFileSync, mkdtempSync, chmodSync, appendFileSync, statSync, openSync, readSync, closeSync, realpathSync, openAsBlob, lstatSync, constants as fsConstants, } from 'node:fs';
 import { join, resolve, basename, dirname, extname, relative, sep, isAbsolute } from 'node:path';
 import { tmpdir, hostname } from 'node:os';
 import { spawnSync, spawn } from 'node:child_process';
@@ -20,6 +20,8 @@ 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, registeredPath } from "./lib/registry.js";
+import * as tui from "./lib/tui.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.
@@ -161,7 +163,7 @@ function saveManifest(root, m) {
 }
 function buildIndex(root) {
     const m = loadManifest(root);
-    const project = basename(dirname(root)) || 'project';
+    const project = basename(projectDirOf(root)) || 'project';
     const htmlPath = htmlPathOf(root);
     // A fresh/nonexistent root builds an empty gallery — mirror saveManifest's
     // dir creation instead of crashing with a raw ENOENT.
@@ -228,7 +230,7 @@ function appendShot(root, shot) {
     // v2: stamp the session's code identity (last append wins — the freshest
     // commit is the one the newest pixels came from).
     m.version = Math.max(m.version || 1, 2);
-    const projectDir = dirname(root);
+    const projectDir = projectDirOf(root);
     const commit = git(['rev-parse', '--short', 'HEAD'], projectDir);
     const branch = git(['branch', '--show-current'], projectDir);
     if (commit)
@@ -236,7 +238,7 @@ function appendShot(root, shot) {
     if (branch)
         m.branch = branch;
     saveManifest(root, m);
-    const project = basename(dirname(root)) || 'project';
+    const project = basename(projectDirOf(root)) || 'project';
     const htmlPath = htmlPathOf(root);
     writeFileSync(htmlPath, renderHtml(m.shots, project));
     return { count: m.shots.length, htmlPath };
@@ -512,6 +514,41 @@ export function mainWorktreeTop(cwd) {
         return dirname(common);
     return git(['rev-parse', '--show-toplevel'], cwd);
 }
+// ── .vitrinka/ home (decisions 2026-07-23) ────────────────────────────────
+// Everything vitrinka writes into a target project lives under ONE dir:
+//   .vitrinka/screenshots/   (was ./.screenshots)
+//   .vitrinka/artifacts/<slug>/ (was ./.artifacts/<slug>)
+//   .vitrinka/scratch/<topic>/  (sanctioned home for ad-hoc session output)
+// Legacy roots auto-migrate on first touch (rename + one notice); the home
+// gets a single `.vitrinka/` .gitignore line on top of the per-root
+// info/exclude self-ignore.
+const VITRINKA_HOME = '.vitrinka';
+function homeRoot(kind, cwd = process.cwd()) {
+    const home = resolve(cwd, VITRINKA_HOME);
+    const next = join(home, kind);
+    const legacy = kind === 'scratch' ? '' : resolve(cwd, kind === 'screenshots' ? '.screenshots' : '.artifacts');
+    if (legacy && existsSync(legacy) && !existsSync(next)) {
+        mkdirSync(home, { recursive: true });
+        renameSync(legacy, next);
+        console.error(`vitrinka: migrated ${relative(cwd, legacy)} → ${relative(cwd, next)}`);
+    }
+    if (existsSync(home))
+        ensureGitIgnored(cwd, `${VITRINKA_HOME}/`);
+    return next;
+}
+// The project dir for a root under the home (<p>/.vitrinka/screenshots) is
+// <p>, NOT the home dir — deriving the project name from dirname(root) would
+// call every project ".vitrinka". Legacy layouts keep their old parents.
+function projectDirOf(root) {
+    let d = dirname(root);
+    if (basename(d) === '.artifacts')
+        d = dirname(d); // legacy artifact container
+    if (['screenshots', 'artifacts', 'scratch'].includes(basename(d)) && basename(dirname(d)) === VITRINKA_HOME)
+        d = dirname(d);
+    if (basename(d) === VITRINKA_HOME)
+        d = dirname(d);
+    return d;
+}
 // originRepo normalizes the origin remote to a schemeless slug, e.g.
 // "github.com/LEFTEQ/fixit". "" outside a repo / without a remote.
 function originRepo(dir) {
@@ -679,6 +716,21 @@ export function buildProjectIndex(projectDir) {
 function indexCachePath(projectDir) {
     return join(git(['rev-parse', '--path-format=absolute', '--git-common-dir'], projectDir), 'vitrinka-index.cache');
 }
+// setupNudge — one dim stderr line when the repo isn't fully set up (setup-project
+// decision #6: registry entry AND index stamp both present = healthy): shown
+// exactly where the pain shows (edit/status), silent on healthy repos. The
+// registry check catches a best-effort recordProject that failed to write.
+// Callers gate on being inside a git repo.
+function setupNudge(projectDir, project, top) {
+    try {
+        if (registeredPath(project) !== top || !existsSync(indexCachePath(projectDir))) {
+            console.error(tui.pc.dim('hint: repo not set up for vitrinka — run: vitrinka setup-project'));
+        }
+    }
+    catch {
+        // best-effort — a nudge must never break the command that hosts it
+    }
+}
 /** pushProjectIndex builds + pushes the index unless nothing changed since
  *  the last successful push. Never throws and never exits — every caller is
  *  a touchpoint where index freshness must not fail the primary job.
@@ -748,7 +800,7 @@ export async function pushProjectIndex(projectDir, base, project, verify = false
 // failure (unlike the piggybacked pushes) so scripts can rely on it; verifies
 // the server actually holds the index rather than trusting the local stamp.
 async function indexCmd(root, args) {
-    const projectDir = dirname(root);
+    const projectDir = projectDirOf(root);
     const cfg = existsSync(vitrinkaCfgPath(root)) ? loadVitrinkaCfg(root) : null;
     const base = (strArg(args.base) || cfg?.base || process.env.VITRINKA_URL || 'https://vitrinka.in').replace(/\/+$/, '');
     const project = sanitizeSeg(strArg(args.project) || cfg?.project || basename(mainWorktreeTop(projectDir) || projectDir), 64);
@@ -823,7 +875,7 @@ function scanComponents(projectDir, srcDirs) {
     return [...seen.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 async function indexComponentsCmd(root, args) {
-    const projectDir = dirname(root);
+    const projectDir = projectDirOf(root);
     const library = strArg(args.library);
     if (!library)
         throw new Error('index-components: --library <kit> is required (one per UI library, e.g. "web" or "expo")');
@@ -847,6 +899,10 @@ async function indexComponentsCmd(root, args) {
         console.log(JSON.stringify({ project, library, components }, null, 2));
         return;
     }
+    await pushComponents(base, project, library, components);
+}
+// pushComponents — the PUT shared by index-components and setup-project.
+async function pushComponents(base, project, library, components) {
     const token = readToken();
     const headers = { 'Content-Type': 'application/json' };
     if (token)
@@ -860,6 +916,42 @@ async function indexComponentsCmd(root, args) {
         throw new Error(`index-components: push rejected (HTTP ${res.status}): ${(await res.text()).slice(0, 200)}`);
     console.log(`components ↑ ${project}/${library}: ${components.length} indexed`);
 }
+// detectComponentDirs — the setup-project heuristic: well-known component roots
+// (plus one level of apps/* and packages/* for monorepos) that actually contain
+// a meaningful number of exported components, best first. Deliberately cheap —
+// it reuses the index-components scanner and never walks the whole repo.
+export function detectComponentDirs(top) {
+    const roots = new Set(['src/components', 'components', 'src/ui', 'ui', 'lib/components']);
+    for (const container of ['apps', 'packages']) {
+        let entries;
+        try {
+            entries = readdirSync(join(top, container), { withFileTypes: true });
+        }
+        catch {
+            continue; // not a monorepo container — normal
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || e.name.startsWith('.'))
+                continue;
+            roots.add(`${container}/${e.name}/src/components`);
+            roots.add(`${container}/${e.name}/components`);
+        }
+    }
+    const out = [];
+    for (const dir of roots) {
+        if (!existsSync(join(top, dir)))
+            continue;
+        const count = scanComponents(top, [dir]).length;
+        if (count >= 3)
+            out.push({ dir, count }); // fewer reads as noise, not a library
+    }
+    return out.sort((a, b) => b.count - a.count).slice(0, 6);
+}
+// guessLibraryName — "apps/web/src/components" → "web"; flat repos → "web".
+export function guessLibraryName(dir) {
+    const m = dir.match(/^(?:apps|packages)\/([^/]+)\//);
+    return m ? m[1] : 'web';
+}
 function loadVitrinkaCfg(root) {
     const raw = readFileSync(vitrinkaCfgPath(root), 'utf8'); // caller checks existsSync
     try {
@@ -912,16 +1004,15 @@ async function remoteInitCmd(root, args) {
         console.log(`vitrinka set (existing) → ${shareUrl(cfg)}`);
         return cfg;
     }
-    const projectDir = dirname(root);
+    const projectDir = projectDirOf(root);
     const base = (args.base && args.base !== true ? String(args.base) : process.env.VITRINKA_URL || 'https://vitrinka.in').replace(/\/+$/, '');
     // Project identity comes from the MAIN worktree (a linked worktree's dir is
     // named after its branch — using it would fork each branch into its own
     // project; the branch already lives in cfg.branch).
     const gitTop = mainWorktreeTop(projectDir);
-    // Artifact roots live at <project>/.artifacts/<slug> — outside a git repo the project
-    // fallback must be the real project dir, not the '.artifacts' container itself.
-    const fallbackDir = basename(projectDir) === '.artifacts' ? dirname(projectDir) : projectDir;
-    const project = sanitizeSeg(args.project && args.project !== true ? String(args.project) : basename(gitTop || fallbackDir), 64);
+    // Outside a git repo the fallback is the real project dir — projectDirOf
+    // already stepped out of the .vitrinka/ home and legacy containers.
+    const project = sanitizeSeg(args.project && args.project !== true ? String(args.project) : basename(gitTop || projectDir), 64);
     const branch = (args.branch && args.branch !== true ? String(args.branch) : git(['branch', '--show-current'], projectDir)) || 'main';
     const d = new Date();
     const p2 = (n) => String(n).padStart(2, '0');
@@ -1016,7 +1107,7 @@ async function pushCmd(root, args) {
         process.exit(2);
     }
     const cfg = loadVitrinkaCfg(root);
-    const projectDir = dirname(root);
+    const projectDir = projectDirOf(root);
     // Control files are excluded here AND skipped server-side (belt and suspenders).
     // COPYFILE_DISABLE stops macOS bsdtar from emitting AppleDouble (._*) junk entries.
     const tar = spawnSync('tar', [
@@ -1323,6 +1414,85 @@ async function operatorCmd(rest, args) {
     }
 }
 // ---------- doctor: setup health check ----------
+// tidyCmd sweeps legacy vitrinka output and shot-shaped session litter into
+// the .vitrinka/ home. Report-first: prints the plan and exits unless --yes.
+// Conservative by design — only known patterns move by default (.screenshots/
+// + .artifacts/ legacy roots, .screenshots-<topic> session dirs, loose
+// shot-*.png); other loose root images and .aud_*/.audit_* text litter are
+// reported and move only under --all. Git-TRACKED paths never move.
+function tidyCmd(args) {
+    const cwd = process.cwd();
+    const top = git(['rev-parse', '--show-toplevel'], cwd) || cwd;
+    const all = args.all === true;
+    const tracked = new Set((git(['ls-files'], top) || '').split('\n').filter(Boolean));
+    const trackedUnder = (rel) => {
+        if (tracked.has(rel))
+            return true;
+        const prefix = rel + '/';
+        for (const t of tracked)
+            if (t.startsWith(prefix))
+                return true;
+        return false;
+    };
+    const moves = [];
+    const skipped = [];
+    const plan = (from, to) => {
+        if (trackedUnder(from)) {
+            skipped.push(`${from}  (git-tracked — not touching)`);
+            return;
+        }
+        if (existsSync(join(top, to))) {
+            skipped.push(`${from}  (target ${to} already exists)`);
+            return;
+        }
+        moves.push({ from, to });
+    };
+    if (existsSync(join(top, '.screenshots')))
+        plan('.screenshots', `${VITRINKA_HOME}/screenshots`);
+    if (existsSync(join(top, '.artifacts')))
+        plan('.artifacts', `${VITRINKA_HOME}/artifacts`);
+    for (const e of readdirSync(top, { withFileTypes: true })) {
+        if (e.name === VITRINKA_HOME || e.name === '.git')
+            continue;
+        if (e.isDirectory()) {
+            const m = e.name.match(/^\.screenshots[-_](.+)$/);
+            if (m)
+                plan(e.name, `${VITRINKA_HOME}/scratch/${m[1]}`);
+        }
+        else if (e.isFile()) {
+            if (trackedUnder(e.name))
+                continue; // committed files are repo content, not litter
+            const isShot = /^shot-.*\.(png|jpe?g|webp)$/i.test(e.name);
+            const isLooseImage = /\.(png|jpe?g|webp)$/i.test(e.name);
+            const isAudit = /^\.aud(it)?_/.test(e.name);
+            if (isShot || (all && (isLooseImage || isAudit)))
+                plan(e.name, `${VITRINKA_HOME}/scratch/loose/${e.name}`);
+            else if (isLooseImage || isAudit)
+                skipped.push(`${e.name}  (loose litter — rerun with --all to move)`);
+        }
+    }
+    if (!moves.length && !skipped.length) {
+        console.log('tidy: nothing to do — repo root is clean');
+        return;
+    }
+    for (const mv of moves)
+        console.log(`  ${mv.from}  →  ${mv.to}`);
+    for (const s of skipped)
+        console.log(`  skip ${s}`);
+    if (!moves.length)
+        return;
+    if (args.yes !== true) {
+        console.log(`\ntidy: ${moves.length} move(s) planned — rerun with --yes to apply`);
+        return;
+    }
+    for (const mv of moves) {
+        const dest = join(top, mv.to);
+        mkdirSync(dirname(dest), { recursive: true });
+        renameSync(join(top, mv.from), dest);
+    }
+    ensureGitIgnored(top, `${VITRINKA_HOME}/`);
+    console.log(`tidy: moved ${moves.length} item(s) into ${VITRINKA_HOME}/`);
+}
 // doctorCmd checks this machine's vitrinka setup: server reachable, write
 // token present AND accepted by the server, operator persona set. The token
 // probe is `PUT /api/v1/operator` with an empty JSON body — auth runs before
@@ -1425,14 +1595,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)
@@ -1633,6 +1795,9 @@ async function installCmd(args) {
     if (!home)
         fail('install: $HOME is not set');
     const local = args.local === true;
+    // --yes (setup-project's inline delegate, or direct use): behave exactly like a
+    // non-TTY run — skip every prompt, config-touchers print their manual command.
+    const noPrompt = args.yes === true || !process.stdin.isTTY;
     const base = resolveBaseUrl(strArg(args.base));
     const mcpScope = local ? 'project' : 'user';
     // ---- probe (before touching anything) ----
@@ -1645,8 +1810,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 +1834,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) {
@@ -1700,7 +1873,7 @@ async function installCmd(args) {
     else if (!mcpOk) {
         if (args['no-mcp'] === true)
             console.log('mcp: skipped (--no-mcp)');
-        else if (args.mcp === true || promptYesNo(`Register the vitrinka MCP for Claude Code (scope ${mcpScope})? [Y/n] `)) {
+        else if (args.mcp === true || (!noPrompt && promptYesNo(`Register the vitrinka MCP for Claude Code (scope ${mcpScope})? [Y/n] `))) {
             if (registerMcp(mcpScope))
                 console.log(`✓ mcp registered (--scope ${mcpScope})`);
             else
@@ -1712,7 +1885,7 @@ async function installCmd(args) {
     }
     // 2. Write token (reads work without one; pushes/board writes 401).
     if (tokenSrc === 'missing') {
-        if (process.stdin.isTTY) {
+        if (!noPrompt) {
             console.log('No write token yet — reads work without one, writes 401. It is the');
             console.log('server\'s VITRINKA_TOKEN (one shared secret — copy it from a configured');
             console.log('machine or the server admin; details: vitrinka doctor).');
@@ -1738,31 +1911,31 @@ async function installCmd(args) {
         await operatorCmd(['operator', opArg], args);
     }
     else if (!op) {
-        const name = promptLine('Operator name — how should vitrinka credit you on boards? (Enter to skip): ');
+        const name = noPrompt ? '' : promptLine('Operator name — how should vitrinka credit you on boards? (Enter to skip): ');
         if (name)
             await operatorCmd(['operator', name], args);
         else
             console.error('⚠ no operator — board writes stay anonymous (set later: vitrinka operator <name>)');
     }
-    // 4. Claude Code UI wiring (edits ~/.claude/settings.json). Already-wired
-    // machines refresh silently (consent was given once); fresh ones are asked.
+    // 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] ')) {
+        || (!noPrompt && promptYesNo('Wire Claude Code UI (clickable 🧷 board footer badge)? [Y/n] '))) {
         installClaudeCmd(args);
     }
-    else if (!process.stdin.isTTY) {
+    else if (noPrompt) {
         console.log('claude ui: skipped (non-interactive — run `vitrinka install-claude`, or pass --claude)');
     }
     else {
         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 +1971,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 +2095,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 +2107,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 +2115,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 +2147,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 +2217,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 +2297,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 +2343,229 @@ 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) {
+        const project = sanitizeSeg(strArg(args.project) || basename(top), 64);
+        recordProject(project, top);
+        setupNudge(absPath, project, 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}`);
+}
+// ---------- setup-project: the repo onboarding wizard ----------
+//
+// One front door for everything a REPO needs before the editor and the board
+// @ autocomplete work (docs/specs/2026-07-23-setup-project-decisions.md):
+// register the repo in the desktop app's project registry, push the file/route
+// index, offer the component index, check the desktop app, and optionally
+// create a hello board. Status-first like install: re-runs refresh the cheap
+// idempotent bits and only prompt for genuinely missing config; --yes and
+// non-TTY runs take every default.
+async function setupProjectCmd(args) {
+    const auto = args.yes === true || !tui.interactive();
+    const base = resolveBaseUrl(strArg(args.base));
+    const cwd = resolve('.');
+    const top = mainWorktreeTop(cwd);
+    if (!top)
+        fail('setup-project: not inside a git repository — run it from the repo you want to onboard');
+    tui.intro(`vitrinka setup-project — ${base}`);
+    // ---- machine gate: offer install inline instead of a dead end (decision #5) ----
+    const missing = [];
+    if (tokenSource() === 'missing')
+        missing.push('token');
+    for (const rt of pluginRuntimes())
+        if (rt.present && !rt.installed)
+            missing.push(`plugin·${rt.name}`);
+    if (claudeCliPresent() && !mcpRegistered())
+        missing.push('mcp');
+    if (missing.length) {
+        tui.note(`missing: ${missing.join(', ')}`, 'machine not fully onboarded');
+        if (await tui.confirm('Run the machine install now?', true, auto))
+            await installCmd(args);
+        else
+            tui.step('skipped — run it later: vitrinka install');
+    }
+    // ---- project identity + registry (the name is asked only while THIS repo is
+    // unregistered — an entry for the same name but another path is a basename
+    // collision with a different checkout, so the prompt is the escape hatch,
+    // never a silent overwrite of the other project's mapping) ----
+    const defaultName = sanitizeSeg(strArg(args.project) || basename(top), 64);
+    let project = defaultName;
+    if (registeredPath(defaultName) !== top) {
+        project = sanitizeSeg(await tui.text('Project name (how boards + indexes file this repo)', defaultName, auto), 64) || defaultName;
+    }
+    recordProject(project, top);
+    tui.step(`registry ✓ ${project} → ${top}`);
+    // ---- file/route index — verify=true so a wiped server row re-pushes even on
+    // a local stamp hit (pushProjectIndex prints its own ↑ line on a real push) ----
+    const sp = tui.spinner();
+    sp.start('pushing the file/route index…');
+    const idxOk = await pushProjectIndex(cwd, base, project, true);
+    sp.stop(idxOk ? 'index ✓ (@ autocomplete + editor file map)' : 'index ✗ — server unreachable? retry: vitrinka index');
+    // ---- component index (decision #3: auto-detect, offer, never mandatory) ----
+    await setupComponentsStep(base, project, top, auto);
+    // ---- desktop app ----
+    const appPath = refreshDesktopAppFlag();
+    if (appPath)
+        tui.step(`app ✓ ${appPath}`);
+    else if (process.platform === 'darwin') {
+        tui.step('app ✗ Vitrinka.app not installed — editor links open in the browser (from the vitrinka repo: cd apps/desktop && make install)');
+    }
+    // ---- hello board (decision #3: a closing "want to try it?" — offered only
+    // while the project has no board at all; default no, so --yes never spams) ----
+    await setupBoardStep(base, project, args, auto);
+    // The index is the core deliverable (editor file map + @ autocomplete) — a
+    // failed push means the repo is NOT ready, and scripts must see a non-zero exit.
+    if (!idxOk) {
+        tui.outro('repo NOT ready — the index push failed (see above); retry once the server is reachable: vitrinka setup-project');
+        process.exit(1);
+    }
+    tui.outro('repo ready — open the editor: vitrinka edit .   dashboard: vitrinka status');
+}
+// setupComponentsStep — the component-index leg of setup-project. Skips loudly
+// but harmlessly whenever the server or the scan has nothing to offer.
+async function setupComponentsStep(base, project, top, auto) {
+    try {
+        // Unauthenticated compact read — already indexed means a ✓ row, no prompt.
+        const res = await fetch(`${base}/api/v1/projects/${encodeURIComponent(project)}/components`, { signal: AbortSignal.timeout(15_000) });
+        if (res.ok) {
+            const d = await res.json();
+            const comps = Array.isArray(d.components) ? d.components : [];
+            if (comps.length) {
+                const libs = [...new Set(comps.map((c) => c.library).filter(Boolean))];
+                tui.step(`components ✓ ${comps.length} indexed (${libs.join(', ')})`);
+                return;
+            }
+        }
+    }
+    catch (e) {
+        tui.step(`components ? server unreachable (${e instanceof Error ? e.message : e}) — index later: vitrinka index-components`);
+        return;
+    }
+    const cands = detectComponentDirs(top);
+    if (!cands.length) {
+        tui.step('components — no component dirs detected; index later: vitrinka index-components --library <kit> --src <dirs>');
+        return;
+    }
+    const dir = await tui.select('Component library to index (powers @ component autocomplete on boards)', [
+        ...cands.map((c) => ({ value: c.dir, label: c.dir, hint: `${c.count} exported components` })),
+        { value: '', label: 'skip', hint: 'index later: vitrinka index-components' },
+    ], auto);
+    if (!dir)
+        return;
+    const library = sanitizeSeg(await tui.text('Library name (one per UI kit, e.g. "web" or "expo")', guessLibraryName(dir), auto), 32) || 'web';
+    try {
+        await pushComponents(base, project, library, scanComponents(top, [dir]));
+    }
+    catch (e) {
+        tui.step(`components ✗ ${e.message}`);
+    }
+}
+// helloBoardSlug — the hello board's slug, kept within the server's 64-char
+// boardSlugRe even for a maximal 64-char project name (57 + "-hello" = 63);
+// the truncation never leaves a dangling separator before the suffix.
+export function helloBoardSlug(project) {
+    return `${project.slice(0, 57).replace(/[-.]+$/, '') || 'x'}-hello`;
+}
+// setupBoardStep — the closing hello-board offer. Every failure path is a quiet
+// row, never an exit: the board is a nicety on top of an already-onboarded repo.
+async function setupBoardStep(base, project, args, auto) {
+    let boards;
+    try {
+        const res = await fetch(`${base}/api/v1/boards`, { signal: AbortSignal.timeout(15_000) });
+        if (!res.ok)
+            return; // older server — the offer is a nicety, not a step
+        boards = (await res.json()).boards || [];
+    }
+    catch {
+        return; // unreachable — the index step already surfaced that loudly
+    }
+    const mine = boards.filter((b) => b.project === project);
+    if (mine.length) {
+        tui.step(`boards ✓ ${mine.length} (latest: ${mine[0].url || mine[0].slug})`);
+        return;
+    }
+    if (!await tui.confirm('Create a hello board to try the round-trip (annotate → work queue)?', false, auto))
+        return;
+    const slug = helloBoardSlug(project);
+    const headers = { 'Content-Type': 'application/json' };
+    const token = readToken();
+    if (token)
+        headers.Authorization = `Bearer ${token}`;
+    const actor = actorFor(args);
+    if (actor)
+        headers['X-Board-Actor'] = actor;
+    try {
+        const res = await fetch(`${base}/api/v1/boards`, {
+            method: 'POST', headers,
+            body: JSON.stringify({ slug, title: `${project} — hello`, project, subgroup: 'testing' }),
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (res.ok) {
+            const url = String((await res.json()).url || `${base}/boards/${slug}`);
+            tui.step(`board ✓ ${url}`);
+            if (process.platform === 'darwin' && tui.interactive())
+                spawnSync('open', [url], { stdio: 'ignore' });
+        }
+        else if (res.status === 409) {
+            // 409 = the slug exists. Re-list and reuse it when it's OURS (a race or a
+            // half-finished earlier run); a different project's board is a genuine
+            // collision — never silently adopt it.
+            let ours;
+            try {
+                const list = await fetch(`${base}/api/v1/boards`, { signal: AbortSignal.timeout(15_000) });
+                if (list.ok) {
+                    ours = ((await list.json()).boards || [])
+                        .find((b) => b.slug === slug && b.project === project);
+                }
+            }
+            catch {
+                // unreachable mid-step — fall through to the collision line
+            }
+            if (ours)
+                tui.step(`board ✓ ${ours.url || slug} (reused)`);
+            else
+                tui.step(`board — slug ${slug} already exists (another project's?) — create one later: /vitrinka:board`);
+        }
+        else {
+            tui.step(`board ✗ create failed (HTTP ${res.status}): ${(await res.text()).slice(0, 200)}`);
+        }
+    }
+    catch (e) {
+        tui.step(`board ✗ ${e.message}`);
+    }
+}
 // ---------- 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 +2573,13 @@ 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
+        setupNudge(cwd, project, top);
+    }
     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 +2861,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');
 }
@@ -2754,8 +3042,8 @@ async function snapCmd(surface, args, rawArgv = []) {
         console.error(`snap: surface must be ios|android|macos|web, got ${JSON.stringify(surface)}`);
         process.exit(2);
     }
-    const root = resolve(strArg(args.root) || '.screenshots');
-    const projectDir = dirname(root);
+    const root = strArg(args.root) ? resolve(strArg(args.root)) : homeRoot('screenshots');
+    const projectDir = projectDirOf(root);
     const route = strArg(args.route);
     const note = strArg(args.note);
     if (!route) {
@@ -3073,6 +3361,7 @@ function scaffoldHead(title) {
     "react-dom/client": "/vendor/react-dom-client.mjs",
     "htm": "/vendor/htm.mjs",
     "kit-1": "/vendor/kit-1.mjs",
+    "kit-2": "/vendor/kit-2.mjs",
     "zipstore-1": "/vendor/zipstore-1.mjs"
 } }
 </script>
@@ -3080,7 +3369,26 @@ function scaffoldHead(title) {
        "@xyflow/react": "/vendor/xyflow-react.mjs"
      and add to <head>:
        <link rel="stylesheet" href="/vendor/xyflow-react.css">
+     shadcn ui components resolve via the map above: import { Button, Card, Tabs, … } from "kit-2"
+     More built-ins (relative-import bundles — no map entry needed;
+     GET /api/v1/runtime lists what the server has):
+       recharts:  import { LineChart, Line, XAxis, … } from "/vendor/recharts.mjs"
+       tables:    import { useReactTable, … } from "/vendor/tanstack-table.mjs"
+       motion:    import { motion, AnimatePresence } from "/vendor/motion.mjs"
+       highlight: import hljs from "/vendor/hljs.mjs"   + <link rel="stylesheet" href="/vendor/hljs.css">
+       math:      import katex from "/vendor/katex.mjs" + <link rel="stylesheet" href="/vendor/katex.css">
+       api ref:   import { ApiRefBody, parseSpec } from "/vendor/apiref-1.mjs"
 -->
+<link rel="modulepreload" href="/vendor/react.mjs">
+<link rel="modulepreload" href="/vendor/scheduler.mjs">
+<link rel="modulepreload" href="/vendor/react-dom.mjs">
+<link rel="modulepreload" href="/vendor/react-dom-client.mjs">
+<link rel="modulepreload" href="/vendor/htm.mjs">
+<link rel="modulepreload" href="/vendor/kit-1.mjs">
+<link rel="modulepreload" href="/vendor/zipstore-1.mjs">
+<!-- importing shelf libs (kit-2, recharts, …)? add a matching modulepreload —
+     it flattens the import waterfall into one parallel fetch round. Only
+     preload what the App actually imports; the scaffold body uses kit-1. -->
 <script src="/vendor/tailwind.js"></script>
 </head>
 <body class="bg-[#f6f2ee] text-[#101113] antialiased">
@@ -3162,7 +3470,7 @@ async function artifactInitCmd(args) {
     assertValidKey(slug, 'artifact-init'); // the slug becomes the set key — fail before any writes
     const kind = strArg(args.kind) || 'report';
     const title = strArg(args.title) || slug;
-    const dir = resolve('.artifacts', slug);
+    const dir = join(homeRoot('artifacts'), slug);
     const indexPath = join(dir, 'index.html');
     if (existsSync(indexPath)) {
         console.error(`artifact-init: ${indexPath} already exists — edit it in place (or remove the dir to re-scaffold)`);
@@ -3170,7 +3478,7 @@ async function artifactInitCmd(args) {
     }
     mkdirSync(dir, { recursive: true });
     writeFileSync(indexPath, blankScaffold(title, existsSync(join(dir, 'data.json'))));
-    ensureGitIgnored(process.cwd(), '.artifacts/');
+    ensureGitIgnored(process.cwd(), `${VITRINKA_HOME}/`);
     await remoteInitCmd(dir, { ...args, key: slug, kind });
     console.log(`scaffolded ${indexPath}`);
     console.log(`author the App, then: node ${CLI_PATH} push --root ${dir} --title "<Human title>"`);
@@ -3183,8 +3491,8 @@ async function artifactFromSetCmd(args) {
     }
     const slug = sanitizeSeg(slugRaw, 64);
     assertValidKey(slug, 'artifact-from-set'); // the slug becomes the set key — fail before any writes
-    const from = resolve(strArg(args.from) || '.screenshots');
-    const dir = resolve('.artifacts', slug);
+    const from = strArg(args.from) ? resolve(strArg(args.from)) : homeRoot('screenshots');
+    const dir = join(homeRoot('artifacts'), slug);
     const indexPath = join(dir, 'index.html');
     if (existsSync(indexPath)) {
         console.error(`artifact-from-set: ${indexPath} already exists — edit it in place (or remove the dir to re-scaffold)`);
@@ -3200,7 +3508,7 @@ async function artifactFromSetCmd(args) {
     const fromManifest = loadManifest(from);
     const title = strArg(args.title) || (fromManifest.journey && fromManifest.journey.title) || slug;
     writeFileSync(indexPath, composedScaffold(title, `${slug}.zip`));
-    ensureGitIgnored(process.cwd(), '.artifacts/');
+    ensureGitIgnored(process.cwd(), `${VITRINKA_HOME}/`);
     await remoteInitCmd(dir, { ...args, key: slug, kind: strArg(args.kind) || 'report' });
     // Record the source screenshot set (project/branchSlug/key) so push sends ?source= and
     // vitrinka can cross-link set ↔ artifact both ways.
@@ -3222,7 +3530,7 @@ async function artifactFromSetCmd(args) {
     console.log(`scaffolded ${indexPath} (${res.count} shots embedded${source ? `, source ${source}` : ''})`);
     console.log(`write the narrative sections, then \`push\`: node ${CLI_PATH} push --root ${dir} --title "<Human title>"`);
 }
-const ROOT_FLAG = { f: '--root', arg: '<dir>', d: 'capture root (default .screenshots)' };
+const ROOT_FLAG = { f: '--root', arg: '<dir>', d: 'capture root (default .vitrinka/screenshots)' };
 const BASE_FLAG = { f: '--base', arg: '<url>', d: 'vitrinka base URL (default $VITRINKA_URL or the mesh host)' };
 const CTX_FLAGS = [
     { f: '--label', arg: '<STAGE>', d: 'journey stage label' },
@@ -3242,17 +3550,17 @@ export const COMMANDS = [
         flags: [ROOT_FLAG, { f: '--file', arg: '<rel>', d: 'screenshot path relative to root (required)' },
             { f: '--surface', arg: '<ios|android|web|macos>', d: 'platform (default other)' },
             { f: '--route', arg: '<r>', d: 'app route' }, { f: '--note', arg: '<n>', d: 'caption' }, ...CTX_FLAGS],
-        examples: ['vitrinka add --root .screenshots --file 2026-07-06/01-web-home.png --surface web --route /home --note "landing"'],
+        examples: ['vitrinka add --root .vitrinka/screenshots --file 2026-07-06/01-web-home.png --surface web --route /home --note "landing"'],
     },
     { name: 'build', summary: 'Rebuild index.html from the manifest', usage: '--root <dir>', flags: [ROOT_FLAG],
-        examples: ['vitrinka build --root .screenshots'] },
+        examples: ['vitrinka build --root .vitrinka/screenshots'] },
     {
         name: 'meta', summary: 'Set the journey header (kicker/title/accent/intro/chips)',
         usage: '--root <dir> [--kicker <k>] [--title <t>] [--accent <substr>] [--intro <p>] [--chip "K=V" ...]',
         flags: [ROOT_FLAG, { f: '--kicker', arg: '<k>', d: 'eyebrow kicker' }, { f: '--title', arg: '<t>', d: 'display title' },
             { f: '--accent', arg: '<substr>', d: 'substring of the title to accent' }, { f: '--intro', arg: '<p>', d: 'intro paragraph' },
             { f: '--chip', arg: '"K=V"', d: 'meta chip (repeatable)' }],
-        examples: ['vitrinka meta --root .screenshots --kicker "FLOW" --title "Payout flow" --accent "Payout"'],
+        examples: ['vitrinka meta --root .vitrinka/screenshots --kicker "FLOW" --title "Payout flow" --accent "Payout"'],
     },
     {
         name: 'remote-init', summary: 'Create a .vitrinka set config for publishing',
@@ -3261,7 +3569,7 @@ export const COMMANDS = [
             { f: '--branch', arg: '<b>', d: 'branch (default: current)' }, { f: '--kind', arg: '<k>', d: 'set kind (default screenshots)' },
             { f: '--key', arg: '<k>', d: 'set key (default: timestamped)' }, { f: '--issue', arg: '<ref>', d: 'linked issue ref' }],
         dynamic: 'projects',
-        examples: ['vitrinka remote-init --root .screenshots --project fixit --branch main'],
+        examples: ['vitrinka remote-init --root .vitrinka/screenshots --project fixit --branch main'],
     },
     {
         name: 'push', summary: 'Publish the set to vitrinka (tar+PUT), refresh the index',
@@ -3269,7 +3577,7 @@ export const COMMANDS = [
         flags: [ROOT_FLAG, { f: '--title', arg: '<t>', d: 'human title (re-sent every push)' },
             { f: '--name', arg: '<slug>', d: 'name the set after publish (sticky)' },
             { f: '--source', arg: '<ref>', d: 'cross-link source set project/branchSlug/key' }],
-        examples: ['vitrinka push --root .screenshots --title "Payout flow"'],
+        examples: ['vitrinka push --root .vitrinka/screenshots --title "Payout flow"'],
     },
     {
         name: 'name', summary: "Set or clear a set's custom URL name",
@@ -3294,6 +3602,13 @@ export const COMMANDS = [
         flags: [{ f: '--fix', d: 'repair everything repairable: refresh skills, rewrite the shim, re-register the MCP, refresh the Claude UI wiring' }, BASE_FLAG],
         examples: ['vitrinka doctor', 'vitrinka doctor --fix'],
     },
+    {
+        name: 'tidy', summary: 'Sweep legacy roots + shot-shaped litter into .vitrinka/ (report-first)',
+        usage: '[--yes] [--all]',
+        flags: [{ f: '--yes', d: 'apply the planned moves (default: report only)' },
+            { f: '--all', d: 'also move loose root images and .aud_*/.audit_* text litter (default: report them)' }],
+        examples: ['vitrinka tidy', 'vitrinka tidy --yes', 'vitrinka tidy --yes --all'],
+    },
     {
         name: 'install', summary: 'Onboard this machine: status table, then skills + shim + completion + MCP + token + operator + Claude UI',
         usage: '[--local] [--operator <name>] [--mcp|--no-mcp] [--claude|--no-claude] [--no-completion]',
@@ -3303,9 +3618,19 @@ export const COMMANDS = [
             { f: '--no-mcp', d: 'skip the MCP registration' },
             { f: '--claude', d: 'wire the Claude Code UI without asking' },
             { f: '--no-claude', d: 'skip the Claude Code UI wiring' },
-            { f: '--no-completion', d: 'skip appending the shell-completion line' }],
+            { f: '--no-completion', d: 'skip appending the shell-completion line' },
+            { f: '--yes', d: 'non-interactive: skip every prompt (config-touchers print their manual command)' }],
         examples: ['vitrinka install', 'vitrinka install --local', 'vitrinka install --operator "Lukáš" --mcp --claude'],
     },
+    {
+        name: 'setup-project', summary: 'Onboard THIS repo: registry + file/route index + component index + editor check (interactive, idempotent)',
+        usage: '[--yes] [--base <url>] [--project <p>]',
+        flags: [BASE_FLAG,
+            { f: '--project', arg: '<p>', d: 'project name (default: repo dir name)' },
+            { f: '--yes', d: 'non-interactive: take every default, prompt for nothing' }],
+        examples: ['vitrinka setup-project', 'vitrinka setup-project --yes'],
+        write: true,
+    },
     {
         name: 'uninstall', summary: 'Remove everything install put here (skills, shim, completion, Claude wiring, MCP); token/operator survive',
         usage: '[--purge] [--yes] [--local]',
@@ -3315,7 +3640,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 +3663,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>]',
@@ -3403,7 +3736,7 @@ export const COMMANDS = [
         flags: [ROOT_FLAG, { f: '--slug', arg: '<board>', d: 'board slug (default: set key)' },
             { f: '--btitle', arg: '<t>', d: 'board title' }, { f: '--actor', arg: '<name>', d: 'override the operator attribution' }],
         dynamic: 'boards',
-        examples: ['vitrinka board-from-set --root .screenshots'],
+        examples: ['vitrinka board-from-set --root .vitrinka/screenshots'],
     },
     {
         name: 'journey-from-set', summary: 'Turn the set into a journey TREE board — signpost screens fan their branches, wires leave from the clicked element (snap --next/--target)',
@@ -3411,7 +3744,7 @@ export const COMMANDS = [
         flags: [ROOT_FLAG, { f: '--slug', arg: '<board>', d: 'board slug (default: set key)' },
             { f: '--btitle', arg: '<t>', d: 'board title' }, { f: '--actor', arg: '<name>', d: 'override the operator attribution' }],
         dynamic: 'boards',
-        examples: ['vitrinka journey-from-set --root .screenshots'],
+        examples: ['vitrinka journey-from-set --root .vitrinka/screenshots'],
     },
     {
         name: 'watch', summary: 'Monitor the work queue (listen v2); auto-scopes to repo+branch, leases the scope (one listener each), one line per new item',
@@ -3432,7 +3765,7 @@ export const COMMANDS = [
         usage: '[--root <dir>] [--base <url>] [--project <p>]',
         flags: [ROOT_FLAG, BASE_FLAG, { f: '--project', arg: '<p>', d: 'project slug (default: worktree name)' }],
         dynamic: 'projects',
-        examples: ['vitrinka index --root .screenshots'],
+        examples: ['vitrinka index --root .vitrinka/screenshots'],
     },
     {
         name: 'index-components', summary: 'Scan a UI library for exported components + push the component index',
@@ -3453,7 +3786,7 @@ export const COMMANDS = [
         usage: '[--root <dir>] [--select 1,3-5] [--size 720] [--quality 85] --out <dir>/data.json',
         flags: [ROOT_FLAG, { f: '--select', arg: '1,3-5', d: '1-based shot selection' }, { f: '--size', arg: '<px>', d: 'longest edge (default 720)' },
             { f: '--quality', arg: '<q>', d: 'JPEG quality (default 85)' }, { f: '--out', arg: '<file>', d: 'output data.json (required)' }],
-        examples: ['vitrinka embed-shots --root .screenshots --out .artifacts/x/data.json'],
+        examples: ['vitrinka embed-shots --root .vitrinka/screenshots --out .vitrinka/artifacts/x/data.json'],
     },
     {
         name: 'artifact-init', summary: 'Scaffold a blank artifact report + set config',
@@ -3464,11 +3797,11 @@ export const COMMANDS = [
     },
     {
         name: 'artifact-from-set', summary: 'Scaffold an artifact report from a screenshot set',
-        usage: '--slug <s> [--from .screenshots] [--select 1,3-5] [--title <t>] [--kind report] [--source <ref>]',
-        flags: [{ f: '--slug', arg: '<s>', d: 'artifact slug (= set key, required)' }, { f: '--from', arg: '<dir>', d: 'source set root (default .screenshots)' },
+        usage: '--slug <s> [--from .vitrinka/screenshots] [--select 1,3-5] [--title <t>] [--kind report] [--source <ref>]',
+        flags: [{ f: '--slug', arg: '<s>', d: 'artifact slug (= set key, required)' }, { f: '--from', arg: '<dir>', d: 'source set root (default .vitrinka/screenshots)' },
             { f: '--select', arg: '1,3-5', d: '1-based shot selection' }, { f: '--title', arg: '<t>', d: 'artifact title' },
             { f: '--kind', arg: '<k>', d: 'set kind (default report)' }, { f: '--source', arg: '<ref>', d: 'source set ref for cross-linking' }, BASE_FLAG],
-        examples: ['vitrinka artifact-from-set --slug payout-report --from .screenshots'],
+        examples: ['vitrinka artifact-from-set --slug payout-report --from .vitrinka/screenshots'],
     },
     // Meta commands — documented + completable, kept out of the compact usage grid.
     { name: 'help', summary: 'Show help (all commands, or one command in detail)', usage: '[<command>]', positional: '[<command>]', hidden: true,
@@ -3947,6 +4280,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(projectDirOf(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' };
@@ -3991,7 +4329,7 @@ async function boardFromSetCmd(root, args, journey = false) {
     const boardUrl = out.board?.url || `${cfg.base}${ws}/boards/${slug}`;
     console.log(`flow board: ${boardUrl}  (${out.cards.length} cards, ${out.edges.length} edges)`);
     // The board is about to be annotated — make sure its autocomplete index is fresh.
-    await pushProjectIndex(dirname(root), cfg.base, cfg.project);
+    await pushProjectIndex(projectDirOf(root), cfg.base, cfg.project);
 }
 // ---------- upload: files → board cards (mcp-file-upload 2026-07-15) ----------
 //
@@ -4096,7 +4434,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 +4446,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 +4461,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 +4726,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 = () => {
@@ -4588,7 +4932,12 @@ async function watchCmd(args) {
 async function runSub(argv) {
     const [cmd, ...rest] = argv;
     const args = parseArgs(rest);
-    const root = resolve(strArg(args.root) || '.screenshots');
+    // The default root may auto-migrate a legacy .screenshots/ — compute it ONLY
+    // for commands that actually take --root. Anything else (tidy, which owns
+    // migration report-first; artifact-from-set, whose --from must keep seeing
+    // the legacy path) must not move dirs as a side effect of dispatch.
+    const takesRoot = COMMAND_MAP[cmd]?.flags?.some((f) => f.f === '--root') ?? false;
+    const root = strArg(args.root) ? resolve(strArg(args.root)) : takesRoot ? homeRoot('screenshots') : '';
     if (cmd === 'add')
         addCmd(root, args, rest);
     else if (cmd === 'build') {
@@ -4609,8 +4958,12 @@ async function runSub(argv) {
         await loginCmd(args);
     else if (cmd === 'doctor')
         await doctorCmd(args);
+    else if (cmd === 'tidy')
+        tidyCmd(args);
     else if (cmd === 'install')
         await installCmd(args);
+    else if (cmd === 'setup-project')
+        await setupProjectCmd(args);
     else if (cmd === 'install-claude')
         installClaudeCmd(args);
     else if (cmd === 'uninstall')
@@ -4621,6 +4974,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')