vouchdev · claytonlin1110 · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026
diff --git a/.github/workflows/flatpak.yml b/.github/workflows/flatpak.yml
@@ -0,0 +1,72 @@
+name: flatpak
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'desktop/flatpak/**'
+      - 'tests/test_flatpak.py'
+      - '.github/workflows/flatpak.yml'
+  pull_request:
+    paths:
+      - 'desktop/flatpak/**'
+      - 'tests/test_flatpak.py'
+      - '.github/workflows/flatpak.yml'
+
+jobs:
+  validate:
+    name: validate packaging
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: generate icons
+        run: python desktop/flatpak/scripts/generate-icons.py
+
+      - name: validate manifest
+        run: python desktop/flatpak/scripts/validate-manifest.py --strict
+
+      - name: pytest flatpak contract
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[dev]'
+          python -m pytest tests/test_flatpak.py -q
+
+  build:
+    name: flatpak-builder smoke
+    runs-on: ubuntu-latest
+    needs: validate
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: install flatpak
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y flatpak flatpak-builder
+
+      - name: add flathub
+        run: sudo flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
+
+      - name: install runtime 23.08
+        run: |
+          sudo flatpak install -y flathub \
+            org.freedesktop.Platform//23.08 \
+            org.freedesktop.Sdk//23.08
+
+      - name: generate icons
+        run: python desktop/flatpak/scripts/generate-icons.py
+
+      - name: build
+        run: |
+          cd desktop/flatpak
+          flatpak-builder --repo=repo --force-clean build-dir com.vouchdev.vouch.yaml
+
+      - name: upload bundle artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: flatpak-repo
+          path: desktop/flatpak/repo/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -50,6 +50,11 @@ 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.
+- flatpak desktop package (#211): `desktop/flatpak/com.vouchdev.vouch.yaml`
+  manifest on `org.freedesktop.Platform//23.08` with `--filesystem=home` and
+  `--share=network`, shipping `vouch review-ui` via a `vouch-review-ui` launcher.
+  Includes AppStream metainfo, hicolor icons, Flathub submission template,
+  validators (`tests/test_flatpak.py`), and a `flatpak` CI workflow.
 - 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
@@ -14,6 +14,7 @@ help:
 	@echo "  make type          mypy"
 	@echo "  make check         lint + type + test"
 	@echo "  make build         build sdist + wheel"
+	@echo "  make flatpak       validate flatpak packaging (icons + manifest)"
 	@echo "  make clean         remove caches, build artifacts, *.egg-info"
 	@echo "  make examples-screenshots  re-render docs/img/examples/*.svg"
 
@@ -46,6 +47,11 @@ build:
 	$(PY) -m pip install --upgrade build
 	$(PY) -m build
 
+flatpak:
+	$(PY) desktop/flatpak/scripts/generate-icons.py
+	$(PY) desktop/flatpak/scripts/validate-manifest.py --strict
+	$(PY) -m pytest tests/test_flatpak.py -q
+
 clean:
 	rm -rf build dist *.egg-info src/*.egg-info \
 	       .pytest_cache .ruff_cache .mypy_cache \

diff --git a/desktop/README.md b/desktop/README.md
@@ -133,6 +133,18 @@ To ship a zero-Python install, freeze vouch with PyInstaller into
 See [`docs/architecture.md`](./docs/architecture.md) for the full design,
 including the method-by-method coverage table.
 
+## Linux packaging
+
+Sandboxed Linux installs for the **review console** live under [`flatpak/`](flatpak/):
+
+| Path | Format | Status |
+|---|---|---|
+| [`flatpak/`](flatpak/) | Flatpak (`com.vouchdev.vouch`) | #211 — `org.freedesktop.Platform//23.08` |
+
+Snap packaging is tracked separately. Each format keeps its own manifest language
+and runtime base. See [`docs/desktop-flatpak.md`](../docs/desktop-flatpak.md) and
+[`flatpak/README.md`](flatpak/README.md) for build and Flathub submission notes.
+
 ## Status
 
 v0.1.0 covers the entire `kb.*` surface plus dual-solve. The CLI-only

diff --git a/desktop/flatpak/Makefile b/desktop/flatpak/Makefile
@@ -0,0 +1,39 @@
+.PHONY: help icons validate requirements build install run clean
+
+ROOT := $(abspath $(dir $(lastword $(MAKEFILE_LIST))))
+PY ?= python3
+MANIFEST := $(ROOT)/com.vouchdev.vouch.yaml
+BUILD_DIR := $(ROOT)/build-dir
+REPO_DIR := $(ROOT)/repo
+
+help:
+	@echo "vouch flatpak targets (#211)"
+	@echo ""
+	@echo "  make icons         regenerate hicolor PNGs from SVG"
+	@echo "  make validate      run packaging validators (strict)"
+	@echo "  make requirements  sync requirements-flatpak.txt from pyproject.toml"
+	@echo "  make build         flatpak-builder (no install)"
+	@echo "  make install       build + --user --install"
+	@echo "  make run           flatpak run com.vouchdev.vouch"
+	@echo "  make clean         remove build-dir/ and repo/"
+
+icons:
+	$(PY) $(ROOT)/scripts/generate-icons.py
+
+validate: icons
+	$(PY) $(ROOT)/scripts/validate-manifest.py --strict
+
+requirements:
+	$(PY) $(ROOT)/scripts/generate-requirements.py
+
+build: validate
+	flatpak-builder --force-clean --repo=$(REPO_DIR) $(BUILD_DIR) $(MANIFEST)
+
+install: validate
+	flatpak-builder --user --install --force-clean --repo=$(REPO_DIR) $(BUILD_DIR) $(MANIFEST)
+
+run:
+	flatpak run com.vouchdev.vouch
+
+clean:
+	rm -rf $(BUILD_DIR) $(REPO_DIR)
diff --git a/desktop/flatpak/README.md b/desktop/flatpak/README.md
@@ -0,0 +1,72 @@
+# vouch Flatpak (#211)
+
+Sandboxed Linux install for the **vouch review console** (`vouch review-ui`).
+Targets Fedora 40+, Arch, and any desktop with Flathub.
+
+## Quick start
+
+```bash
+# one-time runtime (org.freedesktop.Platform//23.08 + Sdk; python3 is in the Sdk)
+./scripts/install-runtime.sh
+
+# build + install for the current user
+make install
+
+# launch from the app menu or:
+flatpak run com.vouchdev.vouch
+```
+
+## Layout
+
+| Path | Purpose |
+|---|---|
+| `com.vouchdev.vouch.yaml` | flatpak-builder manifest (local dev build) |
+| `com.vouchdev.vouch.desktop` | Freedesktop launcher |
+| `com.vouchdev.vouch.metainfo.xml` | AppStream metadata for Flathub |
+| `vouch-review-ui.sh` | `/app/bin` entrypoint |
+| `share/icons/hicolor/` | App icons (16–512 + scalable SVG) |
+| `flathub/` | Flathub submission JSON + checklist |
+| `lib/validate.py` | Packaging validators (pytest + CLI) |
+| `scripts/` | build, icon generation, screenshot capture |
+
+## Permissions (v1)
+
+| finish-arg | rationale |
+|---|---|
+| `--share=network` | uvicorn binds localhost; browser loads the UI |
+| `--filesystem=home` | read/write `.vouch/` KB trees under `$HOME` |
+| `--talk-name=org.freedesktop.portal.Desktop` | open the default browser |
+
+Per-KB filesystem scoping is **out of scope** for v1 — see [issue #211](https://github.com/vouchdev/vouch/issues/211).
+
+## Develop
+
+```bash
+make icons       # regenerate PNGs from SVG
+make validate    # strict manifest/desktop/metainfo checks
+make requirements  # sync requirements-flatpak.txt from pyproject.toml
+make build       # flatpak-builder only (no install)
+```
+
+From repo root:
+
+```bash
+python -m pytest tests/test_flatpak.py -q
+```
+
+## Flathub
+
+After merge, follow `flathub/SUBMISSION.md` to open a Flathub application PR.
+The store listing reuses metainfo screenshots under `screenshots/` — capture with
+`scripts/capture-screenshots.sh` once review-ui is installed.
+
+Acceptance:
+
+- `flatpak install flathub com.vouchdev.vouch` on Fedora 40+ and Arch
+- listing shows icon, description, and screenshots
+
+## Runtime
+
+- **Base:** `org.freedesktop.Platform//23.08`
+- **Python:** bundled in `org.freedesktop.Sdk` (no separate Extension.python3 on Flathub)
+- **Package:** `pip install '.[web]'` — no bundled CPython upgrade automation
diff --git a/desktop/flatpak/com.vouchdev.vouch.desktop b/desktop/flatpak/com.vouchdev.vouch.desktop
@@ -0,0 +1,22 @@
+[Desktop Entry]
+Type=Application
+Name=Vouch
+GenericName=Review Console
+Comment=Review-gated knowledge base for LLM agents
+Exec=vouch-review-ui
+Icon=com.vouchdev.vouch
+Terminal=false
+Categories=Development;Office;TextEditor;
+Keywords=vouch;knowledge;review;agent;mcp;kb;
+StartupNotify=true
+StartupWMClass=vouch-review-ui
+MimeType=
+X-Flatpak-RenamedFrom=vouch.desktop;
+
+[Desktop Action OpenQueue]
+Name=Open review queue
+Exec=vouch-review-ui
+
+[Desktop Action OpenHeadless]
+Name=Start without opening browser
+Exec=vouch-review-ui --no-open-browser
diff --git a/desktop/flatpak/com.vouchdev.vouch.metainfo.xml b/desktop/flatpak/com.vouchdev.vouch.metainfo.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<component type="desktop-application">
+  <id>com.vouchdev.vouch</id>
+  <metadata_license>CC0-1.0</metadata_license>
+  <project_license>MIT</project_license>
+  <name>Vouch</name>
+  <summary>Review-gated knowledge base for LLM agents</summary>
+  <description>
+    <p>
+      Vouch is a git-native knowledge base where every write goes through a human
+      review gate. Agents propose claims and pages; you approve them with the
+      review console or the CLI. Approved artifacts are plain YAML and markdown
+      on disk — diffable in PRs, auditable, and portable.
+    </p>
+    <p>
+      This Flatpak ships the browser-based review console
+      (<code>vouch review-ui</code>): a local FastAPI server that lists pending
+      proposals, shows diffs, and records approve/reject decisions in the audit
+      log. Pair it with the <code>vouch</code> CLI or an MCP host adapter for
+      the full propose → review → commit loop.
+    </p>
+    <p>
+      Filesystem access is limited to your home directory so vouch can read and
+      write <code>.vouch/</code> trees under your projects and
+      <code>~/.vouch/</code>.
+    </p>
+  </description>
+  <launchable type="desktop-id">com.vouchdev.vouch.desktop</launchable>
+  <developer id="com.vouchdev">
+    <name>vouchdev</name>
+  </developer>
+  <url type="homepage">https://github.com/vouchdev/vouch</url>
+  <url type="bugtracker">https://github.com/vouchdev/vouch/issues</url>
+  <url type="vcs-browser">https://github.com/vouchdev/vouch</url>
+  <url type="help">https://github.com/vouchdev/vouch/blob/main/docs/getting-started.md</url>
+  <content_rating type="oars-1.1"/>
+  <categories>
+    <category>Development</category>
+    <category>Office</category>
+  </categories>
+  <keywords>
+    <keyword>vouch</keyword>
+    <keyword>knowledge base</keyword>
+    <keyword>review</keyword>
+    <keyword>llm</keyword>
+    <keyword>mcp</keyword>
+    <keyword>agents</keyword>
+  </keywords>
+  <branding>
+    <color type="primary" scheme_preference="light">#4f5d9e</color>
+    <color type="primary" scheme_preference="dark">#1e2a44</color>
+  </branding>
+  <screenshots>
+    <screenshot type="default">
+      <caption>Review queue — pending proposals awaiting human approval</caption>
+      <image>https://raw.githubusercontent.com/vouchdev/vouch/main/desktop/flatpak/screenshots/queue.png</image>
+    </screenshot>
+    <screenshot>
+      <caption>Proposal detail — diff and metadata before approve/reject</caption>
+      <image>https://raw.githubusercontent.com/vouchdev/vouch/main/desktop/flatpak/screenshots/detail.png</image>
+    </screenshot>
+  </screenshots>
+  <releases>
+    <release version="0.0.1" date="2026-06-22">
+      <description>
+        <p>Initial Flatpak packaging for the vouch review console (#211).</p>
+      </description>
+    </release>
+  </releases>
+</component>
diff --git a/desktop/flatpak/com.vouchdev.vouch.yaml b/desktop/flatpak/com.vouchdev.vouch.yaml
@@ -0,0 +1,57 @@
+# flatpak-builder manifest for vouch review-ui (#211).
+# Build from this directory:
+#   flatpak-builder --user --install --force-clean build-dir com.vouchdev.vouch.yaml
+#
+# Runtime: org.freedesktop.Platform//23.08 (Fedora 40+, Arch, any Flathub desktop).
+# v1 simplification: --filesystem=home covers ~/.vouch/ and project KB trees under $HOME.
+
+id: com.vouchdev.vouch
+runtime: org.freedesktop.Platform
+runtime-version: '23.08'
+sdk: org.freedesktop.Sdk
+
+command: vouch-review-ui
+
+finish-args:
+  # uvicorn binds localhost; browser loads the review console.
+  - --share=network
+  # read/write KB dirs under the user's home (incl. ~/.vouch/).
+  - --filesystem=home
+  # xdg-open / default browser via the desktop portal.
+  - --talk-name=org.freedesktop.portal.Desktop
+  - --socket=wayland
+  - --socket=fallback-x11
+
+modules:
+  # --- python application (vouch-kb + [web] extra) ----------------------------
+  - name: vouch
+    buildsystem: simple
+    build-options:
+      env:
+        PIP_DISABLE_PIP_VERSION_CHECK: '1'
+        PYTHONNOUSERSITE: '1'
+      # pip resolves hatchling + runtime deps from PyPI during the build.
+      build-args:
+        - --share=network
+    build-commands:
+      # default build isolation pulls hatchling (pyproject build-system) automatically.
+      - pip3 install --prefix=${FLATPAK_DEST} '.[web]'
+    sources:
+      - type: dir
+        path: ../..
+
+  # --- launcher, desktop entry, metainfo, icons -------------------------------
+  - name: vouch-desktop
+    buildsystem: simple
+    build-commands:
+      - install -Dm755 vouch-review-ui.sh ${FLATPAK_DEST}/bin/vouch-review-ui
+      - install -Dm644 com.vouchdev.vouch.desktop ${FLATPAK_DEST}/share/applications/com.vouchdev.vouch.desktop
+      - install -Dm644 com.vouchdev.vouch.metainfo.xml ${FLATPAK_DEST}/share/metainfo/com.vouchdev.vouch.metainfo.xml
+      - |
+        for size in 16 32 48 64 128 256 512; do
+          install -Dm644 share/icons/hicolor/${size}x${size}/apps/com.vouchdev.vouch.png \
+            ${FLATPAK_DEST}/share/icons/hicolor/${size}x${size}/apps/com.vouchdev.vouch.png
+        done
+    sources:
+      - type: dir
+        path: .
diff --git a/desktop/flatpak/flathub/.gitkeep b/desktop/flatpak/flathub/.gitkeep
@@ -0,0 +1,5 @@
+# Flathub submission helpers (#211).
+#
+# Flathub hosts manifests in a separate git repository per app. After this
+# upstream manifest lands, open a PR against https://github.com/flathub/flathub
+# with the generated com.vouchdev.vouch.json pointing at a release tag.