Track Q — Desktop & app operator runbook

Audience: operators, contributors, and non-developer users who want the Overseer governance UI without living in a terminal.

Status (2026-07-14): Track Q is DONE (Q0 → Q4b). Mac signed installer is published on GitHub Release v0.1.0 (Apple Silicon aarch64 .dmg, signing.status: signed). Windows/Linux signed installers are not published yet. Host still needs Python 3.11+. Canonical playbook title: Open the local console (Paths 1–3 below; maps to Path C / B / C-dev).

What exists today

The kit is not Cursor-only. Cursor rules and Agent Skills are an optional layer on top of portable policy, templates, and CLI. Claude Code, Copilot, or any chatbot works via handover paste prompts and terminal commands — see README.md §AI tool compatibility.

Path A — Handover paste (any chatbot; no desktop required)

Way forward: Overseer Kit is developer-centric. Day-to-day task/product UX belongs in consumers such as Scooling; this kit stays portable governance. Path A remains valid for anyone with a checkout, but the public site is not an end-user product — it explains and links.

Path A does not require Cursor or the desktop app. It does require a project that already has the kit installed (one-time setup). The public website alone does not replace that install step.

1. Install the kit once on the machine that holds the project (or use a teammate’s checkout path).
2. In your project repo, run once:

   /path/to/overseer-kit/cli/ok -C /path/to/your-repo init --regime git-only --non-interactive
   

3. Open docs/OVERSEER-HANDOVER.md in your repo (filenames may differ per consumer config).
4. Copy the Paste-ready prompt block into any AI session (Cursor, Claude, ChatGPT, etc.).
5. When the session ends, run (or ask the agent to run):

   ok governance-sync --dry-run
   

6. Commit on a feature branch; merge to main only when a human approves (Tier 3).

Wizard equivalent: the HANDOVER NEXT SESSION block is the wizard — one step, one model label, one paste fence. No separate GUI wizard ships in kit core yet.

Website visitors: use the public landing (docs/landing/ / custom domain) to understand structure, download the Mac console (Path 1), or clone GitHub. The site does not mint CSRF / session credentials and does not run the live console. Day-to-day product UX stays in sister projects (Track O — consumer UX, not kit core).

Open the local console (Paths 1–3)

Path 1 — Download Mac console (preferred · Apple Silicon)

1. Confirm Python 3.11+ (python3 --version).
2. Download the signed Apple Silicon (aarch64) asset: https://github.com/aaronrene/overseer-kit/releases/download/v0.1.0/Overseer.Kit_0.1.0_aarch64.dmg
3. Optionally verify SHA256SUMS.txt + manifest signing.status: signed (§Signed installers below).
4. Bind a governed checkout before launch: set OVERSEER_REPO_ROOT to the absolute path of the consumer (or kit) repo that already has .overseer/ from ok init.
   Default without that env var: the desktop launcher binds repo_root to the bundled kit root inside the app resources — useful for dogfooding the kit, not a folder picker.
5. Open the app; desktop shell auto-fills session bootstrap.
6. Confirm the chrome shows the expected bound path before any write action.

Apple Silicon (aarch64) Mac · signed+notarized · requires Python 3.11+. Set OVERSEER_REPO_ROOT to your governed repo. Windows/Linux signed installers are not published yet. No in-app folder picker in Auto v1.

Path 2 — Browser (ok app) — legacy “Path B”

cd /path/to/your-governed-repo   # must have .overseer/ from init
/path/to/overseer-kit/cli/ok app --open

The terminal prints once:

• url: loopback address (default port 8765)
• session_credential: and csrf_token:

Paste those into Session bootstrap → Connect. After Connect, the UI collapses bootstrap and shows the bound checkout from api/health → result.repo_root.

