Debian support: verified build/packaging path + friend install guide

- setup-standalone.sh: falls back to system python3 -m venv + pip when
  uv isn't installed (Debian/Ubuntu path; verified on clean bookworm).
- dist/Dockerfile.debian: debian:bookworm build env for :app:packageDeb
  (needs fakeroot + /usr/share/desktop-directories — both baked in; the
  dir gap made jpackage's postinst fail with exit 3 on minimal systems).
- dist/make-release.sh: clean source tarball from HEAD.
- INSTALL-debian.md: end-to-end install for friends (source tree must
  stay on disk — the app spawns the engine from it via SHONAR_REPO).

Verified on real Debian 12 in Docker: :app:packageDeb builds
shonar-desktop_0.1.0-1_amd64.deb, apt installs it, setup-standalone.sh
provisions the engine (venv+pip path, model fetch, boot smoke test),
and the packaged binary launches under Xvfb.

.gitignore

@@ -8,3 +8,5 @@ backend/__pycache__/
 *.pyc
 .dev-restart-flag
 models/hf-cache/
+dist/*.deb
+dist/*.tar.gz

INSTALL-debian.md

@@ -0,0 +1,54 @@
+# SHONAR Desktop — installing on Debian (12/13) or Ubuntu
+
+Everything runs locally on your machine. No accounts, no cloud, no
+telemetry. Audio, transcripts, and settings never leave your computer.
+
+There are two pieces: the **desktop app** (browse, transcribe, search)
+and the **transcription engine** (faster-whisper, bundled model — works
+offline after setup).
+
+## 1. Put the source tree where the app can find it
+
+The app auto-starts the bundled engine from the source folder, so keep
+the unpacked tarball around. Either:
+
+    mkdir -p ~/Projects && tar xzf shonar-desktop-*.tar.gz -C ~/Projects \
+      && mv ~/Projects/shonar-desktop-* ~/Projects/"Shonar Desktop"
+
+or extract anywhere and export `SHONAR_REPO=/that/path` (add it to
+`~/.profile`, or to the desktop launcher's Environment= line).
+
+## 2. Install the app
+
+Option A — .deb package (if you got `shonar-desktop_*.deb`):
+
+    sudo apt install ./shonar-desktop_0.1.0_amd64.deb
+    shonar-desktop
+
+Option B — run straight from the source tree (needs JDK 17, step 3):
+
+    cd ~/Projects/"Shonar Desktop" && ./launch-desktop.sh
+
+## 3. One-time setup
+
+    sudo apt install -y openjdk-17-jdk python3 python3-venv mpv
+    cd ~/Projects/"Shonar Desktop" && ./setup-standalone.sh
+
+This creates the engine's Python environment, vendors the whisper
+"base" model into `models/hf-cache` (one-time download, ~142 MB), and
+boots the engine once to prove it works.
+
+## 4. Run it
+
+Launch `shonar-desktop` (menu entry) or `./launch-desktop.sh`.
+The app starts the engine itself on first launch (takes a few seconds).
+Point "Choose folder…" at the folder holding your recordings and go.
+
+Notes
+- mpv is used for click-to-play from search results.
+- Summaries: if you run [Ollama](https://ollama.com) locally the app
+  uses it automatically; without it, transcription still works and
+  summaries are simply skipped.
+- Engine logs: `~/.config/shonar-desktop/engine.log`.
+- Wayland/Hyprland works; on X11 set nothing special.
+- Ctrl+= / Ctrl+- zooms the whole app; Ctrl+0 resets.

dist/Dockerfile.debian

@@ -0,0 +1,10 @@
+# Builds the SHONAR Desktop .deb on real Debian 12 and smoke-tests it.
+FROM debian:bookworm
+ENV DEBIAN_FRONTEND=noninteractive
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    openjdk-17-jdk dpkg-dev curl ca-certificates unzip git fakeroot \
+    python3 python3-venv python3-pip \
+    xvfb libasound2 libfreetype6 libfontconfig1 libgl1 libxrender1 \
+    && rm -rf /var/lib/apt/lists/* \
+    && mkdir -p /usr/share/desktop-directories
+WORKDIR /build

dist/make-release.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Build a shonar-desktop source release tarball from HEAD (no secrets, no
+# build junk, no runtime data). Friends unpack it and run setup-standalone.sh.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+VER=$(git describe --tags --always 2>/dev/null || echo dev)
+OUT="dist/shonar-desktop-$VER.tar.gz"
+git archive --format=tar --prefix="shonar-desktop/" HEAD \
+  | gzip > "$OUT"
+echo "wrote $OUT ($(du -h "$OUT" | cut -f1))"

setup-standalone.sh

@@ -6,8 +6,15 @@ cd "$(dirname "$0")"
 
 echo "==> backend venv (local, editable install of THIS backend)"
 if [ ! -x backend/.venv/bin/uvicorn ]; then
-  command -v uv >/dev/null || { echo "uv not found — install it: curl -LsSf https://astral.sh/uv/install.sh | sh"; exit 1; }
-  (cd backend && uv venv .venv --python 3.11 && uv pip install -p .venv/bin/python -e ".[dev,faster-whisper]")
+  if command -v uv >/dev/null; then
+    (cd backend && uv venv .venv --python 3.11 && uv pip install -p .venv/bin/python -e ".[dev,faster-whisper]")
+  else
+    # Plain Debian/Ubuntu path: system python3 (3.11 on bookworm) + venv + pip.
+    command -v python3 >/dev/null || { echo "python3 not found — install python3-venv"; exit 1; }
+    python3 -m venv backend/.venv || { echo "python3 -m venv failed — install the python3-venv package"; exit 1; }
+    backend/.venv/bin/pip install --upgrade pip >/dev/null
+    backend/.venv/bin/pip install -e "backend[dev,faster-whisper]"
+  fi
 else
   echo "    already present"
 fi