vouchdev · claytonlin1110 · Jun 23, 2026 · Jun 23, 2026
diff --git a/.github/workflows/desktop.yml b/.github/workflows/desktop.yml
@@ -0,0 +1,39 @@
+name: desktop
+
+on:
+  push:
+    paths:
+      - "desktop/app/**"
+      - "src/vouch/desktop/**"
+      - "tests/test_desktop*.py"
+  pull_request:
+    paths:
+      - "desktop/app/**"
+      - "src/vouch/desktop/**"
+      - "tests/test_desktop*.py"
+
+jobs:
+  python-desktop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[dev,web]'
+      - run: python -m ruff check src/vouch/desktop tests/test_desktop.py tests/test_desktop_ports.py tests/test_desktop_sidecar.py
+      - run: python -m mypy src/vouch/desktop
+      - run: python -m pytest tests/test_desktop.py tests/test_desktop_ports.py tests/test_desktop_sidecar.py -q
+
+  desktop-typescript:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: desktop/app
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm ci
+      - run: npm run typecheck
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -50,6 +50,13 @@ All notable changes to vouch are documented here. Format follows
   as reviewer; a PR opens only when the repo's own test gate is green and the
   reviewer signs off. A sibling tool — it never writes to the KB or the review
   gate. Paired with the `auto-pr` skill.