Guardrails: loopback only; Bearer + CSRF on api/*; closed Q0 surface except additive repo_root on health (§LAC.6.3).

Path 3 — Dev desktop (legacy “Path C” build-from-source)

Prerequisites: Python 3.11+, Node/npm, Rust 1.88+ via rustup (Homebrew Rust 1.87 is too old for current Tauri deps).

# From overseer-kit root
./scripts/bundle-desktop-kit.sh          # copies Python engine into Tauri resources
cd desktop && npm install
npm run tauri dev                        # dev window → spawns ok app → same UI

Release build (local):

npm run tauri build                      # produces platform installer under desktop/src-tauri/target/release/bundle/

Environment overrides:

Release vs dev (honest status)

Honesty: do not treat smoke-workflow AppImages (names include unsigned) as official installers. Do not market Windows/Linux downloads until a signed Release row ships.

Signed installers (Path 1 download)

Frozen contracts: docs/archive/phases/PHASE-Q3-RELEASE-DESKTOP-INSTALLERS.md, docs/archive/phases/PHASE-LANDING-ACCESS-CLARITY.md (§LAC.2 frozen .dmg href).

Prerequisites on the end host

• Python 3.11+ available so the bundled cli/ok shim can exec the local web UI engine.
• The signed installer removes the need to install Rust/Node to compile Path 3; it does not provide a zero-dependency / embedded-Python install.
• Set OVERSEER_REPO_ROOT for consumer repos (default without it = bundled kit root).

Download + verify

1. Open the kit GitHub Releases page; choose tag v0.1.0 (or later signed tag matching VERSION).

2. Download the Apple Silicon asset Overseer.Kit_0.1.0_aarch64.dmg plus SHA256SUMS.txt and overseer-kit-desktop-{VERSION}-manifest.json. Win/Linux assets are not primary until signed.

3. Verify SHA-256:

   shasum -a 256 -c SHA256SUMS.txt
   # or: sha256sum -c SHA256SUMS.txt
   

4. Confirm the manifest artifacts[].sha256 matches SHA256SUMS.txt and signing.status is signed for your platform.

5. Linux AppImage only (when a signed Release exists): verify the detached cryptographic signature (minisign default):

   minisign -Vm Overseer\ Kit_*_amd64.AppImage -p desktop/keys/release.minisign.pub
   

   AppImage signing is not OS-vendor notarization (no Gatekeeper/Authenticode equivalent in Auto v1). Public key: desktop/keys/release.minisign.pub (public material only).

Operator secret setup checklist (Tier 3 — humans only)

Configure GitHub Actions repository secrets before the first live signed Release. Auto never writes secret values. Exact names (§QR.6.2):

Also:

1. Align Muse tip + GitHub mirror tip; ensure VERSION matches desktop/package.json, desktop/src-tauri/Cargo.toml, and desktop/src-tauri/tauri.conf.json.
2. Cut tag v{VERSION} (tag-push triggers publish with publish: true, allow_partial: false).
3. Confirm Release assets are only the §QR.4.5 allowlist (.dmg / .msi / .AppImage + sidecar + manifest + SHA256SUMS.txt).

Optional: workflow_dispatch with inputs version, publish, allow_partial (see workflow).

Workflows:

Helpers: tools/desktop_release/ (version-align, manifest, refuse, allowlist, checksums).

Consumer repos (e.g. Scooling)

The desktop app is not copied into consumer repos. Consumers get:

Scooling adoption pattern (same as any muse+git-mirror consumer):

KIT=/path/to/overseer-kit
REPO=/path/to/scooling
$KIT/cli/ok -C $REPO init --migrate --from-config $KIT/tests/fixtures/pilot/config-scooling.yaml --non-interactive
$KIT/cli/ok -C $REPO status --check-footprint

• Product runtime (src/phase9a/ router, workers) stays in Scooling — reference only, not vendored.
• Governance (handover, roadmap, freeze review, verify-step, honesty) comes from the kit footprint.
• L1 checkpoints: Scooling adds policy/checkpoints.yaml + scripts/verify/* in its repo.
• Desktop UI: optional; run $KIT/cli/ok -C $REPO app or a future published Overseer Kit desktop installer pointed at the Scooling checkout via OVERSEER_REPO_ROOT.

There is no MuseHub/Cursor marketplace plugin for the kit. “Plugin” in kit terms means L1 checkpoint module (verify-step) and L2 honesty module — config-gated engines the consumer enables in .overseer/config.yaml, not an IDE extension.

Quick decision tree

Need governance in a new repo?
  → ok init (Path A or consumer runbook)

Comfortable in terminal + want UI?
  → ok app (Path B)

Want native window + can build Rust?
  → Tauri dev/build (Path C source)

Want native window + signed installer published for this VERSION?
  → Download from GitHub Releases; verify SHA-256 (+ Linux minisig); need Python 3.11+

Non-technical user + no terminal?
  → Path A only (HANDOVER paste into any chatbot) — installers additive when a signed Release exists

Scooling / Knowtation / VideoFactory?
  → Consumer adapter pattern (§Consumer repos above); see docs/CONSUMER-ADAPTER-PATTERN.md