@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/deploy/ansible/README.md

@@ -0,0 +1,356 @@
+# Review-sandbox provisioning (Ansible) — the VM/server route
+
+Minimal, idempotent provisioning for the review sandbox: **one VM → the release
+image in `daemon` mode** (`ghcr.io/quickchatai/quickreview`: the compiled app,
+pinned pi, tmux, the seeds and the reviewer stub, all baked under `/opt/qcr`),
+**beside the memory sidecar** (`ghcr.io/quickchatai/quickreview-memory`),
+optionally with **cloudflared on the host** forwarding a public
+hostname → `localhost:8787` → the container. The images are built ONCE, by CI,
+from the release tag; the VM pulls those exact images by digest. **Nothing is
+rsynced, built or installed on the VM by a deploy.** The host is provisioned
+once (`deploy.sh provision`, this playbook), which installs a thin updater,
+`qcr-update`, and its run spec; every deploy after that is
+`deploy.sh release <version>`, which runs `ssh vm sudo qcr-update ...`.
+
+> **`qcr onboard` drives this route for you.** The wizard's
+> **topology** step offers it as one of two first-class answers — advertised as
+> the always-on recommendation, because a reviewer that is asleep reviews
+> nothing — then checks your ssh alias and agent *before* anything is built
+> (the passphrase trap, in the open), fills `inventory.ini` from your answers,
+> and runs the **same `scripts/deploy.sh` documented below**, with every one of
+> its preflights. It composes this path; it does not replace it, and drift
+> between the two is a bug. Everything here stays true for a manual run.
+> The step-by-step walkthrough is
+> [../../docs/onboarding.md](../../docs/onboarding.md).
+
+**Prefer one machine?** The other first-class answer is the plain Docker path:
+`docker compose up` on the released images — see `docker/README.md`. It
+needs no server at all, and it reviews only while that machine is awake. This
+Ansible route adds VM host setup, the optional tunnel, and the
+`scripts/deploy.sh` provision/release/verify workflow on top of the same image.
+
+**Ingress is a choice, not a requirement**: any HTTPS proxy or tunnel that
+forwards your webhook hostname to the published port works. The cloudflared
+tasks are gated on `cloudflared_enabled` (group_vars, default `true` — the
+live deployment keeps its tunnel); set `-e cloudflared_enabled=false` to
+bring your own ingress.
+
+Running the whole sandbox inside one container is the isolation answer to pi
+having no built-in permission system.
+
+## Prerequisites (once, manual)
+
+Items 2–4 are what `qcr onboard` fills in for you on this route; item 1 is
+yours either way — the wizard never creates a machine.
+
+1. **A VM you can reach over ssh by an alias**, with passwordless sudo for your
+   login. Any Linux host will do; the playbook installs everything else. The
+   live deployment runs a 4-vCPU / 100 GB box with no external IP, reached
+   through a bastion — that shape is a comfortable default, not a requirement.
+   The container is capped at 2 CPU / 8 GiB.
+2. **Ingress**: either a Cloudflare tunnel (remote-managed tunnel, public
+   hostname → `http://localhost:8787`; its **token** saved as
+   `tunnel_token` in the local secrets dir (item 3) — required only with
+   `cloudflared_enabled: true`), or your own HTTPS proxy/tunnel pointed at
+   the VM's `localhost:8787` (then set `cloudflared_enabled: false`). The
+   wizard's ingress step writes that flag into `inventory.ini` for you: `true`
+   for the named-tunnel shape, `false` for every other one.
+3. **Local secrets dir** — the install's `~/.config/qcr/<install>/secrets/`
+   (`deploy.sh provision` passes the install locator's answer as `secrets_src`;
+   an old `~/.config/quickreview-bot/` is never read — `qcr install migrate`
+   moves it) contains:
+   `app_id`, `app.pem`, `webhook_secret` (plus `openai_api_key` optional —
+   pi's API-key route — and `tunnel_token` when the tunnel is enabled), and
+   `openviking_root_key` / `openviking_reviewer_key` for the memory engine.
+   Memory embeds locally by default (nothing but the model call leaves the
+   VM); `openai_embeddings_api_key` exists only under the hosted-embeddings
+   opt-in, written as inventory host vars beside `cloudflared_enabled`
+   ([docs/memory-embeddings.md](../../docs/memory-embeddings.md)).
+   `bash deploy/collect-secrets.sh` assembles the first set interactively; the
+   wizard's GitHub App and memory steps write the same files.
+   (Never any personal token.)
+4. Controller tooling **on the machine you deploy from** — the deploy is an
+   Ansible run from here, not on the server:
+   ```
+   ansible-galaxy collection install community.docker ansible.posix
+   cp inventory.example.ini inventory.ini   # then edit — inventory.ini is
+                                            # gitignored (your real hostnames
+                                            # stay local; the example documents
+                                            # what to fill)
+   ```
+5. Pins ride `group_vars/all.yml` (pi, OpenViking, llama-cpp-python, …),
+   mirrored with `config.toml`; `tests/openviking.test.ts` and the
+   `scripts/deploy.sh` preflight refuse on drift. There is no `sandbox_src`:
+   nothing is synced from a working copy to the VM.
+
+## Run
+
+Through `scripts/deploy.sh`, which checks the pins and drift first:
+
+```
+scripts/deploy.sh provision                          # once per VM (and when the run spec changes): host, secrets, directories, the updater
+scripts/deploy.sh release 0.1.0 --manifest deploy-manifest-0.1.0.json   # the deploy: ssh vm sudo qcr-update ...
+scripts/deploy.sh verify                             # post-deploy checks over ssh
+scripts/deploy.sh --dry-run <any of them>            # the plan, nothing executed
+```
+
+The old dev modes are gone: they refuse with a pointer to `release`. A fix
+that cannot wait is a release too (a patch version); there is no working-copy
+deploy.
+
+**`provision`** runs this whole playbook (no tags): host packages + Docker →
+(when `cloudflared_enabled`) cloudflared apt repo, install, service
+registration with the tunnel token → directory layout under `/opt/quickreview/`
+→ secrets copied `0400` → `/usr/local/sbin/qcr-update` (root `0755`, from
+`deploy/qcr-update.sh`) and `/etc/qcr/update.conf` (root-owned, the run spec
+`deploy.sh` renders from `group_vars` — container names, mounts, caps, CPU and
+memory limits, networks, the sidecar's `openviking_*` env, a run-spec version
+and a fingerprint) → the operator channel's seal → the runtime directories.
+**It never pulls or starts an image.** Required vars (`deploy.sh` passes them):
+`base_clone_dir` (the reviewed repo's base-clone directory, `[github]
+clone_dir`, else the repo's basename), `secrets_src`, `update_conf_src`, and the
+Slack token file names.
+
+**`release`** reads CI's deploy manifest (`deploy/manifest.schema.json`: the
+version, the revision, both images' index digests and per-arch digests, and the
+pins they were built with), holds those pins to `config.toml` and `group_vars`
+(the pins hold: pi, openviking, llama-cpp-python and the embedder file/sha256
+must agree), refuses a run-spec fingerprint the VM does not hold ("re-run
+provision"), and then sends the install's config home — `config.toml` and
+`profiles/`, never `secrets/` — as a tar to
+`ssh vm sudo qcr-update <version>@<digest> --memory-digest <digest>`.
+`scripts/deploy.sh` refuses a config that lives only in the checkout or a
+`[review] profile` the home (or the checkout's generic examples) does not hold.
+
+### The updater (`qcr-update`)
+
+In order (the header of `deploy/qcr-update.sh` is the contract): flock; refuse
+unless the board is drained and idle (`draining=true`, `running_rounds=0`);
+on the legacy layout refuse without `--cutover-ack <version>`; pull both images
+by digest and check them (`qcr.layout`, a CI `qcr.build-sha`, `qcr.preflight`,
+`qcr.runspec` no newer than `update.conf`'s); stage the config and run the NEW
+image's `qcr config check --json` on it (a failure here changes nothing); stop
+the daemon; snapshot `state.db` (+wal/shm) and a tar of `state/pi-sessions` into
+`/var/backups/qcr/<version>-<ts>/` (root, `0600`; pihome is never included);
+run the new image's `daemon --preflight` on a scratch copy of the snapshot with
+`--network none`; on the legacy layout seed the sidecar store once (copy plus
+checksum verify; the daemon's old store is untouched); swap the config
+(`config-home` → `.prev`, `.next` → `config-home`); start the memory sidecar and
+wait for `/ready` (a long timeout: a re-embed is a boot); recreate the daemon
+container on the new image. At the cutover the recreate is the point of no
+return: the first boot migrates forward.
+
+**The tool uid (run spec v2).** The daemon runs as `container_uid`
+and the model's tools as `tool_uid:tool_gid` (65534:4749), which cannot read
+`secrets/`, pi's login or `state.db` (0600). The bot is not started as root, so
+a `docker exec` into it still lands as `container_uid`; it reaches the tool
+identity through the image's setid helper (`/usr/local/libexec/qcr/qcr-setid`,
+built from `docker/setid/qcr-setid.c`, file capabilities), which switches to the
+identity compiled into the image and to nothing else (never root), and which
+only the gate group in the image's `qcr.setid-gid` label may run. The updater
+refuses a run spec whose `TOOL_UID`/`TOOL_GID` differ from the image's
+`qcr.tool-uid`/`qcr.tool-gid`. The recreate gives the bot `--group-add` for the
+gate group and the tool gid, `--cap-drop ALL` with `SETUID`/`SETGID` (the
+helper) only, `QCR_TOOLS_AS=<tool_uid>`, and no `no-new-privileges` (it would
+void the helper; the model's tools carry `no_new_privs` of their own). The
+operator channel needs no capability: the updater makes `commands/operator`
+root's own `0755` before the bot starts, and the operator's `docker exec -u 0`
+writes only into it. The playbook and the entrypoint share `state/` (`3775`),
+`verdict/` (`2775`) and `commands/` (`3775`) with `tool_gid`; the sticky bit
+keeps the tools from renaming or removing the daemon's entries. An image older
+than run spec v2 has no label and gets no group. The entrypoint refuses to start
+the bot when the helper cannot switch, or when the bot is not in the tool gid.
+Adopting it is `provision` (the new updater and run spec v2), then a release
+built with the helper.
+
+**Rescue.** Any failure from the stop to the recreate restores `.prev`, removes
+the newly started sidecar (the old one is put back), starts the old daemon
+container, waits for its first reconcile in `status.json` (a healthy legacy
+boot lifts the drain), re-sends `drain on` through the operator channel,
+confirms `draining=true` and exits non-zero naming the step. Between the
+auto-lift and the re-sent drain the dispatch pump may already have started held
+`pending_wakes` rounds: the bot is left drained but rounds may be running, so a
+retry waits for `running_rounds` 0. A failure after the recreate keeps the drain
+on (a failed first reconcile never lifts it) and is fixed forward.
+
+`sudo qcr-update status --json` reports the layout, the images' labels, the
+run-spec version and fingerprint, the drain state and the last run.
+
+### What is inside the container
+
+The release image's app root is `/opt/qcr`, root-owned and read-only to the
+container user. Everything the daemon writes lives in a host directory under
+`/opt/quickreview/`, the same ones the legacy container mounted, bind-mounted
+back in: `state/` → `/opt/qcr/state`, `pihome/` → `/home/qcr/.pi`, `secrets/`
+and `config-home/` read-only at `/opt/quickreview/`, and `sandbox/{wt,archive,
+commands,digest,inject,verdict,<clone>}` → `/opt/qcr/<name>`. The worktree
+directory and the base clone are mounted a second time at their old path
+(`/opt/quickreview/sandbox/…`), so the absolute paths git and pi recorded before
+the cutover still resolve. `commands/operator` stays root-owned on the host and
+is re-sealed on every run.
+
+The TUI finds the container's app root by itself: it reads the running
+container's `qcr.layout` label (`release` = `/opt/qcr`, no label = the legacy
+`/opt/quickreview/sandbox`) and reads it again whenever the container id changes,
+so the cutover needs no TUI key edited (`src/tui/layout.ts`). An explicit
+`[tui] remote_sandbox_root` still wins; `deploy.sh` warns, and does not refuse,
+when one names another root. `remote_state_dir` stays the host path.
+
+### Pulling the release
+
+The images are private and are pulled BY the updater, on the VM, by digest. The VM pulls them with ONE credential: your own CLASSIC
+personal access token, scoped `read:packages` and nothing else, stored by
+`docker login` in root's docker config on the VM host (never in a container,
+env, argv or the secrets directory: the daemon holds only the App credential). Not the token `gh auth
+token` prints: that one carries the full scopes of your gh login.
+
+A deploy needs this login to exist before the first `release` (the pull is the
+updater's first step, and a lapsed login fails there with nothing changed).
+
+Once per VM, and again when the token is renewed (it expires after one year):
+
+1. On github.com, Settings, Developer settings, Personal access tokens, Tokens
+   (classic): a new token, expiration one year, the single scope
+   `read:packages`.
+2. Once a version is published, on the controller:
+
+```
+scripts/vm-ghcr-login.sh --version <published X.Y.Z>        # paste the token, then Ctrl-D
+scripts/vm-ghcr-login.sh --version <X.Y.Z> --token-file <0600 file>
+```
+
+The script refuses a token unless GitHub reports its scopes as exactly
+`read:packages` and it has an expiry, runs `ssh <vm> sudo docker login ghcr.io
+-u <you> --password-stdin`, checks the login with `docker manifest inspect` of
+both images at that version, and records the expiry on the controller. It is
+idempotent, and the token is never an argument or an environment variable.
+
+A lapsed login fails the updater's pull before anything on the VM changes
+(`qcr-update` refuses at its `pull` step). `scripts/deploy.sh verify` and
+`release` warn 14 days before the recorded expiry. `ssh <vm> sudo docker logout ghcr.io` removes the login.
+
+### The cutover (legacy image to release image)
+
+The first `release` against a VM still running the legacy image
+(`quickreview-sandbox:v1`, the Ubuntu image the retired `Dockerfile.j2` built)
+swaps the image and the container shape in one restart, and the first boot
+migrates forward. It needs the deliberate `--cutover-ack`, which `deploy.sh`
+hands the updater as `--cutover-ack <version>`; without it both refuse, with
+nothing changed. **Until the cutover the legacy VM takes no deploy**: if something urgent comes
+up, drain and wait for the cutover window. Run `provision` first (it installs
+the updater beside the legacy container and touches no image), then:
+
+```
+qcr drain on                      # wait for running_rounds 0
+scripts/deploy.sh --dry-run release 0.1.0 --manifest deploy-manifest-0.1.0.json --cutover-ack
+scripts/deploy.sh release 0.1.0 --manifest deploy-manifest-0.1.0.json --cutover-ack
+```
+
+Use `scripts/cutover.sh`, which runs these steps in order. At the cutover the
+drain does NOT auto-lift: the release's first boot keeps the operator's drain as
+the no-auto-lift hold (`drain_hold_carried`, then `drain_hold_kept` at its first
+healthy reconcile; `draining_hold: true` in status.json), so no round starts
+until the owner has triggered and checked one worker round and runs `qcr drain
+off`. (A plain drain on a release-layout VM is still lifted by the new boot's
+first healthy reconcile; `qcr drain on --hold` sets the hold by hand.) After
+the deploy, `deploy.sh verify` shows the image and its build stamp, that pi's
+`settings.json` carries no global bash-guard entry, and that `AGENTS.override.md` in the app root
+is the 12-line reviewer stub.
+
+### Rollback
+
+There is no rollback across a migration. The first boot of a release migrates
+`state.db` forward, and an older image run over the newer schema is not a
+supported state. Going back is therefore a **forward fix**: cut a new release
+(a patch version) that contains the fix or the revert, and `deploy.sh release`
+it. Nothing is hand-edited on the VM.
+
+What the updater does for you:
+
+- **Before the recreate** (config check, stop, snapshot, preflight, sidecar
+  seed, config swap, sidecar `/ready`): any failure is a **rescue**. The
+  updater restores `config-home.prev`, puts the old containers back (they were
+  renamed to `<name>-prev`), waits for the old daemon's first reconcile,
+  re-sends `drain on` and exits non-zero naming the step. Nothing was migrated,
+  so the bot is exactly as it was, drained. Fix the cause and run the same
+  release again once `running_rounds` is 0.
+- **After the recreate** the new boot has migrated state: no rescue. The drain
+  stays on until a first reconcile passes healthily; fix forward with a new
+  release.
+- **The snapshot** of every run is `/var/backups/qcr/<version>-<ts>/` on the VM
+  (root, `0600`): `state.db` with its `-wal`/`-shm`, and a tar of
+  `state/pi-sessions`. It is the evidence and the manual restore point, not an
+  automatic one; pihome is never in it. Keep it until the release has proven
+  itself.
+- **Left in place, never deleted by a deploy**: the legacy image
+  `quickreview-sandbox:v1` (nothing here removes an image), the previous
+  containers, and every host directory the container uses (state, pihome, the
+  sandbox tree, the memory sidecar's store).
+  Once the release has proven itself, the owner removes the leftovers with
+  `scripts/vm-postcutover-cleanup.sh` (run on the VM as root; a dry run first,
+  then `--apply <plan key>`): the legacy and VM-built images, the old rsynced
+  checkout by an allowlist that never touches a directory the containers mount,
+  and all but the newest three snapshots. It keeps `state/openviking` and the
+  `memory-state.rescued-*` stores, which are the owner's separate decision.
+
+Redeploying a **previous** version is allowed only when no migration lies
+between it and the running one; `qcr-update status --json` and the release
+notes say whether one does. When in doubt, the answer is a forward fix.
+
+## Verify
+
+```
+scripts/deploy.sh verify     # all of the below, plus the image stamp, settings.json and the stub
+ssh <vm> systemctl is-active cloudflared docker
+ssh <vm> docker ps --filter name=quickreview-sandbox
+ssh <vm> docker exec quickreview-sandbox tmux ls
+ssh <vm> curl -sS http://127.0.0.1:8787/health     # loopback-only by design
+```
+
+That is the same layering `qcr onboard`'s verification step runs — containers,
+then the health endpoint, then GitHub's own webhook delivery log — and the
+order matters: a container that is not up cannot answer a health probe, and a
+daemon that is not answering cannot accept a delivery. While the tunnel is up
+but the daemon is not, a GitHub test delivery returns a 502 *from cloudflared*
+rather than timing out; that distinction is itself the proof the tunnel path
+works.
+
+## OpenAI auth for pi
+
+Native in pi — nothing to install. Both routes and their
+cost shapes are in [../../docs/llm-setup.md](../../docs/llm-setup.md); here is
+what this route does with each:
+
+- **API key (wired automatically)**: the daemon mode of the image's entrypoint
+  exports `OPENAI_API_KEY` from the mounted `secrets/openai_api_key`, so the tmux
+  server and every pi session inherit it. Works headless from the first boot.
+- **ChatGPT-subscription OAuth (optional)**: run `/login` once inside any pi
+  session in the container (`docker exec -it quickreview-sandbox pi` →
+  `/login`); tokens land in `/home/qcr/.pi/agent/auth.json`, which lives on
+  the persistent `pihome` volume, auto-refresh, and **take precedence** over
+  the env-var key (pi's resolution order: CLI flag → auth.json → env var).
+  Both routes can coexist. A login here does **not** cover a companion
+  container on your own machine, or a pi you run on the host: pi's tokens do
+  not transfer, so each pi home needs its own.
+
+The `pihome` volume also persists pi's session JSONLs across container
+recreates — required for the sticky per-PR conversations, not just for auth.
+
+## Notes
+
+- Re-runs are safe: package installs are idempotent, the cloudflared service
+  task is guarded by `creates:`, secrets copies only rewrite on change. A
+  release recreates the containers (the updater's job, not this playbook's).
+- The webhook port is published on loopback only; ingress is whatever HTTPS
+  proxy/tunnel you point at it (the optional cloudflared service, or your
+  own). No inbound firewall rule is ever needed.
+- Image pins: pi and node are pinned in `group_vars/all.yml` (and are the
+  Dockerfile's ARG defaults, which tests hold equal); the images carry them as
+  labels (`qcr.pi`, `qcr.openviking`, ...) and the release manifest copies them.
+  Bumping them is a deliberate edit and a new release, never automatic.
+- Jump-in from your own machine: a bot round runs in a worker with no tmux
+  session, so there is nothing to attach to. The operator TUI (`scripts/qcr
+  tui`, with `[tui] target = "ssh"`) shows each PR's live transcript;
+  `scripts/qcr open pr <n>` opens the PR's session in pi, forked; and
+  `scripts/qcr takeover <n>` / `debug-round <n>` put the PR in an interactive
+  pi (`takeover-pr-<n>` / `debug-pr-<n>`) that the TUI embeds in its pane.

package/deploy/ansible/group_vars/all.yml

@@ -0,0 +1,212 @@
+---
+# Review-sandbox provisioning knobs. Target: an EXISTING, possibly shared VM
+# (e.g. `my-vm`, an e2-standard-4 in your cloud project) — name it in
+# inventory.ini (copy inventory.example.ini). The container is capped; the VM
+# is assumed not ours to resize.
+
+sandbox_root: /opt/quickreview          # on the VM
+webhook_port: 8787
+
+# The daemon container's name (scripts/deploy.sh holds it to the name the
+# updater and the verify checks use).
+image_name: quickreview-sandbox
+# The LEGACY image (Ubuntu + the rendered Dockerfile.j2, retired by the release
+# image cutover). Nothing here builds or runs it any more; it stays on the VM
+# under this tag as the rollback image (README, "Rollback to the legacy image").
+image_tag: v1
+
+# The images the updater (deploy/qcr-update.sh) pulls BY DIGEST: CI builds them
+# once from the release tag and pushes them to these repositories, and
+# `scripts/deploy.sh release <version>` reads the digests from the release's
+# deploy manifest. Nothing is built on the VM. Never `latest`: no such tag exists.
+release_image: ghcr.io/quickchatai/quickreview
+release_memory_image: ghcr.io/quickchatai/quickreview-memory
+# The release image's app root: root-owned, read-only to the container user,
+# with the runtime directories bind-mounted into it from sandbox_root.
+app_root: /opt/qcr
+# Where the legacy container mounted the sandbox root. The playbook mounts the
+# worktree directory and the base clone there too, so absolute paths recorded
+# before the cutover (git worktree metadata, pi session headers) still resolve.
+legacy_sandbox_root: /opt/quickreview/sandbox
+
+node_major: "26"
+# pi CLI npm package + exact version pin (registry-verified). The image never
+# floats — bumping is a deliberate edit and a new release (CI builds the image).
+pi_npm_package: "@earendil-works/pi-coding-agent"
+pi_version: "1.4.0"
+
+# No subagent-extension pin: lenses run through our own lens tool
+# (packages/pi-plugin/src/engine/lens/), so there is nothing to pin. Never add a third-party
+# subagent clone step here (it would bring in an unlicensed dependency).
+
+# No memory-engine npm pin: memory is OpenViking (below) and its pi extension
+# is vendored in the repo, not installed from npm. An npm memory package here
+# would put a second memory engine in the image.
+
+# OpenViking (github.com/volcengine/OpenViking) — the context store, run by the
+# memory sidecar container (docker/memory/) beside the daemon's. Its server
+# binds the container network; the local embedder it supervises stays on
+# loopback 1934.
+# Same pin discipline as pi_version: exact versions, never floating,
+# bumping is a deliberate edit and a new release.
+#
+# TRIPLE MIRROR: openviking_version / llama_cpp_python_version here ==
+# config.toml [openviking] version / llama_cpp_python_version == the memory
+# image's ARG defaults (docker/memory/Dockerfile, tests/memory-image.test.ts)
+# == the labels CI stamps on the memory image (qcr.openviking, ...), which the
+# release's deploy manifest carries as `pins`.
+# tests/openviking.test.ts fails on drift.
+#
+# llama-cpp-python is NOT an openviking dependency — it is an undeclared
+# optional extra, and without it the default local dense embedder raises
+# EmbeddingConfigurationError at startup, so the server cannot boot at all
+# (verified against a running 0.4.15). It is also the runtime of the local
+# English embedder (below). PyPI-verified pins: openviking 0.4.15
+# (requires-python >=3.10; 24.04 ships 3.12), llama-cpp-python 0.3.35.
+openviking_version: "0.4.15"
+llama_cpp_python_version: "0.3.35"
+openviking_venv: /opt/openviking/venv  # a mirror of the memory image's baked OPENVIKING_VENV, not forwarded to the sidecar: changing it here changes nothing at runtime
+openviking_port: 1933                 # never a published port: loopback in the container that runs it
+# WHO RUNS THE SERVER. "remote" (the VM's value) is the memory SIDECAR: a
+# second container beside the daemon's (docker/memory/, the `memory_*` knobs
+# below) runs OpenViking and its local embedder, owns the boot provisioning and
+# the embedder re-embed, and holds its own copy of the store. The daemon then
+# only probes it. "local" is the pre-sidecar layout — OpenViking a child of the
+# daemon's container — which the release image cannot run (it carries no
+# OpenViking), so the playbook and scripts/deploy.sh refuse it: the way back to
+# it is the legacy image and the old playbook (README, "Rollback").
+# MIRRORS config.toml [openviking] endpoint.
+openviking_endpoint: "remote"
+# ~/.openviking is symlinked here at boot, so memory lives on the state volume
+# and survives an image rebuild. Must equal config.toml [openviking] home.
+openviking_home: /opt/quickreview/state/openviking
+openviking_workers: 1                 # ov.conf server.workers (2-CPU cap)
+openviking_queue_concurrency: 2       # ov.conf queue_workers.* (defaults 4/4/8) + embedding.max_concurrent (10)
+# The embedder. LOCAL is the shipped default: a small
+# ENGLISH embedding model served on loopback INSIDE the container by
+# scripts/openviking-embedder.py (over the pinned llama_cpp_python above), so
+# no memory text ever leaves the machine — nothing but the model call does.
+# Under "local" the sidecar's entrypoint renders ov.conf's OpenAI-COMPATIBLE provider
+# with api_base http://127.0.0.1:{{ openviking_local_embedder_port }}/v1 and no
+# key — the engine's async client, so a search does not block the server.
+# A HOSTED embedder is an explicit opt-in, written as INVENTORY HOST VARS on the
+# host line (host vars outrank this file, and this file stays tracked and
+# clean):
+#     openviking_embedding_provider=openai openviking_embedding_model=text-embedding-3-small openviking_embedding_dimension=1536
+# plus the credential in <secrets_src>/<openviking_embedding_key_file> — a
+# SEPARATE file from pi's openai_api_key, so either can be set without the
+# other. The sidecar's entrypoint (docker/memory/entrypoint.sh) renders these into ov.conf `embedding.dense`; ov.conf
+# carries NO `vlm` section either way (extraction, summaries and digest are
+# off — memories are authored, never extracted).
+# MIRRORS config.toml [openviking] embedding_provider / embedding_model /
+# embedding_dimension / embedding_key_file; scripts/deploy.sh's preflight
+# refuses on drift between config.toml and the EFFECTIVE ansible value (host
+# var, else this file) — a config.toml that says "openai" over a boot that
+# renders "local" would reset the vector store on the next start.
+# Under "local" the model/dimension are the local embedder's (the pin below);
+# the render uses the pin's own values and warns if these disagree.
+openviking_embedding_provider: "local"
+openviking_embedding_model: "bge-small-en-v1.5-f16"
+openviking_embedding_dimension: 384
+openviking_embedding_key_file: "openai_embeddings_api_key"
+# The LOCAL EMBEDDER's model file — a rule-7 pin like
+# openviking_version. TRIPLE MIRROR: these == config.toml [openviking]
+# local_embedder_file (== dir/model.gguf) / local_embedder_url /
+# local_embedder_sha256 == the memory image's model layer, which downloads the
+# GGUF at BUILD time and refuses it unless the sha256 matches (the service
+# re-checks it at every start). The image carries it whatever the provider, so
+# a hosted opt-in can return to local without a rebuild; changing the pin needs
+# a new release. tests/openviking.test.ts and the deploy
+# preflight refuse on drift. The dimension is the model's own (the service's
+# model table in scripts/openviking-embedder.py), mirrored here for the render.
+openviking_local_embedder_model: "bge-small-en-v1.5-f16"
+openviking_local_embedder_dimension: 384
+openviking_local_embedder_dir: /opt/openviking/models
+openviking_local_embedder_url: "https://huggingface.co/CompendiumLabs/bge-small-en-v1.5-gguf/resolve/d32f8c040ea3b516330eeb75b72bcc2d3a780ab7/bge-small-en-v1.5-f16.gguf"
+openviking_local_embedder_sha256: "f0b2fef971e8366438bfd2d9aefea1b0115919389448806d290237f638bae999"
+# The service: 127.0.0.1 only — NEVER a published port. One llama.cpp thread
+# is the latency budget the model was chosen on. MIRRORS config.toml
+# [openviking] local_embedder_port / local_embedder_threads (the daemon
+# supervises the long-lived service from those; the boot's provisioning step
+# runs it briefly from these).
+openviking_local_embedder_port: 1934
+openviking_local_embedder_threads: 1
+# Server-side confinement. `api_key` makes every request carry a USER key the
+# server confines to that user's tree; `dev` bypasses authentication and makes
+# the two-user design nominal, so it is never the deployed value. MIRRORS
+# config.toml [openviking] auth_mode / root_key_file / reviewer_key_file / provision_users;
+# tests/openviking.test.ts and the scripts/deploy.sh preflight refuse on drift.
+openviking_auth_mode: "api_key"
+# Secret FILE NAMES under the container's read-only secrets mount. The ROOT key
+# is the SERVER's own credential — ov.conf carries it (0600) and boot
+# provisioning uses it; no daemon surface, no review session and no companion
+# process ever holds it. The REVIEWER key is the one client credential the
+# container may hold. The COMPANION key is deliberately ABSENT from this
+# machine: a review session that could read it would reach companion memory,
+# which is the whole thing confinement exists to prevent.
+openviking_root_key_file: "openviking_root_key"
+openviking_reviewer_key_file: "openviking_reviewer_key"
+# Users boot provisioning ENSURES exist — created if absent, left alone if
+# present, never rotated (a rotation orphans the distributed keys).
+openviking_provision_users: "reviewer,companion"
+
+# The memory sidecar (used under openviking_endpoint: remote). The container
+# name is also its DNS name on the network below, so it MIRRORS config.toml
+# [openviking] host (scripts/deploy.sh refuses drift). The port is
+# openviking_port above, on the container network only — never published.
+memory_container_name: quickreview-memory
+# A user-defined bridge, because Docker resolves container names only there.
+# The daemon's container joins it (and keeps its published webhook port); the
+# network is not internal — the daemon still needs the internet.
+memory_network: quickreview-memory
+# The sidecar's OWN copy of the store, on the VM. Seeded ONCE from the daemon's
+# `openviking_home` while the daemon container is stopped, verified file by
+# file, and never deleted or overwritten afterwards (the .seeded marker). The
+# old directory stays untouched as the rollback's store.
+memory_state_dir: /opt/quickreview/memory-state
+# Hard caps like the daemon's. PROVISIONAL: sized from the daemon container's
+# 2 CPU / 8 GiB, which carried the server and the embedder as children; re-size
+# from `docker stats quickreview-memory` once it has run under load.
+memory_container_cpus: "1"
+memory_container_memory: "3g"
+
+timezone: Europe/Warsaw
+container_uid: 1001                   # the uid the daemon runs as and the host directories belong to
+# The identity the model's tools run as: never the container
+# uid, so they cannot read secrets/ or pi's login, and a gid of its own, which
+# the container user is given too (--group-add) and which owns only the
+# directories the model's scripts write (state/, verdict/, commands/). A MIRROR
+# of the release image's compiled-in identity (docker/Dockerfile QCR_TOOL_UID /
+# QCR_TOOL_GID, its qcr.tool-uid / qcr.tool-gid labels): the updater refuses a
+# run spec that names another.
+tool_uid: 65534
+tool_gid: 4749
+
+# Hard Docker limits — the VM may be shared with other workloads.
+container_cpus: "2"
+container_memory: "8g"
+
+# Preflight refusal threshold on the shared box.
+min_free_disk_gb: 15
+
+# Ingress. The tunnel is OPTIONAL: any HTTPS proxy or tunnel that
+# forwards your webhook hostname to localhost:{{ webhook_port }} on the VM
+# works. `true` keeps the live deployment's cloudflared service (and then
+# `tunnel_token` must exist under secrets_src); set false (or
+# `-e cloudflared_enabled=false`) to bring your own ingress — no other task
+# depends on the tunnel.
+cloudflared_enabled: true
+
+# Controller-side sources
+# scripts/deploy.sh provision passes `-e secrets_src=<dir>` — the install
+# locator's answer: [github] secrets_dir, else the install's config home
+# (~/.config/qcr/<install>/secrets). This default — the default
+# install's home — only serves a playbook run by hand.
+secrets_src: "{{ lookup('env', 'HOME') }}/.config/qcr/default/secrets"
+# Expected files there: app_id, app.pem, webhook_secret; openai_api_key
+# optional (pi's API-key route); tunnel_token only when cloudflared_enabled;
+# openai_embeddings_api_key only under the hosted-embedder opt-in above.
+
+# Flat Slack token names copied from the controller secrets directory.
+slack_bot_token_file: slack_bot_token
+slack_app_token_file: slack_app_token

package/deploy/ansible/inventory.example.ini

@@ -0,0 +1,25 @@
+# Copy to inventory.ini and fill in — inventory.ini is gitignored:
+# it carries YOUR real hostnames and stays local to the controller machine.
+#
+# `scripts/qcr onboard` writes inventory.ini for you on the server route, from
+# answers you have already given (the ssh alias, the login user your ssh config
+# resolves, and whether the playbook should install cloudflared). This file
+# documents what it writes, and what to fill if you do it by hand.
+#
+# What to fill:
+#   [quickreview] host   — any ssh-reachable name for the target VM: a plain
+#                        hostname, an ~/.ssh/config alias, or (on GCP) the
+#                        alias `gcloud compute config-ssh` writes.
+#   ansible_user       — the remote login user (omit when your ssh config
+#                        already sets it, e.g. via config-ssh / OS Login).
+#   ansible_python_interpreter — leave as /usr/bin/python3 for Ubuntu/Debian.
+
+[quickreview]
+quickreview-sandbox.your-zone.your-dev-project
+
+[quickreview:vars]
+ansible_user=your_oslogin_user
+ansible_python_interpreter=/usr/bin/python3
+
+# GCP IAP-only alternative (no external IP, without config-ssh):
+# ansible_ssh_common_args=-o ProxyCommand="gcloud compute start-iap-tunnel %h 22 --listen-on-stdin --project=your-dev-project --zone=your-zone"