WhispAssist/docs/adr/0012-startup-and-enterprise-deployment.md

ADR-0012 — Launch-at-login & enterprise deployment defaults

• Status: Accepted
• Date: 2026-07-14
• Context source: User request (2026-07-14) — auto-start on boot; customize an installation (install location, per-user/all-users, default settings) with native Windows tooling for mass-deployment.

Context

Two related needs. (1) Users want WhispAssist to launch automatically at login. NFR-RES-4 forbids adding WA to OS startup without explicit consent, so this must be opt-in. (2) An admin mass-deploying WA to many machines wants to customize the deployment — install location, whether it installs per-user (no admin) or all-users, and the app's default settings (record-by-default, preferred backend, a model to pre-download, retention, AI provider) — using native Windows tools (GPO / SCCM / Intune / msiexec / silent NSIS), not a bespoke management console.

Decision

1. Launch-at-login is opt-in, off by default. A set_auto_start command uses tauri-plugin-autostart to write a per-user HKCU\...\Run entry (no admin) and persists an auto_start setting. Startup reconciles the OS entry to that flag (restores it after a reinstall). Nothing runs on a timer — this is a registry entry, not a background process (NFR-RES-1).
2. Install location & scope are native, no app code.
   • Location: msiexec INSTALLDIR=… (MSI) / NSIS /D=… (silent).
   • Scope: NSIS installMode: "both" — the .exe setup lets the user choose current-user (no admin) or all-users (admin). The MSI stays per-machine as the enterprise all-users artifact.
3. Default settings via a first-run wa-defaults.ini. On a machine's first launch (before settings.json exists) WA reads an admin-supplied INI — %PROGRAMDATA%\WhispAssist\wa-defaults.ini first, else the bundled <install dir>\wa-defaults.ini — and seeds settings.json from it, with an optional auto_download_model to pre-fetch the model. The shipped template is fully commented, so a normal install is unaffected. This is deployable purely by copying a file with existing Windows management tooling; no WiX custom actions.

Consequences

• Positive: opt-in startup honors NFR-RES-4 with zero idle cost; install location/scope reuse the installers' native behavior (no custom code to maintain); one small INI + a first-run guard covers the whole deployment-customization surface and works for MSI, NSIS, and portable copies alike.
• Guardrail — no secrets in the deploy file (CLAUDE.md): the INI must never carry credentials. deploy.rs drops any key containing key/token/secret/credential/password as defense in depth; API keys, OAuth tokens and sync passwords remain in the OS credential store only. Seeding a provider (e.g. llm_provider=anthropic) still requires the admin/user to provision its key separately — no new egress path is created by the file.
• Negative / care: the seed runs only when settings.json is absent (truly first run); it does not re-apply on upgrade, matching "the user's own settings win thereafter." Array config merges in Tauri replace rather than append, so wa-defaults.ini must be listed in both tauri.conf.json and tauri.vulkan.conf.json bundle resources (the shipped build uses the latter).

Revisit if

Admins need per-machine policy that overrides user settings on every launch (not just seeds first-run), or a signed/locked-down enterprise policy channel beyond a plain INI.