Machine and repo setup

Credentials

One credential per deployment, obtained through a browser approval rather than a pasted secret.

vitrinka auth login
vitrinka auth status    # deployments this machine holds credentials for
vitrinka auth token     # print the stored token, for shell substitution
vitrinka auth logout

Bind the repo

Binds this repository to a workspace on a deployment, so commands run from it know where they belong.

vitrinka config bind acme --project myapp

The operator persona

The default write-attribution name for board writes from this machine. Type your name once and every future write is credited.

vitrinka config operator            # show
vitrinka config operator "Olivia"   # set

Repo wiring

setup onboards a repository: it records the checkout in this machine's ledger, stamps the project and origin into the committed vitrinka.config.json, proposes the @ index policy for review, and wires the agent hooks. It also sends the repository's icon — the first of the well-known files at its root (public/apple-touch-icon.png … favicon.ico, or Expo's expo.icon) — as the project's icon; an icon someone chose in vitrinka stays unless --force-icon. project index refreshes the path autocomplete index later; project index configure edits the policy, project index status shows it.

vitrinka setup
vitrinka project index

setup detects where this repository belongs — the project this machine already filed it under, else the workspace project that declares its origin, else a new project named after the repository — and shows it on the review; --project overrides. A project that spans several repositories — an API, an app, an infra repo — is one project with several repositories, never several projects. link files a repository under an existing project (without an argument you pick from the workspace's projects on a terminal), unlink takes it out again:

vitrinka project link acme        # append this repo's origin to project acme
vitrinka project link             # pick from the workspace's projects
vitrinka project unlink

Every set-up checkout is recorded in this machine's ledger (~/.config/vitrinka/config.json). vitrinka doctor reads the ledger against the disk and the workspace and names what drifted — a path that is gone, an origin the project does not declare, a stale setup. vitrinka doctor --fix prints the whole plan first, applies the machine and server changes after one confirm, and asks per repository how its committed files should land: a worktree branch with a PR (for a protected main), a commit on the current branch, or the files only.

The repo's files

A bound repository carries ONE committed file, vitrinka.config.json at its root: project, origins (origin → workspace), run (the stacks pairing and the sessions pipeline boot), runners (where test runners write results — vitrinka setup --runners), capture (hidpi: web captures at 2×, on unless set — vitrinka config hidpi) and the index policy. Commit it; it holds no secret. Everything machine-local — captures, artifacts, logs, pair and usertest state — lives in .vitrinka/, which ignores itself, so never add a vitrinka line to .gitignore. An older .vitrinka/project.json is folded into the root file by the next write; vitrinka doctor names it.

Hooks and commit trailers

The work is the record, so setup wires the two places it already happens. In the agent harness, the SessionStart, SessionEnd, Stop and PreToolUse hooks bind a session to its task, cue the todos that fired, gate a hand-back and announce a path-conditioned todo when its file is edited — session hooks. In git, a per-repository prepare-commit-msg hook runs vitrinka commit-msg: on a vt-<id> branch (or worktree) it appends a Vitrinka-Task: vt-<id> trailer, which is how the GitHub App attaches the commit and the pull request to the task. It never touches merge, squash or fixup messages and always exits 0 — a commit never fails because of vitrinka. A foreign shell hook is chained, never replaced; setup uninstall strips exactly its own block.

vitrinka project commits                 # show the convention for this project
vitrinka project commits --subject on    # also prefix subjects with the task id
vitrinka workspace commit-prefix colon   # the prefix style, workspace-wide

The trailer is always written. The subject prefix is opt-in per project, in the workspace's style: bracket ([vt-401], the default), bare (vt-401) or colon (vt-401:); setting the style takes a workspace admin.

Tidy the repo

project tidy plans moves of legacy capture roots and loose screenshot litter into .vitrinka/. It only plans until you pass --yes.

vitrinka project tidy          # plan
vitrinka project tidy --yes    # apply