WhispAssist/docs/01-requirements.md

# 01 — Requirements

Each requirement has a stable ID used across the roadmap, tests, and commits. Priority:
**M** = must (v1), **S** = should, **C** = could (later). Each FR notes the phase that delivers it
(see `05-roadmap.md`).

## Functional requirements

### Audio capture (CAP)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-CAP-1 | M | 1 | Capture system (loopback) audio on Windows via WASAPI without a meeting bot or microphone. |
| FR-CAP-2 | M | 1 | Write captured audio to disk continuously during recording (audio = source of truth). |
| FR-CAP-3 | M | 1 | Start, stop, pause, and resume recording from the UI. |
| FR-CAP-4 | M | 1 | Show an unambiguous "recording active" indicator (in-app banner + tray icon). |
| FR-CAP-5 | S | 7 | Render a live input waveform / level meter while recording. |
| FR-CAP-6 | S | 7 | Handle audio device changes mid-recording without losing the session. |
| FR-CAP-7 | S | 1 | Optionally capture the user's **microphone** alongside loopback, mixing it into **both** the live transcript and the saved recording (default ON, local-only/no egress, selectable device + "off"). |
| FR-CAP-8 | S | 1 | Write the retained recording as **16-bit PCM** at the device's native rate/channels — roughly half the size of the 32-bit-float mix, with no material quality loss for speech. |
| FR-CAP-9 | S | 1 | **Cancel** an in-progress recording: stop capture, delete working files, and remove the meeting from the DB entirely (for one started by mistake — no finalize/transcript/sync). |

### Recording retention & consent (REC) — see ADR-0009

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-REC-1 | M | 1 | "Record this meeting" is **off by default** (global default + per-meeting toggle). When on, the meeting's audio is retained and saved as a `.wav` file; when off, working audio is deleted on finalize and only the transcript/notes persist. |
| FR-REC-2 | M | 1 | Before retaining a recording for the first time (and shown near the toggle thereafter), display a consent notice: recording without participants' consent may be illegal in some regions; advise checking local laws. Require a one-time acknowledgment; store it. This is a caution, not legal advice. |
| FR-REC-3 | M | 1 | When retention is on, the UI indicates the meeting is being **saved** (in addition to the "recording active" indicator, FR-CAP-4). |
| FR-REC-4 | M | 2 | Deleting working audio on finalize happens only **after** the transcript is successfully finalized; never race with crash recovery (audio stays source of truth until then). |
| FR-REC-5 | S | 2 | Play a meeting's retained `.wav` back in the app (decrypting a vault-sealed recording on demand for playback). |

### Hardware acceleration (HW)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-HW-1 | M | 3 | Detect available compute backends at startup and on demand: NPU, NVIDIA, AMD, Intel GPU, CPU. |
| FR-HW-2 | S | 3 | Select the best backend by the order NPU→NVIDIA→AMD→Intel→CPU; allow a manual override. |
| FR-HW-3 | M | 3 | Display the active backend, model size, and estimated RTF in Settings and the recording bar. |
| FR-HW-4 | M | 3 | Fall back gracefully to a lower tier (down to CPU) when a backend is unavailable or fails. |

### Transcription (TRX)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-TRX-1 | M | 1 | Transcribe audio to timestamped text segments using a Whisper-class model (CPU baseline). |
| FR-TRX-2 | M | 1 | Stream interim transcript segments to the UI in near real time during recording. |
| FR-TRX-3 | S | 3 | Offer a post-meeting batch re-transcription with a larger model for higher accuracy. |
| FR-TRX-4 | S | 8 | Support multiple languages via multilingual Whisper models; expose language selection/auto. |
| FR-TRX-5 | M | 3 | Run accelerated inference (NPU/GPU) when available; identical segment output across backends. |

### Speaker diarization & naming (SPK)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-SPK-1 | M | 4 | Assign internal speaker IDs (S1, S2, …) to transcript segments via offline diarization. |
| FR-SPK-2 | M | 4 | Let the user name a speaker during recording; apply to that speaker's past & future segments. |
| FR-SPK-3 | M | 4 | Provide a post-meeting review to rename speakers and **merge** over-split speakers. |
| FR-SPK-4 | S | 6 | Populate the naming UI with attendees from the linked calendar event, plus "add new name". |
| FR-SPK-5 | M | 4 | Persist speaker→name mappings and apply them at render/export (never destructively rewrite). |

