app development context

docs/product/mvp-acceptance.md

@@ -0,0 +1,87 @@
+# MVP Acceptance
+
+The MVP is complete only when the following scenarios work together in the production Swift application. Passing the current native capability proof alone is not sufficient.
+
+## Product scenario
+
+Given that enabled Collectors have observed normal work, when the user opens the Companion Island and asks, "What was I working on, and what should I do next?", then Mastermind:
+
+- responds through the configured Local Provider;
+- uses relevant knowledge from screen, workspace, calendar, terminal, and audio Sources;
+- distinguishes user-confirmed Facts from inferred Assertions;
+- identifies conflicting or stale knowledge;
+- states when evidence is insufficient;
+- attaches an inspectable Context Receipt.
+
+## Presence
+
+- Mastermind launches as a menu bar application without a Dock icon.
+- Only the stable Menu Bar Item is visible at rest.
+- Hover reveals the Companion Island on the primary display.
+- Click expands it and focuses text input.
+- Show Mastermind in the menu provides a reliable fallback.
+- The expanded surface contains assistant, history, source, provider, graph, audit, and privacy controls.
+
+## Continuous collection
+
+- Enabled Collectors start after launch unless paused state was persisted.
+- Screen collection follows the display containing the key window and processes meaningful changes rather than every full frame.
+- Microphone and system audio remain separate through local ASR.
+- Workspace collection is limited to explicitly connected roots.
+- Calendar and Reminders are read-only and limited to selected calendars and lists.
+- Terminal collection retains command metadata but not stdout or stderr by default.
+- Low Power Mode and thermal pressure reduce processing without corrupting state.
+- One failed Collector does not stop healthy Collectors.
+
+## Local-only processing
+
+- Packet inspection and integration tests confirm that Source content does not leave the Mac.
+- The configured Local Provider accepts only loopback or Unix-socket endpoints.
+- OCR, ASR, embeddings, Fact extraction, retrieval, and answer generation work without internet access.
+- Raw screen frames, audio, OCR text, and full transcripts are destroyed after local reduction.
+- When a required local processor is unavailable, Mastermind records a Gap and does not queue raw content.
+
+## Knowledge integrity
+
+- Observations are immutable until retention removes them.
+- Assertions retain time, confidence, and Provenance.
+- Conflicting Assertions coexist and produce an explicit conflict instead of silent overwrite.
+- Only explicit user confirmation or correction creates a Fact.
+- Confirmed Facts survive normal age and size eviction.
+- Ambiguous entity matches stay separate until confidence is sufficient or the user merges them.
+- Context retrieval treats instructions inside Source content as untrusted data.
+
+## Retention and control
+
+- Inferred context defaults to 90 days and 2 GB and can be reconfigured.
+- Eviction uses `lastObservedAt` and does not evict confirmed Facts.
+- Assistant History has no automatic TTL.
+- The user can delete one Assistant Session or all Assistant History.
+- Pause All immediately stops every Collector and remains paused after relaunch.
+- Resume All restarts only enabled and permitted Collectors.
+- The encrypted archive round-trips context, history, policies, and settings without Provider credentials.
+
+## Trust and diagnostics
+
+- The Menu Bar Item menu shows the real state of every Collector despite the stable glyph.
+- macOS capture indicators and permission surfaces remain unmodified.
+- Activity Log records Collector lifecycle, Gaps, permission errors, and Provider requests without Source content.
+- Context Receipts name the Provider and all supporting Sources and Observations.
+- The sanitized diagnostic bundle contains no prompts, answers, Facts, OCR, ASR, or Provider payloads.
+- Mastermind's windows are excluded from its own screen context.
+- Third-party capture exclusion is presented and tested as best effort, never guaranteed.
+
+## Assistant boundary
+
+- The assistant streams text answers in Russian, English, and mixed-language work.
+- Outputs are answers, plans, or drafts only.
+- The production target contains no Computer Control, Tool Executor, autonomous action, Codex login, Codex app-server, or hidden experimental Cloud Provider.
+- If the Local Provider is unavailable, existing graph search, history, settings, and diagnostics remain accessible.
+
+## Definition of done
+
+- Automated tests cover domain invariants, retention, encryption boundaries, policy defaults, independent Collector failure, and raw-buffer disposal.
+- Integration tests use synthetic Sources and local mock sidecars.
+- Manual tests cover macOS permissions, microphone, system audio, screen exclusion, primary-display changes, Launch at Login, sleep/wake, Low Power Mode, and relaunch while paused.
+- Logs and fixtures contain no captured user content.
+- Canonical documentation and implementation vocabulary agree with `CONTEXT.md`.