CLI changelog — vitrinka docs

Every release of the vitrinka CLI, newest first, rendered from the changelog the npm package ships. Run vitrinka update to get the newest one. Entries before 5.0.0 use the command names that release retired; its table maps each old name to the new one.

5.25.0

doc.json speaks the board's vocabulary. A document is now a doc element — {"kind": "doc", "payload": {title, …, "elements": [...]}} — and every child is the same {kind, payload} a board composes: md for prose, source for code, cols with keyed rows for tables, elements inside sections. vitrinka board push rewrites a legacy {meta, blocks} doc.json (and its pages) to the new shape on disk before it uploads; the server still converts the old shape for this release and warns, and the next release refuses it. kit-3's Table, Prose, Code and Compare take the element names too; the old ones keep working.

A --json field typo never writes twice. Asking a write verb for a field it does not return (vitrinka task create … --json=id,key) used to fail after the task was filed, with a fix that filed it again. Once a write has landed, a missing field is an unknown_field warning on the successful answer, listing the fields that exist; before the write it is still refused with the corrected call.

Eve can judge a review run. /vitrinka:review … eve plans a run for Eve the way a session's own review does: Eve judges each planned screen or crop once, skips reused and duplicate screens, and fills the same coverage receipt.

A board in another workspace is named, never "no work". vitrinka work on a board slug that lives in another workspace answers the <workspace>/<slug> spelling that reaches it instead of reporting an empty queue.

5.24.0

Reviews read each screen once. vitrinka review plan <board>… (review_plan for agents) plans a review over your boards: the latest capture pass by default, capture gaps left out, exact duplicates judged once, near-duplicates as a crop of what changed, and screens already judged under the same rubric reused — on a few labelled sheets instead of one image per screen. A host that cannot see images is stopped after the first sheet, and the run's receipt says what was inspected, reused or skipped. --checklist adds your own checks; --full re-judges everything.

Pick who judges your reviews. vitrinka config reviewer codex judges screens on the Codex sidekick, self (the default) in the session that runs the review; the session start names the lane when it is not the default.

vitrinka update refreshes a slow Claude Code. When claude --version (or codex --version) took more than three seconds — a busy computer is enough — update printed "claude (absent)" and skipped the plugin refresh without a word. Only a CLI missing from your PATH counts as absent now: a slow one is refreshed, and a refresh that fails says why.

A deleted artifact stays deleted. vitrinka board push to an artifact someone deleted is refused with artifact_deleted and a link to its page, where Restore brings it back. --revive publishes it again on the same page instead.