### Notes & Markdown (NOTE)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-NOTE-1 | M | 2 | Present meeting notes as rendered Markdown with speaker-tagged dialogue sections. |
| FR-NOTE-2 | M | 2 | Edit notes (headings, bold/italic, lists, checkboxes) via Markdown syntax and/or a toolbar. |
| FR-NOTE-3 | M | 2 | Export a meeting's notes as `.md`. |
| FR-NOTE-4 | S | 8 | Export notes as PDF and/or Word via local conversion (no cloud). |
| FR-NOTE-5 | C | 8 | User-defined note templates by meeting type (e.g. Sales Call, 1:1, Standup). |
| FR-NOTE-6 | S | 2 | Show raw transcript and rendered notes side-by-side. |

### Local LLM (LLM)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-LLM-1 | M | 5 | Configure a local LLM provider (Ollama default, custom OpenAI-compatible endpoint, or off). |
| FR-LLM-2 | M | 5 | Generate a summary, decisions, and action items from transcript + metadata (+ optional template). |
| FR-LLM-3 | M | 5 | Parse LLM output into editable action items the user confirms before they become tasks. |
| FR-LLM-4 | S | 5 | Stream LLM output token-by-token into the summary panel. |
| FR-LLM-5 | S | 5 | Detect a missing provider and offer guided install + hardware-aware model suggestions. |
| FR-LLM-6 | M | 5 | Validate the endpoint is local; if remote/proxying, show a clear "data leaves WA" banner. |

### External AI providers (AI) — see ADR-0011 (Layer 1), ADR-0007 update

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-AI-1 | S | 10 | Optionally configure a **hosted** summary provider behind the same `LlmProvider` model: Anthropic Messages API and an OpenAI-compatible client (OpenAI, OpenRouter, LM Studio, gateways). Off by default. |
| FR-AI-2 | M | 10 | Hosted providers are explicit third-party egress: off by default, labeled "data leaves your device", host added to the settings-derived allowlist, API keys in the OS credential store (never settings/DB). |
| FR-AI-3 | S | 10 | Per-use provider selection is allowed (e.g. local Ollama for one meeting, Claude for another); the active provider is shown wherever a summary is generated. |

### MCP server — WhispAssist as a tool source (MCP) — see ADR-0011 (Layer 2)

WA exposes its own meeting context to the user's coding agents (Claude, Codex, Copilot, OpenCode,
…) via a local MCP server. This is the primary "get started right away" handoff (**pull** model).

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-MCP-1 | S | 10 | WA can expose a **local MCP server**, **off by default**, bound to loopback, requiring a token; explicit enable. |
| FR-MCP-2 | M | 10 | Capabilities are exposed as MCP **tools** (not resources/prompts) for max client compatibility (Copilot cloud agent supports tools only): e.g. `list_recent_meetings`, `get_transcript`, `get_action_items`, `get_feature_brief`. |
| FR-MCP-3 | M | 10 | **Scope control:** the user chooses which meetings/artifacts are exposed; recordings (`.wav`) are never exposed unless explicitly allowed. |
| FR-MCP-4 | S | 10 | **Feature brief** primitive: distill a transcript (via the configured LLM) into a structured, agent-ready spec — problem, desired outcome, acceptance criteria, target repo/context, source meeting — served by `get_feature_brief`/`create_feature_brief`. |
| FR-MCP-5 | M | 10 | **Disclosure + audit:** the UI states that a connected agent may send served data to its provider's cloud (outside WA's control); WA logs what each agent read. |
| FR-MCP-6 | S | 10 | Support both MCP transports: **stdio** (thin adapter) and **Streamable HTTP** on loopback (`/mcp`). HTTP+SSE (deprecated) is not used. |
| FR-MCP-7 | M | all | The MCP server is **inbound on loopback** and adds no WA egress; enabling it must not add any host to the egress allowlist. |

### Agent push & task-tracker handoff (AGENT) — see ADR-0011 (Layer 3, later)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-AGENT-1 | C | 10c | Optional `AgentRunner`: spawn a local coding-agent CLI headless (`claude -p`, `codex exec`, `opencode run`, `copilot`) against a user-chosen repo to produce a branch/PR from a feature brief. |
| FR-AGENT-2 | C | 10c | Optional task-tracker handoff: create a GitHub issue from a confirmed action item / feature brief; optionally assign Copilot's cloud agent. Third-party egress: off by default, labeled, allowlisted. |

