PRODUCT.md: impeccable product record — local-first promise, four fixed voices, honest-status principles; sonar look incumbent but not binding

PRODUCT.md

@@ -0,0 +1,61 @@
+# Product
+
+<!-- impeccable:product-schema 1 -->
+
+## Platform
+
+web
+
+(Implementation is Compose Multi/Desktop — JVM desktop app; recorded as `web` per schema since no native mobile target. The desktop app is the only shipped surface.)
+
+## Users
+
+Primary: the creator himself — heavy voice-memo user (meetings, phone calls, dictated thoughts) on a Framework laptop running Omarchy/Hyprland. Situation: a growing pile of audio files on disk that he never has time to re-listen to. Job: turn recordings into trustworthy text (transcripts) and useful summaries without any cloud involvement.
+
+Secondary (confirmed intent): other people may install it later, so the UI must stay presentable and self-explanatory to an outsider — no private-joke labels, no undocumented setup steps buried in code.
+
+## Product Purpose
+
+Shonar Desktop watches a local recordings folder, transcribes each file with Whisper and writes a summary with an LLM, then presents everything as a browsable, searchable library with playback. Success = the user opens any recording and gets its summary/sections (key points, decisions, action items, details) in seconds, and can re-summarize in different voices, with zero data leaving his network.
+
+## Positioning
+
+Local-first pipeline: audio never leaves the machine or LAN. Transcription is Whisper (Base default, Large v3 downloadable); summarization rides the private LAN GPU (H200 via 10.x network) when available, with automatic rescue onto the laptop's own Ollama when the LAN server fails — and the UI names which summarizer wrote each summary. A cloud SaaS competitor cannot copy "your recordings were never on anyone's server."
+
+## Operating Context
+
+- Library = files on disk (~/Music/Recordings), not a database; the engine mirrors them. Sidecar files (`*.shonar.json`, `*.transcript.md`) live next to the audio.
+- Bundled FastAPI engine on 127.0.0.1:8000 with SQLite + an inline job queue; auto-transcribe pump processes new files.
+- Real usage loop: record on phone → files sync in → app transcribes/summarizes → user skims summaries, re-summarizes in a voice (Neutral / Sarcastic / Funny / Dry wit), copies summary or action items into notes/messages.
+- In-app mpv playback with seek; delete is undoable (trash + 10s undo).
+
+## Capabilities and Constraints
+
+- Privacy is the binding product promise: no INTERNET permission on the sibling Android app; the desktop engine binds 127.0.0.1; the LAN LLM is a private 10.x address, never public internet. Any UI or feature must not imply or require cloud connectivity.
+- Voice personas are exactly four (Neutral, Sarcastic, Funny, Dry wit) — user-fixed, do not grow the list.
+- Honest status is a standing user demand: progress labels must reflect truth (transcribe shows real %; summarize shows "working · m:ss" because the LLM gives no real fraction); unfinished integrations are hidden/labeled, never left configurable.
+- Per-recording model override; tone rides the job; user-edited transcripts are final (re-transcribe never overwrites them).
+- Compose Desktop (Kotlin/Material3) + FastAPI backend; SQLite; engine state in ~/.config/shonar-desktop/.
+
+## Brand Commitments
+
+- Name "Shonar" is fixed. The current deep-sea sonar look (deep navy + teal, sonar-ping logo) is the incumbent identity but explicitly NOT binding — the visual world may evolve in a future redesign.
+- Voice of the UI: plain, honest, human sentences ("Summary ready — <file>", "Fix: open Settings → Summarizer…"). No marketing tone.
+
+## Evidence on Hand
+
+- Real transcript reports in ~/Music/Recordings (`*.transcript.md`) — genuine user content; never display, share, or fabricate from it.
+- Working end-to-end pipeline exercised daily (transcribe → summarize → rescue fallback → voice re-summarize), verified via engine DB in dev sessions.
+- Absences to not fabricate: no other users, no testimonials, no benchmarks, no pricing, no hosted service, no mobile app shipping from this repo (the Android sibling is a separate local-only product).
+
+## Product Principles
+
+1. Privacy is the product — every design decision must visibly keep data on the user's network.
+2. Never lie about state: progress, errors, and which model did what are stated plainly.
+3. One button deep: the common loop (open → read summary → copy) needs no manual.
+4. The machine may fail, the workflow may not — rescue paths (fallback summarizer, retry, undo) are surfaced in-UI, not buried in logs.
+5. Built for one, legible to many — personal tool now, but nothing that only its author could decode.
+
+## Accessibility & Inclusion
+
+No formal standard required yet; keep controls keyboard-reachable (detail screen already uses Alt+arrows/Esc) and status text real text, not color-only.