Ticking one step keeps the rest. A checklist written to a task (vitrinka task field set, an agent's update) now merges by item: send only the step you tick and the other steps and gates stay. --replace writes the whole list, the way to drop, rename or reorder items.

5.23.0

Claude Code stays signed in to vitrinka. vitrinka update and setup modules no longer rewrite the MCP registration when the modules it serves are unchanged — each rewrite signed every session out. Agents can no longer start a vitrinka sign-in: that cleared the sign-in every session on the computer shares. They now ask you to run /mcp → vitrinka → Reconnect instead.

A cut refuses a window that moved. vitrinka project release --cut --expect-head <sha> refuses the cut with release_head_mismatch, cutting nothing, when a refresh moved the head since you checked it. The release prints Page: (and --json carries docHeadSha): whether Eve's page was written for the current head or is stale after a refresh. A window now starts after its start commit, so the PR that commit merged is never listed again.

A deploy mark says when its lineage is partial. vitrinka project deploy-mark prod <sha> also prints how many merge commits were read from GitHub, and when GitHub's listing fell short it warns Partial: with how many merged PRs still ship by time.

5.22.0

memo's memory islands reach vitrinka. This update is all a Mac running memo needs: memo calls four hidden doors from its outbox. memory snapshot put publishes each cloud-bound island's snapshot of a merged commit. The island's current moves only by compare-and-set, and a stale publisher gets cas_mismatch with the cloud's current to adopt. memory usage put sends this Mac's hourly usage tally. memory resolve ranks memo recall --deep through Eve. memory watch put|completions mirrors a for: human watch row to one todo and reports the todos completed here. Agents read the cache as get {kind: "project_memory"}: a bounded, ranked index, paged by cursor.

Cut the release you deployed. vitrinka project release --refresh --until <sha> sweeps only the merges that commit contains and answers its head, so a pipeline cuts exactly the tag it shipped. vitrinka deploy-mark says how History ships a production mark: by ancestry, with how many waiting refs it contains, or by the time rule and why.

5.21.0

A fresh session opens again from Claude Code. vitrinka qa session launch <task url> <dir> runs your $VITRINKA_SESSION_LAUNCHER with both appended and prints its receipt; the brainstorm's and the hand-back's fresh-session exits call it. They used to run the launcher through sh -c, which Claude Code's removal check refuses with nobody at the prompt, so the exit always fell back to /continue. Unset, not runnable or a non-zero exit still names the /continue line to run by hand.

5.20.0

The plugin is four plugins. vitrinka (core: publish, artifact, brainstorming, listen, resolve), vitrinka-pm (pickup, handoff, tasks, release, me — and the session hooks of the work loop, so a Claude Code marketplace install gets them without setup), vitrinka-qa (usertest, review, sessions, pair, spot) and the opt-in, Claude Code only vitrinka-experimental (build-idea, make-idea, test, cleanup). A session on a repo that only needs boards no longer pays for the task engine's skills and tools. vitrinka setup installs core + pm + qa (--modules picks, --experimental adds the fourth); this vitrinka update installs pm and qa once on a machine set up before the split, and respects a choice vitrinka setup modules has recorded. Codex keeps one bundle with every module.

vitrinka setup modules list|enable|disable <module> adds or removes the plugin that ships a module (pm, me, qa, experimental; core is always on) and re-registers Claude Code's MCP door as /mcp?modules=…, so the tool catalogue and its instructions shrink with the plugins you have. vitrinka setup skills show|hide <skill> hides one optional skill without dropping its module. vitrinka doctor shows a plugin·claude and plugin·codex row per runtime and a hooks·claude row.

Six MCP doors the skills used to reach with raw calls: undo (revert your newest batch on a board), refresh (re-parse a living-source card), import (a truth source — openapi, sqlddl, compose, pgschema — as one refreshable diagram), review_verify (link a fresh capture to a failed judgment), get_card_image {annotation} and update {kind: "session"}. spot moved to the qa module; five doors nobody called moved to rare. Every skill was rewritten against the doors that exist — no /api/v1/ route anywhere; the ladder is the MCP tool, then the CLI, then stop.

In Claude Code type the bare /pickup, /publish, …; the qualified /vitrinka-pm:pickup always works. Codex keeps $pickup.

5.19.0

A task says which issue it tracks. vitrinka task links add <id> <url> attaches the GitHub, GitLab or Jira issue a task tracks (or a Confluence page it refers to); task links <id> lists them and task links rm <id> <link-id> detaches one. vitrinka task find <url> answers which task tracks an issue — exactly, and links: [] when none does. task create … --link <url> files a task already linked. An issue has one owner task: attaching it to a second answers link_owned with the task that tracks it.

5.18.0

A write made offline is not lost. When the deployment cannot be reached — the network is down, or an agent's MCP connection dropped with it — task comment, task update, task create, task label, task upload, task handback, me todo add, me todo done and the new board compose <board> --file - (compose_board's arguments) queue their request in an outbox on this machine and exit 0 with ⧗ queued offline. The next command that reaches the deployment replays them first, oldest first, each exactly once. vitrinka outbox list shows what waits and what the server parked, and why; flush, retry and drop act on them. --no-queue (or VITRINKA_NO_QUEUE=1) keeps the old fail-fast behaviour.

5.17.1

A code-mode review shows the sheet as an image, never as text. When a Codex code-mode script reads get_card_image, the review skill and the annotation docs now tell it to hand the image block to the host's image call (image(block)) and print only the text block. A script that logged the whole result would otherwise feed the image's base64 to the model as text, which is how one review's transcript grew to 41 GB.

5.17.0

A ui-loop review keeps what did not move. Each review batch carries a digest per screen and a reviewer records the digests of the screens it actually read, so retaking a few blank shots reopens only those screens, never every finished batch. A screen whose shots did not change since the previous pass is carried: it keeps its findings and verdicts, leaves the review batches and counts as reviewed, and the scoreboard callout names how many were carried.

Several review runs share one ui-loop pass. Each review-loop run claims its own review batches, so a big pass can be reviewed by several identical runs at once: the review stage's return says how many (parallel), each of those runs continues as one, and a run that finds every batch left already claimed ends. A run whose reviewer failed hands its claimed batches to its own next run, which reviews them first. Only the run that takes the pass's synthesis lease writes the backlog, scores the pass and posts the callouts; any other ends saying another run is synthesizing. While a capture runs, every stage waits instead of starting beside it, and areas no longer narrows a review.

A stalled reviewer no longer stalls the pass. A review batch whose reviewer stalls twice (the watchdog stops it) is split in halves, and the same run reviews them with the agents it has left. A half that stalls twice is blocked instead of retried: its screens stay unreviewed and are named in the run's problems, the pass still gets its backlog, and the loop then ends naming them, to judge by hand or reshoot, instead of reviewing the pass again.