### Storage & persistence (STORE)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-STORE-1 | M | 2 | Persist audio, transcript, notes, and metadata locally (files + SQLite index). |
| FR-STORE-2 | S | 2 | Configure base storage directory and a retention policy (max size and/or max age). |
| FR-STORE-3 | M | 2 | Single-meeting export (audio + transcript + notes) to a chosen folder. |
| FR-STORE-4 | S | 8 | Bulk export by date range or tag. |
| FR-STORE-5 | M | 2 | List, open, and delete meetings. |

### Search & tagging (SEARCH)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-SEARCH-1 | S | 8 | Full-text search across transcripts and notes (SQLite FTS5). |
| FR-SEARCH-2 | S | 8 | Tag meetings (project/client/topic) and filter the list by date, tag, or participant. |

### Calendar & Outlook .pst (CAL)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-CAL-1 | S | 6 | Read a user-selected `.pst` (with optional password) and extract events + attendees. |
| FR-CAL-2 | S | 6 | Show upcoming/recent meetings; let the user attach a recording to an event. |
| FR-CAL-3 | S | 6 | Display pre-meeting context: title, organizer, participants. |
| FR-CAL-4 | C | 6 | Link a recording to a historical event from `.pst` history. |
| FR-CAL-5 | C | 8 | Create local reminders / OS notifications for action items. |
| FR-CAL-6 | C | later | Optional Microsoft Graph calendar source (explicit consent; calendar metadata only). |

### Remote sync / upload (SYNC) — see ADR-0010

Sync is an **explicit, user-configured export**; it is the only egress for meeting content besides
the local LLM endpoint, and it is **off by default**. Primary targets are self-hostable.

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-SYNC-1 | M | 9 | Sync is disabled by default. No artifact is uploaded anywhere unless the user has configured a target and explicitly enabled it (with acknowledgment). |
| FR-SYNC-2 | M | 9 | Configure one or more **WebDAV** targets covering the primary set — **Nextcloud, ownCloud, Cloudreve, Seafile** — and **Synology** (URL + username + app password; user-chosen remote base path). |
| FR-SYNC-3 | M | 9 | Choose, per target, **what** to upload (transcript, notes, summary, and — only if retained per FR-REC-1 — the `.wav` recording) and **when** (on finalize, manual "Upload now", and automatic retry). |
| FR-SYNC-4 | M | 9 | "Test connection" validates a target's reachability + credentials before saving. |
| FR-SYNC-5 | M | 9 | Durable upload queue with per-job status, exponential-backoff retry, SHA-256 skip-if-unchanged (idempotent), and resumable/chunked upload for large recordings. |
| FR-SYNC-6 | M | 9 | Store target credentials in the OS credential store (Windows Credential Manager / DPAPI), never in `settings.json` or the database. |
| FR-SYNC-7 | M | 9 | Require TLS; refuse plaintext `http://` unless the user explicitly allows it for a LAN address, with a warning. |
| FR-SYNC-8 | M | 9 | Surface sync state in the UI and label targets: self-hosted/primary as "your server"; third-party clouds carry a clear "data leaves your device to a third party" banner. |
| FR-SYNC-9 | S | 9 | **Secondary** targets via provider APIs + OAuth 2.0 (PKCE, loopback redirect): **OneDrive** (MS Graph), **Dropbox**, **Box**. |
| FR-SYNC-10 | C | 9 | Optional client-side encryption of artifacts before upload (ties to FR-SEC-3): destination holds only ciphertext. |
| FR-SYNC-11 | S | 9 | Show **live per-item upload progress** while syncing (stream the upload body and report bytes sent per artifact). |

### UX, accessibility, recovery (UX)

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-UX-1 | M | 7 | Three-pane layout: meetings list · transcript/notes · summary/action-items/participants. |
| FR-UX-2 | M | 7 | Light/dark themes following system setting, with user override. |
| FR-UX-3 | S | 7 | Keyboard shortcuts for start/stop recording, view toggles, and template apply. |
| FR-UX-4 | S | 7 | Screen-reader-friendly labels and sufficient contrast. |
| FR-REL-1 | M | 2 | Crash recovery: regenerate transcript/notes from persisted audio after an unexpected exit. |
| FR-REL-2 | M | 2 | Auto-save transcript and notes at intervals. |

### Privacy & security (SEC) — see also NFR-SEC

