@vitrinka/cli 3.3.0

package/CHANGELOG.md

@@ -0,0 +1,525 @@
+# Changelog
+
+`vitrinka update` prints the sections newer than your previous version after
+updating — keep entries short and user-facing.
+
+## 3.3.0 — unreleased
+
+### Changed
+- **Package renamed: `@lovinka/vitrinka` → `@vitrinka/cli`** (platform packages
+  `@vitrinka/cli-<os>-<arch>`). Same CLI, same `vitrinka` bin, now under the
+  product's own npm scope alongside `@vitrinka/expo`. `vitrinka update` on an
+  old-scope install migrates automatically (removes the legacy package before
+  installing this one); `@lovinka/vitrinka` is deprecated with a pointer here.
+
+## 3.2.0 — 2026-08-23
+
+### Added
+- **vitrinka now works from ANY directory.** `vitrinka install` registers the
+  MCP forwarder at user scope everywhere (a bound repo also keeps its
+  committed project-scope entry, which stays the preferred mechanism and
+  always wins), and a new machine-level **default workspace** answers for
+  directories no binding covers. Onboarding asks you to pick one; later it's
+  `vitrinka config default`.
+- **Path-prefix workspace rules** — map a folder subtree to a workspace
+  (`vitrinka config prefix ~/Work/ClientA acme`); the longest matching rule
+  wins, the default workspace is the fallback behind them.
+- **A confirm gate on defaulted writes.** A write from a directory that
+  resolved through a prefix rule or the default asks once per directory
+  (per workspace) before landing — as a y/N in the CLI, and as a structured
+  `workspace_confirm_required` re-call for MCP agents. `vitrinka config
+  writes auto` turns the asking off; explicit bindings never ask.
+- `vitrinka doctor` shows a `default workspace` row, and the dashboard shows
+  the resolved workspace with its provenance.
+
+### Changed
+- Re-running `install` no longer removes a healthy registration at a scope it
+  is not rewriting — committed `.mcp.json` entries survive the global-first
+  migration untouched.
+
+## 3.1.0 — 2026-08-23
+
+### Added
+- **`vitrinka mcp` — MCP registrations no longer carry your token.** The entry
+  every client now gets is the same three words in every repo
+  (`command: vitrinka, args: ["mcp"]`), with no URL and no credential in it.
+  The command resolves the deployment, workspace, token and operator at
+  request time, from the repo's committed binding and your OS keychain. That
+  makes `.mcp.json` safe to commit — so a clone is born registered — and it
+  gives Codex per-repo workspace routing its global, header-less registry
+  could never express.
+
+### Changed
+- **`vitrinka install` rewrites a legacy token-bearing registration** wherever
+  it finds one — either Claude scope, or Codex's `config.toml` — and tells you
+  to commit the now secret-free `.mcp.json` alongside `project.json`.
+- **`vitrinka doctor` names a credential in a config file for what it is**,
+  per file (`.mcp.json`, `.claude.json`, `config.toml`), with `vitrinka
+  install` as the repair. It also names a registration that predates the
+  forwarder instead of showing it green.
+
+### Fixed
+- A repo whose `.vitrinka/project.json` cannot be read no longer falls back to
+  the default deployment — it refuses and names the file to repair, instead of
+  quietly publishing to the wrong install.
+- A locked or unreadable credential store is reported as itself, not as a
+  generic 401 from the server, and unlocking it heals the running session
+  without relaunching the client.
+- The forwarder no longer outlives the client that launched it: closing the
+  pipe ends in-flight work after a short grace, and a stalled handshake can no
+  longer hold the process open.
+
+## 3.0.2 — 2026-08-22
+
+### Added
+- **Workspace bindings travel with the repo.** `vitrinka config bind` now
+  writes a committed `.vitrinka/project.json` (per deployment, so on-prem
+  coexists) — clone a bound repo on any machine and it is bound at checkout.
+  The machine config remains as credentials + fallback.
+- **`vitrinka install` self-heals multi-workspace setups**: writes the
+  committed binding from a machine-only one, narrows an old wholesale
+  `.vitrinka/` ignore so the binding can reach git, and re-registers the
+  Claude MCP entry project-scope when it predates workspace baking.
+- **`vitrinka doctor` explains multi-workspace problems**: binding source
+  (committed vs machine-only), ignore rules hiding the binding, and stale MCP
+  registrations — each row names the repair.
+
+### Changed
+- Working in several workspaces on one machine no longer needs per-repo
+  header surgery: the server now also resolves the workspace from the
+  project a call names, and refuses (with the fix spelled out) instead of
+  guessing when the answer is ambiguous.
+
+## 3.0.1 — 2026-08-22
+
+### Changed
+- **Hosted Vitrinka now lives at `vitrinka.ai`.** New installs, MCP setup,
+  desktop/Snap defaults, share links, and generated config schemas use the new
+  domain. Existing credentials and workspace bindings stored for
+  `vitrinka.in` continue to work during the compatibility window.
+
+## 3.0.0 — 2026-08-18
+
+The CLI is now a **compiled Go binary**. `@lovinka/vitrinka` is a thin npm
+launcher: it resolves the per-platform binary package for your machine and
+execs it. Same commands, same flags, same config files — no Node runtime
+needed to run vitrinka, and startup is instant.
+
+### Changed
+- **`vitrinka` is Go.** Source moved from `pkg/src/cli.ts` to `cmd/vitrinka` +
+  `internal/cli/*` in the vitrinka repo. The npm package ships `bin/vitrinka.js`,
+  which launches the binary from `@lovinka/vitrinka-<platform>-<arch>`
+  (declared as optionalDependencies, resolved by npm from whatever registry
+  you already use — no postinstall download, works offline and behind proxies).
+- Installing with `--omit=optional` / `--no-optional` skips the binary by
+  design; the launcher says exactly which platform package is missing.
+
+### Removed
+- **The `vitrinka-mcp` bin is gone.** The stdio MCP server is retired in favor
+  of the server's remote endpoint. Re-register once:
+
+  ```bash
+  claude mcp remove vitrinka
+  claude mcp add --scope user --transport http vitrinka https://vitrinka.ai/mcp \
+    --header "Authorization: Bearer $(vitrinka token)"
+  ```
+
+  `vitrinka install` / `vitrinka doctor --fix` do this for you (Claude Code and
+  Codex both).
+- **The unattended fallback worker (`vitrinka-mcp work`) is gone.** `vitrinka
+  watch` plus the native background monitor armed by the `listen` skill is the
+  one listening lane now.
+- The `mcp/server.ts`, `mcp/work.ts` and `mcp/index.ts` repo shims are deleted —
+  a repo checkout no longer registers an stdio MCP; point at `/mcp` instead.
+
+## Unreleased (pre-3.0.0 — TypeScript CLI, never published)
+
+### Removed
+- **Claude Code UI wiring is gone.** The `install-claude` command, the
+  `[Y/n]` install step and the `--claude`/`--no-claude` flags were removed —
+  the statusline extension and the 🧷 board / ⧉ app footer badges never worked
+  well. `install`/`update`/`uninstall` now actively strip the old wiring from
+  `~/.claude/settings.json` (restoring your original `statusLine.command`).
+
+### Added
+- **Consent-gated project indexes.** `setup-project` and `index configure` now
+  create a repo-owned `vitrinka.config.json`, with extension presets, a recursive
+  tri-state directory picker, strict ignore layers, exact-manifest preview, and
+  per-machine approval. `index status`, `--dry-run`, and `--explain <path>` make
+  the resulting policy auditable.
+- **Workspaces follow the project, not the token.** `vitrinka login` now
+  mints a USER-LEVEL token that acts as you in every workspace you're a
+  member of; each repo binds to its own workspace (`vitrinka use`, an
+  indexed table you answer by number — or automatically when exactly one of
+  your workspaces has the project). Commands in an unbound repo stop with
+  the same table and the fix command, so an agent asks you instead of
+  writing into the wrong workspace. Workspace-pinned tokens keep working
+  but are deprecated — doctor and `vitrinka update` nag to re-login.
+  Per-project Claude MCP registrations bake the workspace in as an
+  `X-Vitrinka-Workspace` header.
+- **`vitrinka logout`** revokes this machine's token server-side
+  (`DELETE /api/v1/me/tokens/current`) and removes the local file; your
+  user-level tokens are listable and individually revocable via
+  `GET`/`DELETE /api/v1/me/tokens[/{id}]` — a lost laptop has an answer.
+- **Semantic artifacts.** `artifact-init` now scaffolds a `doc.json` you author
+  plus a fixed shell rendered by the server-owned kit-3 — palette, type,
+  spacing, light/dark and the design direction (editorial · dossier · terminal
+  · gallery) come from the kit, and artifacts follow the viewer's theme
+  automatically. `artifact-from-set` composes the doc (sections + shot
+  figures) the same way. The full-HTML escape hatch lives on as
+  `artifact-init --custom`, now themed by default.
+- `push` warns when a hand-authored `index.html` carries HTML entities inside
+  template literals (`&rarr;` renders literally under htm — write `→`).
+- Findings carry their proof: `status` (verification chip), `cause`, `summary`
+  (the bold conclusion) and `evidence` (mono receipt footer citing the exact
+  log/file/check) joined the finding block.
+- **Codex MCP registration.** `vitrinka install` now offers to register the
+  remote MCP for Codex too (writes `[mcp_servers.vitrinka]` +
+  `http_headers` into `$CODEX_HOME/config.toml`), `vitrinka doctor --fix`
+  repairs it, and `vitrinka uninstall` removes it. Doctor/install rows are now
+  `mcp·claude` / `mcp·codex`. Skills already shipped to Codex via the plugin;
+  the MCP was the missing half.
+
+### Fixed
+- `vitrinka tag` read option VALUES as positionals, so
+  `tag add b1 auth --actor alice` sent `["auth", "alice"]` as tag names — and
+  tags autocreate, so routine invocations silently minted junk tags. A flag
+  placed before the verb (`tag --actor x add …`) also fell through to the `ls`
+  default. Both now come from the shared `positionals()` parse the rest of the
+  CLI already uses.
+
+### Changed
+- Project indexes are path-only v2 manifests. The CLI no longer reads or sends
+  source excerpts, absolute paths, origin remotes, home-directory commands, or
+  command descriptions. Missing/disabled/changed policies fail closed; tracked
+  `.gitignore` matches, credential/key names, and binary/generated paths are
+  denied client-side and again by the server. Deploying this release purges all
+  legacy index rows once.
+- **`tag merge` and `tag drop` now REFUSE without a TTY unless `--yes` is
+  given** (exit 2). They previously treated "no TTY to ask on" as approval, so
+  they ran unconfirmed in scripts, CI and any redirected shell — `drop`
+  detaches the tag from every board, card and session. **If you script either
+  verb, add `--yes`.**
+
+## 1.21.2 — 2026-07-26
+
+### Added
+- `vitrinka doctor` reports listener leases held by dead watch processes on this
+  machine, and `vitrinka doctor --fix` releases them.
+- `vitrinka extension setup | update | doctor` — install the journey-recorder
+  browser extension from the CLI and keep it current. Updates now happen in
+  place: the popup's "update available" banner is a button that has the CLI
+  download, checksum-verify and swap the release, then reloads the extension
+  into it. `--check` reports without installing; `doctor --fix` re-registers the
+  native-messaging host after a CLI reinstall moves `node` or the CLI.
+- The extension takes its base URL and token from this machine's CLI config on
+  first load, so a fresh install needs no pasting (the options page gains a
+  "Fill from the vitrinka CLI" override). Existing settings are never replaced.
+- **Migrating a hand-unzipped copy:** the extension now pins its id, so the
+  CLI-managed folder is a *different* extension to Chrome. Run
+  `vitrinka extension setup`, load `~/.config/vitrinka/extension`, and remove
+  the old card — a token you pasted by hand does not carry over.
+
+### Changed
+- `vitrinka install` now detects the Chromium browsers on the machine and offers
+  the recorder as a step (`--extension` / `--no-extension`), so re-running it on
+  an already-onboarded machine is how you backfill the extension. An install
+  that already has it silently re-registers the update host, which is also how a
+  browser added since the last run starts working. `vitrinka update` keeps an
+  installed extension current, and the update host is registered for the
+  browsers detected on the machine (falling back to all of them when none is
+  detected, so a fresh box still gets a working host) — so `extension doctor`
+  can now tell you the browser you *use* is unregistered instead of counting
+  four blind writes.
+
+### Fixed
+- A listener could outlive the session that armed it and hold its board's lease
+  **forever**. Claude Code signals the wrapper shell it spawned, so the watch
+  underneath never got the SIGTERM — it was adopted by init and kept renewing
+  its lease, which the TTL cannot reap (the TTL only reaps leases that stop
+  heartbeating). Annotations dispatched on that board then vanished into a
+  process nobody was reading. Three fixes: `/vitrinka:listen` now arms
+  `exec vitrinka watch` so the watch *is* the signalled process; `vitrinka
+  watch` self-terminates if it is ever orphaned, covering exits that deliver no
+  signal at all (agent SIGKILLed, crashed, terminal closed); and it now handles
+  SIGHUP alongside SIGINT/SIGTERM.
+- Release integrity is fail-closed: a feed without a usable SHA-256, or an
+  artifact larger than it advertised, is refused before anything is downloaded
+  or swapped. Previously the checksum was only verified when the field happened
+  to be present, and the whole body was buffered unbounded.
+
+## 1.21.1 — 2026-07-25
+
+### Fixed
+- `/vitrinka:brainstorming` sometimes skipped the decision map — the map was
+  reasoned out but never written, so the round opened straight into a "anything
+  to cut, add, or reorder?" picker whose options referenced decisions you could
+  not see anywhere, expanded output included. The map is now printed as its own
+  message before any question is asked, and the board-mode exemption from
+  printing it only applies once a board actually exists.
+
+## 1.21.0 — 2026-07-25
+
+### Added
+- MCP `get_session` — one recorded testing session as a compact digest (the
+  screen walk, issues deduped across steps with live board status, per-route
+  web vitals, and facets to group them into fix batches). Address it by session
+  id or by the session's board slug. Use it instead of walking raw `/events`.
+
+### Changed
+- Closing a session no longer waits for its board. The server builds the board
+  on a worker and reports `projection` state, so a stop returns immediately —
+  and a recording session's board is now kept live as you test, rather than
+  only existing once the session ends. Anything reading `projectionError` off a
+  stop response should read `projection.state` instead.
+
+## 1.20.0 — 2026-07-23
+
+### Changed
+- All output now lives under one `.vitrinka/` home in the target repo:
+  `.vitrinka/screenshots/` (was `.screenshots/`), `.vitrinka/artifacts/<slug>/`
+  (was `.artifacts/`), plus `.vitrinka/scratch/<topic>/` as the sanctioned spot
+  for ad-hoc session output. Legacy roots auto-migrate the first time a command
+  touches them; explicit `--root`/`--from` paths are respected as given.
+
+### Added
+- `vitrinka tidy [--yes] [--all]` — report-first sweep of legacy roots and
+  shot-shaped repo-root litter (`.screenshots-<topic>/`, loose `shot-*.png`)
+  into `.vitrinka/`; `--all` also moves loose images and `.aud_*` text litter.
+  Git-tracked files are never touched.
+- Plugin skills `/vitrinka:annotations` + `/vitrinka:answers` — manual MCP
+  fallback drains for when a "Send to Claude" dispatch doesn't reach the
+  session (annotation work queue / durable question answers).
+
+## 1.19.0 — 2026-07-23
+
+### Added
+- `vitrinka setup-project` — the repo onboarding wizard (clack-styled TUI, the
+  pkg's first runtime deps: `@clack/prompts` + `picocolors`). One front door for
+  everything a repo needs before the editor and board @ autocomplete work:
+  machine-install gate (offers `install` inline when the machine isn't
+  onboarded), project name + registry record, file/route index push (verified),
+  component-index with auto-detected candidate dirs, desktop-app check, and an
+  optional hello board. Status-first and idempotent — re-runs refresh the cheap
+  bits and only prompt for what's missing; `--yes`/non-TTY takes every default.
+- `edit` and `status` print a one-line hint toward `vitrinka setup-project`
+  while the repo has never been indexed.
+
+## 1.18.0 — 2026-07-21
+
+### Added
+- `vitrinka edit [path]` — focus the resident Vitrinka.app editor on a file or
+  project via the `vitrinka://edit?path=…` deep link (`--print` emits only the
+  URL; when the app isn't installed it prints an install hint). The instant
+  editor's CLI entry point.
+- Automatic project registry: `edit`, `status`, `watch`, and `board-from-set`
+  now record `{project → main-worktree path}` to
+  `~/.config/vitrinka/projects.json` as a side effect, so the desktop editor
+  auto-discovers your live checkouts with zero extra UX. Best-effort — a write
+  failure never breaks the command.
+- `compose_board` accepts kind `"artifact"` — a sandboxed self-contained HTML
+  card straight from a compose batch: `{html}` full document or
+  `{body, runtime: "tw4"}` markup-only (server inlines the Tailwind v4
+  runtime; dramatically cheaper). Up to 8 MiB inline.
+
+### Changed
+- `compose_board`'s card schema is slim: the tool description now carries the
+  kind index + quick shapes only; per-kind payload contracts live in the
+  vitrinka plugin skills (the publish skill's `references/card-kinds.md` is
+  the index). Unknown kinds still 400 with the full allowed list.
+- `vitrinka import` (and `POST /import`) replies with a compact per-card
+  summary (`{id, elemNo, kind, title, counts, section?}`); pass `--verbose`
+  (API: `?verbose=1`) for the full card JSON.
+
+## 1.17.0 — 2026-07-20
+
+### Added
+- `get_questions` MCP tool — durable post-send retrieval of a board's answered
+  decisions (options, notes, ⌖ refs). Choices ride the work wire exactly once,
+  so a send with no listening session used to look unrecoverable; now any
+  session can re-read the full answer record at any time.
+- `scrape_board` digest now carries a compact `questions[]`
+  (`{id, prompt, answer?, note?, staged?}`) — one call reads the decision
+  state alongside cards/flow/sections; section scopes keep only their own.
+- `vitrinka watch` keepalive: while a human actually has the board open, the
+  leased watch emits a quiet `· keepalive` heartbeat (default every 3000 s,
+  `--keepalive 0` off) so the listening session's prompt cache stays warm and
+  the next annotation lands cheap. An abandoned board costs nothing.
+
+## 1.16.0 — 2026-07-19
+
+### Added
+- Listener takeover is automatic on the same machine — arming `vitrinka watch`
+  for a scope another of YOUR sessions already holds displaces the older
+  listener (its in-flight items go back to the queue) instead of failing with
+  a 409 and a manual handoff. The displaced watch prints one stand-down line
+  and exits cleanly. Live leases on a *different* machine still refuse the
+  claim; `--takeover` still steals expired leases only.
+
+### Fixed
+- `vitrinka watch` and the background daemon no longer swallow answered
+  brainstorm choices — a pure choice batch used to be drained by the notifier
+  and marked delivered while the listening session never woke. Notifier lanes
+  now peek without consuming, and watch announces each answer as a
+  `№<id> [choice]` line; the acting lane keeps exactly-once delivery.
+
+## 1.15.1 — 2026-07-18
+
+### Added
+- `vitrinka version` (and `--version`/`-V` for the bare number) — the installed
+  version, where it runs from (repo checkout / bun / pnpm / npm install), and
+  the last known update state from the notifier cache. No network, instant.
+
+### Fixed
+- `vitrinka update` now updates through the package manager that OWNS the
+  running copy (bun / pnpm / npm, detected from the executable's path) and
+  verifies the running file actually changed — a bun-installed CLI used to
+  `npm i -g` into a shadowed prefix and stay stale forever, and update warns
+  loudly when another install still shadows it on PATH.
+
+## 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
+- `vitrinka upload <files…> --board <slug>` — put PDFs, documents, and images
+  on a board as cards straight from disk (the bytes never pass through an AI
+  context). PDFs land as live embedded document cards, other files as download
+  chips. Placement is intent-based: `--section "Name"` lands inside a journey
+  frame (grows to fit), `--anchor <cardId> [--side right|below]` docks beside a
+  card, and no flag = server free placement (never a 0,0 pile).
+
+## 1.10.1 — 2026-07-13
+
+### Changed
+- Canonical domain is now **vitrinka.in** — the CLI/MCP default base URL,
+  skills and docs all point there. vitrinka.lovinka.com keeps working as an
+  alias; override per-machine with `VITRINKA_URL` as before. Re-run
+  `vitrinka install` (or `doctor --fix`) to re-register MCP on the new host.
+
+## 1.10.0 — 2026-07-13
+
+### Added
+- `compose_board` question options accept `cardId` — the board draws a trace
+  wire from the option to the card it names, hovering glows it, and picking
+  flies the camera there. Pair it with the new `POST /artifact` params
+  (`section`, `device`, `anchor`/`side`): mockups land inside their take's
+  section frame, sized by device intent, and scale to fit their card
+  automatically (server-measured natural size).
+
+## 1.9.0 — 2026-07-12
+
+### Changed
+- MCP registration moved to the remote `/mcp` endpoint (streamable HTTP) —
+  no local stdio process per session; `vitrinka install`/`doctor --fix`
+  re-register automatically. The old stdio bin is deprecated.
+
+## 1.8.3 — 2026-07-11
+
+### Fixed
+- Interactive prompts (`install`'s operator question, any `promptLine`) strip
+  ANSI escape sequences and control characters — arrow-key edits no longer
+  persist raw `ESC[D`/`ESC[C` bytes into the operator name (which every fresh
+  browser adopted as its board identity). `vitrinka operator <name>` sanitizes
+  the same way, and the server now rejects control characters with 422.
+
+## 1.8.2 — 2026-07-11
+
+### Added
+- Desktop-app flag: `~/.config/vitrinka/desktop-app` is the one canonical
+  "is Vitrinka.app installed" answer (content = app path). Stamped by
+  `apps/desktop make install`, re-synced by `install-claude` and `doctor`.
+- `install-claude` adds a second **⧉ app** footer badge (only when the app is
+  installed) whose `vitrinka://` deep link opens the board in Vitrinka.app.
+- `vitrinka open` opens the board in Vitrinka.app when installed;
+  `--browser` forces the browser.
+
+## 1.8.1 — 2026-07-11
+
+### Added
+- `install-claude` now also wires a `SessionStart` hook
+  (`~/.claude/hooks/vitrinka-board-link.sh`) that puts the repo's live board
+  URL into session context at start — the clickable 🧷 footer badge exists
+  from message one instead of waiting for a board URL to be mentioned.
+  `vitrinka doctor` reports (and `--fix` repairs) the hook; `uninstall`
+  removes it.
+
+## 1.8.0 — 2026-07-11
+
+### Changed
+- Skills now distribute EXCLUSIVELY as the vitrinka plugin — for Claude Code
+  (`claude plugin install vitrinka@lovinka`) AND Codex (`codex plugin add
+  vitrinka`), both from the `LEFTEQ/vitrinka` marketplace. `vitrinka install`,
+  `doctor --fix` and `update` install/refresh the plugin in every runtime CLI
+  they find; the npm package no longer bundles the skills.
+- Skills layout flattened: `listen` is a first-class skill
+  (`/vitrinka:listen` in Claude Code, `$listen` in Codex).
+
+### Removed
+- `vitrinka install-skills` — superseded by the plugin. `vitrinka uninstall`
+  still clears legacy `~/.claude/skills` copies from pre-plugin machines.
+
+## 1.6.0 — 2026-07-08
+
+### Added
+- `vitrinka update` — updates the CLI (git pull in a checkout, `npm i -g` when
+  behind the registry), prints what's new, and refreshes the installed skills
+  and Claude UI wiring.
+- Status-first onboarding: `vitrinka install` now prints a ✓/✗ setup table and
+  handles everything install.sh used to (MCP registration, write token,
+  operator persona, env checks) — asking only for what's missing.
+- `vitrinka uninstall [--purge]` — clean offboarding (skills, shim, completion,
+  Claude wiring, MCP registration; `--purge` also removes token + operator).
+- `vitrinka doctor --fix` — repairs stale skills, a stale/missing shim, a lost
+  MCP registration, and the Claude UI wiring.
+- `vitrinka open [--qr]` — opens the capture root's live board; `--qr` renders
+  a terminal QR code to scan with the iPad.
+- `vitrinka status` — session dashboard: live board, open work queue, and the
+  listener lease for the current repo+branch.
+- Passive update notifier (one dim line, cached daily, npm installs only) and a
+  first-run hint on fully unconfigured machines.
+
+### Removed
+- `install.sh` — the CLI is the installer now: `vitrinka install` (or
+  `node pkg/src/cli.ts install` from a checkout).
+
+## 1.5.0 — 2026-07-08
+
+- project-memory MCP tools + link/board compose vocabulary (pre-changelog release).

package/README.md

@@ -0,0 +1,125 @@
+# @vitrinka/cli
+
+The [vitrinka](https://github.com/FixIt-Technologies/vitrinka) CLI — capture
+screenshots, publish artifact **sets**, scaffold interactive artifacts, and arm
+the annotation-board `watch` monitor that feeds work to a listening AI session.
+
+Since **3.0.0** the CLI is a compiled **Go binary**. This npm package is the
+launcher: `bin/vitrinka.js` resolves the binary for your platform and execs it.
+The binary arrives through per-platform packages declared as
+`optionalDependencies` (`@vitrinka/cli-darwin-arm64` and friends), so npm
+fetches it from whatever registry your machine already uses — no postinstall
+download, no network surprise in sandboxed CI or behind a corporate proxy.
+
+## Install
+
+```bash
+npm i -g @vitrinka/cli
+vitrinka install        # one-command machine setup
+```
+
+`vitrinka install` IS the onboarding: it prints a ✓/✗ table of every component,
+silently installs the harmless ones (the skills plugin into each runtime CLI it
+finds, a `vitrinka` shim on PATH, shell completion — all reversible), then asks
+`[Y/n]` only for the config-touchers: MCP registration, the write token (silent
+input, → the OS keyring) and the operator name.
+
+```bash
+vitrinka doctor          # server, token, operator, skills, shim, MCP
+vitrinka doctor --fix    # repairs the repairable
+vitrinka update          # update the CLI and everything install put here
+vitrinka uninstall       # remove it all (--purge: token too)
+```
+
+Installing with `--omit=optional` / `--no-optional` skips the binary by design.
+The launcher then tells you which platform package is missing rather than
+failing as "command not found".
+
+## MCP
+
+The MCP server is **remote** — it runs inside the vitrinka server, so there is
+nothing to install and nothing to keep up to date. Register it once:
+
+```bash
+claude mcp add --scope user --transport http vitrinka https://vitrinka.ai/mcp \
+  --header "Authorization: Bearer $(vitrinka token)"
+```
+
+For Claude Desktop or any other MCP client, add the equivalent HTTP entry:
+
+```json
+{
+  "mcpServers": {
+    "vitrinka": {
+      "type": "http",
+      "url": "https://vitrinka.ai/mcp",
+      "headers": { "Authorization": "Bearer …" }
+    }
+  }
+}
+```
+
+> The stdio `vitrinka-mcp` bin was **removed in 3.0.0**. If you have a
+> registration pointing at `npx -y --package=@vitrinka/cli vitrinka-mcp`
+> (or at a `mcp/server.ts` repo shim), replace it with the HTTP form above —
+> `vitrinka install` and `vitrinka doctor --fix` will do it for you.
+
+vitrinka is reachable over the WireGuard mesh — bring the VPN up (or point
+`VITRINKA_BASE_URL` at any reachable host) before use.
+
+## Configuration (env)
+
+| Var | Default | Purpose |
+|---|---|---|
+| `VITRINKA_URL` / `VITRINKA_BASE_URL` | `https://vitrinka.ai` | vitrinka server base URL. `VITRINKA_URL` wins, then `VITRINKA_BASE_URL`; the CLI's `--base` flag overrides both. |
+| `VITRINKA_TOKEN` | — | Bearer write token. Falls back to the OS keyring / `~/.config/vitrinka/`. Required only by the **mutating** calls; read calls work unauthenticated. |
+| `VITRINKA_OPERATOR` | — | Operator persona name. When set, write calls carry `X-Board-Actor: <name>` so the board credits the operator — agent-authored content keeps its explicit `claude` attribution. |
+
+## Trustworthy project index
+
+`vitrinka setup-project` or `vitrinka index configure` creates the
+repository-owned `vitrinka.config.json`. The interactive picker chooses
+extension groups and any depth of directory tree, then shows the exact file
+manifest before approval. Choosing "later" writes an explicit disabled policy
+and uploads nothing.
+
+The index contains repository-relative paths, derived routes, and repository
+command names only — never source bytes, absolute paths, remotes, command
+descriptions, or files from `~/.claude`. `.gitignore` is an unconditional deny
+layer even for tracked files; detected `.claudeignore` is offered as another;
+untracked files require an explicit advanced opt-in; credential/key filenames
+and binary/generated assets are blocked by both client and server safety floors.
+
+```bash
+vitrinka index configure              # edit, preview, approve, then refresh
+vitrinka index status                 # policy + local approval/upload receipt
+vitrinka index --dry-run              # exact paths, no network request
+vitrinka index --explain path/to/file # winning selection or deny rule
+```
+
+The config schema is served by the deployment at
+`https://vitrinka.ai/static/vitrinka.config.schema.json` — reference it from
+`$schema` in your `vitrinka.config.json` for editor completion.
+
+## Desktop app
+
+`~/.config/vitrinka/desktop-app` is the ONE canonical "is Vitrinka.app installed
+here" answer (content = the app path). `apps/desktop`'s `make install` stamps it;
+`doctor` and `setup-project` re-sync it to reality. `vitrinka open` uses it to
+open boards in the app (pass `--browser` to force the browser), and
+`vitrinka edit [path]` focuses the resident app on a file or project.
+
+## Development
+
+The CLI source lives in the vitrinka repo — `cmd/vitrinka` + `internal/cli/`:
+
+```bash
+go build -o /tmp/vitrinka ./cmd/vitrinka
+go test ./internal/cli/...
+```
+
+This package carries no implementation; it is the npm front door only.
+
+## License
+
+MIT

package/bin/vitrinka.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// The npm front door for the Go binary (decisions D7 and D12).
+//
+// `npm i -g @vitrinka/cli` and `npx @vitrinka/cli` must keep working
+// exactly as they do today — it is currently the ONLY documented way to install
+// this tool, and every skill, doc and agent instruction says so. So the npm
+// package survives the port; what changes is that it now launches a compiled
+// binary instead of being the implementation.
+//
+// The binary arrives through per-platform packages declared as
+// optionalDependencies (esbuild's pattern), NOT through a postinstall script
+// that downloads one. That distinction is the whole design:
+//
+//   - A postinstall download needs network access at install time, which is
+//     blocked in sandboxed CI, in air-gapped environments, and behind exactly
+//     the corporate proxies decision D13 exists for.
+//   - optionalDependencies are resolved by npm itself, so they come from
+//     whatever registry the machine is already configured to use — including
+//     the bank's internal mirror (D12) — with no extra machinery.
+//   - The lockfile records them, so an install is reproducible.
+//
+// npm installs only the optional dependency matching the host platform and
+// silently skips the rest, which is why all of them can be declared at once.
+
+const { spawnSync } = require('node:child_process');
+
+const WINDOWS = process.platform === 'win32';
+const PKG = `@vitrinka/cli-${process.platform}-${process.arch}`;
+const BIN = `vitrinka${WINDOWS ? '.exe' : ''}`;
+
+function resolveBinary() {
+  try {
+    return require.resolve(`${PKG}/bin/${BIN}`);
+  } catch {
+    return null;
+  }
+}
+
+const binary = resolveBinary();
+
+if (!binary) {
+  // Say which platform package is missing and why it might be. "command not
+  // found" here would send someone to debug their PATH, when the real cause is
+  // almost always an --omit=optional install or an unsupported platform.
+  process.stderr.write(
+    `\n  vitrinka: no binary for ${process.platform}-${process.arch}\n\n` +
+      `  The platform package ${PKG} is not installed.\n\n` +
+      `  Reinstall without omitting optional dependencies\n` +
+      `    npm install -g @vitrinka/cli\n\n` +
+      `  If your installer is configured with --omit=optional or\n` +
+      `  --no-optional, the binary is skipped by design; allow optional\n` +
+      `  dependencies, or install the platform package directly\n` +
+      `    npm install -g ${PKG}\n\n`,
+  );
+  process.exit(1);
+}
+
+// stdio: 'inherit' is LOAD-BEARING, not a default worth changing.
+//
+// The Go CLI decides what to do by asking whether stdin and stdout are
+// terminals: bare `vitrinka` opens the dashboard on a TTY and prints usage
+// otherwise, and every prompt and spinner branches the same way. Piping the
+// child's streams here would make the binary see pipes in every case — so the
+// dashboard would never open for anyone who installed through npm, which is
+// everyone. Inheriting hands the real terminal straight through.
+const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+
+if (result.error) {
+  process.stderr.write(`\n  vitrinka: could not run ${binary}\n  ${result.error.message}\n\n`);
+  process.exit(1);
+}
+
+// A child killed by a signal has a null status. Reporting the conventional
+// 128+signal keeps `vitrinka ... ; echo $?` and CI's failure detection honest;
+// exiting 0 here would make a SIGKILLed run look successful.
+if (result.signal) {
+  const SIGNALS = { SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
+  process.exit(128 + (SIGNALS[result.signal] || 0));
+}
+
+process.exit(result.status === null ? 1 : result.status);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vitrinka/cli",
+  "version": "3.3.0",
+  "description": "vitrinka CLI — capture and publish artifact sets, drive the annotation-board work queue. Thin npm launcher for the single-binary Go CLI.",
+  "bin": {
+    "vitrinka": "bin/vitrinka.js"
+  },
+  "files": [
+    "bin",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@vitrinka/cli-darwin-arm64": "3.3.0",
+    "@vitrinka/cli-darwin-x64": "3.3.0",
+    "@vitrinka/cli-linux-arm64": "3.3.0",
+    "@vitrinka/cli-linux-x64": "3.3.0",
+    "@vitrinka/cli-win32-arm64": "3.3.0",
+    "@vitrinka/cli-win32-x64": "3.3.0"
+  },
+  "keywords": [
+    "vitrinka",
+    "lovinka",
+    "cli",
+    "mcp",
+    "model-context-protocol",
+    "screenshots",
+    "ai"
+  ],
+  "author": "Lovinka",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FixIt-Technologies/vitrinka.git",
+    "directory": "npm/vitrinka"
+  }
+}