A ui-loop polish loop can be paused. vybava ui-loop pause --reason "…" drains the whole loop: no review-loop stage starts (it returns stage paused, a null next and the resume args to launch later), and a running stage ends at its next boundary, after its reviewer round, before the synthesis, between fix lanes or before Settle, keeping what it did. vybava ui-loop resume lifts the pause and frees the stopped runs' batch claims; launch the resume args and the loop goes on where it stopped.

A screen nobody could shoot is one line, not a broken finding. A ui-loop screen marked retired (dead code, a plugin not installed, a feature off) is never shot, reviewed or counted, and map marks such screens instead of calling them unreachable. A screen without a single usable shot (unreachable, a failed recipe, an error) no longer counts against review coverage or gets filed as a broken finding: each area board's "Not captured this pass" card lists it once with its reason, instead of once per viewport and theme. The fix round's rig lane (below) repairs its recipe, and the screens a pass still has no shot of when it reaches its final check are named in one problems line and keep it from completing.

A cross-lane fix is reworked, not blocked. A ui-loop fix lane whose fix needs a file another lane owns now defers the item with the change it needs there, and the fix stage gives it a rework lane after the area lanes that owns both, so it is fixed in the same round. A block now means the fix waits on something outside the repo (seed data, a backend, another repo, a decision), and the run that ends the fix round returns every such item of the round in one list, ownerQuestions, to ask their owner in a single batch. A skipped, blocked or deferred item stays checkpointed while its own files are unchanged, whatever other lanes commit; one that no longer counts is listed in the stage's stale, and the next fix round takes it.

