@lovinka/vitrinka 1.12.0 → 1.15.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 `vitrinka update` prints the sections newer than your previous version after
 updating — keep entries short and user-facing.
 
+## 1.15.0 — 2026-07-18
+
+### Added
+- Update notifier v2 — the daily detached check now asks YOUR vitrinka server
+  first (new `GET /api/v1/version`: a deploy announces the version, works on
+  the mesh with npm unreachable) and falls back to the npm registry. Agent
+  shells (non-TTY — an AI session driving the CLI) see the
+  `update available … · run: vitrinka update` line on every run so the session
+  can offer the update; interactive terminals see it at most once a day.
+
+## 1.14.0 — 2026-07-18
+
+### Added
+- `compose_board` question options accept **`cardRef`** — trace an option to a
+  card created in the SAME compose batch (template + inline cards share one ref
+  space), so a decision map and its per-option architecture diagrams land in
+  ONE call. `cardId` still traces to existing cards; picking flies only on
+  ⌘-click now (plain click just stages the answer).
+- The built-in **`decision-map`** template is documented on `compose_board`:
+  structured params `{title, context, decisions:[{key, title, stakes, options,
+  multiSelect?, kind?: "text"}]}` render the whole brainstorm map — a
+  width-filling grid of merged decision tiles — deterministically server-side.
+
+## 1.13.0 — 2026-07-17
+
+### Added
+- `vitrinka import <file>` + `vitrinka schema push` — refreshable ground-truth
+  diagrams from docker-compose / OpenAPI / SQL DDL / a live Postgres;
+  `--section` lands them inside a journey frame, `--rev` stamps the git SHA.
+- Journey branch capture: `snap --next/--target` groups + journey-from-set.
+- Unified **publish** skill (session · journey · docs · board · artifact).
+- `compose_board` edges accept `fromRegion`/`toRegion`; `arrange` gains a
+  journey mode.
+
+### Fixed
+- `add --file` hardened (out-of-root copies, symlinks, non-regular files);
+  `push` guards against a huge `--root` and reports tar failures legibly.
+- `doctor` no longer health-checks every Claude MCP server.
+
 ## 1.11.0 — 2026-07-15
 
 ### Added

package/dist/cli.js

@@ -10,8 +10,8 @@
 // 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, } from 'node:fs';