| ID | Pri | Phase | Requirement |
|---|---|---|---|
| FR-SEC-1 | M | all | WA originates **no** outbound connection for audio or transcript content except to destinations the user has explicitly configured: the LLM endpoint (local or, if chosen, a hosted AI provider — ADR-0007/0011), enabled sync targets (ADR-0010), and (Layer 3) a configured task tracker. With none configured, WA makes no content egress at all. Model downloads are the only other allowed egress and are explicit. The **local MCP server is inbound on loopback and is not egress** (FR-MCP-7). |
| FR-SEC-2 | M | 7 | A privacy panel shows current hardware backend, LLM/AI provider endpoint, **every enabled sync target** (self-hosted vs third-party), and **MCP server state** (and that connected agents may forward served data to their own provider), stating exactly what leaves the device. |
| FR-SEC-3 | C | 8 | Optional at-rest encryption of stored audio/transcripts; optional password-protected vault. |
| FR-MODEL-1 | S | 3 | Model management UI: choose Whisper size, download/remove transcription & diarization models. |

## Non-functional requirements

### Performance (PERF)
- **NFR-PERF-1 (M):** Real-time transcription latency under ~2–3 s per phrase on accelerated paths.
- **NFR-PERF-2 (M):** Batch transcription of a 60-min meeting completes within ≤1–2× meeting length
  on CPU-only; faster on NPU/GPU.
- **NFR-PERF-3 (M):** Out-of-the-box defaults run acceptably on a typical Windows laptop with no
  dedicated GPU/NPU (small/efficient model, conservative settings).
- **NFR-PERF-4 (S):** Cold start to interactive UI under ~2 s; heavy components (models) lazy-load
  after the window is shown.

### Resource usage (RES)
- **NFR-RES-1 (M):** Near-zero CPU/GPU/NPU and minimal memory/disk when idle (no recording or active
  transcription) — behave like a lightweight background app; no polling timers when idle.
- **NFR-RES-2 (M):** During recording, prefer accelerated backends but stay responsive on CPU-only.
- **NFR-RES-3 (S):** A "Low overhead" preset caps model size, disables real-time summarization, and
  reduces background indexing.
- **NFR-RES-4 (M):** Do not add WA to OS startup or run invasive background tasks without explicit
  user consent.

### Reliability (REL)
- **NFR-REL-1 (M):** Tolerate audio glitches and device changes without crashing or corrupting data.
- **NFR-REL-2 (M):** Graceful fallback when hardware acceleration is unavailable.
- **NFR-REL-3 (M):** No data loss on crash — audio persisted continuously; derived artifacts
  regenerable.

### Security (SEC)
- **NFR-SEC-1 (M):** Store data under the user profile, respecting Windows ACLs.
- **NFR-SEC-2 (M):** Operate without admin privileges.
- **NFR-SEC-3 (S):** Network egress is restricted to an allowlist derived from user configuration:
  the LLM/AI-provider endpoint, enabled sync target hosts, a configured task tracker, and explicit
  model downloads; nothing else. Verifiable (network test in CI / a privacy self-check). Any
  connection to a host not on the derived allowlist is a defect. The MCP server is inbound and does
  not add to the allowlist.
- **NFR-SEC-4 (M):** Sync and AI-provider credentials/keys live only in the OS credential store; TLS
  is required for sync transport (plaintext only via explicit per-target LAN opt-in). See FR-SYNC-6/7,
  FR-AI-2.
- **NFR-SEC-5 (M):** The MCP server binds to **loopback only**, requires a token, is **off by
  default**, and honors the configured exposure scope; it never serves recordings unless explicitly
  allowed, and logs agent reads (FR-MCP-1/3/5).

### Maintainability & portability (MNT)
- **NFR-MNT-1 (M):** Modular services (audio, transcription, diarization, storage, llm, calendar,
  hardware, notes, sync, mcp) with trait-defined boundaries enabling component replacement.
- **NFR-MNT-2 (S):** Engines selectable/swappable without changes to callers.
- **NFR-MNT-3 (C):** Architecture portable to macOS/Linux/Windows-on-ARM later without a rewrite.
- **NFR-MNT-4 (M):** CPU-only build always compiles; accelerated backends behind Cargo features.

## Traceability

The roadmap (`05-roadmap.md`) tags each task with the FR/NFR it satisfies; the test strategy
(`06-test-strategy.md`) maps tests to the same IDs. A requirement is "done" only when its
acceptance criteria (in the roadmap) pass the tests named for it.