+- **desktop multi-KB picker** ([#207](https://github.com/vouchdev/vouch/issues/207)):
+  Tauri shell under `desktop/app/` with **File → Open KB…**, **Recent KBs**
+  (last five, persisted in `~/.config/vouch-desktop/state.json`), and **New KB…**
+  (`vouch init` then open). Switching KBs restarts the `review-ui` sidecar;
+  window title and masthead show the active project label. Shared Python helpers
+  in `src/vouch/desktop/` plus `vouch desktop *` CLI commands; `vouch init --json`
+  for structured init output; `/healthz` and templates expose `kb_label`.
 - typed page kinds (#234): a KB can declare extra page kinds in
   `.vouch/config.yaml` under `page_kinds`, each with `required_fields`, a
   JSON-Schema-subset `frontmatter_schema`, `required_citations`, and one level

diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: help install dev test test-cov lint format type check build clean examples-screenshots
+.PHONY: help install dev test test-cov lint format type check build clean examples-screenshots desktop-typecheck
 
 PY ?= python
 PIP ?= $(PY) -m pip
@@ -16,6 +16,7 @@ help:
 	@echo "  make build         build sdist + wheel"
 	@echo "  make clean         remove caches, build artifacts, *.egg-info"
 	@echo "  make examples-screenshots  re-render docs/img/examples/*.svg"
+	@echo "  make desktop-typecheck  npm typecheck in desktop/app (Tauri shell)"
 
 install:
 	$(PIP) install -e '.[dev]'
@@ -51,3 +52,6 @@ clean:
 	       .pytest_cache .ruff_cache .mypy_cache \
 	       coverage.xml .coverage htmlcov
 	find . -type d -name __pycache__ -prune -exec rm -rf {} +
+
+desktop-typecheck:
+	cd desktop/app && npm ci && npm run typecheck
diff --git a/desktop/README.md b/desktop/README.md
@@ -139,6 +139,33 @@ v0.1.0 covers the entire `kb.*` surface plus dual-solve. The CLI-only
 orchestration commands (`auto-pr`, `migrate`, `schema`, `sync-*`) are not yet
 surfaced — see the [CHANGELOG](./CHANGELOG.md).
 
+## Tauri review-ui shell (`app/`)
+
+A lighter [Tauri](https://tauri.app/) window around `vouch review-ui` with the
+multi-KB picker from [#207](https://github.com/vouchdev/vouch/issues/207). Use
+this when you only need the review console (queue / approve / reject) with
+**File → Open KB…**, **Recent KBs**, and **New KB…** — not the full Electron
+`kb.*` surface above.
+
+| Path | Purpose |
+|------|---------|
+| [`app/`](./app/) | Tauri + TypeScript shell (menus, sidecar lifecycle, welcome/error UI) |
+| [`app/README.md`](./app/README.md) | Build and dev instructions |
+| [`../src/vouch/desktop/`](../src/vouch/desktop/) | Shared Python helpers (state, KB validation, sidecar spawn) |
+| [`flatpak/`](./flatpak/) | Linux Flatpak packaging (review-ui only; WIP) |
+
+```bash
+pip install -e '.[web]'
+cd desktop/app
+npm install
+python scripts/generate-icons.py
+npm run tauri:dev
+```
+
+Recent KBs persist in `~/.config/vouch-desktop/state.json` (XDG;
+`%APPDATA%\vouch-desktop` on Windows). From the monorepo root:
+`make desktop-typecheck`.
+
 ## License
 
 MIT.
diff --git a/desktop/app/.gitignore b/desktop/app/.gitignore
@@ -0,0 +1,4 @@
+node_modules/
+dist/
+src-tauri/target/
+.DS_Store
diff --git a/desktop/app/README.md b/desktop/app/README.md
@@ -0,0 +1,94 @@
+# vouch desktop
+
+Native shell for the [vouch review console](https://github.com/vouchdev/vouch) with a **multi-KB picker** ([#207](https://github.com/vouchdev/vouch/issues/207)).
+
+The desktop app wraps the existing Python `vouch review-ui` server in a Tauri window. One window hosts one knowledge base at a time; switching KBs restarts the sidecar against the new project root.
+
+## Features
+
+| Menu item | Behaviour |
+|-----------|-----------|
+| **File → Open KB…** | Folder picker; folder must contain `.vouch/` or you get an inline error with **create KB here** |
+| **File → Recent KBs** | Last five opened KBs, persisted in `~/.config/vouch-desktop/state.json` |
+| **File → New KB…** | Pick a folder, run `vouch init`, open the new KB |
+
+The window title updates to `vouch · <project-name>`. The review UI masthead also shows the active KB label.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 20+
+- [Rust](https://rustup.rs/) stable (for Tauri)
+- vouch installed with the `[web]` extra: `pip install -e '.[web]'`
+
+Ensure `vouch` is on your `PATH` (or configure the Tauri sidecar — see `src-tauri/sidecars/vouch.json`).
+
+## Development
+
+```bash
+cd desktop/app
+npm install
+npm run tauri:dev
+```
+
+`tauri dev` starts the Vite shell on port 1420 for welcome/error screens, then navigates the webview to `http://127.0.0.1:7780/` once a KB is selected.
+
+## Build
+
+```bash
+cd desktop/app
+npm run tauri:build
+```
+
+Artifacts land under `src-tauri/target/release/bundle/`.
+
+## State file
+
+```json
+{
+  "version": 1,
+  "last_kb": "/abs/path/to/project",
+  "recent_kbs": [
+    { "path": "/abs/path/a", "label": "a", "opened_at": "2026-06-22T12:00:00+00:00" }
+  ]
+}
+```
+
+Path follows [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) conventions (`%APPDATA%/vouch-desktop` on Windows).
+
+## Python CLI helpers
+
+The shell can invoke these for scripting and tests:
+
+```bash
+vouch desktop config-dir
+vouch desktop state-show
+vouch desktop state-touch /path/to/project --label my-app
+vouch desktop kb-check /path/to/project
+vouch desktop kb-init /path/to/new-project
+vouch init --path /path --json
+```
+
+## Architecture
+
+```
+┌─────────────────────┐
+│  Tauri window       │
+│  File menu / title  │
+└─────────┬───────────┘
+          │ spawn / kill
+          ▼
+┌─────────────────────┐
+│  vouch review-ui    │  ← same review gate as CLI/MCP
+│  127.0.0.1:7780     │
+└─────────┬───────────┘
+          │
+          ▼
+     <project>/.vouch/
+```
+
+Shared logic also lives in `src/vouch/desktop/` (state persistence, KB validation, sidecar spawn helpers) and is covered by `tests/test_desktop.py`.
+
+## Out of scope (v1)
+
+- Side-by-side multi-KB views in one window
+- Cross-KB search / federation
diff --git a/desktop/app/index.html b/desktop/app/index.html
@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>vouch desktop</title>
+    <link rel="stylesheet" href="/src/styles/shell.css" />
+    <link rel="stylesheet" href="/src/styles/error-panel.css" />
+    <link rel="stylesheet" href="/src/styles/loading.css" />
+  </head>
+  <body>
+    <div id="app" class="shell" data-view="loading">
+      <section id="loading" class="loading-panel" aria-live="polite">
+        <div class="loading-spinner" aria-hidden="true"></div>
+        <p id="loading-message">starting review console…</p>
+      </section>
+      <section id="error" class="error-panel hidden" role="alert">
+        <h1>could not open knowledge base</h1>
+        <p id="error-message"></p>
+        <p id="error-path" class="error-path"></p>
+        <div class="error-actions">
+          <button id="btn-create-kb" type="button">create KB here</button>
+          <button id="btn-pick-folder" type="button" class="secondary">choose another folder…</button>
+        </div>
+      </section>
+      <section id="welcome" class="welcome-panel hidden">
+        <h1>vouch review</h1>
+        <p>open a project knowledge base to review pending proposals.</p>
+        <div class="welcome-actions">
+          <button id="btn-open-kb" type="button">open KB…</button>
+          <button id="btn-new-kb" type="button" class="secondary">new KB…</button>
+        </div>
+        <ul id="recent-list" class="recent-list"></ul>
+      </section>
+    </div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>