-import { join, resolve, basename, dirname, extname, relative, sep } from 'node:path';
+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 { join, resolve, basename, dirname, extname, relative, sep, isAbsolute } from 'node:path';
 import { tmpdir, hostname } from 'node:os';
 import { spawnSync, spawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
@@ -21,6 +21,9 @@ import { readToken, tokenSource, tokenPath, tokenHelp } from "./lib/token.js";
 import { operatorPath, readOperator, actorHeaderValue } from "./lib/operator.js";
 import { resolveBaseUrl } from "./lib/base-url.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.
+const TAR_MAX_BUFFER = 512 * 1024 * 1024;
 export function parseArgs(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -244,11 +247,65 @@ function addCmd(root, args, rawArgv = []) {
         console.error('cli.ts add: --file <rel-path> is required');
         process.exit(2);
     }
+    // --file is a manifest reference relative to root: it is stored verbatim, served as a
+    // relative img.src in index.html, and becomes the tar member name under `-C root` at push.
+    // An absolute or ../-escaping path therefore can't be referenced in place — push (which
+    // tars root only) would silently drop it → broken image on the board with no error.
+    // But /tmp captures and vault exports are a real workflow, so an out-of-root path that
+    // EXISTS is copied into root and the manifest stores the in-root copy. Only an
+    // out-of-root path with no bytes behind it is an error (nothing to copy, nothing to
+    // serve). In-root rel-paths keep the old contract: existence NOT required, shots are
+    // often added before the bytes land.
+    let fileStr = String(file);
+    const rootAbs = resolve(root);
+    const source = resolve(rootAbs, fileStr);
+    const relToRoot = relative(rootAbs, source);
+    const lexicallyOut = relToRoot === '' || relToRoot === '..' || relToRoot.startsWith(`..${sep}`) || isAbsolute(relToRoot);
+    // A symlink source must ALSO be materialized even when lexically in-root: push tars
+    // symlinks as symlink entries and the server ingest rejects those, so storing the link
+    // verbatim would defer the failure to push — exactly what this guard exists to prevent.
+    const sourceLst = lstatSync(source, { throwIfNoEntry: false });
+    if (lexicallyOut || sourceLst?.isSymbolicLink()) {
+        if (!sourceLst) {
+            console.error(`cli.ts add: --file ${fileStr} is outside root (${rootAbs}) and does not exist — an outside file must exist so it can be copied into root`);
+            process.exit(2);
+        }
+        // stat follows symlinks: directories, FIFOs, devices, and dangling symlinks all get
+        // the same actionable exit instead of a raw copyFileSync throw (EISDIR, hang on FIFO).
+        if (!statSync(source, { throwIfNoEntry: false })?.isFile()) {
+            console.error(`cli.ts add: --file ${fileStr} does not resolve to a regular file — only regular files can be stored in root`);
+            process.exit(2);
+        }
+        mkdirSync(rootAbs, { recursive: true });
+        if (!lexicallyOut) {
+            // In-root symlink: replace it in place with the target's bytes so the manifest
+            // name the caller chose stays valid and push ships a regular file.
+            const real = realpathSync(source);
+            rmSync(source);
+            copyFileSync(real, source, fsConstants.COPYFILE_EXCL);
+            console.log(`copied ${real} → ${source} (replaced symlink)`);
+        }
+        else {
+            // Basename collisions get a numeric suffix instead of clobbering an earlier shot.
+            // lstat, not existsSync: a dangling symlink at the destination must count as a
+            // collision, or copyFileSync would follow it and write outside root.
+            let name = basename(source);
+            for (let i = 2; lstatSync(join(rootAbs, name), { throwIfNoEntry: false }); i++) {
+                const ext = extname(basename(source));
+                name = `${basename(source, ext)}-${i}${ext}`;
+            }
+            // COPYFILE_EXCL: if a dirent races in between the lstat loop and the copy,
+            // fail loudly rather than follow it.
+            copyFileSync(source, join(rootAbs, name), fsConstants.COPYFILE_EXCL);
+            console.log(`copied ${source} → ${join(rootAbs, name)}`);
+            fileStr = name;
+        }
+    }
     // Branch groups need the raw argv (which --target belongs to which --next);
     // with branches present the grouped parse also owns the action flags.
     const { branches, linearAction } = parseBranches(rawArgv);
     const shot = {
-        file: String(file),
+        file: fileStr,
         surface: args.surface && args.surface !== true ? String(args.surface) : 'other',
         route: args.route && args.route !== true ? String(args.route) : '',
         note: args.note && args.note !== true ? String(args.note) : '',
@@ -914,11 +971,50 @@ function markOffline(root, error) {
     }
     writeFileSync(p, JSON.stringify({ ts: new Date().toISOString(), error, ...(warned ? { warned } : {}) }) + '\n');
 }
+// pushExcluded mirrors the tar --exclude basename patterns below, so the pre-tar
+// file-count guard sees exactly what would be packaged.
+function pushExcluded(name) {
+    return name.startsWith('.vitrinka') || name === '.active' || name.startsWith('._') || name === '.DS_Store';
+}
+// countPushFiles counts the files tar would include under root (excludes pruned,
+// dirs not counted). Used to catch a --root pointed at something far bigger than a
+// screenshot set before the expensive tar spawn.
+function countPushFiles(root) {
+    let count = 0;
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir: tar would report it; the guard just skips it
+        }
+        for (const e of entries) {
+            if (pushExcluded(e.name))
+                continue;
+            if (e.isDirectory())
+                walk(join(dir, e.name));
+            else
+                count++;
+        }
+    };
+    walk(root);
+    return count;
+}
+const PUSH_FILE_GUARD = 100;
 async function pushCmd(root, args) {
     if (!existsSync(vitrinkaCfgPath(root))) {
         console.error(`push: no ${vitrinkaCfgPath(root)} — run \`node ${CLI_PATH} remote-init --root ${root}\` first`);
         process.exit(2);
     }
+    // Guard BEFORE the expensive tar spawn: a --root accidentally pointed at a whole
+    // repo (node_modules and all) blows past tar's maxBuffer. --confirm overrides; it is
+    // intentionally undocumented (not in the push flags/help) — an escape hatch, not a workflow.
+    const fileCount = countPushFiles(root);
+    if (fileCount > PUSH_FILE_GUARD && args.confirm !== true) {
+        console.error(`push: ${fileCount} files under ${root} exceeds the ${PUSH_FILE_GUARD}-file guard — that is far more than a screenshot set. If --root really is your capture dir, re-run with --confirm; otherwise point --root at the right directory.`);
+        process.exit(2);
+    }
     const cfg = loadVitrinkaCfg(root);
     const projectDir = dirname(root);
     // Control files are excluded here AND skipped server-side (belt and suspenders).
@@ -929,9 +1025,24 @@ async function pushCmd(root, args) {
         '--exclude', '.active', '--exclude', './.active',
         '--exclude', '._*', '--exclude', './._*', '--exclude', '.DS_Store',
         '-C', root, '.',
-    ], { maxBuffer: 512 * 1024 * 1024, env: { ...process.env, COPYFILE_DISABLE: '1' } });
+    ], { maxBuffer: TAR_MAX_BUFFER, env: { ...process.env, COPYFILE_DISABLE: '1' } });
     if (tar.status !== 0) {
-        console.error(`push: tar failed: ${String(tar.stderr)}`);
+        // When spawnSync kills tar for exceeding maxBuffer, the reason is on tar.error/tar.signal
+        // and tar.stderr is an empty Buffer — so the old `String(tar.stderr)` printed a blank line.
+        // Surface every diagnostic field so a maxBuffer kill (or any other failure) is legible.
+        const stderr = tar.stderr ? String(tar.stderr).trim() : '';
+        const stdoutBytes = tar.stdout ? tar.stdout.length : 0;
+        const parts = [
+            stderr && `stderr: ${stderr}`,
+            tar.error && `error: ${tar.error.message}`,
+            `status: ${tar.status}`,
+            tar.signal && `signal: ${tar.signal}`,
+            `stdout: ${stdoutBytes} bytes (maxBuffer ${TAR_MAX_BUFFER})`,
+        ].filter(Boolean);
+        console.error(`push: tar failed — ${parts.join(', ')}`);
+        if (stdoutBytes >= TAR_MAX_BUFFER || tar.error?.code === 'ENOBUFS') {
+            console.error(`push: the tarball exceeded the ${Math.round(TAR_MAX_BUFFER / (1024 * 1024))} MB buffer — check that --root (${root}) points at your capture dir, not a whole repo`);
+        }
         process.exit(1);
     }
     const commit = git(['rev-parse', '--short', 'HEAD'], projectDir);
