@lovinka/vitrinka 1.18.0 → 1.21.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,7 +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 } from "./lib/registry.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.
@@ -162,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.
@@ -229,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)
@@ -237,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 };
@@ -513,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) {
@@ -680,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.
@@ -749,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);
@@ -824,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")');
@@ -848,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)
@@ -861,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 {
@@ -913,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');
@@ -1017,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', [
@@ -1324,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
@@ -1626,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) ----
@@ -1701,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
@@ -1713,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).');
@@ -1739,7 +1911,7 @@ 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
@@ -1754,10 +1926,10 @@ async function installCmd(args) {
         console.log('claude ui: skipped (--no-claude)');
     }
     else if (uiOk || args.claude === true
-        || promptYesNo('Wire Claude Code UI (clickable 🧷 board footer badge)? [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 {
@@ -2190,8 +2362,11 @@ function editCmd(rest, args) {
     // 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);
+    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);
@@ -2208,6 +2383,189 @@ function editCmd(rest, args) {
     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
@@ -2218,8 +2576,10 @@ async function statusCmd(root, args) {
     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)
+    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)');
@@ -2682,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) {
@@ -3001,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>
@@ -3008,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">
@@ -3090,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)`);
@@ -3098,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>"`);
@@ -3111,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)`);
@@ -3128,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.
@@ -3150,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' },
@@ -3170,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',
@@ -3189,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',
@@ -3197,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",
@@ -3222,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]',
@@ -3231,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]',
@@ -3339,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)',
@@ -3347,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',
@@ -3368,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',
@@ -3389,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',
@@ -3400,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,
@@ -3885,7 +4282,7 @@ async function boardFromSetCmd(root, args, journey = false) {
     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));
+    const projTop = mainWorktreeTop(projectDirOf(root));
     if (cfg.project && projTop)
         recordProject(sanitizeSeg(cfg.project, 64), projTop);
     const slug = (strArg(args.slug) || cfg.key).toLowerCase();
@@ -3932,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) ----------
 //
@@ -4535,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') {
@@ -4556,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')