A ui-loop fix round repairs its capture recipes. The round ends with one rig lane that fixes the recipes a renamed label or a dead step broke: the literal names vybava ui-loop check --labels finds in no label source, the screens the pass never shot (unless the manifest marks them unreachable with the seed data) and those whose recipe failed; a screen whose code is dead or whose feature is off it marks retired. It reaches a control by its role and accessible name (the harness's action step) instead of a CSS or nth= selector, checks each repair with vybava ui-loop run --probe before it checkpoints it, re-renders the app map with them, and the verify pass reshoots those screens. A screen it cannot repair joins the round's ownerQuestions when its environment blocks it, or reworkStuck when the repair needs the app or the rig's project file. A pass whose review converged gets the same repair: the loop runs the rig lane on it and then captures the screens it repaired, instead of ending with them unshot. A label miss no longer stops a capture, and map writes new recipes the same way.

A ui-loop pass triages its failures. After each capture, and before the review writes the backlog, vybava ui-loop triage groups the shots that failed by cause. Screens that failed on infrastructure (a network blip, a page that stayed blank) come back as one vybava ui-loop run --retake … command in the stage's problems, and one application failure behind many screens is filed as ONE broken item that names them all, instead of a finding per screen. A recipe whose literal left the app goes to the fix round's rig lane. Every ui-loop stage needs Výbava v0.45.0 or later (ui-loop state contract 10) and refuses an older one; run brew upgrade --cask vybava. Update vitrinka with it: an older vitrinka neither waits for a running capture, shares a review between runs nor splits a stalled batch, it cannot finish a review in which a newer one blocked a batch, it would complete a pass whose never-shot screens it never names, and it stops a fix round in which a lane deferred an item.

5.16.1

Every survey uses the contact sheet. The publish and resolve skills and the experimental test flow now survey a set with get_card_image {cardIds} and measure on a single-card read, like review. When the server is busy, a sheet now tells the agent to retry instead of dropping the card, so a survey no longer silently loses a screen.

A ui-loop stage checks its Výbava before it starts. review-loop reads the contract number vybava ui-loop state reports and runs vybava ui-loop doctor for the stage: an older Výbava, a state field it did not report, or a failing doctor check stops the run before anything changes, naming the fix. Reviewers judge against the grid and touch target your vybava.config.ts sets.

A ui-loop pass knows when its shots went stale. vybava ui-loop state reports what changed since a pass was captured (application source, the capture rig, the spec's rules), and review-loop runs the stage it routes to as it is, including the exact screens a verify reshoots, or every screen when a shared primitive changed. A stage you asked for is never swapped for a capture: when the app drifted it stops, lists the changed paths and hands back the capture to run, and a run limited to areas never shoots. Spec rules changed since the capture reach reviewers and fixers as final owner decisions; a screen no reviewer could judge (a missing or blank shot) is filed as a recipe or capture finding the fix round repairs and the verify reshoots, not recaptured. A pass whose captured revision this clone lacks, or one shot before passes recorded their revision, hands back a capture (or the fetch) instead of running on shots nobody can date. Every ui-loop stage needs Výbava v0.35.0 or later (ui-loop state contract 2) and refuses an older one; run brew upgrade --cask vybava.

5.16.0

Review a set of screens through one contact sheet. get_card_image takes cardIds (up to 12) and answers with one labelled sheet plus each tile's card id, source size and version. The review skill surveys a board that way on every host, Codex included, and image bytes never pass through a shell command again: one Codex review had grown to 41 GB echoing base64 into its own commands.

5.15.0

Publish any number of screenshots. board push, board upload, board dump and qa run publish no longer stop at a few hundred files: pushes upload six files at a time, uploads travel in batches with retries, and a big run's screenshots are staged first and published by reference. Nothing to split by hand, ever.

Your project wears its app's icon. vitrinka setup finds the icon in the repository root (public/apple-touch-icon.png, app/icon.png, public/favicon.svg, favicon.ico, Expo's expo.icon, …) and sends it as the project's icon; an icon someone chose in vitrinka stays unless you run vitrinka setup --force-icon.

5.14.2

Every test case keeps its own screenshot. vitrinka qa run used to match screenshots by file name, so a Playwright report written on another machine (a devbox, CI) could put one test-finished-1.png on every card. Paths from another machine are now found again under the report's folder, same-named files from different tests get distinct names, and a screenshot that can't be found is left out with one warning instead of borrowing another test's picture.

5.14.1

Workflows resume from verified progress. Build and review runs share a bounded agent allowance, serialize edits, retain unfinished route and journey checks, and tie reusable reviews to the captured source and screenshot contents. Interrupted fixes resume before stale screenshots trigger a new capture.

5.14.0

A full UI polish pass, chained run by run. In a repo whose vybava.config.ts carries a uiLoop section, the map workflow (scope: "screens") extends the screen manifest, and review-loop runs one stage per run — capture, review, fix, verify — handing back the arguments for the next run. A pass resumes from the files it left after any cutoff. Pass repo (an absolute path) to pin the run to one checkout; a mismatch stops it before anything changes. Needs Výbava v0.25.0 or newer.

One board per area, every pass. A ui-loop pass lays itself out on the area's set board — a section per pass, viewport and theme, plus one "Not captured this pass" card — and never creates a second board.

A pass never calls unjudged screens clean. An empty screen list stops the run, the backlog records which screens were actually reviewed, and the stages hand lists over through vybava ui-loop instead of an agent summarizing them, so large passes (hundreds of screens) run end to end.

vitrinka update migrates a pre-rename Codex plugin. A machine whose Codex marketplace still carries an old name ends up on vitrinka@kit after one update, and vitrinka doctor names the legacy id until then.

5.13.0

Push a big take from a file. vitrinka board artifact push page.html --board <slug> --section "D1 · <title>" --device phone lands one self-contained HTML page (up to 8 MiB) as an artifact card — for takes too large for MCP. On a brainstorm board --section (the decision's chapter) and --device are required; a refusal lists the chapters to pick from.

Brainstorms stay on the brainstorming flow. The brainstorming skill builds a board through the decision map and its chapters — no more raw API takes, which a brainstorm board now refuses with the corrected call. Each option gets its own card that pictures only that take: two options naming one card are refused. The board owns its decisions, so a session no longer mirrors a chapter into a separate question prompt.

5.12.0

Ask a whole project. vitrinka task ask --project <p> "what blocks 4.0.0?" puts an open question to Eve, which searches the project with its own task search and answers in prose with the tasks it found, each with its link and one line on why. Only live tasks of that project come back, and it spends AI credits. task ask <id> "…" still asks about one task.

vitrinka update stops tripping on other marketplaces. Refreshing the Codex plugin now upgrades only the kit marketplace. A failing third-party marketplace no longer reports the vitrinka refresh as failed.

5.11.1

The handoff no longer files a decision you could be asked. The handoff skill's list of steps to file on the task names a decision only when a run nobody attends leaves it; with a human in the session the call is asked and answered there.

Ask for tasks in words. task list --ask "open stories under the restart epic" lets Eve compile the phrase into the filter document, prints what it read, and pages on with that document as --filter; a facet flag beside --ask is refused, and a server that predates it says so instead of answering the unfiltered page. search <ref> --resolve --deep lets Eve break an ambiguous verdict's tie (AI credits).

Decisions are asked while you are there. The handoff and spot skills ask a call the person in the session can answer now and record the answer in the hand-back; a Decide: gate is filed only by a run nobody attends (a Workflow, a headless or scheduled run). A brainstorm decision settled in the terminal closes its board question, and the skills' ?modules= advice names every module to keep (core,pm,qa,me,rare), so opting into rare no longer hides the task and personal tools.

Task search travels light. task search reads compact rows, about 2.5× smaller on the wire, with the same columns; task list --text matches tasks carrying every word while task search ranks any of them. vitrinka help json documents the envelope as it ships (next[].do, diagnostics[].why, exit_code on failure only), and the skills, help and session hints name the current commands and MCP calls.

5.10.0

Find one task in one call. vitrinka search <ref> --resolve reads a title, any id spelling, a URL, a branch or "bugs under <epic>" as one task reference and answers a verdict (exact, confident, ambiguous, none) with at most five candidates, each with its parent, child count and why it matched; a task verb handed a name instead of an id points at that exact call. task search filters by --type, --state, --parent and --epic (any depth), --within <task> searches one task's tree, each row says where it matched (≈ marks a typo correction), and a type, state or project that names nothing is refused with the allowed values instead of an empty list.

Each shot uploads once. Screenshot sets sync file by file: every capture sends only its new shots and the board fills live as they land, an explicit board push drops what the folder no longer holds, a set past 100 files no longer trips the guard, and qa run reuses shots the set already holds; older deployments keep the whole-set upload. The plugin's review and code loops now fix on their last pass, converge only when every gate was green and walk every fixed usertest failure again; the experimental test run marks a PR ready only on a record a reviewer judged.

5.9.0

Task reads are flat, and every task spelling works. task search and task list return flat rows with parentId and url; --json=id,title works on search, list and get; task list --parent <task> and task get --include children read an epic's tree in one call; search stays in this checkout's project unless you pass --all (--limit sizes it). Every task verb reads 42, #42, vt-42, VIT-42, fixit/42 or the task URL, and a spelling it cannot read fails with the fix before any request. --jq never hides a failure: a failed call prints its whole envelope with its exit code.

A failed request names its phase. A DNS lookup that did not answer (with the resolver file behind it), a server that took the connection but never answered, or the network, instead of blanket proxy advice; vitrinka doctor gains a dns row. Also new: board capture safari shoots Mobile Safari on the iOS Simulator through Appium in six states with the measured safe-area insets; setup --experimental installs the opt-in vitrinka-experimental plugin (Claude Code only). setup and doctor keep a ?modules= MCP list, work watch stops with a fix on a board this workspace does not hold, task get marks Eve and agent comments, admin smtp names who may edit the deployment mailer, and the tasks skill finds an epic by name in one call.

5.8.0

Release notes read like a register. Pushed documents take the new release vocabulary — galleries, compare charts, audience-tagged sections and table rows ({cells, audience}), a unit per compare item — and export from one viewer as PDF, HTML, email or Word. vitrinka project release --notes <ref> links a release to its notes document (--notes-clear unlinks it), and the release pool ranks screenshots by visual score so the notes carry the best shots once each. Web captures are 2× device scale by default (capture.hidpi in vitrinka.config.json). Slow uploads fail on an idle stall instead of a fixed deadline (VITRINKA_UPLOAD_IDLE overrides it), rapid captures on a slow link share one background push per capture folder that always ends on the newest shots, and review file without a valid --agent names the accepted runtimes and the corrected call.

5.7.1

Errors say what the server said. When the server answers a 502/503/504 with its own problem (a release sweep that cannot read a repository, for example), the CLI now shows that reason and fix instead of claiming the deployment is not answering; a real gateway outage still reads as one. Composed document cards on boards now size to their content instead of arriving clipped.

5.7.0

Releases span every repository of a project. A new release track sweeps each repository bound to the project, each on its own branch and from its own start, and stores both on the release — later refreshes and the next window after a cut need no flags. PR links name their repository, so two repositories' #123 never mix. Drive it with the new vitrinka project release (--refresh --repo <owner>/<name>:<branch>@<start>, --cut); the release skill documents the fork-point rule for choosing a start on an integration branch, the page's real shape and the X-Vitrinka-Workspace header for raw API calls. Prose links in documents are underlined like table links.

5.6.2

Links are first-class in authored documents. Every section is an anchor (id authored or derived from its label), so /a/<card>#<id> deep-links into a document and {kind:"ref", section} cross-references it in place. Table cells take {v, href, tone} and render inline markdown like prose. meta.sources declares a repository once and alias:path#L3-L9 works as any link target: the push expands it to the canonical GitHub URL and, where the deployment holds a GitHub credential, verifies the path exists at that ref. The artifact skill carries the new rules.

5.6.1

/vitrinka:review files findings and stops. A review pass, local or Eve's, ends with staged annotations on the board and a report grouped by root cause; it no longer fixes code or composes a next pass on its own. The user accepts or dismisses on the board, and /vitrinka:resolve works what was accepted — including re-capturing as a new pass and linking the Eve post-fix audit.

5.6.0

A native work hub without marking your project briefs read. vitrinka me hub --json gathers projects, tasks waiting on you, active runs and linked completion, verification, merge and deployment evidence. History covers up to 30 days, with resumable pages and explicit source coverage.

Live updates over one read-only connection. vitrinka me hub --watch --json streams snapshots when workspace activity changes, without idle polling or claiming an annotation listener. Successes and failures each use one JSON envelope per line, suitable for native clients such as Switcheroo.

Automatic achievements grounded in recorded outcomes. vitrinka me hub --generate --json requests daily-capped Eve proposals and reuses cached definitions. Starter milestones and cached results remain explicit when AI is unavailable; proposals never declare work complete. These commands need the matching work-hub server endpoints and a personal Vitrinka identity.

Capture details survive publishing. Usertest snapshots retain their route, state, device and capture context on QA cards. Capture writes also restore the runtime directory's Git ignore file, keeping local screenshots out of accidental commits.

5.5.1

The 5.5.0 hook ceilings actually arrive. vitrinka setup compared a hook's command but never its timeout, so a row whose command never changed kept the ceiling it was first written with — the Stop gate stayed at 20 s on every upgraded machine while setup reported done and doctor agreed. The timeout is now part of the hook's identity: setup rewrites a stale ceiling in place and counts it as drift. Re-run vitrinka setup once on 5.5.1.

setup repairs the Codex hooks it is told to repair. doctor's hooks·codex row has always named vitrinka setup as its fix, but setup only ever touched Claude's settings.json, so a machine kept the retired hook-context task row in ~/.codex/hooks.json indefinitely. The step now covers every harness present, and the presence probe for the Claude CLI is memoized like its Codex twin — setup asked for it up to three times, each a 3-second subprocess.

5.5.0

Breaking: a hand-back files STEPS on the task, not a pile of child tasks. hand_back / vitrinka task handback lands each next item as a step on the task's own checklist; a child task appears only when the item says task: true with a type, so an agent has to argue for a task and never for a step. New flags: --step "name[::kind][::who-or-date][::when]" and --gate "name[::who][::when]"; --next now means a child TASK. An omitted item starting with Decide: becomes a human gate that blocks Done. A step whose trigger is observable carries when in the todo grammar (pr 12 merged) and the server ticks it with evidence. A pickup leads with the task's open steps, then its children. ⚠️ An older @vitrinka/cli sending a raw next item as {title, type} with no task key now gets a 422 telling it to set task: true — update before handing back.

The session-end auto-archive is gone. vitrinka qa session archive on|off|status and the SessionEnd hook that uploaded a whole redacted transcript whenever a session naming a task ended no longer exist — every such session left a record nobody asked for, and the record buried the hand-back. Archiving a transcript is an explicit hand-off act: vitrinka qa session archive <transcript.jsonl> --task <id> when the work passes to a colleague, with the task labelled eve-distill so they open the digest. vitrinka setup strips the retired hook.

One SessionStart hook instead of three. vitrinka hook-context start prints the run stamp with the pickup, the todo cue and the schedule cue in one process and one envelope; the cues fire only on a real start (Claude Code's source is startup or clear), so a resume or a compaction pays the stamp alone and needs no matcher. Timeouts are short (8 s start, 10 s task-end, 5 s stop, 5 s touch) and the Stop gate reads only the last 4 MiB of a transcript. vitrinka setup replaces the old task, todo and schedule rows in place; the old verbs still answer for machines that have not re-run setup.

NEXT is a work queue, not a menu. The pickup skill works the task's open steps and then every child down the list until only rows a human must do remain — a decision the tree waits on is asked mid-flight, never filed and left; only the context window ends a sitting. Its mirror in the handoff skill: next holds only what the human must do, and work the agent can do is built before the hand-back.

Smaller: the listen skill's ladder is served by the server (docs {topic: "…"}) instead of shipping as a file in the plugin, and the Claude plugin renders into its own kit subtree so an installed plugin cache holds nothing installable.

5.4.0

Breaking: the old <verb>_<kind> tool names are gone. list_tasks, get_task, create_board, get_brief, list_work, get_session and every other name the six generic verbs absorbed in 5.3.0 no longer answer; the call is list · get · create · update · delete · search {kind: "<kind>", …} — the kind is the old name's tail, singular for list and search (list_tasks → list {kind: "task"}, get_brief → get {kind: "brief"}, list_work → list {kind: "work"}). An old name answers a one-line rename hint, nothing else. Per-kind contracts: docs {topic: "kind:<kind>"}. update_cards, get_card_image, get_templates and search keep their names.

The catalogue lost weight. Argument prose moved out of tools/list into docs topics, so a registration pays for the tools it can call, not for their manuals. A new rare module holds the doors a session almost never needs (transfer_project, merge_project, mark_deploy, promote_meeting, rename_set, review_judge*, review_stats, review_job, meeting_notes, save_template, dry_run_rule, edit_journey_node, set_preferences, favorite, unfavorite, my_favorites, retract_questions, board_working, request_review) — never listed by default; opt in on the registration's /mcp URL with ?modules=core,pm,qa,me,rare. usage joins select, jq and budget as a universal argument. vitrinka doctor prints the tool count the server advertises to this registration.

A bare task id is refused where it is ambiguous. On an organisation-wide grant that spans more than one workspace, an id-only tool on the root /mcp door no longer guesses: a bare {id: 42} answers spell it <workspace>/<id>. A project argument that pins the workspace, the /w/<slug>/mcp door and the <workspace>/<id> spelling all work as before.

The contract date moves to 2026-09-15 — served by /api/v1/version, stamped in every skill and in the kit export. Every skill now spells the generic verbs, and the ones that lean on a rare tool say so.

5.3.0

Skills went on a token diet; the MCP refuses to dump. Every MCP tool takes select, jq and budget; a reply above the budget (8k tokens by default, 30k ceiling) comes back as an over_budget envelope naming the tool's narrowing arguments instead of the dump. The 52 <verb>_<kind> tools collapsed behind six generic verbs (list · get · create · update · delete · search {kind}; the old names still answer, flagged deprecated), tools/list is scoped to the project's modules, and PM reads ride compact rows. The plugin ships 15 skills instead of 21: the five personal skills are ONE manual-only me skill, answers and annotations dissolved into the MCP instructions, and every SKILL.md is a trigger plus contracts.

Procedure moved to the server. The step choreography the publish, brainstorming and sessions skills used to carry is served as guide pages: vitrinka docs guide:publish-capture, guide:brainstorm-flow, guide:sessions-pipeline (MCP docs {topic: "guide:<name>"}, index docs {family: "guide"}). A wording fix is a deploy, never a plugin update.

--json envelopes of task pickup, task start, task spot, task handback, qa run and qa usertest start · case · verdict now carry next[] — the command to run next, executable as printed. vitrinka doctor reports MCP replies that ran over budget.

MCP: set_board_meta {archived: true} retires a board (false restores it); a task id spelled as a numeric string ("289") is accepted like the number; the spot and hand_back receipts name the parent task as a line instead of embedding its whole row.

vitrinka project merge <from> --into <to> merges a project into another project of the same workspace: everything <from> owns moves — tasks with their ledger, comments and attachments, boards, sets, sessions, reports, releases, press editions and project memory — nothing is dropped (a clashing custom field is renamed <key>_from_<from>, a clashing set <key>-from-<from>, values kept), and the old name stays as an alias so every old link keeps working. Dry run by default; --apply writes, --adopt --title "<epic>" parents the moved root tasks under one new epic. project merge-plan --into <to> lists the strays a merge would sweep. project fold / fold-plan keep working as hidden aliases; --adopt "<title>" became --adopt --title "<title>".

vitrinka task update <id> --project <slug> moves one task with its whole subtree into another project; states, labels, fields, sprint and milestone map by key and missing keys are created in the target.

5.2.0

One sign-in ever on Claude Code. Claude Code keeps a separate OAuth token per MCP entry, so the project-scope .mcp.json entry cost a sign-in in every repo. vitrinka setup now registers the root /mcp door at user scope only and removes a leftover project entry (commit the change); vitrinka doctor names one; the SessionStart hook tells the session which workspace the repo is bound to and how to address another (<workspace>/<project>). The server resolves a named project to the workspace that knows it — the grant's home first, then the single other workspace of the organisation that has it. Cursor, OpenCode, VS Code and Gemini CLI keep their committed files.

--local no longer registers anything for Claude Code (its registry is global, like Codex's).

5.1.1

vitrinka setup actually performs the 5.1.0 layout migration. In 5.1.0 it reported success and changed nothing on any machine whose plugin and MCP were already registered — which is every machine with a repo old enough to need migrating. Run vitrinka setup once in each bound repo and commit what it prints: the fold into vitrinka.config.json, the untracked manifests and the pruned .gitignore. An ignore line for a SIBLING path like .vitrinka-verify/ is left alone; only the runtime dir's own lines go.

5.1.0

One MCP sign-in per origin, and vitrinka mcp is gone. The OAuth grant now covers every workspace of your organisation: consent picks a home workspace, and every registration names the same /mcp endpoint, so switching repos never re-authenticates and parallel sessions in different workspaces no longer knock each other out. A repo's workspace rides an X-Vitrinka-Workspace header in its committed entry (.mcp.json spells the origin ${VITRINKA_URL:-https://app.vitrinka.ai} so self-hosted clones follow one exported variable); to act in another workspace of the organisation, name the project <workspace>/<project> — in MCP calls and in --project. Codex registers the same door (codex mcp login vitrinka).

--mcp-stdio no longer exists.

One committed vitrinka file per repo. The workspace binding, project slug, runners and run stacks now live at the top of the root vitrinka.config.json, beside the index policy. .vitrinka/ is a machine-local runtime directory that ignores itself, so your .gitignore needs no vitrinka lines at all — and journeys.json / sessions.json are no longer committed (the task engine is their record). The old .vitrinka/project.json is still read for this release; doctor names it until it is gone.

Run vitrinka setup once after updating. It folds .vitrinka/project.json into the root file, untracks the old manifests, removes every .vitrinka line from .gitignore and .git/info/exclude, and rewrites stdio-forwarder and /w/<workspace>/mcp entries onto the one /mcp door. vitrinka doctor names a leftover forwarder as a dead door.

5.0.2

vitrinka setup now installs the todo hooks it always claimed to. doctor names setup as the repair when the SessionStart todo rows are missing their startup|clear matcher or the PreToolUse touch row is absent, but setup only ever wrote the task-run hooks — it printed "Claude hooks done" and changed nothing. Run vitrinka setup once after updating and vitrinka doctor goes clean.

Until a machine does that, its session starts still inject the whole open todo list on every start, resume and compaction, instead of the handful of todos whose condition actually fired.

5.0.1

vitrinka update and vitrinka doctor are back at the top level, the way brew doctor, flutter doctor and <tool> update read; setup update and setup doctor are gone (unknown command, exit 2 — no aliases). setup keeps the bare first run plus uninstall, extension and skills.

vitrinka task list --json id,title (a space before the field list) used to fail as "unknown command id,title". It now says what it means: the field list rides the flag with = — --json=id,title — and the fix line is the corrected command.

5.0.0

One vocabulary. The CLI is twenty entries: nouns that group verbs, three leaf verbs (status, help, completion), nothing else. Old names are gone — they print "unknown command" and exit 2. There are no aliases.

Old                                New
install · project setup            setup            (the whole first run)
doctor · extension doctor          doctor
update · uninstall                 update · setup uninstall
extension … · skills …             setup extension … · setup skills …
set init|push|capture|rename|meta  board init|push|capture|rename|meta
artifact … · diagram …             board artifact … · board diagram …
open · edit                        board open · board edit
run · usertest · pair · session    qa run · qa usertest · qa pair · qa session
todo · diary · brief · time        me todo · me diary · me brief · me time
schedule <title> --in …            me schedule add <title> --in …
schedule list|ripe|move|skip|end   me schedule …
listen                             work listen
resolve <url> · query <sql>        search resolve <url> · search query <sql>
ai <words>                         docs ask <words>
tidy                               project tidy
ui                                 (bare `vitrinka` on a terminal)
login · logout · token             auth login · auth logout · auth token
push · snap · remote-init          board push · board capture · board init
name · meta · upload               board rename · board meta · board upload
board-from-set · journey-from-set  board create · board create --journey
artifact-init · artifact-from-set  board artifact init · board artifact create
watch · setup-project · index      work watch · setup · project index
import · schema                    board diagram import · board diagram schema
operator · use · smtp              config operator · config bind · admin smtp

First run

vitrinka setup is the one door: sign in, agent plugin + MCP, detect this repository, review the proposed index (all tracked supported files minus lockfiles, generated, vendored and .github), apply, next action. Done steps are skipped on rerun; Back keeps your answers; the key bar survives 80 columns. --advanced opens the directory picker.
vitrinka doctor checks the installation and this repository; --all adds every registered project. --fix shows a target · before · after plan and applies it after review.

Agents

--no-input never prompts (also VITRINKA_NO_INPUT=1, CI=true); --yes accepts the proposed plan; a step that needs a person exits 5 needs_human with the plan in the envelope and the --yes rerun in next[].
--json=id,title prunes data to those fields; --jq '<expr>' filters the envelope.
Exit codes: 0 · 1 · 2 misuse · 3 nothing found · 4 sign in · 5 needs a human · 130 cancelled.
vitrinka help exit-codes|json|no-input|environment|agents explain each contract; every command's help carries the same vocabulary.

4.2.0

update can no longer skip a plugin silently, doctor catches a plugin that fell behind the CLI, board reviews become audited judgments, and work time is measured instead of typed.

Fixed

vitrinka update refreshes the Codex plugin again. When the codex plugin list probe failed, the runtime printed as (no plugin) and the refresh was skipped without a word — Codex sat two releases behind while update reported success. A failed probe now prints codex (probe failed), warns with the real failure and lands under "steps need a hand" with the re-run; a probe whose process exited is taken as its answer even when a grandchild held the pipe past the deadline.
vitrinka doctor reports plugin version drift: an installed plugin whose version disagrees with the CLI shows stale — 3.11.0 installed, CLI is 4.2.0 — repair: vitrinka update instead of a green installed; a failed probe is a red probe failed row, never not installed.