@@ -1353,10 +1464,12 @@ function pluginRuntimes() {
         }
     }
     out.push({ name: 'claude', present: claudePresent, installed: claudeInstalled });
-    const codexPresent = !spawnSync('codex', ['--version'], { stdio: 'ignore' }).error;
+    const codexPresent = !spawnSync('codex', ['--version'], { stdio: 'ignore', timeout: 3_000 }).error;
     let codexInstalled = false;
     if (codexPresent) {
-        const r = spawnSync('codex', ['plugin', 'list'], { encoding: 'utf8' });
+        // Already fast in practice (~200ms); timeout is belt-and-suspenders so a
+        // hung codex child cannot freeze doctor the way `claude mcp list` did.
+        const r = spawnSync('codex', ['plugin', 'list'], { encoding: 'utf8', timeout: 5_000 });
         codexInstalled = r.status === 0 && /\bvitrinka\b/.test(r.stdout || '');
     }
     out.push({ name: 'codex', present: codexPresent, installed: codexInstalled });
@@ -1399,12 +1512,55 @@ function rcPathOf(home) {
 // every /mcp request, so registration without a token is refused with the
 // token help. X-Board-Actor rides along when an operator persona exists
 // (UTF-8 bytes latin-1-encoded — header values are ByteStrings).
+//
+// mcpRegistered MUST stay O(1)/fast: doctor and install status call it on every
+// run. Never shell out to `claude mcp list` — that health-checks EVERY approved
+// MCP server (measured ~60s with ~13 servers; one flaky server can hang longer).
+// Prefer reading Claude Code's config file; fall back to `claude mcp get
+// vitrinka` (health-checks only that one server, ~1s) with a hard timeout.
 function claudeCliPresent() {
-    return !spawnSync('claude', ['--version'], { stdio: 'ignore' }).error;
+    return !spawnSync('claude', ['--version'], { stdio: 'ignore', timeout: 3_000 }).error;
+}
+function mcpRegisteredFromClaudeConfig() {
+    const home = process.env.HOME || '';
+    if (!home)
+        return null;
+    const cfgPath = join(home, '.claude.json');
+    if (!existsSync(cfgPath))
+        return null;
+    try {
+        const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'));
+        if (cfg.mcpServers && Object.prototype.hasOwnProperty.call(cfg.mcpServers, 'vitrinka')) {
+            return true;
+        }
+        // Project-scoped registrations (less common for our remote HTTP install,
+        // which uses --scope user) — accept any project that names vitrinka.
+        for (const proj of Object.values(cfg.projects || {})) {
+            if (proj?.mcpServers && Object.prototype.hasOwnProperty.call(proj.mcpServers, 'vitrinka')) {
+                return true;
+            }
+        }
+        // Config readable and no vitrinka entry anywhere → definitive no (skip the
+        // slower get-fallback). A missing file / parse error returns null instead.
+        return false;
+    }
+    catch {
+        return null;
+    }
 }
 function mcpRegistered() {
-    const r = spawnSync('claude', ['mcp', 'list'], { encoding: 'utf8' });
-    return r.status === 0 && /\bvitrinka\b/.test(r.stdout);
+    const fromCfg = mcpRegisteredFromClaudeConfig();
+    if (fromCfg !== null)
+        return fromCfg;
+    // Schema unknown / unreadable config — single-server probe (not fleet list).
+    const r = spawnSync('claude', ['mcp', 'get', 'vitrinka'], {
+        encoding: 'utf8',
+        timeout: 5_000,
+    });
+    if (r.error || r.status !== 0)
+        return false;
+    // "get" prints the server block when registered; otherwise errors / no match.
+    return /\bvitrinka\b/i.test((r.stdout || '') + (r.stderr || ''));
 }
 function mcpTarget() {
     const args = ['--transport', 'http', 'vitrinka', `${resolveBaseUrl()}/mcp`];
@@ -2196,12 +2352,33 @@ const HINT_SKIP = new Set(['install', 'install-claude', 'update', 'uninstall',
 function updateCheckPath() {
     return join(process.env.HOME || '', '.config', 'vitrinka', 'update-check');
 }
-// maybeNotifyUpdate — one dim stderr line when a newer published version is
+// updateNotice — PURE decision core of the notifier (exported for tests).
+// Returns the notice line to print (or null) and whether the detached check
+// should refresh the cache. TTY sessions see the line at most once a day
+// (notifiedAt throttle); non-TTY consumers (agent shells — Claude runs the
+// CLI constantly) get it on EVERY run so the session can't miss it and can
+// offer `vitrinka update` to the user.
+export function updateNotice(current, cache, isTTY, now) {
+    const DAY = 24 * 3600 * 1000;
+    const newer = !!(cache.latest && current && cmpSemver(cache.latest, current) > 0);
+    const throttled = isTTY && now - (cache.notifiedAt || 0) < DAY;
+    const line = newer && !throttled
+        ? `update available ${current} → ${cache.latest} · run: vitrinka update`
+        : null;
+    return { line, check: now - (cache.ts || 0) >= DAY, markNotified: newer && !throttled && isTTY };
+}
+// maybeNotifyUpdate — one quiet stderr line when a newer published version is
 // known, npm installs only (a repo checkout is a dev seat that pulls itself).
-// The registry check runs DETACHED at most once a day and writes a cache file;
-// the hot path only ever reads it — a command never waits on the network.
+// The check runs DETACHED at most once a day and writes a cache file; the hot
+// path only ever reads it — a command never waits on the network. The check
+// asks the VITRINKA SERVER first (GET /api/v1/version — the deploy is the
+// announcement, works on the mesh) and falls back to the npm registry.
 function maybeNotifyUpdate(cmd) {
-    if (HINT_SKIP.has(cmd) || !process.stderr.isTTY || !process.env.HOME)
+    if (HINT_SKIP.has(cmd) || !process.env.HOME)
+        return;
+    // Opt-outs: explicit, CI, and test runners (spawned CLIs inherit
+    // NODE_TEST_CONTEXT) — a notifier must never add load or noise there.
+    if (process.env.VITRINKA_NO_UPDATE_CHECK || process.env.CI || process.env.NODE_TEST_CONTEXT)
         return;
     if (git(['rev-parse', '--show-toplevel'], dirname(CLI_PATH)))
         return;
@@ -2213,16 +2390,30 @@ function maybeNotifyUpdate(cmd) {
     catch {
         // Absent or corrupt cache — the background refresh below rewrites it.
     }
-    const current = pkgVersion();
-    if (cache.latest && current && cmpSemver(cache.latest, current) > 0) {
-        console.error(`\x1b[2mupdate available ${current} → ${cache.latest} · run: vitrinka update\x1b[0m`);
+    const isTTY = !!process.stderr.isTTY;
+    const { line, check, markNotified } = updateNotice(pkgVersion(), cache, isTTY, Date.now());
+    if (line)
+        console.error(isTTY ? `\x1b[2m${line}\x1b[0m` : line);
+    if (markNotified) {
+        try {
+            mkdirSync(dirname(p), { recursive: true });
+            writeFileSync(p, JSON.stringify({ ...cache, notifiedAt: Date.now() }));
+        }
+        catch {
+            // Throttle state is best-effort; worst case the line repeats.
+        }
     }
-    if (Date.now() - (cache.ts || 0) < 24 * 3600 * 1000)
+    if (!check)
         return;
+    const versionUrl = `${resolveBaseUrl()}/api/v1/version`;
     const script = `const fs=require('fs'),path=require('path'),f=${JSON.stringify(p)};`
-        + `fetch('https://registry.npmjs.org/@lovinka/vitrinka/latest',{signal:AbortSignal.timeout(10000)})`
-        + `.then(r=>r.json()).then(d=>{fs.mkdirSync(path.dirname(f),{recursive:true});`
-        + `fs.writeFileSync(f,JSON.stringify({ts:Date.now(),latest:String(d.version||'')}))}).catch(()=>{})`;
+        + `const save=v=>{fs.mkdirSync(path.dirname(f),{recursive:true});`
+        + `let prev={};try{prev=JSON.parse(fs.readFileSync(f,'utf8'))}catch{}`
+        + `fs.writeFileSync(f,JSON.stringify({...prev,ts:Date.now(),latest:String(v||'')}))};`
+        + `fetch(${JSON.stringify(versionUrl)},{signal:AbortSignal.timeout(4000)})`
+        + `.then(r=>r.ok?r.json():Promise.reject(0)).then(d=>{if(!d.cli)throw 0;save(d.cli)})`
+        + `.catch(()=>fetch('https://registry.npmjs.org/@lovinka/vitrinka/latest',{signal:AbortSignal.timeout(10000)})`
+        + `.then(r=>r.json()).then(d=>save(d.version)).catch(()=>{}))`;
     try {
         spawn(process.execPath, ['-e', script], { detached: true, stdio: 'ignore' }).unref();
     }
@@ -3122,6 +3313,32 @@ export const COMMANDS = [
         examples: ['vitrinka upload report.pdf --board pr-105-vitrinka --section "Evidence"',
             'vitrinka upload spec.docx shots/*.png --board payout-flow'],
     },
+    {
+        name: 'import', summary: 'Parse a source file (OpenAPI / SQL DDL / docker-compose) into a refreshable diagram card',
+        usage: '<file> --board <slug> [--kind auto|openapi|sqlddl|compose] [--title "…"] [--section "Name"] [--rev <sha>] [--actor <name>] [--base <url>]',
+        positional: '<file>',
+        flags: [{ f: '--board', arg: '<slug>', d: 'target board (required)' },
+            { f: '--kind', arg: '<auto|openapi|sqlddl|compose>', d: 'source kind (default: auto-detect from name/content)' },
+            { f: '--title', arg: '<t>', d: 'diagram title (default: derived from the source)' },
+            { f: '--section', arg: '<name>', d: 'land inside the named section frame (docs boards: Architecture/Database/API/Pages)' },
+            { f: '--rev', arg: '<sha>', d: 'source revision (git SHA) stamped on the ↻ label' },
+            { f: '--actor', arg: '<name>', d: 'override the operator attribution' }, BASE_FLAG],
+        dynamic: 'boards',
+        examples: ['vitrinka import openapi.yaml --board arch-docs',
+            'vitrinka import schema.sql --board myapp-docs --section Database --rev $(git rev-parse --short HEAD)',
+            'vitrinka import docker-compose.yml --board infra'],
+    },
+    {
+        name: 'schema', summary: 'Introspect a live Postgres LOCALLY (psql) and push its schema as a refreshable diagram — the connection string never leaves the machine',
+        usage: 'push --db <postgres-url> --board <slug> [--title "…"] [--actor <name>] [--base <url>]',
+        positional: 'push',
+        flags: [{ f: '--db', arg: '<postgres-url>', d: 'connection string, passed to local psql (required)' },
+            { f: '--board', arg: '<slug>', d: 'target board (required)' },
+            { f: '--title', arg: '<t>', d: 'diagram title (default: derived from the database name)' },
+            { f: '--actor', arg: '<name>', d: 'override the operator attribution' }, BASE_FLAG],
+        dynamic: 'boards',
+        examples: ['vitrinka schema push --db postgres://localhost/shop --board db-docs'],
+    },
     {
         name: 'board-from-set', summary: 'Turn the set into an annotation flow board',
         usage: '[--root <dir>] [--slug <board>] [--btitle <t>] [--actor <name>]',
@@ -3788,6 +4005,192 @@ async function uploadCmd(rest, args) {
     }
     console.log(text);
 }
+// ---------- import / schema push: refreshable diagram sources ----------
+//
+// `vitrinka import <file>` parses a real source (OpenAPI / SQL DDL /
+// docker-compose) SERVER-SIDE into a living diagram card; `vitrinka schema
+// push` introspects a live Postgres LOCALLY (the connection string never
+// leaves the machine) and posts only the parsed schema JSON. Both land on
+// POST /api/v1/boards/{slug}/import, which stamps payload.source so the card
+// refreshes in place as the source evolves.
+// detectImportKind picks the importer kind from an explicit flag, the file
+// name, then a content sniff. Returns "" when it can't decide.
+export function detectImportKind(explicit, file, content) {
+    if (explicit && explicit !== 'auto')
+        return explicit;
+    const base = basename(file).toLowerCase();
+    const ext = extname(base);
+    if (/(^|[.-])(docker-)?compose\.ya?ml$/.test(base))
+        return 'compose';
+    if (ext === '.sql')
+        return 'sqlddl';
+    const head = content.slice(0, 4000);
+    if (/^\s*services\s*:/m.test(head))
+        return 'compose';
+    if (/["']?(openapi|swagger)["']?\s*:/.test(head) || /^\s*(openapi|swagger)\s*:/m.test(head))
+        return 'openapi';
+    if (/create\s+table/i.test(head))
+        return 'sqlddl';
+    if (/["']?paths["']?\s*:/.test(head))
+        return 'openapi';
+    if (ext === '.json' || ext === '.yaml' || ext === '.yml')
+        return 'openapi';
+    return '';
+}
+// postImport sends a raw source to the board import endpoint and prints the card.
+async function postImport(board, body, args) {
+    const base = resolveBaseUrl(strArg(args.base));
+    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;
+    const res = await fetch(`${base}/api/v1/boards/${encodeURIComponent(board)}/import`, {
+        method: 'POST', headers, body: JSON.stringify(body), signal: AbortSignal.timeout(120_000),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        console.error(`import: ${res.status} ${text}`);
+        process.exit(1);
+    }
+    console.log(text);
+}
+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 "…"]');
+        process.exit(2);
+    }
+    if (!existsSync(file)) {
+        console.error(`import: no such file: ${file}`);
+        process.exit(2);
+    }
+    const source = readFileSync(file, 'utf8');
+    const kind = detectImportKind(strArg(args.kind), file, source);
+    if (!kind) {
+        console.error(`import: could not detect the source kind of ${basename(file)} — pass --kind openapi|sqlddl|compose`);
+        process.exit(2);
+    }
+    const body = { kind, source, ref: basename(file) };
+    const title = strArg(args.title);
+    if (title)
+        body.title = title;
+    // Placement + provenance passthrough (docs-boards decisions #2/#6): --section
+    // lands inside a scaffold frame (Architecture/Database/API/Pages on docs
+    // boards); --rev stamps the source revision (git SHA) for the ↻ micro-label.
+    const section = strArg(args.section);
+    if (section)
+        body.section = section;
+    const rev = strArg(args.rev);
+    if (rev)
+        body.rev = rev;
+    await postImport(board, body, args);
+}
+// PG_INTROSPECT_SQL emits the pgschema JSON document (one row) from
+// information_schema — tables, columns (type/nullable/pk/unique) and single-
+// column foreign keys. Shelled to `psql`; the connection string stays local.
+const PG_INTROSPECT_SQL = `
+WITH cols AS (
+  SELECT table_schema, table_name, column_name, data_type, ordinal_position,
+         (is_nullable = 'YES') AS nullable
+  FROM information_schema.columns
+  WHERE table_schema NOT IN ('pg_catalog','information_schema')
+),
+pk AS (
+  SELECT tc.table_schema, tc.table_name, kcu.column_name
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+  WHERE tc.constraint_type = 'PRIMARY KEY'
+),
+uq AS (
+  SELECT tc.table_schema, tc.table_name, kcu.column_name
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+  WHERE tc.constraint_type = 'UNIQUE'
+),
+fk AS (
+  SELECT tc.table_schema, tc.table_name, kcu.column_name,
+         ccu.table_schema AS ref_schema, ccu.table_name AS ref_table, ccu.column_name AS ref_column
+  FROM information_schema.table_constraints tc
+  JOIN information_schema.key_column_usage kcu
+    ON tc.constraint_name = kcu.constraint_name AND tc.table_schema = kcu.table_schema
+  JOIN information_schema.constraint_column_usage ccu
+    ON tc.constraint_name = ccu.constraint_name AND tc.table_schema = ccu.table_schema
+  WHERE tc.constraint_type = 'FOREIGN KEY'
+),
+tabs AS (
+  SELECT table_schema, table_name FROM information_schema.tables
+  WHERE table_type = 'BASE TABLE' AND table_schema NOT IN ('pg_catalog','information_schema')
+)
+SELECT json_build_object(
+  'database', current_database(),
+  'tables', COALESCE(json_agg(json_build_object(
+    'schema', t.table_schema, 'name', t.table_name,
+    'columns', (SELECT COALESCE(json_agg(json_build_object(
+        'name', c.column_name, 'type', c.data_type, 'nullable', c.nullable,
+        'pk', EXISTS(SELECT 1 FROM pk WHERE pk.table_schema=c.table_schema AND pk.table_name=c.table_name AND pk.column_name=c.column_name),
+        'unique', EXISTS(SELECT 1 FROM uq WHERE uq.table_schema=c.table_schema AND uq.table_name=c.table_name AND uq.column_name=c.column_name)
+      ) ORDER BY c.ordinal_position), '[]'::json)
+      FROM cols c WHERE c.table_schema=t.table_schema AND c.table_name=t.table_name),
+    'foreignKeys', (SELECT COALESCE(json_agg(json_build_object(
+        'column', f.column_name, 'refSchema', f.ref_schema, 'refTable', f.ref_table, 'refColumn', f.ref_column
+      )), '[]'::json)
+      FROM fk f WHERE f.table_schema=t.table_schema AND f.table_name=t.table_name)
+  ) ORDER BY t.table_schema, t.table_name), '[]'::json)
+) FROM tabs t;
+`;
+async function schemaCmd(rest, args) {
+    const sub = rest.find((a) => !a.startsWith('--'));
+    if (sub !== 'push') {
+        console.error('usage: vitrinka schema push --db <postgres-url> --board <slug> [--title "…"]');
+        process.exit(2);
+    }
+    const db = strArg(args.db);
+    const board = strArg(args.board);
+    if (!db || !board) {
+        console.error('usage: vitrinka schema push --db <postgres-url> --board <slug> [--title "…"]');
+        process.exit(2);
+    }
+    // Introspect LOCALLY via psql; the connection string never leaves the machine.
+    const run = spawnSync('psql', [db, '-X', '-A', '-t', '-c', PG_INTROSPECT_SQL], {
+        encoding: 'utf8', maxBuffer: 64 * 1024 * 1024,
+    });
+    if (run.error && run.error.code === 'ENOENT') {
+        console.error('schema push: `psql` not found on PATH — install the PostgreSQL client (the introspection runs locally; only the parsed schema is uploaded)');
+        process.exit(1);
+    }
+    if (run.status !== 0) {
+        console.error(`schema push: psql failed:\n${(run.stderr || '').trim()}`);
+        process.exit(1);
+    }
+    const schemaJSON = (run.stdout || '').trim();
+    if (!schemaJSON) {
+        console.error('schema push: psql returned no schema (empty database, or the connection string is wrong)');
+        process.exit(1);
+    }
+    const body = { kind: 'pgschema', source: schemaJSON, ref: pgRefLabel(db) };
+    const title = strArg(args.title);
+    if (title)
+        body.title = title;
+    await postImport(board, body, args);
+}
+// pgRefLabel derives a non-secret "host/db" label from a connection string for
+// payload.source.ref — never the credentials.
+export function pgRefLabel(db) {
+    try {
+        const u = new URL(db);
+        const name = u.pathname.replace(/^\//, '') || 'postgres';
+        return `${u.hostname || 'localhost'}/${name}`;
+    }
+    catch {
+        return 'postgres';
+    }
+}
 // announceLine renders the single stdout line for one work item:
 //   №<id> [<intent>] <board>: <prompt, single line, ≤100 chars>
 export function announceLine(it) {
@@ -4075,6 +4478,10 @@ async function runSub(argv) {
         await snapCmd(rest[0] && !rest[0].startsWith('--') ? rest[0] : '', args, rest);
     else if (cmd === 'upload')
         await uploadCmd(rest, args);
+    else if (cmd === 'import')
+        await importCmd(rest, args);
+    else if (cmd === 'schema')
+        await schemaCmd(rest, args);
     else if (cmd === 'board-from-set')
         await boardFromSetCmd(root, args);
     else if (cmd === 'journey-from-set')