refactor: update architecture documentation and add commenting standards

app development context
native first
2026-09-05 19:40:35 +03:00 · 2026-09-05 04:37:28 +03:00 · 2026-09-05 02:20:11 +03:00 · 2026-02-21 23:19:57 +03:00 · 2026-02-20 23:53:12 +03:00 · 2026-02-20 23:33:29 +03:00
57 changed files with 4004 additions and 695 deletions
@@ -68,7 +68,7 @@ jobs:
    release:
        needs: build
-        runs-on: ubuntu-latest
+        runs-on: macos-latest
        if: github.server_url == 'https://github.com'
        permissions:
@@ -0,0 +1,24 @@
 {
    "configurations": [
        {
            "type": "swift",
            "request": "launch",
            "args": [],
            "cwd": "${workspaceFolder:cheating-daddy}/native/MastermindPOC",
            "name": "Debug MastermindPOC (native/MastermindPOC)",
            "target": "MastermindPOC",
            "configuration": "debug",
            "preLaunchTask": "swift: Build Debug MastermindPOC (native/MastermindPOC)"
        },
        {
            "type": "swift",
            "request": "launch",
            "args": [],
            "cwd": "${workspaceFolder:cheating-daddy}/native/MastermindPOC",
            "name": "Release MastermindPOC (native/MastermindPOC)",
            "target": "MastermindPOC",
            "configuration": "release",
            "preLaunchTask": "swift: Build Release MastermindPOC (native/MastermindPOC)"
        }
    ]
 }
@@ -1,130 +1,146 @@
-# Repo Guidelines
+# Repository Guidelines
-This repository is a fork of [`cheating-daddy`](https://github.com/sohzm/cheating-daddy).
+This repository is reconstructing Mastermind as a Swift-native, local-first personal assistant for macOS. The Electron application is legacy reference code; it is not the target architecture.
 It provides an Electron-based real‑time assistant which captures screen and audio
 for contextual AI responses. The code is JavaScript and uses Electron Forge for
 packaging.
-## Getting started
+## Read first
-Install dependencies and run the development app:
+Before planning or implementing product work, read:
-```
+1. [`CONTEXT.md`](CONTEXT.md) for canonical domain language.
-1. npm install
+2. [`docs/product/mastermind-product-brief.md`](docs/product/mastermind-product-brief.md) for scope and non-goals.
-2. npm start
+3. [`docs/architecture/native-mastermind.md`](docs/architecture/native-mastermind.md) for system boundaries.
 4. [`docs/architecture/system-patterns.md`](docs/architecture/system-patterns.md) and [`docs/architecture/swift-patterns.md`](docs/architecture/swift-patterns.md) for design and implementation standards.
 5. [`docs/development/commenting-standard.md`](docs/development/commenting-standard.md) for documentation rules.
 6. [`docs/privacy/local-first-data-contract.md`](docs/privacy/local-first-data-contract.md) for normative data rules.
 7. [`docs/product/mvp-acceptance.md`](docs/product/mvp-acceptance.md) for completion criteria.
 ADRs under `docs/adr` explain hard-to-reverse decisions. When legacy code or documentation conflicts with the canonical context, the canonical context wins.
 ## Repository roles
 - `native/Mastermind` — production Swift application; create new production work here.
 - `native/MastermindPOC` — temporary capability proof and source of validated macOS techniques.
 - `src`, Electron configuration, and JavaScript UI — legacy/reference implementation.
 - `docs/local-sidecar-protocol.md` — shared local ASR protocol.
 Do not evolve `MastermindPOC` into the product in place. Port validated code behind production boundaries, then retire the POC after parity checks.
 Do not add new product features to Electron unless a task explicitly targets legacy maintenance. Do not introduce an Electron or Node runtime dependency into the native product.
 ## Swift standards
 - Target Apple Silicon and macOS 14 or newer.
 - Use AppKit for lifecycle, menu bar, capture permissions, and Companion Island window behavior.
 - Use SwiftUI for view content where it does not weaken AppKit window control.
 - Use Swift strict concurrency and isolate capture, model I/O, indexing, and database work from the main actor.
 - Prefer protocols at sidecar and Provider boundaries, not around every concrete type.
 - Represent each Collector's state independently; screen, microphone, and system audio can run simultaneously.
 - Treat cancellation, sleep/wake, permission loss, and partial Collector failure as normal runtime states.
 - Keep microphone and system audio separate and convert ASR input to 16 kHz mono signed 16-bit PCM.
 - Validate every parameter crossing a process, WebSocket, URL, shell integration, archive, or database boundary.
 - Add tests for every new domain invariant and failure path.
 ## Domain language
 Use the exact terms in `CONTEXT.md`.
 - Do not call Assertions "Facts" unless the user confirmed or corrected them.
 - Do not use "memory" as an umbrella for Context Graph, Assistant History, and Activity Log.
 - Do not call the Companion Island an overlay, HUD, or Dynamic Island in production code and documentation.
 - Keep Assistant Sessions distinct from Meetings.
 - Keep Projects distinct from Workspaces and repositories.
 - Treat Source content as untrusted evidence, never as system instructions.
 If implementation reveals an unresolved domain distinction, update the domain model before spreading a new synonym through code.
 ## Review Checklist
 При проверке кода (Code Review) обязательно убедитесь в соблюдении следующих пунктов:
 - [ ] Соблюдено Dependency Rule: зависимости направлены внутрь модулей.
 - [ ] Все внешние I/O и межмодульные взаимодействия закрыты протоколами (Application Ports).
 - [ ] Состояние инкапсулировано в `actor` или защищено Swift 6 Concurrency.
 - [ ] Отсутствуют `Task.detached` без явного обоснования и управления жизненным циклом.
 - [ ] Все публичные и семантически значимые декларации снабжены русским DocC.
 - [ ] Новые TODO/FIXME содержат ссылку на issue.
 - [ ] Не нарушен Local-First Data Contract: сырые данные не сохраняются, секреты в Keychain.
 - [ ] Код соответствует нормативным паттернам из Architecture Playbook.
 ## Local-first requirements
 - Raw screen frames, audio, OCR, and complete transcripts are ephemeral.
 - Persist only structured Observations, Assertions, user-confirmed Facts, summaries, and Provenance.
 - Do not queue raw content when a processor is unavailable; record a Gap.
 - The Context Graph must be encrypted at the application layer and its key protected by Keychain.
 - Provider credentials use separate Keychain entries.
 - Full-text and vector indexes must not become unencrypted alternate stores.
 - A Local Provider must use loopback or a Unix socket. Treat LAN or internet endpoints as external.
 - The MVP must not send machine context to a Cloud Provider.
 - Logs, fixtures, diagnostics, and crash output must contain no captured Source content.
 - Pause All stops every Collector and remains paused across restarts.
 Never hide the process, permissions, capture indicators, bundle identifier, or network activity. Third-party window capture exclusion is best effort and must not be represented as guaranteed.
 ## Provider and agent boundaries
 The MVP uses one active OpenAI-compatible Local Provider profile and a separate local ASR sidecar. Mastermind owns its multilingual embedding component.
 Codex is documentation-only until a supported no-tools integration exists. Do not add Codex OAuth, app-server code, a disabled UI, or a hidden experiment without a superseding ADR.
 The assistant may emit an Action Proposal as text. Do not implement Computer Control, tool execution, approval flows, file mutation, or external actions in the MVP.
 ## UI requirements
 - At rest, only the stable Menu Bar Item is visible.
 - Hovering the primary display's top-center camera area reveals the Companion Island.
 - Clicking expands it and focuses text input.
 - Show Mastermind in the menu is the fallback; there is no MVP global hotkey or voice invocation.
 - Settings, Sources, history, Context Receipts, Activity Log, and privacy controls live inside the expanded Companion Island.
 - Respect Reduce Motion and keyboard navigation.
 - Exclude Mastermind windows from its own Screen Collector.
 ## Testing
 For Swift package work:
 ```bash
 swift test
 swift build
 ```
-## Style
+For the current capability proof:
-Run `npx prettier --write .` before committing. Prettier uses the settings in
+```bash
-`.prettierrc` (four-space indentation, print width 150, semicolons and single
+cd native/MastermindPOC
-quotes). `src/assets` and `node_modules` are ignored via `.prettierignore`.
+swift test
-The project does not provide linting; `npm run lint` simply prints
+swift build --product MastermindPOC
-"No linting configured".
+./scripts/build-app.sh
 ```
-## Code standards
+For explicitly requested legacy Electron maintenance:
-Development is gradually migrating toward a TypeScript/React codebase inspired by the
+```bash
-[transcriber](https://github.com/Gatecrashah/transcriber) project. Keep the following
+npm test
-rules in mind as new files are created:
+```
- **TypeScript strict mode** – avoid `any` and prefer explicit interfaces.
+Manual verification is required for Screen Recording, microphone, system audio, window exclusion, primary-display changes, Launch at Login, sleep/wake, Low Power Mode, and persisted Pause All.
 - **React components** should be functional with hooks and wrapped in error
  boundaries where appropriate.
 - **Secure IPC** – validate and sanitize all parameters crossing the renderer/main
  boundary.
 - **Non‑blocking audio** – heavy processing must stay off the UI thread.
 - **Tests** – every new feature requires tests once the test suite is available.
-## Shadcn and Electron
+Do not claim the production MVP complete until the scenarios in `docs/product/mvp-acceptance.md` pass.
-The interface is being rebuilt with [shadcn/ui](https://ui.shadcn.com) components.
+## Formatting
 Follow these guidelines when working on UI code:
- **Component directory** – place generated files under `src/components/ui` and export them from that folder.
+- Use the repository's Swift formatter configuration when one exists; otherwise follow standard Swift API Design Guidelines and existing native code style.
- **Add components with the CLI** – run `npx shadcn@latest add <component>`; never hand-roll components.
+- Use four-space indentation in JavaScript and Markdown examples where indentation is semantic.
- **Component pattern** – use `React.forwardRef` with the `cn()` helper for class names.
+- Use Prettier only for files it supports; do not reformat generated assets or unrelated legacy code.
- **Path aliases** – import modules from `src` using the `@/` prefix.
+- Keep ADRs short and record only decisions that are hard to reverse, surprising without context, and based on a real trade-off.
 - **React 19 + Compiler** – target React 19 with the new compiler when available.
 - **Context isolation** – maintain Electron's context isolation pattern for IPC.
 - **TypeScript strict mode** – run `npm run typecheck` before claiming work complete.
 - **Tailwind theming** – rely on CSS variables and utilities in `@/utils/tailwind` for styling.
 - **Testing without running** – confirm `npm run typecheck` and module resolution with `node -e "require('<file>')"`.
-## Tests
+## Upstream changes
-No automated tests yet. When a suite is added, run `npm test` before each
+This remains a fork of [`sohzm/cheating-daddy`](https://github.com/sohzm/cheating-daddy), but upstream Electron changes are not automatically product direction.
 commit. Until then, at minimum ensure `npm install` and `npm start` work after
 merging upstream changes.
-## Merging upstream PRs
+Before cherry-picking upstream work:
-Pull requests from <https://github.com/sohzm/cheating-daddy> are commonly
+1. Inspect whether it serves legacy maintenance or the native product.
-cherry‑picked here. When merging:
+2. Keep only reusable protocol, test, or migration value.
-
+3. Reject stealth, anti-detection, insecure IPC, and cloud-by-default behavior.
-1. Inspect the diff and keep commit messages short (`feat:` / `fix:` etc.).
+4. Run the relevant Swift and legacy tests.
 2. After merging, run the application locally to verify it still builds and
   functions.
 ## Strategy and Future Work
 We plan to extend this project with ideas from the
 [`transcriber`](https://github.com/Gatecrashah/transcriber) project which also
 uses Electron. Key goals are:
 - **Local Transcription** – integrate `whisper.cpp` to allow offline speech-to-
  text. Investigate the architecture used in `transcriber/src/main` for model
  validation and GPU acceleration.
 - **Dual Audio Capture** – capture microphone and system audio simultaneously.
  `transcriber` shows one approach using a native helper for macOS and
  Electron's `getDisplayMedia` for other platforms.
 - **Speaker Diarization** – explore tinydiarize for identifying speakers in mono
  audio streams.
 - **Voice Activity Detection** – skip silent or low‑quality segments before
  sending to the AI service.
 - **Improved Note Handling** – store transcriptions locally and associate them
  with meeting notes, similar to `transcriber`'s note management system.
 - **Testing Infrastructure** – adopt Jest and React Testing Library (if React is
  introduced) to cover audio capture and transcription modules.
 ### TODO
 1. Research and prototype local transcription using `whisper.cpp`.
 2. Add dual‑stream audio capture logic for cross‑platform support.
 3. Investigate speaker diarization options and integrate when feasible.
 4. Plan a migration path toward a proper testing setup (Jest or similar).
 5. Document security considerations for audio storage and processing.
 6. Rebuild the entire UI using shadcn components.
 These plans are aspirational; implement them gradually while keeping the app
 functional.
 ## Audio processing principles
 When implementing transcription features borrow the following rules from
 `transcriber`:
 - **16 kHz compatibility** – resample all audio before sending to whisper.cpp.
 - **Dual‑stream architecture** – capture microphone and system audio on separate
  channels.
 - **Speaker diarization** – integrate tinydiarize (`--tinydiarize` flag) for mono
  audio and parse `[SPEAKER_TURN]` markers to label speakers (Speaker A, B, C…).
 - **Voice activity detection** – pre‑filter silent segments to improve speed.
 - **Quality preservation** – keep sample fidelity and avoid blocking the UI
  during heavy processing.
 - **Memory efficiency** – stream large audio files instead of loading them all at
  once.
 - **Error recovery** – handle audio device failures gracefully.
 ## Privacy by design
 - **Local processing** – transcriptions should happen locally whenever possible.
 - **User control** – provide clear options for data retention and deletion.
 - **Transparency** – document what is stored and where.
 - **Minimal data** – only persist what is required for functionality.
 ## LLM plans
 There are placeholder files for future LLM integration (e.g. Qwen models via
 `llama.cpp`). Continue development after the core transcription pipeline is
 stable and ensure tests cover this new functionality.
@@ -0,0 +1,111 @@
 # Mastermind
 Mastermind is a personal, local-first macOS assistant that turns activity on the user's Mac into inspectable context for grounded assistance.
 ## Product
 **Mastermind**:
 The personal assistant product and the only target product name.
 _Avoid_: Cheating Daddy, Mastermind Native, AI helper
 **Local Profile**:
 The local identity whose sources, knowledge, history, and policies belong to the current macOS user. A future cloud account may authenticate services but does not own the Local Profile.
 _Avoid_: User account, cloud profile
 **Companion Island**:
 Mastermind's normally hidden interaction surface at the top center of the primary display. Hover reveals a capsule and clicking expands it into the assistant interface.
 _Avoid_: Overlay, HUD, Dynamic Island, floating window
 ## Context acquisition
 **Source**:
 A configured origin from which Mastermind may observe context, such as a workspace, calendar, screen, audio stream, or terminal integration.
 _Avoid_: Connector, data source
 **Collector**:
 The independently operating part of Mastermind that observes one kind of Source and emits Observations.
 _Avoid_: Capture mode, watcher, sensor
 **Observation**:
 Immutable, time-stamped evidence emitted by a Collector about a Source. An Observation is evidence, not a claim that Mastermind treats as true.
 _Avoid_: Event, Fact, memory
 **Gap**:
 An explicit interval in which an enabled Collector could not produce usable Observations.
 _Avoid_: Missing memory, silent failure
 ## Knowledge
 **Context Graph**:
 The Local Profile's structured, time-aware representation of entities, relationships, Observations, Assertions, and Facts.
 _Avoid_: Memory, activity database, transcript archive
 **Assertion**:
 A time-scoped claim inferred from one or more Observations, with confidence and Provenance. Assertions may conflict and expire.
 _Avoid_: Fact, summary
 **Fact**:
 An Assertion explicitly confirmed or corrected by the user. Facts remain until the user removes or supersedes them.
 _Avoid_: High-confidence inference, model output
 **Provenance**:
 The trace from an Assertion, Fact, summary, or answer back to the Source and Observations that support it.
 _Avoid_: Citation text, model reasoning
 **Person**:
 A human relevant to the Local Profile's work.
 _Avoid_: Speaker, participant record
 **Project**:
 An ongoing effort directed toward an outcome. A Project may span multiple Workspaces, Tasks, Events, Meetings, and Artifacts.
 _Avoid_: Repository, folder, session
 **Task**:
 An actionable unit of work represented by an external source. Mastermind understands Tasks but is not their system of record.
 _Avoid_: Action Proposal, reminder
 **Event**:
 A time-bounded occurrence meaningful to the user's work, such as a deadline or milestone.
 _Avoid_: Observation, log entry
 **Meeting**:
 A human interaction inferred from calendar, application, and audio Observations. Audio channel roles do not establish a participant's identity.
 _Avoid_: Assistant Session, Conversation
 **Artifact**:
 A persistent work product or reference relevant to a Project, such as a document or source file.
 _Avoid_: Observation, screen frame
 **Workspace**:
 An explicitly connected directory or repository that provides Artifacts and project context.
 _Avoid_: Project, home directory
 ## Assistance and trust
 **Assistant Session**:
 A bounded text interaction in the Companion Island using one selected Provider. Assistant Sessions are distinct from Meetings.
 _Avoid_: Conversation, capture session, chat memory
 **Provider**:
 An inference service used to generate assistance. A Local Provider runs on the same Mac; a Cloud Provider receives data outside the Mac.
 _Avoid_: Model, agent, sidecar
 **Provider Context Permission**:
 The user's explicit permission for a Cloud Provider to receive locally selected context. Permission is denied by default and can be revoked for future requests.
 _Avoid_: Source Policy, blanket consent
 **Context Receipt**:
 The inspectable record attached to an answer that identifies its supporting context, Provider, and any external data transfer.
 _Avoid_: Citation, Activity Log
 **Activity Log**:
 The local audit trail of Collector lifecycle, permission failures, gaps, and Provider requests without captured content.
 _Avoid_: Assistant History, transcript
 **Assistant History**:
 The persistent local record of Assistant Sessions. It is separate from the Context Graph and Activity Log.
 _Avoid_: Memory, Context Graph
 **Action Proposal**:
 A plan or draft suggested by Mastermind for the user to carry out. It does not authorize Mastermind to act on the Mac.
 _Avoid_: Tool call, agent action, Task
@@ -1,279 +1,97 @@
 <div align="center">
  <img src="assets/images/logo.png" alt="Mastermind Logo" width="200"/>
-  # Mastermind
+# Mastermind
-  ### Your AI Assistant for High-Stakes Conversations
+### A personal local-first assistant for macOS
  *Real-time contextual suggestions when you need them most*
  [![Release](https://img.shields.io/github/actions/workflow/status/ShiftyX1/Mastermind/release.yml?label=release)](https://github.com/ShiftyX1/Mastermind/actions/workflows/release.yml)
  [![License](https://img.shields.io/badge/license-GPL3.0-blue.svg)](LICENSE)
  [![Latest Version](https://img.shields.io/github/v/release/ShiftyX1/Mastermind?include_prereleases&label=latest&color=FFFF00)](https://github.com/ShiftyX1/Mastermind/releases)
  [![Stable Version](https://img.shields.io/github/v/release/ShiftyX1/Mastermind?color=6666FF)](https://github.com/ShiftyX1/Mastermind/releases)
  [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Windows-lightgrey.svg)](#requirements)
 </div>
---
+Mastermind is a Swift-native assistant that builds an inspectable understanding of work happening on a Mac and uses it to answer grounded questions. Its primary interface is the normally hidden Companion Island at the top center of the primary display; a Menu Bar Item remains present while the app runs.
-## What is Mastermind?
+The production product is currently in reconstruction. `native/MastermindPOC` proves the macOS capture and windowing capabilities, while the Electron application under `src` is legacy reference code.
-Mastermind is an **AI assistant** for high-stakes conversations. Whether you're in a job interview, closing a deal, or navigating a complex negotiation, Mastermind analyzes what you see and hear in real-time, providing contextual suggestions and talking points to support your responses.
+## Canonical context
-Think of it as having an experienced coach reviewing the conversation and offering suggestions, helping you recall relevant information and structure your thoughts more effectively. The AI provides support material—you still need to understand, adapt, and deliver the responses in your own words.
+Start here before product or implementation work:
-> [!WARNING]
+- [`CONTEXT.md`](CONTEXT.md) — canonical domain language.
-> **AI models can and do make mistakes.** Suggestions may contain errors, outdated information, or inappropriate content. This tool is designed to assist people who already have relevant knowledge and need help organizing their thoughts—not to fake expertise you don't possess. Always verify critical information and use your own judgment.
+- [`docs/product/mastermind-product-brief.md`](docs/product/mastermind-product-brief.md) — product boundary and MVP.
 - [`docs/product/companion-island.md`](docs/product/companion-island.md) — interaction model.
 - [`docs/product/mvp-acceptance.md`](docs/product/mvp-acceptance.md) — completion criteria.
 - [`docs/architecture/native-mastermind.md`](docs/architecture/native-mastermind.md) — production architecture map.
 - [`docs/architecture/system-patterns.md`](docs/architecture/system-patterns.md) — normative system patterns.
 - [`docs/architecture/swift-patterns.md`](docs/architecture/swift-patterns.md) — Swift implementation standards.
 - [`docs/development/commenting-standard.md`](docs/development/commenting-standard.md) — documentation rules.
 - [`docs/privacy/local-first-data-contract.md`](docs/privacy/local-first-data-contract.md) — normative privacy and data rules.
 - [`docs/adr`](docs/adr) — hard-to-reverse decisions and their rationale.
-### The Hidden Assistant Advantage
+When older code or text conflicts with these documents, the canonical context wins.
-Mastermind operates discreetly with a transparent overlay that blends into your screen. The system analyzes both visual content and audio in real-time, generating contextual suggestions within seconds. It adapts its suggestions based on your selected scenario—interview, sales, meeting, or presentation. Ghost mode allows you to interact with content behind the overlay without closing it.
+## MVP direction
-**Remember:** This is an assistive tool, not a magic solution. It works best when you have genuine knowledge and need support organizing your thoughts under pressure.
+- Apple Silicon and macOS 14 or newer.
 - Swift/AppKit host with SwiftUI content where appropriate.
 - Continuous local context from screen, microphone, system audio, selected workspaces, selected calendars and Reminders lists, and terminal metadata.
 - Ephemeral raw screen/audio/transcript data; only structured local derivations persist.
 - Encrypted local Context Graph with inspectable Provenance.
 - User-confirmed Facts kept distinct from inferred Assertions.
 - OpenAI-compatible Local Provider over loopback or a Unix socket.
 - Separate local ASR sidecar using 16 kHz mono PCM.
 - Russian, English, and mixed-language work.
 - Text answers, plans, and drafts only; no autonomous actions.
-## Key Features
+Codex is a future Provider direction and is deliberately absent from the MVP until an official no-tools integration boundary exists.
-### Real-Time Multi-Modal Analysis
+## Privacy boundary
 Mastermind captures your screen and audio simultaneously, processing both visual content and audio streams to understand conversation context. It analyzes what's being discussed and generates relevant suggestions based on that context. The system supports dual-stream audio capture to distinguish between system audio and your microphone input, though transcription accuracy depends on audio quality, accents, and background noise.
-### Local-First Privacy Option
+The MVP does not send machine context to cloud services. Mastermind does not hide its process, permissions, capture indicators, or network activity from macOS or managed environments.
 Choose between cloud AI providers for maximum performance or run everything locally with Ollama integration and offline Whisper.js transcription. When using local processing, no audio or screen data ever leaves your machine. The local transcription engine uses ONNX Runtime with GPU acceleration support for fast, private speech-to-text conversion.
-### Conversation History & Context
+Window exclusion from the app's own capture is required. Exclusion from third-party capture is best effort and is never guaranteed.
 Mastermind saves conversation turns during the session, building context as the conversation progresses. You can view session history and export conversations for later review. The AI uses this accumulated context to provide more relevant suggestions as it learns about the discussion topic—though the quality of contextual understanding is limited by the AI model's capabilities and the clarity of the captured audio/screen content.
-### Specialized Profiles
+## Current native capability proof
-Mastermind comes with six pre-configured personas designed for different scenarios:
+`native/MastermindPOC` currently demonstrates:
-**Job Interview** — Suggested responses to technical and behavioral questions, STAR method frameworks, and structured talking points based on your background.
+- a menu bar application and transparent AppKit panel;
 - ScreenCaptureKit screen and system-audio capture;
 - AVAudioEngine microphone capture;
 - separate 16 kHz PCM output for microphone and system audio;
 - current-process window exclusion;
 - click-through, hide/show, opacity settings, and Pause All;
 - Swift unit tests and app-bundle build script.
-**Sales Call** — Objection handling suggestions, closing technique ideas, pricing strategy considerations, and rapport building approaches.
+See [`docs/migration/native-poc-results.md`](docs/migration/native-poc-results.md) for verified and manual checks. The POC is not the production application and will be retired after its validated capabilities are ported to `native/Mastermind`.
-**Business Meeting** — Data-driven talking points, strategic recommendations, and action-oriented communication suggestions.
+### Build and test the POC
 **Presentation** — Fact-checking support, audience engagement ideas, and recovery suggestions for unexpected situations.
 **Negotiation** — Tactical considerations, counter-offer frameworks, and strategic talking points to support your position.
 **Exam Assistant** — Information lookup and answer suggestions for exam questions, optimized for quick reference.
 ### Invisible Design
 The transparent overlay stays on top without blocking your view, with keyboard-driven positioning for quick adjustments. You can hide the window instantly with one click if needed, and customize opacity to match your environment perfectly.
 ### Flexible AI Backend
 Mastermind supports multiple AI providers and can work with both cloud and local models:
 **Google Gemini** — Fast, cost-effective multimodal processing with excellent vision capabilities. Supports Gemini 2.0 Flash with real-time API for ultra-low latency responses.
 **OpenAI** — Industry-leading language understanding with GPT-4 and GPT-4o models.
 **Groq** — High-speed inference with competitive pricing and excellent performance.
 **Ollama** — Run completely local AI models on your machine for full privacy. No data ever leaves your device.
 **Any OpenAI-Compatible API** — Connect to LocalAI, LM Studio, or any custom endpoint that follows the OpenAI API format.
 ---
 ## Advanced Features
 **Response Modes** — Toggle between Brief mode (1-3 sentences, optimal for quick glances) and Detailed mode (comprehensive explanations with full context) based on your needs during the session.
 **Google Search Integration** — Optional real-time web search capability allows the AI to fetch current information. Note that search results may include outdated or incorrect information—always verify critical facts from authoritative sources.
 **Custom System Prompts** — Tailor the AI's behavior with custom instructions specific to your industry, role, or situation. Add your resume, company information, or specialized knowledge to improve context relevance.
 **Multi-Language Support** — Works in 30+ languages including English, Spanish, German, French, Japanese, Korean, Chinese, Hindi, Arabic, and many more. Auto-detection available for multilingual conversations, though accuracy varies by language and accent.
 **Customizable Keyboard Shortcuts** — Every shortcut can be remapped to your preference. Create your own workflow that feels natural to you.
 ---
 ## Getting Started
 ### Installation
 #### For Users (Recommended)
 Download the latest release for your platform from the [GitHub Releases](https://github.com/ShiftyX1/Mastermind/releases) page:
 **macOS:**
 1. Download `Mastermind-[version].dmg`
 2. Open the DMG file and drag Mastermind to your Applications folder
 3. Launch Mastermind from Applications (you may need to allow the app in System Preferences → Security & Privacy on first launch)
 **Windows:**
 1. Download `Mastermind-[version]-Setup.exe`
 2. Run the installer and follow the setup wizard
 3. Launch Mastermind from the Start menu or desktop shortcut
 #### For Developers
 If you want to build from source or contribute to development:
 ```bash
-# Clone the repository
+cd native/MastermindPOC
-git clone https://github.com/ShiftyX1/Mastermind.git
+swift test
-cd Mastermind
+swift build --product MastermindPOC
-
+./scripts/build-app.sh
 # Install dependencies
 pnpm install
 # Launch in development mode
 pnpm start
 # Build distributable packages (DMG for macOS, Setup.exe for Windows)
 pnpm run make
 # Package without creating installers
 pnpm run package
 ```
-### First-Time Setup
+## Legacy Electron application
-**Get Your AI Key:** Start by obtaining an API key from [Google AI Studio](https://aistudio.google.com/apikey) (recommended for beginners), [OpenAI Platform](https://platform.openai.com/api-keys), [Groq Console](https://console.groq.com), or configure a local Ollama instance for complete privacy.
+The Electron implementation remains available as reference during reconstruction. New product functionality belongs in the Swift application.
-**Configure Your Assistant:** Enter your API key in the main window and select your preferred AI provider and model. Choose your primary use case profile from the six available scenarios. Select your language or use Auto for multilingual support.
+```bash
 npm install
 npm test
 npm start
 ```
-**Start Your Session:** Click "Start Session" to activate your hidden assistant. Grant screen recording and audio capture permissions when prompted by your system. Position the overlay window where it's most useful and adjust opacity to blend naturally with your environment.
+Do not use Electron UI, storage, provider coupling, or marketing copy as the source of truth for the native product.
-### Daily Usage
+## Responsible boundary
-**Starting a Session:** Select the appropriate profile for your scenario—Interview, Sales, Meeting, Presentation, Negotiation, or Exam. Adjust opacity and position to blend naturally with your environment. Choose your audio mode: Speaker Only (system audio), Microphone Only, or Both for dual-stream capture.
+Mastermind is a personal work assistant. It is not a proctoring bypass, process-hiding system, monitoring-evasion tool, or means to conceal prohibited AI use. AI output can be wrong; grounded answers must expose evidence and uncertainty.
 **During Your Conversation:** The AI analyzes your screen and audio context in real-time, with suggestions appearing in the overlay. You can type questions directly for clarification and use keyboard shortcuts to reposition or hide the window. Toggle between brief and detailed response modes depending on your needs.
 **Important:** Treat AI suggestions as reference material, not verified facts. Quickly scan suggestions, extract useful points, and deliver responses in your own words with your own understanding. Don't read AI responses verbatim—this often sounds unnatural and may include errors.
 **Pro Tips:** Position the window in your natural eye-line to avoid obvious glances. Use click-through mode when you need to interact with content behind the overlay. Keep sessions focused on one topic for better context. Enable local transcription when working with sensitive information.
 ---
 ## Keyboard Shortcuts
 Master these shortcuts for seamless, discreet operation:
 | Action | Shortcut | Purpose |
 |--------|----------|---------|
 | **Move Window** | `Ctrl/Cmd + Arrow Keys` | Reposition without using mouse |
 | **Toggle Click-Through** | `Ctrl/Cmd + M` | Make window transparent to clicks |
 | **Quick Hide** | `Ctrl/Cmd + \` | Instantly hide/show or go back |
 | **Send Message** | `Enter` | Send text query to AI |
 | **Quick Position** | Custom | Set your favorite window positions |
 > **Pro Tip**: All shortcuts are fully customizable in settings. Create your own stealth workflow!
 ---
 ## Audio Capture Technology
 Mastermind uses advanced audio capture to understand conversations in real-time, with support for both cloud and local transcription.
 **macOS** — Leverages [SystemAudioDump](https://github.com/sohzm/systemAudioDump) for crystal-clear system audio capture. Supports three modes: Speaker Only (system audio), Microphone Only (your voice), or Both (simultaneous dual-stream capture).
 **Windows** — Professional loopback audio capture for system sounds, with full microphone support and dual-stream capabilities for capturing both sides of the conversation.
 **Linux** — Microphone input support. System audio capture is currently in development.
 **Local Transcription** — Built-in offline speech-to-text using Whisper.js powered by ONNX Runtime. Your audio is processed locally on your machine without sending data to external services. Supports GPU acceleration on compatible hardware.
 ---
 ## Use Cases
 ### Job Interviews
 Get suggested responses and frameworks for technical questions, helping you structure your thoughts using proven methods like STAR. Mastermind can help you recall relevant examples from your background and organize talking points, but you need to adapt and deliver them authentically in your own voice.
 ### Sales & Client Calls
 Access reference material for objection handling and competitive positioning. The system can suggest talking points and strategies by analyzing the conversation context, but closing deals requires genuine understanding of your product and the client's needs—AI suggestions are starting points, not scripts to read verbatim.
 ### Business Negotiations
 Receive strategic considerations and framework suggestions based on the conversation flow. Mastermind can help you structure counter-offers and identify discussion points, but successful negotiation requires reading the room, building rapport, and making judgment calls that AI cannot make for you.
 ### Presentations & Demos
 Get quick fact-checking and audience engagement ideas during your presentation. If questions arise, Mastermind can suggest relevant information, but you should verify accuracy and ensure you genuinely understand what you're presenting—especially important for technical content where deep knowledge is expected.
 ---
 ## System Requirements
 | Component | Requirement |
 |-----------|-------------|
 | **Operating System** | macOS 10.15+, Windows 10/11 (latest versions recommended) |
 | **Permissions** | Screen recording, audio capture (system audio and/or microphone) |
 | **Internet** | Required for cloud AI providers (Gemini, OpenAI, Groq). Optional for local Ollama models |
 | **AI Provider** | API key from Gemini, OpenAI, Groq, or local Ollama installation |
 | **For Local Transcription** | 4GB+ RAM recommended, GPU acceleration optional but recommended |
 **Current Version:** 0.7.3
 > [!NOTE]  
 > **Platform Support**: macOS and Windows are fully supported and tested. Linux support is experimental.
 > [!TIP]  
 > **Testing Mode**: When testing, simulate someone asking you questions. The AI responds to detected questions rather than your own queries.
 ---
 ## Known Limitations
 **AI Response Quality** — AI models can make mistakes, provide outdated information, or misinterpret context. Always verify critical information and use suggestions as supporting material, not absolute truth. The quality of responses depends heavily on the AI model you choose and the context you provide.
 **Not a Replacement for Knowledge** — Mastermind is a tool to help you recall and structure information, not to replace your actual expertise. The most effective use is when you already understand the subject matter and need help articulating or remembering specific details.
 **Linux Support** — System audio capture is not yet implemented on Linux. Only microphone input is currently supported.
 **Local Transcription Performance** — First-time usage requires downloading the Whisper model files (approximately 150MB). Transcription speed depends on your hardware; GPU acceleration is recommended for optimal performance.
 **macOS Permissions** — Screen recording and audio capture require explicit system permissions. You may need to restart the app after granting permissions on first launch.
 **Session Context** — The AI maintains context only within the current session. Starting a new session clears previous conversation history (though history can be saved and viewed later).
 ---
 ## Privacy & Ethics
 **Your Data, Your Control:** All audio and screen capture happens locally on your device. API communications are direct and clear between you and your chosen provider. For complete privacy, you can use local AI models through Ollama without any data leaving your machine.
 **Critical Disclaimers:**
 - AI models can generate incorrect, biased, or inappropriate content. Always verify important information from authoritative sources.
 - This tool provides suggestions, not verified facts. You are responsible for the accuracy of what you say.
 - Relying entirely on AI suggestions without understanding the content can backfire—especially in technical or expert conversations where follow-up questions will reveal lack of genuine knowledge.
 **Responsible Use:** 
 Mastermind is designed as a preparation and cognitive support tool—like having notes or a reference guide. It works best when you already have foundational knowledge and need help organizing thoughts or recalling details under pressure.
 **Ethical Boundaries:** Always comply with the rules and policies of your specific context. Many situations explicitly prohibit external assistance:
 - Academic exams and certification tests typically ban any form of external help
 - Some professional interviews and assessments prohibit such tools
 - Certain regulated industries have strict rules about information access during calls
 - Using AI assistance where prohibited can result in serious consequences, including job loss or legal issues
 **Use this tool to support your genuine expertise, not to fake knowledge you don't have.** The best outcomes happen when AI assists someone who understands the subject, not when it replaces actual competence.
 ---
 ## Contributing
-Based on the excellent work from [Cheating Daddy](https://github.com/sohzm/cheating-daddy).
+Read [`AGENTS.md`](AGENTS.md) and the canonical context before making changes. Keep production work inside the Swift-native direction and preserve the local-first data contract.
 Contributions are welcome! Please see [AGENTS.md](AGENTS.md) for development guidelines.
 ---
 ## License
-This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.
+Mastermind is licensed under GPL-3.0. See [`LICENSE`](LICENSE).
 ---
 <div align="center">
 ### A tool to support your expertise, not replace it
 *Use responsibly. Verify information. Understand what you're saying.*
 </div>
@@ -0,0 +1,3 @@
 # Swift-native host with local sidecars
 Mastermind's production runtime is a Swift/AppKit macOS host that owns UI, lifecycle, permissions, capture, policy, and storage. Local LLM and ASR processes stay behind loopback or Unix-socket protocols, while Electron is retained only as legacy reference; this keeps macOS capabilities native without forcing model runtimes into the application process.
@@ -0,0 +1,3 @@
 # Encrypted observation ledger
 The Context Graph uses application-encrypted SQLite/SQLCipher as its source of truth. Collectors append immutable Observations, project versioned Assertions, and create Facts only through explicit user confirmation; this preserves Provenance and temporal conflicts while keeping full-text and vector indexes rebuildable instead of making a separate graph service authoritative.
@@ -0,0 +1,3 @@
 # Continuous Collectors with ephemeral input
 Enabled screen, microphone, system-audio, workspace, calendar, and terminal Collectors run continuously and adapt to power and thermal pressure. Raw frames, audio, OCR, and full transcripts remain ephemeral while only structured local derivations persist; this trades recoverability for a strict local data-minimization boundary, so processor outages are recorded as Gaps rather than buffered raw content.
@@ -0,0 +1,3 @@
 # Defer Codex until a no-tools boundary exists
 Codex integration is excluded from the MVP even though it remains a future Provider direction. The official app-server is an agent protocol and its read-only sandbox does not provide a documented no-tools guarantee, so Mastermind will not ship OAuth, app-server code, or a hidden experimental path until a supported draft-only boundary can enforce the product's no-action contract.
@@ -0,0 +1,46 @@
 # ADR 0005: Strict Clean Architecture and Capability Modules
 ## Context
 Mastermind is a complex macOS application with multiple responsibilities: continuous capture, knowledge extraction, local graph management, and AI assistance. To ensure maintainability, testability, and clear ownership of privacy boundaries, we need a robust architectural structure.
 ## Decision
 We adopt a **Strict Clean Architecture** organized around **Capability Modules**.
 ### 1. Capability Modules
 The codebase is divided into stable capability boundaries:
 - **AppShell**: Orchestration, lifecycle, and composition root.
 - **Observation**: Collectors and raw evidence acquisition.
 - **Knowledge**: The Context Graph, projection, and retrieval logic.
 - **Assistant**: AI sessions, provider routing, and prompt management.
 - **Trust**: Activity logging, health monitoring, and privacy enforcement.
 - **Infrastructure**: Shared utilities, encryption, and low-level storage.
 ### 2. Strict Clean Architecture
 Each module follows Clean Architecture principles:
 - **Entities**: Pure domain models and logic (inner-most).
 - **Use Cases/Services**: Application-specific business rules.
 - **Interface Adapters**: Controllers, presenters, and gatekeepers.
 - **Frameworks & Drivers**: External tools like ScreenCaptureKit, SQLite, and sidecar clients (outer-most).
 ### 3. Compile-Time Dependency Rule
 - Dependencies flow **inwards**: outer layers depend on inner layers.
 - Modules communicate through **Application Ports** (protocols).
 - **Protocols are required** at module boundaries and for all I/O (adapters).
 - Internal module logic does not require protocols for every internal function or value type, avoiding unnecessary boilerplate.
 ### 4. Enforcement
 - Boundaries are enforced by separate Swift targets/modules where possible.
 - The **Composition Root** (in AppShell) is the only place where concrete adapters are instantiated and injected.
 ## Consequences
 - **Pros**: Clearer boundaries, easier to mock dependencies for testing, better isolation of sensitive data processing, and independent evolution of capabilities.
 - **Cons**: Higher initial setup cost for new modules and mandatory boilerplate for cross-module communication.
@@ -0,0 +1,223 @@
 # Native Mastermind Architecture
 ## Scope
 This document defines the production architecture for Mastermind. Domain language comes from [`../../CONTEXT.md`](../../CONTEXT.md), product scope from [`../product/mastermind-product-brief.md`](../product/mastermind-product-brief.md), and privacy invariants from [`../privacy/local-first-data-contract.md`](../privacy/local-first-data-contract.md).
 Нормативные паттерны проектирования и реализации вынесены в отдельные документы:
 - [Системные паттерны](system-patterns.md) — взаимодействие подсистем, потоки данных и безопасность.
 - [Swift Implementation Patterns](swift-patterns.md) — стандарты реализации на Swift, конкурентность и управление состоянием.
 - [Стандарт комментирования](../development/commenting-standard.md) — правила документирования кода.
 The production application lives under `native/Mastermind`. `native/MastermindPOC` is a capability reference, not the production architecture. The Electron application is legacy source material and is not part of the production runtime.
 ## Runtime boundary
 The application host is Swift-native:
 - AppKit owns lifecycle, windows, menu bar behavior, permissions, and capture.
 - SwiftUI may render Companion Island content inside AppKit-controlled windows.
 - Swift concurrency isolates Collectors and processing from the main actor.
 - The host owns the encrypted Context Graph and all policy decisions.
 - Local model processes remain outside the host behind narrow protocols.
 - No Node or Electron process is required.
 Permitted external local processes:
 - an OpenAI-compatible Local Provider on loopback or a Unix socket;
 - a local ASR sidecar using the existing WebSocket protocol.
 Mastermind owns a small multilingual embedding component because chat endpoints do not reliably expose embeddings.
 ## System shape
 ```mermaid
 flowchart LR
    subgraph host [Swift native host]
        AppCoordinator --> MenuBar
        AppCoordinator --> CompanionIsland
        AppCoordinator --> CollectorSupervisor
        CollectorSupervisor --> ScreenCollector
        CollectorSupervisor --> AudioCollectors
        CollectorSupervisor --> WorkspaceCollector
        CollectorSupervisor --> CalendarCollector
        CollectorSupervisor --> TerminalCollector
        ScreenCollector --> LocalReduction
        AudioCollectors --> LocalReduction
        WorkspaceCollector --> LocalReduction
        CalendarCollector --> LocalReduction
        TerminalCollector --> LocalReduction
        LocalReduction --> ObservationLedger
        ObservationLedger --> KnowledgeProjector
        KnowledgeProjector --> ContextGraph
        ContextGraph --> Retriever
        Retriever --> AssistantSession
        AssistantSession --> ContextReceipt
        CollectorSupervisor --> ActivityLog
        AssistantSession --> ActivityLog
    end
    AudioCollectors --> AsrSidecar
    AssistantSession --> LocalProvider
    EmbeddingModel --> KnowledgeProjector
    EmbeddingModel --> Retriever
 ```
 Every arrow carrying Source content stays on the Mac. Activity Log entries contain metadata, not Source content.
 ## Application components
 ### AppCoordinator
 Owns lifecycle and composes the application. It restores the persisted paused state before starting Collectors, coordinates sleep/wake and Launch at Login, and never places heavy processing on the main actor.
 ### CompanionIslandController
 Owns the hidden, revealed, and expanded window states on the primary display. The controller separates non-activating hover behavior from the key window used for text entry and management.
 ### MenuBarController
 Owns the stable status glyph and detailed menu. Collector states are represented in menu content rather than by changing the glyph.
 ### CollectorSupervisor
 Owns independent Collector lifecycles. It starts enabled Collectors, pauses them atomically, persists Pause All, applies power and thermal policy, and records Gaps. One Collector failure must not collapse the rest of the pipeline.
 ### ScreenCollector
 Uses ScreenCaptureKit for pixels and Accessibility for application/window structure. The active display is the display containing the key window, falling back to pointer location and then the primary display. Changed-region detection, OCR, and deduplication reduce pixels locally before immediate disposal.
 Mastermind windows are excluded from its own stream. Third-party exclusion is a best-effort window policy, not a security guarantee.
 ### AudioCollectors
 Microphone and system audio are separate Collectors and remain separate. Both emit 16 kHz mono signed 16-bit PCM frames to VAD and local ASR. The pipeline labels channel role as User Speech or System Speech but does not infer a Person from voice.
 ### WorkspaceCollector
 Observes explicitly connected roots. It respects `.gitignore`, configured excludes, binary detection, and size limits, and emits changes to Artifacts and repository metadata.
 ### CalendarCollector
 Uses EventKit read-only for selected calendars and Reminders lists. External applications remain systems of record for Tasks and Events.
 ### TerminalCollector
 Receives shell integration events for working directory, command, exit status, duration, and Git metadata. It does not persist stdout or stderr by default.
 ## Knowledge pipeline
 ### Observation ledger
 Collectors append immutable Observations. Each record includes:
 - stable identifier;
 - Source identifier and Collector kind;
 - observed time and source event time when available;
 - structured payload;
 - sensitivity metadata;
 - derivation version.
 Observations are retained until age or size eviction. Corrections never mutate them.
 ### Knowledge projector
 The projector derives versioned Assertions, entity relationships, short summaries, and Provenance. Multiple contradictory Assertions may coexist. A current view selects relevant Assertions without erasing history.
 Only explicit user confirmation or correction promotes an Assertion to a Fact. A correction creates a new version and supersedes prior current views; it does not rewrite supporting Observations.
 Entity resolution automatically links only high-confidence matches. Ambiguous entities remain separate and can be merged or split from a Context Receipt.
 ### Context store
 The source of truth is encrypted SQLite/SQLCipher with explicit schema migrations. It stores:
 - Sources and Collector configuration;
 - immutable Observations;
 - entities and relations;
 - versioned Assertions and Facts;
 - Provenance;
 - Assistant History;
 - Context Receipts;
 - Activity Log metadata;
 - retention and Provider policies.
 Full-text and vector indexes are derived and rebuildable. They must not become unencrypted alternate stores.
 The database key is generated locally and protected by Keychain. Provider secrets use separate Keychain entries. An encrypted, versioned archive supports manual export and import without Provider credentials.
 ### Retention
 The default inferred-context budget is 90 days and 2 GB. Eviction considers `lastObservedAt` and utility. User-confirmed Facts are pinned. Assistant History has no automatic TTL and supports per-session and complete deletion.
 Raw frames, audio, OCR, and full transcripts never enter the Context store. If local reduction cannot complete, the system records a Gap.
 ## Retrieval and assistance
 The Retriever combines:
 - structured entity and relationship queries;
 - temporal filtering;
 - full-text search;
 - multilingual vector similarity;
 - recency and confidence;
 - Provenance completeness.
 Retrieved Source content is always untrusted data. It cannot alter system instructions or grant capabilities.
 An Assistant Session binds to one Provider profile. The MVP has one active OpenAI-compatible Local Provider profile at a time and streams text responses. Failure leaves the query draft intact and preserves access to graph search, history, settings, and diagnostics.
 Every answer produces a Context Receipt containing:
 - Provider profile and locality;
 - supporting Sources, Observations, Assertions, and Facts;
 - time range and stale/conflict indicators;
 - any external-transfer record.
 ## State model
 Capture and assistant state are orthogonal. Do not reproduce the POC's single `TrustStatus` enum, which loses information when screen, microphone, and system audio run simultaneously.
 Model at least:
 - one `CollectorState` per Collector: disabled, starting, running, paused, permission-needed, degraded, or failed;
 - an application pause state persisted across launches;
 - Companion Island presentation state;
 - Assistant Session state;
 - Local Provider and sidecar health;
 - Context Graph migration and maintenance state.
 The menu and Activity Log project these states for the user.
 ## Failure rules
 - Permission loss changes only the affected Collector to permission-needed.
 - Processor or sidecar failure creates Gaps; it never creates a raw-content backlog.
 - Database or encryption failure prevents new context writes and surfaces a blocking error.
 - Thermal and low-power pressure reduce sampling and local processing.
 - Quit stops all Collectors and flushes metadata.
 - Relaunch while paused remains paused.
 ## Future boundaries
 ### Cloud Provider
 A future Cloud Provider must implement the Provider boundary and Provider Context Permission. It may receive only minimized, locally filtered context and must generate a Context Receipt for every request.
 ### Codex
 Codex remains documentation-only until it exposes a supported no-tools integration. The MVP has no Codex code or UI.
 ### Agent actions
 The MVP may emit an Action Proposal as text. Computer Control, Tool execution, approvals, and action auditing form a future bounded context and are not represented by executable stubs in the MVP.
 ## Migration direction
 1. Treat `native/MastermindPOC` as evidence that the required macOS capture and window primitives are viable.
 2. Create the production application under `native/Mastermind`.
 3. Port validated capability code behind production state and protocol boundaries.
 4. Build the Context Graph vertical slice and primary acceptance scenario.
 5. Retire the POC after production parity checks pass.
 6. Keep Electron code as legacy reference only; do not migrate its data or runtime.
@@ -0,0 +1,83 @@
 # Swift Implementation Patterns Mastermind
 Этот документ описывает нормативные паттерны реализации кода на Swift.
 ## 1. Concurrency & State Ownership
 **Problem**: Состояние гонки (race conditions) и неопределённое поведение при многопоточности.
 **Rule**: Каждая stateful-возможность (Capability) или сервис принадлежат конкретному `actor`. Межмодульный обмен — только через `Sendable` неизменяемые типы (value types). `MainActor` используется исключительно для UI-проекций.
 **Apply when**: При проектировании хранилищ, сервисов и вью-моделей.
 **Avoid**: Использование `lock`, `DispatchQueue` для синхронизации состояния вручную; захват мутабельного состояния в замыканиях.
 **Trade-offs**: Требует понимания Swift Concurrency и использования `await`.
 **Verification**: Swift 6 Strict Concurrency не должен выдавать предупреждений и ошибок.
 ## 2. Bounded Async Streams
 **Problem**: Неконтролируемое накопление событий в очередях (backpressure) приводит к утечкам памяти и задержкам.
 **Rule**: Все `AsyncStream` должны иметь ограниченный буфер (bounded) и явную политику обработки переполнения (`dropOldest`, `dropNewest` или `coalesce`).
 **Apply when**: Для потоков аудио-фреймов, скриншотов и событий UI.
 **Avoid**: Создание неограниченных потоков событий.
 **Verification**: Каждый стрим должен иметь тесты на поведение при переполнении.
 ## 3. Lightweight UDF (Unidirectional Data Flow)
 **Problem**: Сложная двусторонняя синхронизация UI и бизнес-логики.
 **Rule**: Использование однонаправленного потока данных: Immutable State → View → Intent (Action) → Service/Reducer → New State. Без обязательной зависимости от тяжелых фреймворков (TCA).
 **Apply when**: В реализации Companion Island и экранов управления.
 **Avoid**: Прямая мутация состояния из View; использование `Binding` для бизнес-логики.
 **Verification**: View зависит только от `State` и отправляет `Intents`.
 ## 4. Boundary State Machines
 **Problem**: Неявные переходы между состояниями (например, Collectors) приводят к трудновоспроизводимым багам.
 **Rule**: Использование явных конечных автоматов (State Machines) для жизненного циклаCollectors, сессий и миграций. Недопустимые переходы должны быть невозможны на уровне типов.
 **Apply when**: Управление жизненным циклом сложных компонентов.
 **Avoid**: Большое количество разрозненных `Bool` флагов для описания состояния.
 **Verification**: Unit-тесты покрывают матрицу переходов.
 ## 5. Validated Value Types
 **Problem**: Проброс примитивов (String, Int) через все слои приводит к потере смысла и ошибкам валидации.
 **Rule**: Использование отдельных типов-обёрток для доменных понятий (ID, Timestamp, Confidence). Проверка инвариантов происходит при создании типа.
 **Apply when**: Все доменные сущности и параметры портов.
 **Avoid**: Использование `String` для ID или `Double` для Confidence без обёртки.
 **Verification**: Код компилируется только при передаче правильных типов; невозможны "пустые" или некорректные значения.
 ## 6. Manual Composition Root
 **Problem**: Глобальные синглтоны и Service Locator делают зависимости неявными.
 **Rule**: Использование ручного внедрения зависимостей (Constructor Injection) в единственной точке входа (Composition Root). Глобальные мутабельные синглтоны запрещены.
 **Apply when**: Инициализация приложения в `AppShell`.
 **Avoid**: Использование `shared` instance для бизнес-логики.
 **Verification**: Все зависимости можно подменить (mock) в тестах без изменения кода модулей.
 ## 7. Workflow-Sized Services
 **Problem**: Use cases, которые делают слишком мало (один метод) или слишком много (весь модуль).
 **Rule**: Application Service должен отражать осмысленный пользовательский или системный воркфлоу (например, `AssistantSessionService`) и оркестровать несколько портов.
 **Avoid**: Создание класса UseCase для каждой мелкой функции; "божественные" объекты-координаторы.
 **Verification**: Сервис покрывает логически связанную группу действий.
 ## 8. Typed Failure States
 **Problem**: Обобщённые ошибки `Swift.Error` не дают понимания, как на них реагировать.
 **Rule**: Ожидаемые ошибки моделируются как типизированные состояния (Enum). Ошибки адаптеров переводятся в доменные ошибки на границе модуля.
 **Apply when**: Возврат результатов из портов и сервисов.
 **Avoid**: Проброс `NSError` или `URLError` в доменные слои.
 **Verification**: UI может точно отобразить причину сбоя на основе типа ошибки.
 ## 9. Structured Task Ownership
 **Problem**: Утечки задач (detached tasks) и сложности с отменой (cancellation).
 **Rule**: Каждая долгоживущая `Task` принадлежит владельцу жизненного цикла и отменяется при его завершении. `Task.detached` запрещён, кроме системных воркеров.
 **Apply when**: Запуск Collectors и фоновой обработки.
 **Avoid**: "Fire-and-forget" задачи без сохранения ссылки на отмену.
 **Verification**: Deinit объекта приводит к остановке всех запущенных им задач.
 ## 10. Dedicated Executors for Blocking Work
 **Problem**: Блокировка потока актора или MainActor тяжелыми вычислениями.
 **Rule**: Все блокирующие операции (SQLite, ML, PCM) выносятся на выделенные очереди или исполнители (Dedicated Executors/Queues). Оркестрация акторов не должна выполнять тяжелую работу.
 **Apply when**: I/O, обработка медиа, криптография.
 **Avoid**: Выполнение `Data(contentsOf:)` или сложных циклов на MainActor.
 **Verification**: Профилирование в Instruments не показывает блокировок UI потока.
@@ -0,0 +1,85 @@
 # Системные паттерны Mastermind
 Этот документ описывает нормативные паттерны взаимодействия подсистем Mastermind.
 ## 1. Capability-Oriented Clean Architecture
 **Problem**: Высокая связность между захватом, хранилищем и UI мешает тестированию и безопасности.
 **Rule**: Каждая функциональная область (Capability) инкапсулирована в отдельный модуль с чёткими границами. Взаимодействие происходит через порты (протоколы).
 **Apply when**: При добавлении новой крупной функциональности (например, новый вид захвата).
 **Avoid**: Прямой импорт конкретных реализаций (Adapters) между модулями.
 **Trade-offs**: Требует больше кода для инициализации (Dependency Injection).
 **Verification**: Запрещены перекрёстные импорты в Swift модулях; Unit-тесты используют Mock-реализации портов.
 ## 2. Ports & Async Events
 **Problem**: Глобальные шины событий (EventBus) делают зависимости неявными и затрудняют отладку.
 **Rule**: Запросы и команды идут через явные порты (Application Ports). Факты о произошедшем передаются через типизированные асинхронные потоки событий (Typed Async Events). Глобальная шина запрещена.
 **Apply when**: Для межмодульного взаимодействия.
 **Avoid**: Использование `NotificationCenter` или глобальных `ObservableObject`.
 **Trade-offs**: Требует явной оркестрации в Composition Root.
 **Verification**: Каждый исходящий поток событий должен быть частью интерфейса порта модуля.
 ## 3. Observation Ledger
 **Problem**: Прямая запись результатов захвата в граф знаний приводит к потере контекста и невозможности переобработки данных.
 **Rule**: Collectors записывают только неизменяемые "свидетельства" (Observations) в лог (Ledger). Только Knowledge Pipeline читает этот лог.
 **Apply when**: При обработке любого потока данных из источников (Sources).
 **Avoid**: Прямое обновление Facts или Entities из Collectors.
 **Trade-offs**: Увеличивает объём хранимых данных на диске до момента очистки (Retention).
 **Verification**: База данных содержит таблицу `Observations` с Provenance.
 ## 4. Idempotent Projectors & Durable Checkpoints
 **Problem**: Сбой во время обработки Observations может привести к дублированию или потере знаний в графе.
 **Rule**: Проекторы (Projectors) читают лог Observations и обновляют граф, сохраняя контрольные точки (Checkpoints). Процесс должен быть идемпотентным.
 **Apply when**: При преобразовании сырых данных в Assertions и Facts.
 **Avoid**: Логика проекции, зависящая от текущего времени или внешнего состояния вне лога.
 **Trade-offs**: Усложняет логику обновления графа.
 **Verification**: Перезапуск проектора с одного и того же чекпоинта должен приводить к идентичному состоянию графа.
 ## 5. Capability-Specific Persistence Ports
 **Problem**: Общие репозитории (Generic Repository<T>) скрывают специфичные требования к данным и производительности.
 **Rule**: Каждый модуль определяет свои узкие порты для работы с данными (например, `AppendObservation`, `QueryContext`). Реализация за скрытым SQLite/SQLCipher адаптером.
 **Avoid**: Использование общего DAO или прямого доступа к БД вне адаптера.
 **Verification**: Интерфейсы портов содержат только те методы, которые реально нужны данному модулю.
 ## 6. Central Egress Gate & Privacy Envelopes
 **Problem**: Риск случайной отправки конфиденциальных данных (PII) в облако.
 **Rule**: Весь исходящий трафик к внешним провайдерам проходит через единый Egress Gate. Данные передаются в типизированных конвертах (Privacy Envelopes) с метаданными о классификации.
 **Apply when**: Любая передача данных за пределы Mac (Cloud Providers).
 **Avoid**: Прямые сетевые запросы из Assistant или других модулей.
 **Trade-offs**: Единая точка отказа и бутылочное горлышко производительности.
 **Verification**: Egress Gate блокирует любые данные без явного Provider Context Permission.
 ## 7. Work Scheduler & Budgets
 **Problem**: Непрерывный захват и ML-обработка могут замедлять UI или разряжать батарею.
 **Rule**: Центральный планировщик распределяет задачи по приоритетам и бюджетам ресурсов. Аудио и интерактив всегда выше фоновой индексации.
 **Avoid**: Запуск `Task.detached` без указания приоритета и лимитов.
 **Trade-offs**: Может увеличивать задержку (latency) для фоновых задач.
 **Verification**: Приложение снижает активность в Low Power Mode.
 ## 8. Bounded Derived Caches
 **Problem**: Кэширование может приводить к несогласованности данных и утечкам памяти.
 **Rule**: Все кэши ограничены (bounded), принадлежат конкретным акторам (actor-owned) и могут быть полностью перестроены из Context Store.
 **Apply when**: Для OCR, embeddings и UI элементов.
 **Avoid**: Использование глобального `NSCache` без ограничений по времени и размеру.
 **Verification**: Unit-тесты проверяют очистку кэша при достижении лимитов.
 ## 9. Structured Local Tracing
 **Problem**: Текстовые логи бесполезны для отладки сложных распределённых процессов без передачи контента.
 **Rule**: Использование структурированных спанов и событий с Correlation IDs (SourceID, ObservationID). Redacted metadata — только технические детали.
 **Avoid**: Логирование распознанного текста или аудио-транскриптов.
 **Verification**: Логи не содержат персональных данных пользователя, но позволяют проследить путь конкретной Observation.
 ## 10. Versioned Boundaries
 **Problem**: Изменение формата данных (ASR, LLM, Export) ломает совместимость.
 **Rule**: Все границы (Sidecars, Providers, Archives) используют типизированные DTO с версионированием и Contract Tests. Tolerant Reader обязателен.
 **Avoid**: Сериализация внутренних доменных типов напрямую.
 **Verification**: Наличие тестов на обратную совместимость схем.
@@ -0,0 +1,80 @@
 # Стандарт комментирования Mastermind
 Этот документ устанавливает правила документирования и комментирования кода в Swift-проекте Mastermind.
 ## 1. Язык и стиль
 - **Язык**: Все комментарии, документация DocC и пометки TODO/FIXME пишутся на **русском языке**.
 - **Стиль**: Лаконичный, технический, без лишних слов. Используйте DocC для всех семантически значимых деклараций.
 ## 2. Обязательный DocC
 DocC (тройной слэш `///`) обязателен для следующих элементов:
 - Все типы (Struct, Class, Enum, Actor, Protocol).
 - Все требования протоколов.
 - Все функции, методы и инициализаторы.
 - Все свойства (properties), имеющие самостоятельный доменный или технический смысл.
 **Исключения**:
 - Локальные переменные внутри функций.
 - Очевидные элементы тестовых фикстур (если их смысл понятен из названия).
 - Однородные `enum cases` (можно документировать одной группой перед перечислением).
 ## 3. Формат DocC (Concise Semantic DocC)
 **Правила**:
 - Первая строка — одно предложение, описывающее роль или контракт элемента.
 - Секции `- Parameters:`, `- Returns:`, `- Throws:` добавляются только если они несут дополнительную информацию.
 - **Запрещено**:
  - Пустые секции.
  - Дословный пересказ сигнатуры (например, `/// Возвращает строку` для функции `func getString() -> String`).
  - Комментарии ради комментариев.
 **Пример**:
 ```swift
 /// Обрабатывает входящий аудио-фрейм и извлекает наблюдения.
 ///
 /// - Parameter frame: PCM данные в формате 16 кГц моно.
 /// - Throws: `AudioError.invalidFormat`, если данные повреждены.
 func process(frame: PCMFrame) throws { ... }
 ```
 ## 4. Внутренние комментарии (Inline)
 Используйте двойной слэш `//` только в следующих случаях:
 - **Почему (Rationale)**: Объяснение нетривиального архитектурного решения.
 - **Инварианты**: Описание условий, которые должны соблюдаться в этом блоке кода.
 - **Безопасность и Concurrency**: Пояснения по поводу владения данными или специфики потоков.
 - **OS Quirks**: Описание обходных путей (workarounds) для особенностей macOS/AppKit.
 **Запрещено**:
 - "Narrating comments" — пересказ того, что делает код (например, `// увеличиваем счетчик`).
 - Закомментированный код (удаляйте его, история есть в Git).
 ## 5. Навигация и пометки
 ### MARK
 Используйте `// MARK: -` для разделения больших файлов на смысловые секции.
 - Группируйте методы расширений (extensions) по протоколам, которым они соответствуют.
 - Не используйте MARK для одиночных методов.
 ### TODO и FIXME
 Использование этих пометок разрешено только с указанием ссылки на задачу (issue).
 - `// TODO(#123): Описание задачи и что именно нужно сделать.`
 - `// FIXME(#456): Описание нарушения или риска, который нужно устранить.`
 ## 6. Актуальность
 - Комментарий, не соответствующий коду — это дезинформация.
 - При изменении контракта функции или логики типа, комментарий **обязан** быть обновлён в том же коммите.
 - Устаревшие комментарии должны безжалостно удаляться.
@@ -0,0 +1,77 @@
 # Local ASR Sidecar Protocol
 Mastermind local-first mode expects speech-to-text to run as an external local
 streaming service. The app connects to the service over WebSocket and sends
 16 kHz mono PCM audio.
 ## Default Endpoint
 ```text
 ws://127.0.0.1:8765/v1/asr/stream
 ```
 The endpoint is configurable in the Local AI settings.
 ## Client Start Message
 After the WebSocket opens, the app sends a JSON start frame:
 ```json
 {
  "type": "start",
  "sampleRate": 16000,
  "channels": 1,
  "encoding": "pcm_s16le",
  "language": "en-US"
 }
 ```
 After that, the app sends binary frames containing raw little-endian signed
 16-bit PCM audio at 16 kHz.
 ## Sidecar Events
 The sidecar should send JSON text frames:
 ```json
 { "type": "ready" }
 ```
 ```json
 { "type": "partial", "text": "intermediate transcript" }
 ```
 ```json
 { "type": "final", "text": "final transcript" }
 ```
 ```json
 { "type": "error", "error": "human-readable error" }
 ```
 Only `final` transcript events enter local semantic reduction. `partial` events
 are transient status and must not be persisted.
 ## v1 Scope
 - Required language modes: English (`en-US`), Russian (`ru-RU`), and automatic
  or mixed Russian-English recognition (`auto` or an implementation-equivalent
  mode).
 - Sidecar implementation is external to this repository.
 - The app does not require a specific Nemotron, NeMo, Riva, or ONNX runtime as
  long as the WebSocket protocol above is implemented.
 - The endpoint must be loopback-only. LAN and internet ASR endpoints are not
  Local Providers.
 ## Native macOS Client Compatibility
 The Swift-native app uses the same WebSocket protocol as the Electron client.
 Audio frames are raw 16 kHz mono signed 16-bit little-endian PCM.
 Microphone and system audio use independent client connections so the sidecar
 does not mix channel roles. The sidecar does not need to know whether a client
 is Electron or Swift; Mastermind associates each connection with its Source.
 Full transcripts are ephemeral sensitive input. The Swift client consumes a
 `final` event, derives structured local context, and then releases transcript
 content instead of storing it in Assistant History or the Context Graph.
@@ -0,0 +1,65 @@
 # Native macOS POC Results
 > This document records capability evidence, not the production product specification.
 > Canonical direction is defined by [`../../CONTEXT.md`](../../CONTEXT.md),
 > [`../product/mastermind-product-brief.md`](../product/mastermind-product-brief.md), and
 > [`../architecture/native-mastermind.md`](../architecture/native-mastermind.md).
 ## Implemented
 - SwiftPM-based macOS POC under `native/MastermindPOC`.
 - AppKit lifecycle with a menu bar status item.
 - Transparent non-activating overlay window with hide/show and click-through controls.
 - Overlay window uses `NSWindowSharingType.none` and ScreenCaptureKit filtering excludes the current process windows from app-owned capture.
 - ScreenCaptureKit screen stream proof with frame counters.
 - ScreenCaptureKit system audio proof with best-effort PCM extraction to 16 kHz mono signed 16-bit little-endian frames.
 - AVAudioEngine microphone proof with 16 kHz mono signed 16-bit little-endian frames.
 - Separate microphone and system audio counters in the overlay.
 - Compact HUD controls for Settings, Hide, and Quit.
 - Draggable overlay title area.
 - Settings panel with persisted overlay background opacity.
 - Swift unit tests for status labels, PCM frame metadata, PCM S16LE encoding, and separate audio counters.
 - App bundle build script at `native/MastermindPOC/scripts/build-app.sh`.
 ## Verified Automatically
 - `swift test` passes for `MastermindPOCCore`.
 - `swift build --product MastermindPOC` compiles the native executable.
 - `native/MastermindPOC/scripts/build-app.sh` produces `native/MastermindPOC/build/MastermindPOC.app`.
 - Existing Electron local provider tests pass when run outside the managed sandbox restrictions.
 ## Manual Verification Needed
 - Launch `native/MastermindPOC/build/MastermindPOC.app`.
 - Confirm the menu bar item is visible while the app runs.
 - Confirm the overlay appears locally and can be hidden.
 - Confirm the overlay can be dragged by its top title bar.
 - Confirm the overlay Settings button opens the settings panel.
 - Confirm the opacity slider changes only the HUD background opacity and persists across relaunches.
 - Confirm the overlay Quit button exits the app.
 - Confirm click-through lets pointer events pass to apps underneath.
 - Grant Screen Recording permission when macOS prompts, then restart the POC if needed.
 - Start `Screen + System Audio` and confirm screen frame and system PCM counters increase.
 - Start `Microphone` and confirm microphone PCM counters increase while speaking.
 - Confirm `Pause All Capture` stops screen, system audio, and microphone updates.
 - Confirm app-owned screen capture does not include the Mastermind overlay.
 ## Boundary
 This POC is not a stealth or anti-detection system. It shows a menu bar item while running, requests normal macOS permissions, and only excludes its own overlay from the context it captures for itself.
 ## Role in production migration
 `native/MastermindPOC` proves that AppKit windowing, ScreenCaptureKit screen and system-audio capture, AVAudioEngine microphone capture, current-process exclusion, and 16 kHz PCM conversion are viable.
 Production development moves to `native/Mastermind`. Validated capability code may be ported behind production boundaries, but the POC is not renamed into the product and is retired after parity checks pass.
 The production design intentionally differs from the POC:
 - the Companion Island is hidden at launch and anchored to the primary display's top center;
 - enabled Collectors start continuously after onboarding instead of through manual start menu items;
 - the Menu Bar Item uses a stable glyph with detailed states inside its menu;
 - screen, microphone, and system-audio states are simultaneous per-Collector states rather than one `TrustStatus`;
 - settings and management live inside the expanded Companion Island;
 - screen context follows the active display rather than always selecting the main display;
 - the Context Graph, Local Provider, local ASR client, retention, encryption, Context Receipts, and Activity Log are production requirements not implemented by the POC.
@@ -0,0 +1,145 @@
 # Local-First Data Contract
 This document is normative. Product and implementation work must preserve these boundaries unless a superseding ADR explicitly changes them.
 ## Local-first definition
 Mastermind's Local Profile, Source configuration, captured context, Context Graph, Assistant History, Activity Log, embeddings, and inference remain on the user's Mac in the MVP.
 A Provider is local only when it is reachable through loopback or a Unix socket on the same Mac. LAN and internet endpoints are external and are not supported by the MVP.
 The application must remain useful without internet access. It may not silently fall back from local processing to a Cloud Provider.
 ## Data classes
 ### Ephemeral sensitive input
 - screen frames and changed image regions;
 - microphone and system-audio PCM;
 - OCR output;
 - complete ASR transcripts;
 - transient prompts assembled for local derivation.
 These values exist only in bounded processing buffers and must be destroyed after local reduction. They must not enter logs, crash reports, archives, fixtures, or the Context store.
 ### Persisted context
 - structured Observations;
 - Assertions, Facts, summaries, and entity relationships;
 - Provenance references;
 - Source and Collector configuration;
 - Assistant History and Context Receipts;
 - Activity Log metadata;
 - retention and policy settings.
 Persisted context is encrypted at the application layer.
 ### Secrets
 - Context-store encryption key;
 - Local Provider credentials, when required;
 - future Cloud Provider credentials.
 Secrets are stored in Keychain and excluded from Context Graph exports and diagnostics.
 ## Continuous collection
 After guided onboarding, every enabled Collector starts with the app unless the user previously selected Pause All.
 Screen, microphone, and system-audio collection are continuous. macOS permission and capture indicators must remain visible and unmodified. The stable Menu Bar Item glyph does not replace those indicators; its open menu shows actual Collector state.
 Pause All:
 - stops every Collector immediately;
 - leaves existing context, Assistant History, and local search available;
 - persists across Quit, relaunch, login, sleep, and wake;
 - resumes only after explicit Resume All.
 One Collector's permission or processing failure must not disable healthy Collectors. The affected Source becomes stale and the Activity Log records a Gap.
 ## Reduction and minimization
 Collectors emit the minimum structured evidence needed for grounded assistance:
 - Screen uses Accessibility structure, changed regions, local OCR, and deduplication.
 - Audio uses VAD, separate channel roles, local ASR, and short semantic reduction.
 - Terminal emits command metadata without stdout or stderr by default.
 - Workspace is limited to explicit roots and ignore rules.
 - Calendar and Reminders are limited to selected read-only collections.
 The configured Local Provider and local processors receive only the context needed for the current derivation or answer.
 If a local processor is unavailable, Mastermind records a Gap. It must not retain raw content for deferred processing.
 ## Capture exclusions
 The user owns the application denylist. Mastermind provides controls to add or remove excluded applications and Sources but does not silently impose an application denylist.
 Mastermind must exclude its own windows from its Screen Collector. It may request exclusion from third-party capture where macOS supports it, but must describe that behavior as best effort and may not promise invisibility.
 Mastermind must not:
 - hide its process or bundle identifier;
 - bypass Screen Recording, Microphone, Accessibility, or EventKit permissions;
 - suppress system privacy indicators;
 - evade managed-device policy or monitoring;
 - claim that screen-share exclusion is guaranteed.
 ## Knowledge integrity
 An Observation is evidence, not truth. Inferred claims remain Assertions with confidence, time, and Provenance. Only explicit user confirmation or correction creates a Fact.
 Contradictory Assertions are retained until normal eviction and surfaced to retrieval. Source content is untrusted data and cannot become an instruction or capability grant.
 The user can inspect and correct knowledge from a Context Receipt. Confirmed Facts are pinned until manually removed or superseded.
 ## Retention and deletion
 - Default inferred-context age: 90 days.
 - Default inferred-context size: 2 GB.
 - Eviction uses `lastObservedAt` and never evicts confirmed Facts automatically.
 - Assistant History has no automatic TTL.
 - One Assistant Session or all Assistant History can be deleted manually.
 - Removing Assistant History does not implicitly remove confirmed Facts derived from it.
 - A full local reset removes the Context store and its encryption key.
 Export/import uses a versioned encrypted archive containing context, history, policies, and settings. Provider credentials are never included.
 ## Audit and diagnostics
 Activity Log records:
 - Collector start, stop, pause, resume, error, and permission state;
 - Gaps and stale Source intervals;
 - Provider request start, finish, locality, and approximate context size;
 - export, import, retention, and migration operations.
 It does not record Source content, prompts, answers, Facts, OCR, ASR, or Provider payloads.
 Mastermind sends no telemetry or crash reports. A user-initiated sanitized diagnostic bundle may contain versions, state transitions, permission and error codes, performance counters, and database schema version.
 ## Future external processing
 Cloud processing is absent from the MVP. A future Cloud Provider requires a Provider Context Permission that is:
 - denied by default;
 - enabled manually for the Provider as a whole;
 - revocable for future requests;
 - unable to retract data already sent.
 Permission is an upper bound, not permission to send everything. Before each request, Mastermind must minimize context and filter recognized secrets locally. Every request must create a Context Receipt naming the Provider, supporting Sources, and transferred context categories.
 Codex remains disabled until a supported no-tools boundary exists.
 ## Onboarding disclosure
 Before enabling continuous Collectors, onboarding must explain:
 - which Source each permission exposes;
 - that screen and both audio channels run continuously while enabled;
 - that raw media and full transcripts are not retained;
 - where derived knowledge is stored;
 - how Pause All and the denylist work;
 - that other people may be represented in locally derived context;
 - that capture exclusion is best effort;
 - that the MVP performs no cloud context transfer.
@@ -0,0 +1,87 @@
 # Companion Island
 ## Purpose
 The Companion Island is Mastermind's only primary interaction surface. It keeps the assistant absent from the desktop until requested while making it available at a stable physical location.
 It is inspired by the expansion behavior of Dynamic Island, but it is a Mastermind concept and must not be described as an Apple system feature.
 ## Placement
 - The Companion Island belongs to the primary display only.
 - Its activation area is centered on the display's top edge.
 - On a notched display, the activation area follows the camera housing.
 - On a display without a notch, the same area behaves as a virtual camera housing.
 - Changing the primary display relocates the Companion Island.
 ## Interaction states
 ### Hidden
 No Companion Island content is visible. Moving the pointer into the activation area begins the reveal transition.
 ### Revealed
 A compact capsule grows from the camera area without taking keyboard focus. Leaving the activation region without clicking collapses it after a short grace period.
 ### Expanded
 Clicking the revealed capsule expands it downward into an interactive panel and focuses text input. Expansion must feel spatially connected to the camera area rather than like an unrelated window appearing.
 The expanded surface contains navigation for:
 - Assistant;
 - Assistant History;
 - Sources;
 - Local Provider;
 - Context Graph and Context Receipts;
 - Activity Log;
 - Privacy, storage, export/import, and diagnostics.
 Escape, an explicit close action, or clicking outside the panel returns it to Hidden. Long-running local work continues after collapse and is visible when the panel is reopened.
 ### Paused
 Paused is a Collector condition, not a separate window mode. The user can still open the Companion Island, search existing context, and use Assistant History while all Collectors remain stopped.
 ## Menu Bar Item
 The Menu Bar Item is visible whenever Mastermind runs. Its glyph does not change with capture state.
 Its menu must expose:
 - current state of every enabled Collector;
 - permission and processing errors;
 - Pause All or Resume All;
 - Show Mastermind;
 - Launch at Login state;
 - Quit Mastermind.
 Show Mastermind expands the Companion Island and is the fallback when pointer activation is unavailable. The MVP has no global hotkey.
 ## Focus and accessibility
 - Hidden and Revealed do not steal focus.
 - Expanded accepts keyboard focus and text input.
 - Pointer activation must not create a dead strip that prevents access to the macOS menu bar.
 - Animation respects Reduce Motion.
 - The interface remains keyboard-navigable after it is expanded.
 - Collector state and errors are conveyed with text, not color alone.
 ## Capture behavior
 Mastermind excludes its own windows from the Screen Collector. It also requests exclusion from third-party capture where supported by macOS.
 Capture exclusion is best effort. The UI must not promise that the Companion Island is invisible to every screen-sharing or recording application. Mastermind never hides its process or system permission indicators.
 ## Acceptance checks
 - At launch, only the Menu Bar Item is visible.
 - Hovering the primary display's camera area reveals the capsule.
 - A notchless primary display gets the same top-center interaction.
 - A click expands the panel and focuses text input.
 - Show Mastermind works when hover activation cannot be used.
 - Escape and click-away collapse the panel.
 - Pause All does not prevent access to existing knowledge or history.
 - The Companion Island is absent from Mastermind's own captured frames.
 - Changing the primary display relocates the activation area.
@@ -0,0 +1,134 @@
 # Mastermind Product Brief
 ## Product thesis
 Mastermind is a personal, local-first assistant for macOS. It continuously builds an inspectable understanding of the user's work and answers grounded questions about what happened, what matters now, and what may come next.
 Mastermind is not an interview helper, a hidden proctoring tool, or a generic shell around a cloud agent. The first product is a personal/internal Swift application for one macOS user.
 ## Core promise
 The user's machine context remains on the Mac. Screen, audio, files, calendar, reminders, and terminal activity are reduced to useful knowledge locally. Mastermind does not transmit that context to a cloud service in the MVP.
 The assistant distinguishes observed evidence, inferred claims, and user-confirmed facts. Every grounded answer can show what evidence it used and where that evidence came from.
 ## Target platform
 - Apple Silicon Mac.
 - macOS 14 or newer.
 - One Local Profile for the current macOS user.
 - No Mastermind account, backend, telemetry, or synchronization in the MVP.
 - The domain keeps a future cloud identity separate from the Local Profile.
 - Personal/internal distribution; Mac App Store constraints are out of scope.
 ## Primary experience
 Mastermind runs as a menu bar application without a Dock presence. Its Menu Bar Item is always present while the app runs and uses a stable glyph. Opening its menu reveals Collector states, permission failures, Pause All or Resume All, Show Mastermind, and Quit.
 The Companion Island is hidden by default. Hovering the top-center camera area of the primary display reveals a compact capsule with a smooth animation. Clicking expands the capsule into the complete Mastermind interface. A virtual top-center activation area provides the same behavior when the primary display has no physical notch. Show Mastermind in the menu is the fallback; the MVP has no global shortcut or voice invocation.
 The expanded Companion Island contains:
 - text input and streamed answers;
 - Assistant History;
 - Context Receipts and Fact correction;
 - Source and Collector management;
 - Local Provider configuration;
 - Context Graph limits and encrypted export/import;
 - Activity Log and diagnostics.
 Mastermind is on-demand, not proactive. Background collection may update status and knowledge, but the assistant does not interrupt the user with unsolicited advice.
 ## MVP sources
 Enabled Collectors start automatically with the application unless Pause All was previously selected:
 - Screen: the active display, defined by the frontmost key window, with pointer display and primary display as fallbacks.
 - Audio: separate microphone and system-audio channels.
 - Workspace: explicitly connected directories and Git repositories.
 - Calendar and Reminders: user-selected calendars and lists, read-only.
 - Terminal: shell integration metadata including working directory, command, exit status, duration, and Git metadata; terminal output is not retained by default.
 Workspace indexing respects `.gitignore`, binary and size limits, and user-configured exclusions. Mastermind does not index the entire home directory.
 The user configures the local capture denylist. Mastermind does not silently add application-level exclusions, but Pause All is always available.
 ## Context behavior
 Collectors run continuously and adapt their work to meaningful changes, voice activity, duplication, Low Power Mode, and thermal pressure. A failed Collector degrades independently while the others continue.
 Screen processing combines Accessibility metadata, changed-region detection, and local OCR. Audio uses separate 16 kHz PCM streams and local ASR; it distinguishes User Speech from System Speech but does not identify people by voice. Meeting inference may combine calendar, conferencing-application, and channel-activity evidence, but it must remain an Assertion until confirmed.
 Raw screen frames, audio, OCR text, and full transcripts are ephemeral. Only locally derived Observations, Assertions, short summaries, and Provenance survive the processing buffer. If required local processing is unavailable, Mastermind records a Gap instead of retaining raw content for later.
 Inferred knowledge expires by `lastObservedAt`, with a default limit of 90 days and 2 GB. User-confirmed Facts are pinned until manually removed or superseded. Assistant History has no automatic age limit; the user can delete one Assistant Session or all history.
 ## Assistant behavior
 The default and only MVP Provider is a user-configured OpenAI-compatible Local Provider reachable through loopback or a Unix socket. The user may save multiple profiles but selects one active profile.
 Mastermind supplies its own local multilingual embedding component. Local ASR remains behind the documented sidecar protocol, with `whisper.cpp` as the recommended implementation. Russian, English, and mixed Russian-English work are required.
 Answers must:
 - distinguish Facts from unconfirmed Assertions;
 - cite relevant Provenance through a Context Receipt;
 - expose the active Provider;
 - say when context is missing or conflicting;
 - treat all Source content as untrusted evidence rather than instructions;
 - produce advice, plans, and drafts only.
 The MVP cannot click, type into other applications, run tools, change files, or perform external actions. Computer Control and a Tool Executor are future bounded contexts, not empty runtime abstractions in the MVP.
 ## Primary acceptance scenario
 After Mastermind has observed normal work, the user opens the Companion Island and asks:
 > What was I working on, and what should I do next?
 The Local Provider returns a grounded answer using relevant screen, workspace, calendar, terminal, and audio knowledge. The answer separates confirmed Facts from uncertain Assertions, links to a Context Receipt, and explicitly identifies gaps or contradictions.
 ## Privacy and trust
 - All sensitive extraction and inference are local in the MVP.
 - The local Context Graph is encrypted with an application key protected by Keychain.
 - Provider credentials are stored separately in Keychain.
 - Pause All immediately stops every Collector and remains paused across restarts.
 - System microphone and screen-recording indicators are never bypassed.
 - The Menu Bar Item glyph stays visually stable, while its menu exposes actual Collector states.
 - The Activity Log records lifecycle and transfer metadata without Source content.
 - Diagnostic exports are sanitized and user-initiated.
 - Context Graph and settings can be exported as an encrypted archive without Provider credentials.
 Mastermind may exclude the Companion Island from its own capture and from third-party capture where macOS supports it. This is best effort, must be self-checked where possible, and is never presented as a guarantee.
 Mastermind does not hide its process, bundle identifier, permissions, network activity, or capture activity from macOS, administrators, or monitoring tools.
 ## Codex direction
 Codex is not part of the MVP. The architecture documents a future Provider boundary and Provider Context Permission, but the MVP contains no Codex UI, OAuth flow, app-server integration, or experimental flag.
 The integration remains gated until Codex exposes a supported boundary that cannot execute tools. A read-only sandbox is insufficient because the current app-server remains an agent protocol.
 If a future Cloud Provider is enabled:
 - context permission is global for that Provider and denied by default;
 - the user must enable it manually;
 - Mastermind still minimizes context and filters detected secrets locally;
 - every request produces a Context Receipt;
 - revocation blocks future requests but cannot retract already transmitted data.
 ## Explicit non-goals
 - Cloud inference or context transfer in the MVP.
 - Autonomous actions, Computer Control, or tool execution.
 - Proactive suggestions or scheduled briefings.
 - Wake word, push-to-talk, global shortcut, or voice queries.
 - Browser, mail, messages, clipboard, or full home-directory indexing.
 - Voice identity and speaker attribution to a Person.
 - Owning or synchronizing the user's tasks and calendar.
 - Multi-display Companion Island behavior.
 - A visual whole-graph explorer.
 - Electron feature development or an Electron bridge.
 - Intel Mac, Windows, Linux, or Mac App Store support.
 - Stealth, anti-detection, permission bypass, or guaranteed screen-share invisibility.
@@ -0,0 +1,97 @@
 # 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`.
 ## Architectural compliance
 - [ ] Code follows **Strict Clean Architecture** with capability modules.
 - [ ] Dependency Rule is enforced at compile-time between targets.
 - [ ] No global EventBus; communication uses ports and typed async streams.
 - [ ] Context Graph updates are performed by idempotent projectors with durable checkpoints.
 - [ ] Privacy-sensitive egress is gated by a central fail-closed Egress Gate.
 - [ ] Swift 6 Strict Concurrency is enabled and produces no warnings.
 - [ ] All semantic declarations have Russian DocC per the **Commenting Standard**.
@@ -50,15 +50,6 @@ module.exports = {
      config: {
        format: "UDZO",
        icon: "src/assets/logo.icns",
        name: "Mastermind",
        additionalDMGOptions: {
          window: {
            size: {
              width: 660,
              height: 400,
            },
          },
        },
      },
    },
    {
@@ -0,0 +1,2 @@
 .build/
 build/
@@ -0,0 +1,34 @@
 // swift-tools-version: 5.9
 import PackageDescription
 let package = Package(
    name: "MastermindPOC",
    platforms: [
        .macOS(.v14),
    ],
    products: [
        .executable(name: "MastermindPOC", targets: ["MastermindPOC"]),
        .library(name: "MastermindPOCCore", targets: ["MastermindPOCCore"]),
    ],
    targets: [
        .target(name: "MastermindPOCCore"),
        .executableTarget(
            name: "MastermindPOC",
            dependencies: ["MastermindPOCCore"],
            linkerSettings: [
                .linkedFramework("AppKit"),
                .linkedFramework("AVFoundation"),
                .linkedFramework("CoreGraphics"),
                .linkedFramework("CoreMedia"),
                .linkedFramework("CoreVideo"),
                .linkedFramework("ScreenCaptureKit"),
                .linkedFramework("SwiftUI"),
            ]
        ),
        .testTarget(
            name: "MastermindPOCCoreTests",
            dependencies: ["MastermindPOCCore"]
        ),
    ]
 )
@@ -0,0 +1,183 @@
 import AppKit
 import AVFoundation
 import CoreGraphics
 import MastermindPOCCore
 final class AppDelegate: NSObject, NSApplicationDelegate {
    private let settingsStore = OverlaySettingsStore()
    private lazy var overlayController = OverlayWindowController(
        initialSettings: settingsStore.settings,
        actions: OverlayActions(
            openSettings: { [weak self] in self?.showSettings() },
            hideOverlay: { [weak self] in self?.hideOverlay() },
            quitApp: { NSApplication.shared.terminate(nil) }
        )
    )
    private lazy var settingsWindowController = SettingsWindowController(settingsStore: settingsStore)
    private var stats = AudioPipelineStats()
    private var screenFrameCount = 0
    private lazy var captureCoordinator = CaptureCoordinator(
        onScreenFrame: { [weak self] frameCount in
            Task { @MainActor in
                self?.recordScreenFrame(frameCount)
            }
        },
        onSystemAudioFrame: { [weak self] frame in
            Task { @MainActor in
                self?.recordAudioFrame(frame)
            }
        },
        onError: { [weak self] message in
            Task { @MainActor in
                self?.setStatus(.error(message))
            }
        }
    )
    private lazy var microphoneEngine = MicrophoneCaptureEngine(
        onFrame: { [weak self] frame in
            Task { @MainActor in
                self?.recordAudioFrame(frame)
            }
        },
        onError: { [weak self] message in
            Task { @MainActor in
                self?.setStatus(.error(message))
            }
        }
    )
    private lazy var menuBarController = MenuBarController(
        actions: MenuBarController.Actions(
            showOverlay: { [weak self] in self?.showOverlay() },
            hideOverlay: { [weak self] in self?.hideOverlay() },
            openSettings: { [weak self] in self?.showSettings() },
            toggleClickThrough: { [weak self] in self?.toggleClickThrough() },
            startScreenAndSystemAudio: { [weak self] in self?.startScreenAndSystemAudio() },
            startMicrophone: { [weak self] in self?.startMicrophone() },
            pauseAllCapture: { [weak self] in self?.pauseAllCapture() },
            quit: { NSApplication.shared.terminate(nil) }
        )
    )
    func applicationDidFinishLaunching(_ notification: Notification) {
        settingsStore.onChange = { [weak self] settings in
            self?.overlayController.viewModel.backgroundOpacity = settings.backgroundOpacity
        }
        overlayController.show()
        setStatus(.idle)
        refreshCounters()
    }
    private func showOverlay() {
        overlayController.show()
        menuBarController.setOverlayVisible(true)
    }
    private func hideOverlay() {
        overlayController.hide()
        menuBarController.setOverlayVisible(false)
    }
    private func showSettings() {
        settingsWindowController.show()
    }
    private func toggleClickThrough() {
        let enabled = overlayController.toggleClickThrough()
        overlayController.viewModel.clickThroughEnabled = enabled
        menuBarController.setClickThrough(enabled)
    }
    private func startScreenAndSystemAudio() {
        Task {
            do {
                try await captureCoordinator.start(excludingWindowIDs: overlayController.excludedWindowIDs)
                setStatus(.screenContext)
            } catch {
                setStatus(.error(error.localizedDescription))
            }
        }
    }
    private func startMicrophone() {
        Task {
            do {
                try await requestMicrophoneAccess()
                try microphoneEngine.start()
                setStatus(.listening)
            } catch {
                setStatus(.error(error.localizedDescription))
            }
        }
    }
    private func pauseAllCapture() {
        Task {
            await captureCoordinator.stop()
            microphoneEngine.stop()
            setStatus(.paused)
        }
    }
    private func recordScreenFrame(_ frameCount: Int) {
        screenFrameCount = frameCount
        overlayController.viewModel.screenFrames = frameCount
        setStatus(.screenContext)
    }
    private func recordAudioFrame(_ frame: PCMFrame) {
        stats.recordFrame(source: frame.source, byteCount: frame.pcmS16LE.count)
        refreshCounters()
        switch frame.source {
        case .microphone:
            setStatus(.listening)
        case .system:
            setStatus(.systemAudio)
        }
    }
    private func refreshCounters() {
        overlayController.viewModel.microphoneFrames = stats.microphoneFrames
        overlayController.viewModel.microphoneBytes = stats.microphoneBytes
        overlayController.viewModel.systemFrames = stats.systemFrames
        overlayController.viewModel.systemBytes = stats.systemBytes
    }
    private func setStatus(_ status: TrustStatus) {
        overlayController.viewModel.apply(status: status)
        menuBarController.setStatus(status)
    }
    private func requestMicrophoneAccess() async throws {
        switch AVCaptureDevice.authorizationStatus(for: .audio) {
        case .authorized:
            return
        case .notDetermined:
            let granted = await AVCaptureDevice.requestAccess(for: .audio)
            if granted {
                return
            }
            throw POCError("Microphone permission was denied")
        case .denied, .restricted:
            throw POCError("Microphone permission is not available")
        @unknown default:
            throw POCError("Unknown microphone permission state")
        }
    }
 }
 struct POCError: LocalizedError {
    let message: String
    init(_ message: String) {
        self.message = message
    }
    var errorDescription: String? {
        message
    }
 }
@@ -0,0 +1,100 @@
 import CoreGraphics
 import CoreMedia
 import CoreVideo
 import Foundation
 import MastermindPOCCore
 import ScreenCaptureKit
 final class CaptureCoordinator: NSObject, SCStreamOutput, SCStreamDelegate {
    private let outputQueue = DispatchQueue(label: "app.mastermind.poc.screencapture")
    private let onScreenFrame: (Int) -> Void
    private let onSystemAudioFrame: (PCMFrame) -> Void
    private let onError: (String) -> Void
    private var stream: SCStream?
    private var screenFrameCount = 0
    init(
        onScreenFrame: @escaping (Int) -> Void,
        onSystemAudioFrame: @escaping (PCMFrame) -> Void,
        onError: @escaping (String) -> Void
    ) {
        self.onScreenFrame = onScreenFrame
        self.onSystemAudioFrame = onSystemAudioFrame
        self.onError = onError
        super.init()
    }
    func start(excludingWindowIDs: Set<CGWindowID>) async throws {
        await stop()
        let content = try await SCShareableContent.current
        guard let display = content.displays.first(where: { $0.displayID == CGMainDisplayID() }) ?? content.displays.first else {
            throw POCError("No capturable display found")
        }
        let currentPID = ProcessInfo.processInfo.processIdentifier
        let excludedWindows = content.windows.filter { window in
            excludingWindowIDs.contains(window.windowID) || window.owningApplication?.processID == currentPID
        }
        let filter = SCContentFilter(display: display, excludingWindows: excludedWindows)
        let configuration = SCStreamConfiguration()
        configuration.width = max(1, display.width)
        configuration.height = max(1, display.height)
        configuration.minimumFrameInterval = CMTime(value: 1, timescale: 2)
        configuration.pixelFormat = kCVPixelFormatType_32BGRA
        configuration.queueDepth = 3
        configuration.capturesAudio = true
        configuration.sampleRate = 16_000
        configuration.channelCount = 1
        configuration.excludesCurrentProcessAudio = true
        let stream = SCStream(filter: filter, configuration: configuration, delegate: self)
        try stream.addStreamOutput(self, type: .screen, sampleHandlerQueue: outputQueue)
        try stream.addStreamOutput(self, type: .audio, sampleHandlerQueue: outputQueue)
        try await stream.startCapture()
        screenFrameCount = 0
        self.stream = stream
    }
    func stop() async {
        guard let stream else {
            return
        }
        do {
            try await stream.stopCapture()
        } catch {
            onError("Screen capture stop failed: \(error.localizedDescription)")
        }
        self.stream = nil
    }
    func stream(_ stream: SCStream, didOutputSampleBuffer sampleBuffer: CMSampleBuffer, of type: SCStreamOutputType) {
        guard CMSampleBufferIsValid(sampleBuffer) else {
            return
        }
        switch type {
        case .screen:
            screenFrameCount += 1
            onScreenFrame(screenFrameCount)
        case .audio:
            if let frame = SampleBufferPCMExtractor.extractFrame(from: sampleBuffer, source: .system) {
                onSystemAudioFrame(frame)
            }
        case .microphone:
            return
        @unknown default:
            return
        }
    }
    func stream(_ stream: SCStream, didStopWithError error: Error) {
        onError("Screen capture stopped: \(error.localizedDescription)")
    }
 }
@@ -0,0 +1,121 @@
 import AppKit
 import MastermindPOCCore
 final class MenuBarController: NSObject {
    struct Actions {
        let showOverlay: () -> Void
        let hideOverlay: () -> Void
        let openSettings: () -> Void
        let toggleClickThrough: () -> Void
        let startScreenAndSystemAudio: () -> Void
        let startMicrophone: () -> Void
        let pauseAllCapture: () -> Void
        let quit: () -> Void
    }
    private let actions: Actions
    private let statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
    private let statusMenuItem = NSMenuItem(title: "Mastermind: Idle", action: nil, keyEquivalent: "")
    private let showItem = NSMenuItem(title: "Show Assistant", action: #selector(showOverlay), keyEquivalent: "")
    private let hideItem = NSMenuItem(title: "Hide Assistant", action: #selector(hideOverlay), keyEquivalent: "")
    private let clickThroughItem = NSMenuItem(title: "Enable Click-Through", action: #selector(toggleClickThrough), keyEquivalent: "")
    init(actions: Actions) {
        self.actions = actions
        super.init()
        configureMenu()
        setStatus(.idle)
    }
    func setStatus(_ status: TrustStatus) {
        let title = status.menuBarTitle
        statusMenuItem.title = title
        statusItem.button?.title = title
    }
    func setOverlayVisible(_ visible: Bool) {
        showItem.isEnabled = !visible
        hideItem.isEnabled = visible
    }
    func setClickThrough(_ enabled: Bool) {
        clickThroughItem.title = enabled ? "Disable Click-Through" : "Enable Click-Through"
        clickThroughItem.state = enabled ? .on : .off
    }
    private func configureMenu() {
        statusItem.button?.title = "Mastermind: Idle"
        statusItem.button?.toolTip = "Mastermind AI helper status"
        let menu = NSMenu()
        statusMenuItem.isEnabled = false
        menu.addItem(statusMenuItem)
        menu.addItem(.separator())
        showItem.target = self
        hideItem.target = self
        clickThroughItem.target = self
        menu.addItem(showItem)
        menu.addItem(hideItem)
        menu.addItem(clickThroughItem)
        menu.addItem(.separator())
        let settingsItem = NSMenuItem(title: "Settings...", action: #selector(openSettings), keyEquivalent: ",")
        settingsItem.target = self
        menu.addItem(settingsItem)
        menu.addItem(.separator())
        let screenItem = NSMenuItem(title: "Start Screen + System Audio", action: #selector(startScreenAndSystemAudio), keyEquivalent: "")
        screenItem.target = self
        menu.addItem(screenItem)
        let microphoneItem = NSMenuItem(title: "Start Microphone", action: #selector(startMicrophone), keyEquivalent: "")
        microphoneItem.target = self
        menu.addItem(microphoneItem)
        let pauseItem = NSMenuItem(title: "Pause All Capture", action: #selector(pauseAllCapture), keyEquivalent: "")
        pauseItem.target = self
        menu.addItem(pauseItem)
        menu.addItem(.separator())
        let quitItem = NSMenuItem(title: "Quit Mastermind POC", action: #selector(quit), keyEquivalent: "q")
        quitItem.target = self
        menu.addItem(quitItem)
        statusItem.menu = menu
        setOverlayVisible(true)
        setClickThrough(false)
    }
    @objc private func showOverlay() {
        actions.showOverlay()
    }
    @objc private func hideOverlay() {
        actions.hideOverlay()
    }
    @objc private func openSettings() {
        actions.openSettings()
    }
    @objc private func toggleClickThrough() {
        actions.toggleClickThrough()
    }
    @objc private func startScreenAndSystemAudio() {
        actions.startScreenAndSystemAudio()
    }
    @objc private func startMicrophone() {
        actions.startMicrophone()
    }
    @objc private func pauseAllCapture() {
        actions.pauseAllCapture()
    }
    @objc private func quit() {
        actions.quit()
    }
 }
@@ -0,0 +1,54 @@
 import AVFoundation
 import Foundation
 import MastermindPOCCore
 final class MicrophoneCaptureEngine {
    private let engine = AVAudioEngine()
    private let onFrame: (PCMFrame) -> Void
    private let onError: (String) -> Void
    private var isRunning = false
    init(onFrame: @escaping (PCMFrame) -> Void, onError: @escaping (String) -> Void) {
        self.onFrame = onFrame
        self.onError = onError
    }
    func start() throws {
        guard !isRunning else {
            return
        }
        let inputNode = engine.inputNode
        let format = inputNode.outputFormat(forBus: 0)
        inputNode.removeTap(onBus: 0)
        inputNode.installTap(onBus: 0, bufferSize: 1024, format: format) { [weak self] buffer, _ in
            guard let self else {
                return
            }
            if let frame = MicrophonePCMConverter.extractFrame(from: buffer) {
                self.onFrame(frame)
            }
        }
        do {
            try engine.start()
            isRunning = true
        } catch {
            inputNode.removeTap(onBus: 0)
            onError("Microphone start failed: \(error.localizedDescription)")
            throw error
        }
    }
    func stop() {
        guard isRunning else {
            return
        }
        engine.inputNode.removeTap(onBus: 0)
        engine.stop()
        isRunning = false
    }
 }
@@ -0,0 +1,57 @@
 import AVFoundation
 import Foundation
 import MastermindPOCCore
 enum MicrophonePCMConverter {
    static func extractFrame(from buffer: AVAudioPCMBuffer) -> PCMFrame? {
        let frameCount = Int(buffer.frameLength)
        guard frameCount > 0 else {
            return nil
        }
        let channelCount = max(1, Int(buffer.format.channelCount))
        let sourceRate = Int(buffer.format.sampleRate.rounded())
        let samples: [Float]
        if let floatData = buffer.floatChannelData {
            samples = mixFloatChannels(floatData, channelCount: channelCount, frameCount: frameCount)
        } else if let int16Data = buffer.int16ChannelData {
            samples = mixInt16Channels(int16Data, channelCount: channelCount, frameCount: frameCount)
        } else {
            return nil
        }
        let mono16k = PCM16LE.resampleLinear(samples: samples, sourceRate: sourceRate, targetRate: 16_000)
        let data = PCM16LE.encode(samples: mono16k)
        return PCMFrame(source: .microphone, sampleRate: 16_000, channels: 1, pcmS16LE: data)
    }
    private static func mixFloatChannels(_ channelData: UnsafePointer<UnsafeMutablePointer<Float>>, channelCount: Int, frameCount: Int) -> [Float] {
        var mono = [Float](repeating: 0, count: frameCount)
        let divisor = Float(channelCount)
        for channel in 0..<channelCount {
            let channelPointer = channelData[channel]
            for frame in 0..<frameCount {
                mono[frame] += channelPointer[frame] / divisor
            }
        }
        return mono
    }
    private static func mixInt16Channels(_ channelData: UnsafePointer<UnsafeMutablePointer<Int16>>, channelCount: Int, frameCount: Int) -> [Float] {
        var mono = [Float](repeating: 0, count: frameCount)
        let divisor = Float(channelCount)
        for channel in 0..<channelCount {
            let channelPointer = channelData[channel]
            for frame in 0..<frameCount {
                mono[frame] += (Float(channelPointer[frame]) / Float(Int16.max)) / divisor
            }
        }
        return mono
    }
 }
@@ -0,0 +1,33 @@
 import Foundation
 import MastermindPOCCore
 final class OverlaySettingsStore: ObservableObject {
    static let backgroundOpacityKey = "overlay.backgroundOpacity"
    @Published private(set) var settings: OverlaySettings
    var onChange: ((OverlaySettings) -> Void)?
    private let defaults: UserDefaults
    init(defaults: UserDefaults = .standard) {
        self.defaults = defaults
        if defaults.object(forKey: Self.backgroundOpacityKey) == nil {
            settings = .default
        } else {
            settings = OverlaySettings(backgroundOpacity: defaults.double(forKey: Self.backgroundOpacityKey))
        }
    }
    var backgroundOpacity: Double {
        settings.backgroundOpacity
    }
    func updateBackgroundOpacity(_ opacity: Double) {
        let nextSettings = OverlaySettings(backgroundOpacity: opacity)
        settings = nextSettings
        defaults.set(nextSettings.backgroundOpacity, forKey: Self.backgroundOpacityKey)
        onChange?(nextSettings)
    }
 }
@@ -0,0 +1,164 @@
 import MastermindPOCCore
 import SwiftUI
 final class OverlayViewModel: ObservableObject {
    @Published var statusTitle = "Mastermind: Idle"
    @Published var statusDetail = "Native macOS companion proof"
    @Published var clickThroughEnabled = false
    @Published var backgroundOpacity = OverlaySettings.default.backgroundOpacity
    @Published var screenFrames = 0
    @Published var microphoneFrames = 0
    @Published var microphoneBytes = 0
    @Published var systemFrames = 0
    @Published var systemBytes = 0
    func apply(status: TrustStatus) {
        statusTitle = status.menuBarTitle
        switch status {
        case .idle:
            statusDetail = "Ready. Capture is off."
        case .listening:
            statusDetail = "Microphone capture is active."
        case .screenContext:
            statusDetail = "Screen context proof is active."
        case .systemAudio:
            statusDetail = "System audio proof is active."
        case .agentWorking:
            statusDetail = "Agent work placeholder."
        case .paused:
            statusDetail = "All capture paused."
        case .permissionNeeded(let message):
            statusDetail = message
        case .error(let message):
            statusDetail = message
        }
    }
 }
 struct OverlayView: View {
    @ObservedObject var viewModel: OverlayViewModel
    let actions: OverlayActions
    var body: some View {
        VStack(alignment: .leading, spacing: 12) {
            HudTitleBar(viewModel: viewModel, actions: actions)
            VStack(alignment: .leading, spacing: 4) {
                Text(viewModel.statusTitle)
                    .font(.system(.title3, design: .rounded, weight: .semibold))
                    .foregroundStyle(.white)
                Text(viewModel.statusDetail)
                    .font(.callout)
                    .foregroundStyle(.white.opacity(0.78))
                    .lineLimit(2)
            }
            Divider()
                .overlay(.white.opacity(0.2))
            HStack(spacing: 14) {
                CounterView(label: "Screen", value: viewModel.screenFrames)
                CounterView(label: "Mic", value: viewModel.microphoneFrames)
                CounterView(label: "System", value: viewModel.systemFrames)
            }
            Text("PCM bytes mic \(viewModel.microphoneBytes) | system \(viewModel.systemBytes)")
                .font(.caption2.monospacedDigit())
                .foregroundStyle(.white.opacity(0.62))
        }
        .padding(18)
        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .topLeading)
        .background(
            RoundedRectangle(cornerRadius: 18, style: .continuous)
                .fill(.black.opacity(viewModel.backgroundOpacity))
                .stroke(.white.opacity(0.16), lineWidth: 1)
        )
    }
 }
 private struct HudTitleBar: View {
    @ObservedObject var viewModel: OverlayViewModel
    let actions: OverlayActions
    var body: some View {
        HStack(spacing: 10) {
            ZStack(alignment: .leading) {
                WindowDragRegion()
                HStack(spacing: 8) {
                    Image(systemName: "sparkles")
                        .font(.caption.weight(.semibold))
                    Text("Mastermind")
                        .font(.headline)
                    Text(viewModel.clickThroughEnabled ? "Click-through" : "Interactive")
                        .font(.caption)
                        .foregroundStyle(.white.opacity(0.66))
                }
                .foregroundStyle(.white)
                .allowsHitTesting(false)
            }
            .frame(height: 28)
            HStack(spacing: 6) {
                HudIconButton(systemName: "gearshape", help: "Settings", action: actions.openSettings)
                HudIconButton(systemName: "eye.slash", help: "Hide assistant", action: actions.hideOverlay)
                HudIconButton(systemName: "xmark", help: "Quit Mastermind POC", role: .destructive, action: actions.quitApp)
            }
        }
    }
 }
 private struct HudIconButton: View {
    let systemName: String
    let help: String
    var role: ButtonRole?
    let action: () -> Void
    var body: some View {
        Button(role: role, action: action) {
            Image(systemName: systemName)
                .font(.caption.weight(.semibold))
                .frame(width: 24, height: 24)
                .contentShape(Rectangle())
        }
        .buttonStyle(.plain)
        .foregroundStyle(.white.opacity(0.82))
        .background(.white.opacity(0.08), in: RoundedRectangle(cornerRadius: 6, style: .continuous))
        .help(help)
    }
 }
 private struct WindowDragRegion: NSViewRepresentable {
    func makeNSView(context: Context) -> DragHandleView {
        DragHandleView()
    }
    func updateNSView(_ nsView: DragHandleView, context: Context) {}
 }
 private final class DragHandleView: NSView {
    override var mouseDownCanMoveWindow: Bool {
        true
    }
    override func mouseDown(with event: NSEvent) {
        window?.performDrag(with: event)
    }
 }
 private struct CounterView: View {
    let label: String
    let value: Int
    var body: some View {
        VStack(alignment: .leading, spacing: 3) {
            Text(label)
                .font(.caption2)
                .foregroundStyle(.white.opacity(0.58))
            Text("\(value)")
                .font(.caption.monospacedDigit().weight(.semibold))
                .foregroundStyle(.white)
        }
        .frame(maxWidth: .infinity, alignment: .leading)
    }
 }
@@ -0,0 +1,58 @@
 import AppKit
 import CoreGraphics
 import MastermindPOCCore
 import SwiftUI
 final class OverlayWindowController {
    let viewModel = OverlayViewModel()
    private let panel: NSPanel
    private var clickThroughEnabled = false
    init(initialSettings: OverlaySettings, actions: OverlayActions) {
        let screenFrame = NSScreen.main?.visibleFrame ?? NSRect(x: 0, y: 0, width: 1280, height: 800)
        let size = NSSize(width: 440, height: 210)
        let origin = NSPoint(
            x: screenFrame.maxX - size.width - 28,
            y: screenFrame.maxY - size.height - 28
        )
        panel = NSPanel(
            contentRect: NSRect(origin: origin, size: size),
            styleMask: [.borderless, .nonactivatingPanel],
            backing: .buffered,
            defer: false
        )
        panel.isReleasedWhenClosed = false
        panel.isOpaque = false
        panel.backgroundColor = .clear
        panel.hasShadow = true
        panel.level = .floating
        panel.isMovableByWindowBackground = true
        panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary, .stationary, .ignoresCycle]
        panel.sharingType = .none
        panel.title = "Mastermind POC Overlay"
        viewModel.backgroundOpacity = initialSettings.backgroundOpacity
        panel.contentView = NSHostingView(rootView: OverlayView(viewModel: viewModel, actions: actions))
    }
    var excludedWindowIDs: Set<CGWindowID> {
        [CGWindowID(panel.windowNumber)]
    }
    func show() {
        panel.orderFrontRegardless()
    }
    func hide() {
        panel.orderOut(nil)
    }
    @discardableResult
    func toggleClickThrough() -> Bool {
        clickThroughEnabled.toggle()
        panel.ignoresMouseEvents = clickThroughEnabled
        return clickThroughEnabled
    }
 }
@@ -0,0 +1,88 @@
 import AudioToolbox
 import CoreMedia
 import Foundation
 import MastermindPOCCore
 enum SampleBufferPCMExtractor {
    static func extractFrame(from sampleBuffer: CMSampleBuffer, source: AudioSource) -> PCMFrame? {
        guard let formatDescription = CMSampleBufferGetFormatDescription(sampleBuffer),
              let streamDescription = CMAudioFormatDescriptionGetStreamBasicDescription(formatDescription)
        else {
            return nil
        }
        let asbd = streamDescription.pointee
        guard asbd.mFormatID == kAudioFormatLinearPCM else {
            return nil
        }
        var bufferListSize = 0
        var blockBuffer: CMBlockBuffer?
        var status = CMSampleBufferGetAudioBufferListWithRetainedBlockBuffer(
            sampleBuffer,
            bufferListSizeNeededOut: &bufferListSize,
            bufferListOut: nil,
            bufferListSize: 0,
            blockBufferAllocator: kCFAllocatorDefault,
            blockBufferMemoryAllocator: kCFAllocatorDefault,
            flags: kCMSampleBufferFlag_AudioBufferList_Assure16ByteAlignment,
            blockBufferOut: &blockBuffer
        )
        guard status == noErr, bufferListSize > 0 else {
            return nil
        }
        let bufferListPointer = UnsafeMutableRawPointer.allocate(byteCount: bufferListSize, alignment: MemoryLayout<AudioBufferList>.alignment)
        defer {
            bufferListPointer.deallocate()
        }
        let audioBufferList = bufferListPointer.bindMemory(to: AudioBufferList.self, capacity: 1)
        status = CMSampleBufferGetAudioBufferListWithRetainedBlockBuffer(
            sampleBuffer,
            bufferListSizeNeededOut: nil,
            bufferListOut: audioBufferList,
            bufferListSize: bufferListSize,
            blockBufferAllocator: kCFAllocatorDefault,
            blockBufferMemoryAllocator: kCFAllocatorDefault,
            flags: kCMSampleBufferFlag_AudioBufferList_Assure16ByteAlignment,
            blockBufferOut: &blockBuffer
        )
        guard status == noErr else {
            return nil
        }
        let buffers = UnsafeMutableAudioBufferListPointer(audioBufferList)
        guard let firstBuffer = buffers.first,
              let mData = firstBuffer.mData
        else {
            return nil
        }
        let sourceRate = Int(asbd.mSampleRate.rounded())
        let byteCount = Int(firstBuffer.mDataByteSize)
        let rawPointer = UnsafeRawPointer(mData)
        let samples: [Float]
        if asbd.mBitsPerChannel == 32, asbd.mFormatFlags & kAudioFormatFlagIsFloat != 0 {
            let sampleCount = byteCount / MemoryLayout<Float>.size
            let pointer = rawPointer.bindMemory(to: Float.self, capacity: sampleCount)
            samples = (0..<sampleCount).map { pointer[$0] }
        } else if asbd.mBitsPerChannel == 16, asbd.mFormatFlags & kAudioFormatFlagIsSignedInteger != 0 {
            let sampleCount = byteCount / MemoryLayout<Int16>.size
            let pointer = rawPointer.bindMemory(to: Int16.self, capacity: sampleCount)
            samples = (0..<sampleCount).map { index in
                Float(Int16(littleEndian: pointer[index])) / Float(Int16.max)
            }
        } else {
            return nil
        }
        let mono16k = PCM16LE.resampleLinear(samples: samples, sourceRate: sourceRate, targetRate: 16_000)
        let data = PCM16LE.encode(samples: mono16k)
        return PCMFrame(source: source, sampleRate: 16_000, channels: 1, pcmS16LE: data)
    }
 }
@@ -0,0 +1,64 @@
 import AppKit
 import MastermindPOCCore
 import SwiftUI
 final class SettingsWindowController {
    private let panel: NSPanel
    init(settingsStore: OverlaySettingsStore) {
        panel = NSPanel(
            contentRect: NSRect(x: 0, y: 0, width: 360, height: 160),
            styleMask: [.titled, .closable, .utilityWindow],
            backing: .buffered,
            defer: false
        )
        panel.isReleasedWhenClosed = false
        panel.hidesOnDeactivate = false
        panel.title = "Mastermind Settings"
        panel.level = .floating
        panel.collectionBehavior = [.canJoinAllSpaces, .fullScreenAuxiliary]
        panel.contentView = NSHostingView(rootView: SettingsView(settingsStore: settingsStore))
    }
    func show() {
        panel.center()
        NSApp.activate(ignoringOtherApps: true)
        panel.makeKeyAndOrderFront(nil)
    }
 }
 private struct SettingsView: View {
    @ObservedObject var settingsStore: OverlaySettingsStore
    var body: some View {
        VStack(alignment: .leading, spacing: 16) {
            Text("Window")
                .font(.headline)
            VStack(alignment: .leading, spacing: 8) {
                HStack {
                    Text("Opacity")
                    Spacer()
                    Text("\(Int(settingsStore.backgroundOpacity * 100))%")
                        .font(.caption.monospacedDigit())
                        .foregroundStyle(.secondary)
                }
                Slider(
                    value: Binding(
                        get: { settingsStore.backgroundOpacity },
                        set: { settingsStore.updateBackgroundOpacity($0) }
                    ),
                    in: OverlaySettings.minimumOpacity...OverlaySettings.maximumOpacity
                )
            }
            Text("Changes apply to the HUD background only.")
                .font(.caption)
                .foregroundStyle(.secondary)
        }
        .padding(20)
        .frame(width: 360, height: 160)
    }
 }
@@ -0,0 +1,8 @@
 import AppKit
 let app = NSApplication.shared
 let delegate = AppDelegate()
 app.delegate = delegate
 app.setActivationPolicy(.accessory)
 app.run()
@@ -0,0 +1,24 @@
 public struct AudioPipelineStats: Equatable {
    public private(set) var microphoneFrames: Int
    public private(set) var microphoneBytes: Int
    public private(set) var systemFrames: Int
    public private(set) var systemBytes: Int
    public init(microphoneFrames: Int = 0, microphoneBytes: Int = 0, systemFrames: Int = 0, systemBytes: Int = 0) {
        self.microphoneFrames = microphoneFrames
        self.microphoneBytes = microphoneBytes
        self.systemFrames = systemFrames
        self.systemBytes = systemBytes
    }
    public mutating func recordFrame(source: AudioSource, byteCount: Int) {
        switch source {
        case .microphone:
            microphoneFrames += 1
            microphoneBytes += byteCount
        case .system:
            systemFrames += 1
            systemBytes += byteCount
        }
    }
 }
@@ -0,0 +1,11 @@
 public struct OverlayActions {
    public let openSettings: () -> Void
    public let hideOverlay: () -> Void
    public let quitApp: () -> Void
    public init(openSettings: @escaping () -> Void, hideOverlay: @escaping () -> Void, quitApp: @escaping () -> Void) {
        self.openSettings = openSettings
        self.hideOverlay = hideOverlay
        self.quitApp = quitApp
    }
 }
@@ -0,0 +1,15 @@
 public struct OverlaySettings: Equatable {
    public static let minimumOpacity = 0.35
    public static let maximumOpacity = 0.95
    public static let `default` = OverlaySettings(backgroundOpacity: 0.72)
    public let backgroundOpacity: Double
    public init(backgroundOpacity: Double) {
        self.backgroundOpacity = Self.clamp(backgroundOpacity)
    }
    public static func clamp(_ opacity: Double) -> Double {
        min(maximumOpacity, max(minimumOpacity, opacity))
    }
 }
@@ -0,0 +1,51 @@
 import Foundation
 public enum PCM16LE {
    public static func encode(samples: [Float]) -> Data {
        var data = Data()
        data.reserveCapacity(samples.count * MemoryLayout<Int16>.size)
        for sample in samples {
            let clamped = max(-1.0, min(1.0, sample))
            let scaled: Int16
            if clamped >= 1.0 {
                scaled = Int16.max
            } else if clamped <= -1.0 {
                scaled = Int16.min
            } else {
                scaled = Int16((clamped * Float(Int16.max)).rounded())
            }
            var littleEndian = scaled.littleEndian
            withUnsafeBytes(of: &littleEndian) { bytes in
                data.append(contentsOf: bytes)
            }
        }
        return data
    }
    public static func resampleLinear(samples: [Float], sourceRate: Int, targetRate: Int = 16_000) -> [Float] {
        guard sourceRate > 0, targetRate > 0, !samples.isEmpty else {
            return []
        }
        guard sourceRate != targetRate else {
            return samples
        }
        let ratio = Double(sourceRate) / Double(targetRate)
        let outputCount = max(1, Int(Double(samples.count) / ratio))
        return (0..<outputCount).map { index in
            let sourcePosition = Double(index) * ratio
            let lowerIndex = Int(sourcePosition)
            let upperIndex = min(lowerIndex + 1, samples.count - 1)
            let fraction = Float(sourcePosition - Double(lowerIndex))
            let lower = samples[min(lowerIndex, samples.count - 1)]
            let upper = samples[upperIndex]
            return lower + ((upper - lower) * fraction)
        }
    }
 }
@@ -0,0 +1,22 @@
 import Foundation
 public enum AudioSource: String, Equatable {
    case microphone
    case system
 }
 public struct PCMFrame: Equatable {
    public let source: AudioSource
    public let sampleRate: Int
    public let channels: Int
    public let pcmS16LE: Data
    public let timestamp: Date
    public init(source: AudioSource, sampleRate: Int, channels: Int, pcmS16LE: Data, timestamp: Date = Date()) {
        self.source = source
        self.sampleRate = sampleRate
        self.channels = channels
        self.pcmS16LE = pcmS16LE
        self.timestamp = timestamp
    }
 }
@@ -0,0 +1,40 @@
 public enum TrustStatus: Equatable {
    case idle
    case listening
    case screenContext
    case systemAudio
    case agentWorking
    case paused
    case permissionNeeded(String)
    case error(String)
    public var menuBarTitle: String {
        switch self {
        case .idle:
            return "Mastermind: Idle"
        case .listening:
            return "Mastermind: Listening"
        case .screenContext:
            return "Mastermind: Screen"
        case .systemAudio:
            return "Mastermind: System Audio"
        case .agentWorking:
            return "Mastermind: Working"
        case .paused:
            return "Mastermind: Paused"
        case .permissionNeeded:
            return "Mastermind: Permission"
        case .error:
            return "Mastermind: Error"
        }
    }
    public var isCapturing: Bool {
        switch self {
        case .listening, .screenContext, .systemAudio:
            return true
        case .idle, .agentWorking, .paused, .permissionNeeded, .error:
            return false
        }
    }
 }
@@ -0,0 +1,51 @@
 import XCTest
@testable import MastermindPOCCore
 final class AudioModelTests: XCTestCase {
    func testPCMFrameStoresSidecarCompatibleAudioMetadata() {
        let data = Data([0x00, 0x00, 0xff, 0x7f])
        let timestamp = Date(timeIntervalSince1970: 42)
        let frame = PCMFrame(
            source: .microphone,
            sampleRate: 16_000,
            channels: 1,
            pcmS16LE: data,
            timestamp: timestamp
        )
        XCTAssertEqual(frame.source, .microphone)
        XCTAssertEqual(frame.sampleRate, 16_000)
        XCTAssertEqual(frame.channels, 1)
        XCTAssertEqual(frame.pcmS16LE, data)
        XCTAssertEqual(frame.timestamp, timestamp)
    }
    func testPCM16LEClampsAndEncodesLittleEndianSamples() {
        let encoded = PCM16LE.encode(samples: [-2.0, -1.0, 0.0, 0.5, 2.0])
        XCTAssertEqual(
            Array(encoded),
            [
                0x00, 0x80,
                0x00, 0x80,
                0x00, 0x00,
                0x00, 0x40,
                0xff, 0x7f,
            ]
        )
    }
    func testAudioStatsCountMicrophoneAndSystemFramesSeparately() {
        var stats = AudioPipelineStats()
        stats.recordFrame(source: .microphone, byteCount: 320)
        stats.recordFrame(source: .system, byteCount: 640)
        stats.recordFrame(source: .microphone, byteCount: 160)
        XCTAssertEqual(stats.microphoneFrames, 2)
        XCTAssertEqual(stats.microphoneBytes, 480)
        XCTAssertEqual(stats.systemFrames, 1)
        XCTAssertEqual(stats.systemBytes, 640)
    }
 }
@@ -0,0 +1,24 @@
 import XCTest
@testable import MastermindPOCCore
 final class OverlayActionsTests: XCTestCase {
    func testOverlayActionsInvokeInjectedCallbacks() {
        var openedSettings = false
        var hidOverlay = false
        var quitApp = false
        let actions = OverlayActions(
            openSettings: { openedSettings = true },
            hideOverlay: { hidOverlay = true },
            quitApp: { quitApp = true }
        )
        actions.openSettings()
        actions.hideOverlay()
        actions.quitApp()
        XCTAssertTrue(openedSettings)
        XCTAssertTrue(hidOverlay)
        XCTAssertTrue(quitApp)
    }
 }
@@ -0,0 +1,26 @@
 import XCTest
@testable import MastermindPOCCore
 final class OverlaySettingsTests: XCTestCase {
    func testDefaultOpacityIsReadableHudDefault() {
        XCTAssertEqual(OverlaySettings.default.backgroundOpacity, 0.72, accuracy: 0.0001)
    }
    func testOpacityBelowMinimumClampsToMinimum() {
        let settings = OverlaySettings(backgroundOpacity: 0.1)
        XCTAssertEqual(settings.backgroundOpacity, 0.35, accuracy: 0.0001)
    }
    func testOpacityAboveMaximumClampsToMaximum() {
        let settings = OverlaySettings(backgroundOpacity: 1.0)
        XCTAssertEqual(settings.backgroundOpacity, 0.95, accuracy: 0.0001)
    }
    func testValidOpacityStaysUnchanged() {
        let settings = OverlaySettings(backgroundOpacity: 0.64)
        XCTAssertEqual(settings.backgroundOpacity, 0.64, accuracy: 0.0001)
    }
 }
@@ -0,0 +1,21 @@
 import XCTest
@testable import MastermindPOCCore
 final class TrustStatusTests: XCTestCase {
    func testMenuBarTitlesDescribeVisibleAssistantState() {
        XCTAssertEqual(TrustStatus.idle.menuBarTitle, "Mastermind: Idle")
        XCTAssertEqual(TrustStatus.listening.menuBarTitle, "Mastermind: Listening")
        XCTAssertEqual(TrustStatus.screenContext.menuBarTitle, "Mastermind: Screen")
        XCTAssertEqual(TrustStatus.systemAudio.menuBarTitle, "Mastermind: System Audio")
        XCTAssertEqual(TrustStatus.paused.menuBarTitle, "Mastermind: Paused")
        XCTAssertEqual(TrustStatus.error("No permission").menuBarTitle, "Mastermind: Error")
    }
    func testCaptureStatesIdentifyActiveCapture() {
        XCTAssertFalse(TrustStatus.idle.isCapturing)
        XCTAssertFalse(TrustStatus.paused.isCapturing)
        XCTAssertTrue(TrustStatus.listening.isCapturing)
        XCTAssertTrue(TrustStatus.screenContext.isCapturing)
        XCTAssertTrue(TrustStatus.systemAudio.isCapturing)
    }
 }
@@ -0,0 +1,58 @@
 #!/usr/bin/env bash
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 APP_NAME="MastermindPOC"
 BUILD_DIR="$ROOT_DIR/build"
 APP_DIR="$BUILD_DIR/$APP_NAME.app"
 CONTENTS_DIR="$APP_DIR/Contents"
 MACOS_DIR="$CONTENTS_DIR/MacOS"
 export CLANG_MODULE_CACHE_PATH="$ROOT_DIR/.build/module-cache"
 cd "$ROOT_DIR"
 swift build --product "$APP_NAME"
 rm -rf "$APP_DIR"
 mkdir -p "$MACOS_DIR"
 cp "$ROOT_DIR/.build/debug/$APP_NAME" "$MACOS_DIR/$APP_NAME"
 chmod +x "$MACOS_DIR/$APP_NAME"
 cat > "$CONTENTS_DIR/Info.plist" <<'PLIST'
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
    <key>CFBundleDevelopmentRegion</key>
    <string>en</string>
    <key>CFBundleDisplayName</key>
    <string>Mastermind POC</string>
    <key>CFBundleExecutable</key>
    <string>MastermindPOC</string>
    <key>CFBundleIdentifier</key>
    <string>app.mastermind.poc</string>
    <key>CFBundleInfoDictionaryVersion</key>
    <string>6.0</string>
    <key>CFBundleName</key>
    <string>Mastermind POC</string>
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleShortVersionString</key>
    <string>0.1.0</string>
    <key>CFBundleVersion</key>
    <string>1</string>
    <key>LSMinimumSystemVersion</key>
    <string>14.0</string>
    <key>LSUIElement</key>
    <true/>
    <key>NSMicrophoneUsageDescription</key>
    <string>Mastermind POC uses microphone audio only when you start microphone capture.</string>
 </dict>
 </plist>
 PLIST
 printf 'APPL????' > "$CONTENTS_DIR/PkgInfo"
 echo "Built $APP_DIR"
@@ -1,7 +1,7 @@
 {
  "name": "mastermind",
  "productName": "Mastermind",
-  "version": "0.7.6",
+  "version": "0.7.9",
  "description": "Mastermind AI assistant",
  "main": "src/index.js",
  "scripts": {
@@ -10,6 +10,8 @@
    "make": "electron-forge make",
    "publish": "electron-forge publish",
    "lint": "echo \"No linting configured\"",
    "test:local-providers": "node --test test/localProviders.test.js",
    "mock:nemotron-sidecar": "node scripts/mock-nemotron-sidecar.js",
    "postinstall": "electron-rebuild -f -w onnxruntime-node"
  },
  "keywords": [
@@ -0,0 +1,66 @@
 #!/usr/bin/env node
 const WebSocket = require("ws");
 const port = Number(process.env.MOCK_NEMOTRON_PORT || 8765);
 const transcript =
  process.env.MOCK_NEMOTRON_TRANSCRIPT ||
  "hello from the mock nemotron sidecar";
 const server = new WebSocket.Server({ host: "127.0.0.1", port });
 server.on("connection", (socket) => {
  let binaryChunks = 0;
  let finalSent = false;
  socket.on("message", (data, isBinary) => {
    if (!isBinary) {
      let message = null;
      try {
        message = JSON.parse(data.toString("utf8"));
      } catch (_) {
        socket.send(JSON.stringify({ type: "error", error: "Invalid JSON" }));
        return;
      }
      if (message.type === "start") {
        socket.send(JSON.stringify({ type: "ready" }));
      }
      return;
    }
    binaryChunks += 1;
    if (binaryChunks === 1) {
      socket.send(
        JSON.stringify({
          type: "partial",
          text: transcript.split(" ").slice(0, 3).join(" "),
        }),
      );
    }
    if (!finalSent && binaryChunks >= 5) {
      finalSent = true;
      socket.send(JSON.stringify({ type: "final", text: transcript }));
    }
  });
 });
 server.on("listening", () => {
  console.log(
    `Mock Nemotron sidecar listening on ws://127.0.0.1:${port}/v1/asr/stream`,
  );
 });
 server.on("error", (error) => {
  console.error("Mock Nemotron sidecar error:", error);
  process.exitCode = 1;
 });
 function shutdown() {
  server.close(() => process.exit(0));
 }
 process.on("SIGINT", shutdown);
 process.on("SIGTERM", shutdown);
@@ -612,7 +612,7 @@ export class CheatingDaddyApp extends LitElement {
  async handleStart() {
    const prefs = await cheatingDaddy.storage.getPreferences();
-    const providerMode = prefs.providerMode || "byok";
+    const providerMode = prefs.providerMode || "local";
    if (providerMode === "local") {
      const success = await cheatingDaddy.initializeLocal(this.selectedProfile);
@@ -1,143 +1,160 @@
-import { html, css, LitElement } from '../../assets/lit-core-2.7.4.min.js';
+import { html, css, LitElement } from "../../assets/lit-core-2.7.4.min.js";
-import { unifiedPageStyles } from './sharedPageStyles.js';
+import { unifiedPageStyles } from "./sharedPageStyles.js";
 export class AICustomizeView extends LitElement {
-    static styles = [
+  static styles = [
-        unifiedPageStyles,
+    unifiedPageStyles,
-        css`
+    css`
-            .unified-page {
+      .unified-page {
-                height: 100%;
+        height: 100%;
-            }
+      }
-            .unified-wrap {
+      .unified-wrap {
-                height: 100%;
+        height: 100%;
-            }
+      }
-            section.surface {
+      section.surface {
-                flex: 1;
+        flex: 1;
-                display: flex;
+        display: flex;
-                flex-direction: column;
+        flex-direction: column;
-            }
+      }
-            .form-grid {
+      .form-grid {
-                flex: 1;
+        flex: 1;
-                display: flex;
+        display: flex;
-                flex-direction: column;
+        flex-direction: column;
-            }
+      }
-            .form-group.vertical {
+      .form-group.vertical {
-                flex: 1;
+        flex: 1;
-                display: flex;
+        display: flex;
-                flex-direction: column;
+        flex-direction: column;
-            }
+      }
-            textarea.control {
+      textarea.control {
-                flex: 1;
+        flex: 1;
-                resize: none;
+        resize: none;
-                overflow-y: auto;
+        overflow-y: auto;
-                min-height: 0;
+        min-height: 0;
-            }
+      }
-        `,
+    `,
  ];
  static properties = {
    selectedProfile: { type: String },
    onProfileChange: { type: Function },
    _context: { state: true },
    _providerMode: { state: true },
  };
  constructor() {
    super();
    this.selectedProfile = "interview";
    this.onProfileChange = () => {};
    this._context = "";
    this._providerMode = "local";
    this._loadFromStorage();
  }
  async _loadFromStorage() {
    try {
      const prefs = await cheatingDaddy.storage.getPreferences();
      this._context = prefs.customPrompt || "";
      this._providerMode = prefs.providerMode || "local";
      this.requestUpdate();
    } catch (error) {
      console.error("Error loading AI customize storage:", error);
    }
  }
  _handleProfileChange(e) {
    this.onProfileChange(e.target.value);
  }
  async _handleProviderModeChange(e) {
    this._providerMode = e.target.value;
    await cheatingDaddy.storage.updatePreference(
      "providerMode",
      this._providerMode,
    );
    this.requestUpdate();
  }
  async _saveContext(val) {
    this._context = val;
    await cheatingDaddy.storage.updatePreference("customPrompt", val);
  }
  _getProfileName(profile) {
    const names = {
      interview: "Job Interview",
      sales: "Sales Call",
      meeting: "Business Meeting",
      presentation: "Presentation",
      negotiation: "Negotiation",
      exam: "Exam Assistant",
    };
    return names[profile] || profile;
  }
  render() {
    const profiles = [
      { value: "interview", label: "Job Interview" },
      { value: "sales", label: "Sales Call" },
      { value: "meeting", label: "Business Meeting" },
      { value: "presentation", label: "Presentation" },
      { value: "negotiation", label: "Negotiation" },
      { value: "exam", label: "Exam Assistant" },
    ];
-    static properties = {
+    return html`
-        selectedProfile: { type: String },
+      <div class="unified-page">
-        onProfileChange: { type: Function },
+        <div class="unified-wrap">
-        _context: { state: true },
+          <div>
-        _providerMode: { state: true },
+            <div class="page-title">AI Context</div>
-    };
+          </div>
    constructor() {
        super();
        this.selectedProfile = 'interview';
        this.onProfileChange = () => {};
        this._context = '';
        this._providerMode = 'byok';
        this._loadFromStorage();
    }
    async _loadFromStorage() {
        try {
            const prefs = await cheatingDaddy.storage.getPreferences();
            this._context = prefs.customPrompt || '';
            this._providerMode = prefs.providerMode || 'byok';
            this.requestUpdate();
        } catch (error) {
            console.error('Error loading AI customize storage:', error);
        }
    }
    _handleProfileChange(e) {
        this.onProfileChange(e.target.value);
    }
    async _handleProviderModeChange(e) {
        this._providerMode = e.target.value;
        await cheatingDaddy.storage.updatePreference('providerMode', this._providerMode);
        this.requestUpdate();
    }
    async _saveContext(val) {
        this._context = val;
        await cheatingDaddy.storage.updatePreference('customPrompt', val);
    }
    _getProfileName(profile) {
        const names = {
            interview: 'Job Interview',
            sales: 'Sales Call',
            meeting: 'Business Meeting',
            presentation: 'Presentation',
            negotiation: 'Negotiation',
            exam: 'Exam Assistant',
        };
        return names[profile] || profile;
    }
    render() {
        const profiles = [
            { value: 'interview', label: 'Job Interview' },
            { value: 'sales', label: 'Sales Call' },
            { value: 'meeting', label: 'Business Meeting' },
            { value: 'presentation', label: 'Presentation' },
            { value: 'negotiation', label: 'Negotiation' },
            { value: 'exam', label: 'Exam Assistant' },
        ];
        return html`
            <div class="unified-page">
                <div class="unified-wrap">
                    <div>
                        <div class="page-title">AI Context</div>
                    </div>
                    <section class="surface">
                        <div class="form-grid">
                            <div class="form-group">
                                <label class="form-label">Regime</label>
                                <select class="control" .value=${this._providerMode} @change=${this._handleProviderModeChange}>
                                    <option value="byok">BYOK (API Keys)</option>
                                    <option value="local">Local AI (Ollama)</option>
                                </select>
                            </div>
                            <div class="form-group">
                                <label class="form-label">Profile</label>
                                <select class="control" .value=${this.selectedProfile} @change=${this._handleProfileChange}>
                                    ${profiles.map(profile => html`<option value=${profile.value}>${profile.label}</option>`)}
                                </select>
                            </div>
                            <div class="form-group vertical">
                                <label class="form-label">Custom Instructions</label>
                                <textarea
                                    class="control"
                                    placeholder="Resume details, role requirements, constraints..."
                                    .value=${this._context}
                                    @input=${e => this._saveContext(e.target.value)}
                                ></textarea>
                                <div class="form-help">Sent as context at session start. Keep it short.</div>
                            </div>
                        </div>
                    </section>
          <section class="surface">
            <div class="form-grid">
              <div class="form-group">
                <label class="form-label">Regime</label>
                <select
                  class="control"
                  .value=${this._providerMode}
                  @change=${this._handleProviderModeChange}
                >
                  <option value="byok">BYOK (API Keys)</option>
                  <option value="local">Local AI (LM Studio)</option>
                </select>
              </div>
              <div class="form-group">
                <label class="form-label">Profile</label>
                <select
                  class="control"
                  .value=${this.selectedProfile}
                  @change=${this._handleProfileChange}
                >
                  ${profiles.map(
                    (profile) =>
                      html`<option value=${profile.value}>
                        ${profile.label}
                      </option>`,
                  )}
                </select>
              </div>
              <div class="form-group vertical">
                <label class="form-label">Custom Instructions</label>
                <textarea
                  class="control"
                  placeholder="Resume details, role requirements, constraints..."
                  .value=${this._context}
                  @input=${(e) => this._saveContext(e.target.value)}
                ></textarea>
                <div class="form-help">
                  Sent as context at session start. Keep it short.
                </div>
              </div>
            </div>
-        `;
+          </section>
-    }
+        </div>
      </div>
    `;
  }
 }
-customElements.define('ai-customize-view', AICustomizeView);
+customElements.define("ai-customize-view", AICustomizeView);
@@ -208,7 +208,7 @@ export class CustomizeView extends LitElement {
    this.onImageQualityChange = () => {};
    this.onLayoutModeChange = () => {};
    this.googleSearchEnabled = true;
-    this.providerMode = "byok";
+    this.providerMode = "local";
    this.isClearing = false;
    this.isRestoring = false;
    this.clearStatusMessage = "";
@@ -232,7 +232,7 @@ export class CustomizeView extends LitElement {
        cheatingDaddy.storage.getKeybinds(),
      ]);
      this.googleSearchEnabled = prefs.googleSearchEnabled ?? true;
-      this.providerMode = prefs.providerMode || "byok";
+      this.providerMode = prefs.providerMode || "local";
      this.backgroundTransparency = prefs.backgroundTransparency ?? 0.8;
      this.fontSize = prefs.fontSize ?? 20;
      this.audioMode = prefs.audioMode ?? "speaker_only";
@@ -664,7 +664,7 @@ export class CustomizeView extends LitElement {
              @change=${this.handleProviderModeChange}
            >
              <option value="byok">BYOK (API Keys)</option>
-              <option value="local">Local AI (Ollama)</option>
+              <option value="local">Local AI (LM Studio)</option>
            </select>
          </div>
        </div>
@@ -501,6 +501,11 @@ export class MainView extends LitElement {
    _whisperModel: { state: true },
    _customWhisperModel: { state: true },
    _showLocalHelp: { state: true },
    _localLlmBaseUrl: { state: true },
    _localLlmModel: { state: true },
    _localLlmApiKey: { state: true },
    _localSttUrl: { state: true },
    _localSttLanguage: { state: true },
  };
  constructor() {
@@ -513,7 +518,7 @@ export class MainView extends LitElement {
    this.whisperDownloading = false;
    this.whisperProgress = null;
-    this._mode = "byok";
+    this._mode = "local";
    this._token = "";
    this._geminiKey = "";
    this._groqKey = "";
@@ -528,6 +533,11 @@ export class MainView extends LitElement {
    this._tokenError = false;
    this._keyError = false;
    this._showLocalHelp = false;
    this._localLlmBaseUrl = "http://127.0.0.1:1234/v1";
    this._localLlmModel = "";
    this._localLlmApiKey = "";
    this._localSttUrl = "ws://127.0.0.1:8765/v1/asr/stream";
    this._localSttLanguage = "en-US";
    this._ollamaHost = "http://127.0.0.1:11434";
    this._ollamaModel = "llama3.1";
    this._whisperModel = "Xenova/whisper-small";
@@ -549,7 +559,7 @@ export class MainView extends LitElement {
        cheatingDaddy.storage.getCredentials().catch(() => ({})),
      ]);
-      this._mode = prefs.providerMode || "byok";
+      this._mode = prefs.providerMode || "local";
      // Load keys
      this._token = "";
@@ -571,6 +581,13 @@ export class MainView extends LitElement {
      this._responseProvider = prefs.responseProvider || "gemini";
      // Load local AI settings
      this._localLlmBaseUrl =
        prefs.localLlmBaseUrl || "http://127.0.0.1:1234/v1";
      this._localLlmModel = prefs.localLlmModel || "";
      this._localLlmApiKey = prefs.localLlmApiKey || "";
      this._localSttUrl =
        prefs.localSttUrl || "ws://127.0.0.1:8765/v1/asr/stream";
      this._localSttLanguage = prefs.localSttLanguage || "en-US";
      this._ollamaHost = prefs.ollamaHost || "http://127.0.0.1:11434";
      this._ollamaModel = prefs.ollamaModel || "llama3.1";
      this._whisperModel = prefs.whisperModel || "Xenova/whisper-small";
@@ -917,6 +934,51 @@ export class MainView extends LitElement {
    this.requestUpdate();
  }
  async _saveLocalLlmBaseUrl(val) {
    this._localLlmBaseUrl = val;
    await cheatingDaddy.storage.updatePreference("localLlmBaseUrl", val);
    this.requestUpdate();
  }
  async _saveLocalLlmModel(val) {
    this._localLlmModel = val;
    await cheatingDaddy.storage.updatePreference("localLlmModel", val);
    this.requestUpdate();
  }
  async _saveLocalLlmApiKey(val) {
    this._localLlmApiKey = val;
    await cheatingDaddy.storage.updatePreference("localLlmApiKey", val);
    this.requestUpdate();
  }
  async _saveLocalSttUrl(val) {
    this._localSttUrl = val;
    await cheatingDaddy.storage.updatePreference("localSttUrl", val);
    this.requestUpdate();
  }
  async _saveLocalSttLanguage(val) {
    this._localSttLanguage = val;
    await cheatingDaddy.storage.updatePreference("localSttLanguage", val);
    this.requestUpdate();
  }
  _isLoopbackUrl(value) {
    try {
      const url = new URL(value);
      const hostname = url.hostname.toLowerCase();
      return (
        hostname === "localhost" ||
        hostname === "127.0.0.1" ||
        hostname === "::1" ||
        hostname === "[::1]"
      );
    } catch (_) {
      return false;
    }
  }
  async _saveOllamaHost(val) {
    this._ollamaHost = val;
    await cheatingDaddy.storage.updatePreference("ollamaHost", val);
@@ -1002,8 +1064,13 @@ export class MainView extends LitElement {
        return;
      }
    } else if (this._mode === "local") {
-      // Local mode doesn't need API keys, just Ollama host
+      if (
-      if (!this._ollamaHost.trim()) {
+        !this._localLlmBaseUrl.trim() ||
        !this._localLlmModel.trim() ||
        !this._localSttUrl.trim()
      ) {
        this._keyError = true;
        this.requestUpdate();
        return;
      }
    }
@@ -1258,105 +1325,88 @@ export class MainView extends LitElement {
  // ── Local AI mode ──
  _renderLocalMode() {
    const llmIsLocal = this._isLoopbackUrl(this._localLlmBaseUrl);
    const sttIsLocal = this._isLoopbackUrl(this._localSttUrl);
    return html`
      <div class="form-group">
-        <label class="form-label">Ollama Host</label>
+        <label class="form-label">LM Studio Base URL</label>
        <input
          type="text"
-          placeholder="http://127.0.0.1:11434"
+          placeholder="http://127.0.0.1:1234/v1"
-          .value=${this._ollamaHost}
+          .value=${this._localLlmBaseUrl}
-          @input=${(e) => this._saveOllamaHost(e.target.value)}
+          @input=${(e) => this._saveLocalLlmBaseUrl(e.target.value)}
-        />
+          class=${this._keyError && !this._localLlmBaseUrl.trim()
-        <div class="form-hint">Ollama must be running locally</div>
+            ? "error"
-      </div>
+            : ""}
      <div class="form-group">
        <label class="form-label">Ollama Model</label>
        <input
          type="text"
          placeholder="llama3.1"
          .value=${this._ollamaModel}
          @input=${(e) => this._saveOllamaModel(e.target.value)}
        />
        <div class="form-hint">
-          Run
+          LM Studio local server endpoint for OpenAI-compatible chat
-          <code
+          ${!llmIsLocal
-            style="font-family: var(--font-mono); font-size: 11px; background: var(--bg-elevated); padding: 1px 4px; border-radius: 3px;"
+            ? html`<span style="color: var(--warning, #d97706);">
-            >ollama pull ${this._ollamaModel}</code
+                · not a localhost URL
-          >
+              </span>`
-          first
+            : ""}
        </div>
      </div>
      <div class="form-group">
-        <div class="whisper-label-row">
+        <label class="form-label">LM Studio Model ID</label>
-          <label class="form-label">Whisper Model</label>
+        <input
-          ${this.whisperDownloading
+          type="text"
-            ? html`<div class="whisper-spinner"></div>`
+          placeholder="gemma-4 or the exact loaded model id"
          .value=${this._localLlmModel}
          @input=${(e) => this._saveLocalLlmModel(e.target.value)}
          class=${this._keyError && !this._localLlmModel.trim() ? "error" : ""}
        />
        <div class="form-hint">
          Manual only: use the model identifier shown in LM Studio
        </div>
      </div>
      <div class="form-group">
        <label class="form-label">LM Studio API Key</label>
        <input
          type="password"
          placeholder="Optional for most local LM Studio setups"
          .value=${this._localLlmApiKey}
          @input=${(e) => this._saveLocalLlmApiKey(e.target.value)}
        />
        <div class="form-hint">
          Leave blank unless your local server requires a token
        </div>
      </div>
      <div class="form-group">
        <label class="form-label">Nemotron ASR Sidecar URL</label>
        <input
          type="text"
          placeholder="ws://127.0.0.1:8765/v1/asr/stream"
          .value=${this._localSttUrl}
          @input=${(e) => this._saveLocalSttUrl(e.target.value)}
          class=${this._keyError && !this._localSttUrl.trim() ? "error" : ""}
        />
        <div class="form-hint">
          External streaming STT service that accepts 16 kHz mono PCM
          ${!sttIsLocal
            ? html`<span style="color: var(--warning, #d97706);">
                · not a localhost URL
              </span>`
            : ""}
        </div>
-        <select
+      </div>
-          .value=${this._whisperModel}
+
-          @change=${(e) => this._saveWhisperModel(e.target.value)}
+      <div class="form-group">
-        >
+        <label class="form-label">STT Language</label>
-          <option
+        <input
-            value="Xenova/whisper-tiny"
+          type="text"
-            ?selected=${this._whisperModel === "Xenova/whisper-tiny"}
+          placeholder="en-US"
-          >
+          .value=${this._localSttLanguage}
-            Tiny (fastest, least accurate)
+          @input=${(e) => this._saveLocalSttLanguage(e.target.value)}
-          </option>
+        />
-          <option
+        <div class="form-hint">
-            value="Xenova/whisper-base"
+          First local sidecar target is English streaming ASR
-            ?selected=${this._whisperModel === "Xenova/whisper-base"}
+        </div>
          >
            Base
          </option>
          <option
            value="Xenova/whisper-small"
            ?selected=${this._whisperModel === "Xenova/whisper-small"}
          >
            Small (recommended)
          </option>
          <option
            value="Xenova/whisper-medium"
            ?selected=${this._whisperModel === "Xenova/whisper-medium"}
          >
            Medium (most accurate, slowest)
          </option>
          <option
            value="__custom__"
            ?selected=${this._whisperModel === "__custom__"}
          >
            Custom HuggingFace model...
          </option>
        </select>
        ${this._whisperModel === "__custom__"
          ? html`
              <input
                type="text"
                placeholder="e.g. onnx-community/whisper-large-v3-turbo"
                .value=${this._customWhisperModel}
                @change=${(e) => this._saveCustomWhisperModel(e.target.value)}
                @input=${(e) => {
                  this._customWhisperModel = e.target.value;
                }}
                style="margin-top: 6px;"
              />
              <div class="form-hint">
                Enter a HuggingFace model ID compatible with
                @huggingface/transformers speech-to-text pipeline
              </div>
            `
          : html`
              <div class="form-hint">
                ${this.whisperDownloading
                  ? "Downloading model..."
                  : "Downloaded automatically on first use"}
              </div>
            `}
        ${this.whisperDownloading && this.whisperProgress
          ? this._renderWhisperProgress()
          : ""}
      </div>
      ${this._renderStartButton()}
@@ -1458,74 +1508,51 @@ export class MainView extends LitElement {
    return html`
      <div class="help-content">
        <div class="help-section">
-          <div class="help-section-title">What is Ollama?</div>
+          <div class="help-section-title">LM Studio</div>
          <div class="help-section-text">
-            Ollama lets you run large language models locally on your machine.
+            LM Studio runs the answer model locally and exposes an
-            Everything stays on your computer — no data leaves your device.
+            OpenAI-compatible server for streaming responses.
          </div>
        </div>
        <div class="help-section">
-          <div class="help-section-title">Install Ollama</div>
+          <div class="help-section-title">Start LM Studio server</div>
          <div class="help-section-text">
-            Download from
+            Download LM Studio, load a model, then start the local server from
-            <span
+            the Developer tab. The default endpoint is:
-              class="help-link"
+          </div>
-              @click=${() => this.onExternalLink("https://ollama.com/download")}
+          <code class="help-code">http://127.0.0.1:1234/v1</code>
-              >ollama.com/download</span
+        </div>
-            >
+
-            and install it.
+        <div class="help-section">
          <div class="help-section-title">Model ID</div>
          <div class="help-section-text">
            Enter the exact model identifier shown by LM Studio. Gemma 4 is the
            reference target, but any loaded compatible model can be used.
          </div>
        </div>
        <div class="help-section">
-          <div class="help-section-title">Ollama must be running</div>
+          <div class="help-section-title">Nemotron ASR sidecar</div>
          <div class="help-section-text">
-            Ollama needs to be running before you start a session. If it's not
+            Speech-to-text runs as a separate local streaming service. The app
-            running, open your terminal and type:
+            connects to:
          </div>
-          <code class="help-code">ollama serve</code>
+          <code class="help-code">ws://127.0.0.1:8765/v1/asr/stream</code>
        </div>
        <div class="help-section">
-          <div class="help-section-title">Pull a model</div>
+          <div class="help-section-title">Screenshots</div>
          <div class="help-section-text">
-            Download a model before first use:
+            Manual screenshots are sent to the same local LM Studio model. Use a
-          </div>
+            vision-capable model for screen analysis.
          <code class="help-code">ollama pull gemma3:4b</code>
        </div>
        <div class="help-section">
          <div class="help-section-title">Recommended models</div>
          <div class="help-models">
            <div class="help-model">
              <span class="help-model-name">gemma3:4b</span
              ><span>4B — fast, multimodal (images + text)</span>
            </div>
            <div class="help-model">
              <span class="help-model-name">mistral-small</span
              ><span>8B — solid all-rounder, text only</span>
            </div>
          </div>
          <div class="help-section-text">
            gemma3:4b and above supports images — screenshots will work with
            these models.
          </div>
        </div>
        <div class="help-section">
          <div class="help-warn">
-            Avoid "thinking" models (e.g. deepseek-r1, qwq). Local inference is
+            Non-local endpoints are allowed, but they may send audio transcripts
-            already slower — a thinking model adds extra delay before
+            or screenshots outside this machine.
            responding.
          </div>
        </div>
        <div class="help-section">
          <div class="help-section-title">Whisper</div>
          <div class="help-section-text">
            The Whisper speech-to-text model is downloaded automatically the
            first time you start a session. This is a one-time download.
          </div>
        </div>
      </div>
@@ -30,7 +30,15 @@ const DEFAULT_PREFERENCES = {
  fontSize: "medium",
  backgroundTransparency: 0.8,
  googleSearchEnabled: false,
  providerMode: "local",
  responseProvider: "gemini",
  llmProvider: "lmstudio",
  sttProvider: "nemotron-sidecar",
  localLlmBaseUrl: "http://127.0.0.1:1234/v1",
  localLlmModel: "",
  localLlmApiKey: "",
  localSttUrl: "ws://127.0.0.1:8765/v1/asr/stream",
  localSttLanguage: "en-US",
  ollamaHost: "http://127.0.0.1:11434",
  ollamaModel: "llama3.1",
  whisperModel: "Xenova/whisper-small",
@@ -1073,7 +1073,7 @@ function setupGeminiIpcHandlers(geminiSessionRef) {
    "initialize-local",
    async (
      event,
-      ollamaHost,
+      localConfigOrOllamaHost,
      ollamaModel,
      whisperModel,
      profile,
@@ -1081,7 +1081,7 @@ function setupGeminiIpcHandlers(geminiSessionRef) {
    ) => {
      currentProviderMode = "local";
      const success = await getLocalAi().initializeLocalSession(
-        ollamaHost,
+        localConfigOrOllamaHost,
        ollamaModel,
        whisperModel,
        profile,
@@ -0,0 +1,304 @@
 const { EventEmitter } = require("events");
 const WebSocket = require("ws");
 const DEFAULT_LOCAL_LLM_BASE_URL = "http://127.0.0.1:1234/v1";
 const DEFAULT_LOCAL_STT_URL = "ws://127.0.0.1:8765/v1/asr/stream";
 const DEFAULT_LOCAL_STT_LANGUAGE = "en-US";
 function normalizeOpenAiBaseUrl(baseUrl) {
  const trimmed = (baseUrl || DEFAULT_LOCAL_LLM_BASE_URL)
    .trim()
    .replace(/\/+$/, "");
  if (!trimmed) return DEFAULT_LOCAL_LLM_BASE_URL;
  return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
 }
 function isLoopbackUrl(value) {
  try {
    const url = new URL(value);
    const hostname = url.hostname.toLowerCase();
    return (
      hostname === "localhost" ||
      hostname === "127.0.0.1" ||
      hostname === "::1" ||
      hostname === "[::1]"
    );
  } catch (_) {
    return false;
  }
 }
 function buildChatMessages({
  systemPrompt,
  history = [],
  userText,
  imageBase64,
 }) {
  const messages = [];
  if (systemPrompt && systemPrompt.trim()) {
    messages.push({ role: "system", content: systemPrompt.trim() });
  }
  for (const message of history) {
    if (!message || !message.role || !message.content) continue;
    if (
      message.role !== "user" &&
      message.role !== "assistant" &&
      message.role !== "system"
    )
      continue;
    messages.push({
      role: message.role,
      content: String(message.content),
    });
  }
  const text = (userText || "").trim();
  if (imageBase64) {
    messages.push({
      role: "user",
      content: [
        { type: "text", text },
        {
          type: "image_url",
          image_url: { url: `data:image/jpeg;base64,${imageBase64}` },
        },
      ],
    });
  } else if (text) {
    messages.push({ role: "user", content: text });
  }
  return messages;
 }
 function parseChatCompletionSseLine(line) {
  if (!line.startsWith("data: ")) return null;
  const data = line.slice(6).trim();
  if (!data || data === "[DONE]") return null;
  const parsed = JSON.parse(data);
  return parsed.choices?.[0]?.delta?.content || "";
 }
 async function streamLmStudioChat({
  baseUrl,
  apiKey,
  model,
  messages,
  temperature = 0.7,
  maxTokens = 2048,
  onToken,
 }) {
  if (!model || !model.trim()) {
    throw new Error("LM Studio model id is required");
  }
  const normalizedBaseUrl = normalizeOpenAiBaseUrl(baseUrl);
  const response = await fetch(`${normalizedBaseUrl}/chat/completions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      ...(apiKey && apiKey.trim()
        ? { Authorization: `Bearer ${apiKey.trim()}` }
        : {}),
    },
    body: JSON.stringify({
      model: model.trim(),
      messages,
      stream: true,
      temperature,
      max_tokens: maxTokens,
    }),
  });
  if (!response.ok) {
    const errorText = await response.text().catch(() => "");
    if (response.status === 400 && /image|vision|multimodal/i.test(errorText)) {
      throw new Error(
        "The selected local model does not appear to support image input",
      );
    }
    throw new Error(
      `LM Studio error ${response.status}: ${errorText || response.statusText}`,
    );
  }
  if (!response.body) {
    throw new Error("LM Studio response did not include a stream body");
  }
  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = "";
  let fullText = "";
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split(/\r?\n/);
    buffer = lines.pop() || "";
    for (const line of lines) {
      const trimmed = line.trim();
      if (!trimmed) continue;
      let token = "";
      try {
        token = parseChatCompletionSseLine(trimmed) || "";
      } catch (_) {
        continue;
      }
      if (token) {
        fullText += token;
        if (onToken) onToken(token, fullText);
      }
    }
  }
  return fullText;
 }
 class NemotronSidecarClient extends EventEmitter {
  constructor({
    url = DEFAULT_LOCAL_STT_URL,
    language = DEFAULT_LOCAL_STT_LANGUAGE,
    sampleRate = 16000,
    channels = 1,
    encoding = "pcm_s16le",
  } = {}) {
    super();
    this.url = url;
    this.language = language;
    this.sampleRate = sampleRate;
    this.channels = channels;
    this.encoding = encoding;
    this.socket = null;
    this.connected = false;
  }
  connect() {
    if (this.connected && this.socket?.readyState === WebSocket.OPEN) {
      return Promise.resolve();
    }
    return new Promise((resolve, reject) => {
      const socket = new WebSocket(this.url);
      this.socket = socket;
      const cleanup = () => {
        socket.removeListener("open", onOpen);
        socket.removeListener("error", onErrorBeforeOpen);
      };
      const onOpen = () => {
        cleanup();
        this.connected = true;
        this.emit("connected");
        this._sendStart();
        resolve();
      };
      const onErrorBeforeOpen = (error) => {
        cleanup();
        this.connected = false;
        this.emit("error", error);
        reject(error);
      };
      socket.once("open", onOpen);
      socket.once("error", onErrorBeforeOpen);
      socket.on("message", (data) => this._handleMessage(data));
      socket.on("close", (code, reason) => {
        this.connected = false;
        this.emit("close", { code, reason: reason?.toString?.() || "" });
      });
      socket.on("error", (error) => {
        this.connected = false;
        this.emit("error", error);
      });
    });
  }
  _sendStart() {
    if (!this.socket || this.socket.readyState !== WebSocket.OPEN) return;
    this.socket.send(
      JSON.stringify({
        type: "start",
        sampleRate: this.sampleRate,
        channels: this.channels,
        encoding: this.encoding,
        language: this.language,
      }),
    );
  }
  _handleMessage(data) {
    let message;
    try {
      message = JSON.parse(data.toString("utf8"));
    } catch (error) {
      this.emit(
        "error",
        new Error(`Invalid ASR sidecar message: ${error.message}`),
      );
      return;
    }
    if (!message || !message.type) return;
    if (message.type === "partial") {
      this.emit("partial", message.text || "");
    } else if (message.type === "final") {
      this.emit("final", message.text || "");
    } else if (message.type === "ready") {
      this.emit("ready", message);
    } else if (message.type === "error") {
      this.emit(
        "error",
        new Error(message.error || message.message || "ASR sidecar error"),
      );
    } else {
      this.emit(message.type, message);
    }
  }
  sendAudio(pcm16kBuffer) {
    if (!this.socket || this.socket.readyState !== WebSocket.OPEN) return false;
    if (!pcm16kBuffer || pcm16kBuffer.length === 0) return false;
    this.socket.send(pcm16kBuffer, { binary: true });
    return true;
  }
  close() {
    if (!this.socket) return;
    try {
      if (this.socket.readyState === WebSocket.OPEN) {
        this.socket.send(JSON.stringify({ type: "stop" }));
      }
      this.socket.close();
    } catch (_) {
      // Best-effort close.
    }
    this.connected = false;
    this.socket = null;
  }
 }
 module.exports = {
  DEFAULT_LOCAL_LLM_BASE_URL,
  DEFAULT_LOCAL_STT_LANGUAGE,
  DEFAULT_LOCAL_STT_URL,
  NemotronSidecarClient,
  buildChatMessages,
  isLoopbackUrl,
  normalizeOpenAiBaseUrl,
  parseChatCompletionSseLine,
  streamLmStudioChat,
 };
@@ -5,6 +5,16 @@ const {
  initializeNewSession,
  saveConversationTurn,
 } = require("./gemini");
 const {
  DEFAULT_LOCAL_LLM_BASE_URL,
  DEFAULT_LOCAL_STT_LANGUAGE,
  DEFAULT_LOCAL_STT_URL,
  NemotronSidecarClient,
  buildChatMessages,
  isLoopbackUrl,
  normalizeOpenAiBaseUrl,
  streamLmStudioChat,
 } = require("./localProviders");
 const { fork } = require("child_process");
 const path = require("path");
 const { getSystemNode } = require("./nodeDetect");
@@ -19,6 +29,8 @@ let whisperReady = false;
 let localConversationHistory = [];
 let currentSystemPrompt = null;
 let isLocalActive = false;
 let localConfig = null;
 let nemotronClient = null;
 // Set when we intentionally kill the worker to suppress crash handling
 let whisperShuttingDown = false;
@@ -63,6 +75,58 @@ const MAX_SPEECH_BUFFER_BYTES = 16000 * 2 * 30; // 960,000 bytes
 // Audio resampling buffer
 let resampleRemainder = Buffer.alloc(0);
 function resolveLocalSessionConfig(
  configOrHost,
  model,
  whisperModel,
  profile,
  customPrompt,
 ) {
  if (configOrHost && typeof configOrHost === "object") {
    return {
      llmProvider: configOrHost.llmProvider || "lmstudio",
      sttProvider: configOrHost.sttProvider || "nemotron-sidecar",
      localLlmBaseUrl:
        configOrHost.localLlmBaseUrl || DEFAULT_LOCAL_LLM_BASE_URL,
      localLlmModel: configOrHost.localLlmModel || "",
      localLlmApiKey: configOrHost.localLlmApiKey || "",
      localSttUrl: configOrHost.localSttUrl || DEFAULT_LOCAL_STT_URL,
      localSttLanguage:
        configOrHost.localSttLanguage || DEFAULT_LOCAL_STT_LANGUAGE,
      ollamaHost: configOrHost.ollamaHost || "http://127.0.0.1:11434",
      ollamaModel: configOrHost.ollamaModel || "llama3.1",
      whisperModel: configOrHost.whisperModel || "Xenova/whisper-small",
      profile: configOrHost.profile || profile || "interview",
      customPrompt: configOrHost.customPrompt || customPrompt || "",
    };
  }
  return {
    llmProvider: "ollama",
    sttProvider: "whisper",
    localLlmBaseUrl: DEFAULT_LOCAL_LLM_BASE_URL,
    localLlmModel: "",
    localLlmApiKey: "",
    localSttUrl: DEFAULT_LOCAL_STT_URL,
    localSttLanguage: DEFAULT_LOCAL_STT_LANGUAGE,
    ollamaHost: configOrHost || "http://127.0.0.1:11434",
    ollamaModel: model || "llama3.1",
    whisperModel: whisperModel || "Xenova/whisper-small",
    profile: profile || "interview",
    customPrompt: customPrompt || "",
  };
 }
 function stripThinkingTags(text) {
  return (text || "").replace(/<think>[\s\S]*?<\/think>/g, "").trim();
 }
 function trimLocalHistory(maxMessages = 40) {
  if (localConversationHistory.length > maxMessages) {
    localConversationHistory = localConversationHistory.slice(-maxMessages);
  }
 }
 // ── Audio Resampling (24kHz → 16kHz) ──
 function resample24kTo16k(inputBuffer) {
@@ -550,6 +614,66 @@ async function transcribeAudio(pcm16kBuffer) {
  });
 }
 // ── Nemotron Sidecar Streaming STT ──
 async function connectNemotronSidecar(config) {
  closeNemotronSidecar();
  nemotronClient = new NemotronSidecarClient({
    url: config.localSttUrl,
    language: config.localSttLanguage,
  });
  nemotronClient.on("connected", () => {
    sendToRenderer("update-status", "ASR sidecar connected");
  });
  nemotronClient.on("ready", () => {
    console.log("[LocalAI] Nemotron sidecar ready");
    sendToRenderer("update-status", "ASR sidecar ready - Listening...");
  });
  nemotronClient.on("partial", (text) => {
    if (!text || !text.trim()) return;
    sendToRenderer(
      "update-status",
      "Transcribing... " + text.trim().slice(-80),
    );
  });
  nemotronClient.on("final", (text) => {
    const transcription = (text || "").trim();
    if (!transcription) return;
    sendToRenderer("update-status", "Generating response...");
    handleFinalTranscription(transcription).catch((error) => {
      console.error("[LocalAI] Final transcript handler error:", error);
      sendToRenderer("update-status", "Local AI error: " + error.message);
    });
  });
  nemotronClient.on("close", ({ code }) => {
    if (!isLocalActive) return;
    console.warn("[LocalAI] Nemotron sidecar disconnected:", code);
    sendToRenderer("update-status", "ASR sidecar disconnected");
  });
  nemotronClient.on("error", (error) => {
    console.error("[LocalAI] Nemotron sidecar error:", error);
    sendToRenderer("update-status", "ASR sidecar error: " + error.message);
  });
  sendToRenderer("update-status", "Connecting to ASR sidecar...");
  await nemotronClient.connect();
 }
 function closeNemotronSidecar() {
  if (nemotronClient) {
    nemotronClient.removeAllListeners();
    nemotronClient.close();
    nemotronClient = null;
  }
 }
 // ── Speech End Handler ──
 async function handleSpeechEnd(audioData) {
@@ -578,7 +702,7 @@ async function handleSpeechEnd(audioData) {
    }
    sendToRenderer("update-status", "Generating response...");
-    await sendToOllama(transcription);
+    await handleFinalTranscription(transcription);
  } catch (error) {
    console.error("[LocalAI] handleSpeechEnd error:", error);
    sendToRenderer(
@@ -588,6 +712,144 @@ async function handleSpeechEnd(audioData) {
  }
 }
 async function handleFinalTranscription(transcription) {
  if (!localConfig) {
    await sendToOllama(transcription);
    return;
  }
  if (localConfig.llmProvider === "lmstudio") {
    await sendToLmStudio(transcription);
    return;
  }
  await sendToOllama(transcription);
 }
 // ── LM Studio Chat (OpenAI-compatible) ──
 function getLmStudioConfig() {
  return {
    baseUrl: normalizeOpenAiBaseUrl(
      localConfig?.localLlmBaseUrl || DEFAULT_LOCAL_LLM_BASE_URL,
    ),
    apiKey: localConfig?.localLlmApiKey || "",
    model: localConfig?.localLlmModel || "",
  };
 }
 async function verifyLmStudioConnection(config) {
  if (!config.localLlmModel || !config.localLlmModel.trim()) {
    sendToRenderer("update-status", "LM Studio model id is required");
    return false;
  }
  const baseUrl = normalizeOpenAiBaseUrl(config.localLlmBaseUrl);
  if (!isLoopbackUrl(baseUrl)) {
    sendToRenderer(
      "update-status",
      "Warning: LM Studio endpoint is not localhost",
    );
  }
  try {
    const response = await fetch(`${baseUrl}/models`, {
      headers: {
        ...(config.localLlmApiKey && config.localLlmApiKey.trim()
          ? { Authorization: `Bearer ${config.localLlmApiKey.trim()}` }
          : {}),
      },
    });
    if (!response.ok) {
      const text = await response.text().catch(() => "");
      throw new Error(`HTTP ${response.status}${text ? ": " + text : ""}`);
    }
    console.log("[LocalAI] LM Studio connection verified");
    sendToRenderer("update-status", "LM Studio reachable");
    return true;
  } catch (error) {
    console.error("[LocalAI] Cannot connect to LM Studio:", error);
    sendToRenderer(
      "update-status",
      "Cannot connect to LM Studio: " + error.message,
    );
    return false;
  }
 }
 async function sendToLmStudio(userText, imageBase64 = null) {
  const config = getLmStudioConfig();
  if (!config.model || !config.model.trim()) {
    sendToRenderer("update-status", "LM Studio model id is required");
    return { success: false, error: "LM Studio model id is required" };
  }
  if (!userText || !userText.trim()) {
    return { success: false, error: "Empty prompt" };
  }
  const previousHistory = localConversationHistory.slice(-20);
  const messages = buildChatMessages({
    systemPrompt: currentSystemPrompt || "You are a helpful assistant.",
    history: previousHistory,
    userText: userText.trim(),
    imageBase64,
  });
  localConversationHistory.push({
    role: "user",
    content: userText.trim(),
  });
  trimLocalHistory();
  try {
    console.log(
      `[LocalAI] Sending to LM Studio (${config.model}):`,
      userText.substring(0, 100) + "...",
    );
    let isFirst = true;
    const fullText = await streamLmStudioChat({
      baseUrl: config.baseUrl,
      apiKey: config.apiKey,
      model: config.model,
      messages,
      onToken: (_token, accumulated) => {
        const cleaned = stripThinkingTags(accumulated);
        if (!cleaned) return;
        sendToRenderer(isFirst ? "new-response" : "update-response", cleaned);
        isFirst = false;
      },
    });
    const cleanedResponse = stripThinkingTags(fullText);
    if (cleanedResponse && cleanedResponse !== fullText) {
      sendToRenderer("update-response", cleanedResponse);
    }
    if (cleanedResponse) {
      localConversationHistory.push({
        role: "assistant",
        content: cleanedResponse,
      });
      trimLocalHistory();
      saveConversationTurn(userText, cleanedResponse);
    }
    console.log("[LocalAI] LM Studio response completed");
    sendToRenderer("update-status", "Listening...");
    return { success: true, text: cleanedResponse, model: config.model };
  } catch (error) {
    console.error("[LocalAI] LM Studio error:", error);
    sendToRenderer("update-status", "LM Studio error: " + error.message);
    return { success: false, error: error.message };
  }
 }
 // ── Ollama Chat ──
 async function sendToOllama(transcription) {
@@ -658,53 +920,95 @@ async function sendToOllama(transcription) {
 // ── Public API ──
 async function initializeLocalSession(
-  ollamaHost,
+  configOrOllamaHost,
  model,
  whisperModel,
  profile,
  customPrompt,
 ) {
-  console.log("[LocalAI] Initializing local session:", {
+  const config = resolveLocalSessionConfig(
-    ollamaHost,
+    configOrOllamaHost,
    model,
    whisperModel,
    profile,
    customPrompt,
  );
  console.log("[LocalAI] Initializing local session:", {
    llmProvider: config.llmProvider,
    sttProvider: config.sttProvider,
    localLlmBaseUrl: config.localLlmBaseUrl,
    localLlmModel: config.localLlmModel,
    localSttUrl: config.localSttUrl,
    profile: config.profile,
  });
  sendToRenderer("session-initializing", true);
  try {
    closeNemotronSidecar();
    isLocalActive = false;
    // Setup system prompt
-    currentSystemPrompt = getSystemPrompt(profile, customPrompt, false);
+    currentSystemPrompt = getSystemPrompt(
      config.profile,
      config.customPrompt,
      false,
    );
-    // Initialize Ollama client
+    localConfig = config;
-    ollamaClient = new Ollama({ host: ollamaHost });
+    ollamaClient = null;
-    ollamaModel = model;
+    ollamaModel = null;
-    // Test Ollama connection
+    if (config.llmProvider === "lmstudio") {
-    try {
+      const lmStudioReady = await verifyLmStudioConnection(config);
-      await ollamaClient.list();
+      if (!lmStudioReady) {
-      console.log("[LocalAI] Ollama connection verified");
+        sendToRenderer("session-initializing", false);
-    } catch (error) {
+        return false;
-      console.error(
+      }
-        "[LocalAI] Cannot connect to Ollama at",
+    } else {
-        ollamaHost,
+      // Initialize Ollama client fallback
-        ":",
+      ollamaClient = new Ollama({ host: config.ollamaHost });
-        error.message,
+      ollamaModel = config.ollamaModel;
-      );
+
-      sendToRenderer("session-initializing", false);
+      try {
-      sendToRenderer(
+        await ollamaClient.list();
-        "update-status",
+        console.log("[LocalAI] Ollama connection verified");
-        "Cannot connect to Ollama at " + ollamaHost,
+      } catch (error) {
-      );
+        console.error(
-      return false;
+          "[LocalAI] Cannot connect to Ollama at",
          config.ollamaHost,
          ":",
          error.message,
        );
        sendToRenderer("session-initializing", false);
        sendToRenderer(
          "update-status",
          "Cannot connect to Ollama at " + config.ollamaHost,
        );
        return false;
      }
    }
-    // Load Whisper model
+    if (config.sttProvider === "nemotron-sidecar") {
-    const pipeline = await loadWhisperPipeline(whisperModel);
+      try {
-    if (!pipeline) {
+        await connectNemotronSidecar(config);
-      sendToRenderer("session-initializing", false);
+      } catch (error) {
-      return false;
+        console.error("[LocalAI] Cannot connect to ASR sidecar:", error);
        sendToRenderer("session-initializing", false);
        sendToRenderer(
          "update-status",
          "Cannot connect to ASR sidecar: " + error.message,
        );
        return false;
      }
    } else {
      // Load Whisper model fallback
      const pipeline = await loadWhisperPipeline(config.whisperModel);
      if (!pipeline) {
        sendToRenderer("session-initializing", false);
        return false;
      }
    }
    // Reset VAD state
@@ -716,7 +1020,7 @@ async function initializeLocalSession(
    localConversationHistory = [];
    // Initialize conversation session
-    initializeNewSession(profile, customPrompt);
+    initializeNewSession(config.profile, config.customPrompt);
    isLocalActive = true;
    sendToRenderer("session-initializing", false);
@@ -737,14 +1041,22 @@ function processLocalAudio(monoChunk24k) {
  // Resample from 24kHz to 16kHz
  const pcm16k = resample24kTo16k(monoChunk24k);
-  if (pcm16k.length > 0) {
+  if (pcm16k.length === 0) return;
-    processVAD(pcm16k);
+
  if (localConfig?.sttProvider === "nemotron-sidecar") {
    if (!nemotronClient || !nemotronClient.sendAudio(pcm16k)) {
      sendToRenderer("update-status", "ASR sidecar is not connected");
    }
    return;
  }
  processVAD(pcm16k);
 }
 function closeLocalSession() {
  console.log("[LocalAI] Closing local session");
  isLocalActive = false;
  closeNemotronSidecar();
  isSpeaking = false;
  speechBuffers = [];
  silenceFrameCount = 0;
@@ -753,6 +1065,7 @@ function closeLocalSession() {
  localConversationHistory = [];
  ollamaClient = null;
  ollamaModel = null;
  localConfig = null;
  currentSystemPrompt = null;
  // Note: whisperWorker is kept alive to avoid reloading model on next session
  // To fully clean up, call killWhisperWorker()
@@ -762,14 +1075,17 @@ function isLocalSessionActive() {
  return isLocalActive;
 }
-// ── Send text directly to Ollama (for manual text input) ──
+// ── Send text directly to the active local LLM ──
 async function sendLocalText(text) {
-  if (!isLocalActive || !ollamaClient) {
+  if (!isLocalActive) {
    return { success: false, error: "No active local session" };
  }
  try {
    if (localConfig?.llmProvider === "lmstudio") {
      return await sendToLmStudio(text);
    }
    await sendToOllama(text);
    return { success: true };
  } catch (error) {
@@ -778,10 +1094,19 @@ async function sendLocalText(text) {
 }
 async function sendLocalImage(base64Data, prompt) {
-  if (!isLocalActive || !ollamaClient) {
+  if (!isLocalActive) {
    return { success: false, error: "No active local session" };
  }
  if (localConfig?.llmProvider === "lmstudio") {
    sendToRenderer("update-status", "Analyzing image locally...");
    return await sendToLmStudio(prompt, base64Data);
  }
  if (!ollamaClient) {
    return { success: false, error: "No active Ollama session" };
  }
  try {
    console.log("[LocalAI] Sending image to Ollama");
    sendToRenderer("update-status", "Analyzing image...");
@@ -177,19 +177,22 @@ async function initializeGemini(profile = "interview", language = "en-US") {
 async function initializeLocal(profile = "interview") {
  const prefs = await storage.getPreferences();
-  const ollamaHost = prefs.ollamaHost || "http://127.0.0.1:11434";
+  const localConfig = {
-  const ollamaModel = prefs.ollamaModel || "llama3.1";
+    llmProvider: prefs.llmProvider || "lmstudio",
-  const whisperModel = prefs.whisperModel || "Xenova/whisper-small";
+    sttProvider: prefs.sttProvider || "nemotron-sidecar",
-  const customPrompt = prefs.customPrompt || "";
+    localLlmBaseUrl: prefs.localLlmBaseUrl || "http://127.0.0.1:1234/v1",
-
+    localLlmModel: prefs.localLlmModel || "",
-  const success = await ipcRenderer.invoke(
+    localLlmApiKey: prefs.localLlmApiKey || "",
-    "initialize-local",
+    localSttUrl: prefs.localSttUrl || "ws://127.0.0.1:8765/v1/asr/stream",
-    ollamaHost,
+    localSttLanguage: prefs.localSttLanguage || "en-US",
-    ollamaModel,
+    ollamaHost: prefs.ollamaHost || "http://127.0.0.1:11434",
-    whisperModel,
+    ollamaModel: prefs.ollamaModel || "llama3.1",
    whisperModel: prefs.whisperModel || "Xenova/whisper-small",
    profile,
-    customPrompt,
+    customPrompt: prefs.customPrompt || "",
-  );
+  };
  const success = await ipcRenderer.invoke("initialize-local", localConfig);
  if (success) {
    cheatingDaddy.setStatus("Local AI Live");
    return true;
@@ -1090,7 +1093,10 @@ const theme = {
    // Determine if theme is light or dark
    const lightThemes = ["light", "sepia"];
    const isLightTheme = lightThemes.includes(themeName);
-    document.body.setAttribute("data-theme-type", isLightTheme ? "light" : "dark");
+    document.body.setAttribute(
      "data-theme-type",
      isLightTheme ? "light" : "dark",
    );
    // New design tokens (used by components)
    root.style.setProperty("--text-primary", colors.text);
@@ -0,0 +1,151 @@
 const test = require("node:test");
 const assert = require("node:assert/strict");
 const http = require("node:http");
 const WebSocket = require("ws");
 const {
  buildChatMessages,
  isLoopbackUrl,
  NemotronSidecarClient,
  normalizeOpenAiBaseUrl,
  streamLmStudioChat,
 } = require("../src/utils/localProviders");
 test("normalizes LM Studio OpenAI-compatible base URLs without selecting models automatically", () => {
  assert.equal(
    normalizeOpenAiBaseUrl("http://127.0.0.1:1234"),
    "http://127.0.0.1:1234/v1",
  );
  assert.equal(
    normalizeOpenAiBaseUrl("http://127.0.0.1:1234/v1/"),
    "http://127.0.0.1:1234/v1",
  );
 });
 test("detects loopback URLs but does not reject non-local URLs", () => {
  assert.equal(isLoopbackUrl("http://localhost:1234/v1"), true);
  assert.equal(isLoopbackUrl("http://127.0.0.1:1234/v1"), true);
  assert.equal(isLoopbackUrl("http://[::1]:1234/v1"), true);
  assert.equal(isLoopbackUrl("http://192.168.1.40:1234/v1"), false);
  assert.equal(isLoopbackUrl("https://example.com/v1"), false);
 });
 test("builds OpenAI-compatible image messages for local screenshot analysis", () => {
  const messages = buildChatMessages({
    systemPrompt: "Be useful.",
    history: [{ role: "assistant", content: "Previous answer" }],
    userText: "Analyze this screen",
    imageBase64: "abc123",
  });
  assert.deepEqual(messages[0], { role: "system", content: "Be useful." });
  assert.equal(messages[1].role, "assistant");
  assert.equal(messages[2].role, "user");
  assert.equal(messages[2].content[0].type, "text");
  assert.equal(messages[2].content[1].type, "image_url");
  assert.equal(
    messages[2].content[1].image_url.url,
    "data:image/jpeg;base64,abc123",
  );
 });
 test("requires a manually configured LM Studio model id", async () => {
  await assert.rejects(
    () =>
      streamLmStudioChat({
        baseUrl: "http://127.0.0.1:1234/v1",
        model: "",
        messages: [{ role: "user", content: "hello" }],
      }),
    /model id is required/,
  );
 });
 test("streams LM Studio chat completion tokens from an OpenAI-compatible endpoint", async () => {
  let receivedBody = null;
  const server = http.createServer((req, res) => {
    assert.equal(req.method, "POST");
    assert.equal(req.url, "/v1/chat/completions");
    let raw = "";
    req.setEncoding("utf8");
    req.on("data", (chunk) => {
      raw += chunk;
    });
    req.on("end", () => {
      receivedBody = JSON.parse(raw);
      res.writeHead(200, {
        "Content-Type": "text/event-stream",
      });
      res.write('data: {"choices":[{"delta":{"content":"hel"}}]}\n\n');
      res.write('data: {"choices":[{"delta":{"content":"lo"}}]}\n\n');
      res.end("data: [DONE]\n\n");
    });
  });
  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
  const { port } = server.address();
  const accumulations = [];
  const fullText = await streamLmStudioChat({
    baseUrl: `http://127.0.0.1:${port}/v1`,
    model: "manual-gemma4",
    messages: [{ role: "user", content: "hello" }],
    onToken: (_token, accumulated) => accumulations.push(accumulated),
  });
  assert.equal(fullText, "hello");
  assert.deepEqual(accumulations, ["hel", "hello"]);
  assert.equal(receivedBody.model, "manual-gemma4");
  assert.equal(receivedBody.stream, true);
  assert.deepEqual(receivedBody.messages, [{ role: "user", content: "hello" }]);
  await new Promise((resolve) => server.close(resolve));
 });
 test("Nemotron sidecar client sends start JSON, binary PCM, and emits final transcripts", async () => {
  const server = new WebSocket.Server({ host: "127.0.0.1", port: 0 });
  await new Promise((resolve) => server.once("listening", resolve));
  const { port } = server.address();
  const received = [];
  server.on("connection", (socket) => {
    socket.on("message", (data, isBinary) => {
      if (isBinary) {
        received.push({ isBinary, data: Buffer.from(data) });
        socket.send(JSON.stringify({ type: "final", text: "hello world" }));
        return;
      }
      received.push({ isBinary, data: JSON.parse(data.toString("utf8")) });
      socket.send(JSON.stringify({ type: "ready" }));
    });
  });
  const client = new NemotronSidecarClient({
    url: `ws://127.0.0.1:${port}/v1/asr/stream`,
    language: "en-US",
  });
  const finalPromise = new Promise((resolve) => client.once("final", resolve));
  await client.connect();
  client.sendAudio(Buffer.from([1, 2, 3, 4]));
  assert.equal(await finalPromise, "hello world");
  assert.deepEqual(received[0], {
    isBinary: false,
    data: {
      type: "start",
      sampleRate: 16000,
      channels: 1,
      encoding: "pcm_s16le",
      language: "en-US",
    },
  });
  assert.equal(received[1].isBinary, true);
  assert.deepEqual([...received[1].data], [1, 2, 3, 4]);
  client.close();
  await new Promise((resolve) => server.close(resolve));
 });
Author	SHA1	Message	Date
Илья Глазунов	ead0eecbc5	refactor: update architecture documentation and add commenting standards	2026-09-05 19:40:35 +03:00
Илья Глазунов	a55ee10d2b	app development context	2026-09-05 04:37:28 +03:00
Илья Глазунов	8beccdf101	native first	2026-09-05 02:20:11 +03:00
Илья Глазунов	219f35cc04	chore: bump version to 0.7.9 and remove unused additional DMG options Build and Release / build (x64, ubuntu-latest, linux) (push) Has been skipped Details Build and Release / build (arm64, macos-latest, darwin) (push) Has been cancelled Details Build and Release / build (x64, macos-latest, darwin) (push) Has been cancelled Details Build and Release / build (x64, windows-latest, win32) (push) Has been cancelled Details Build and Release / release (push) Has been cancelled Details	2026-02-21 23:19:57 +03:00
Илья Глазунов	b6560f3c6c	feat: update DMG configuration to use UDZO format and add additional options	2026-02-20 23:53:12 +03:00
Илья Глазунов	b1d9130b50	chore: bump version to 0.7.8 and remove unused DMG options in forge.config.js Build and Release / build (x64, ubuntu-latest, linux) (push) Has been skipped Details Build and Release / build (arm64, macos-latest, darwin) (push) Has been cancelled Details Build and Release / build (x64, macos-latest, darwin) (push) Has been cancelled Details Build and Release / build (x64, windows-latest, win32) (push) Has been cancelled Details Build and Release / release (push) Has been cancelled Details	2026-02-20 23:33:29 +03:00
Илья Глазунов	07c39455be	fix: update release workflow to use macOS runner; bump version to 0.7.7 Build and Release / build (x64, ubuntu-latest, linux) (push) Has been skipped Details Build and Release / build (arm64, macos-latest, darwin) (push) Has been cancelled Details Build and Release / build (x64, macos-latest, darwin) (push) Has been cancelled Details Build and Release / build (x64, windows-latest, win32) (push) Has been cancelled Details Build and Release / release (push) Has been cancelled Details	2026-02-20 23:20:23 +03:00
		`@@ -0,0 +1,3 @@`
							`# Swift-native host with local sidecars`

							`Mastermind's production runtime is a Swift/AppKit macOS host that owns UI, lifecycle, permissions, capture, policy, and storage. Local LLM and ASR processes stay behind loopback or Unix-socket protocols, while Electron is retained only as legacy reference; this keeps macOS capabilities native without forcing model runtimes into the application process.`
		`@@ -0,0 +1,3 @@`
							`# Encrypted observation ledger`

							`The Context Graph uses application-encrypted SQLite/SQLCipher as its source of truth. Collectors append immutable Observations, project versioned Assertions, and create Facts only through explicit user confirmation; this preserves Provenance and temporal conflicts while keeping full-text and vector indexes rebuildable instead of making a separate graph service authoritative.`
		`@@ -0,0 +1,3 @@`
							`# Continuous Collectors with ephemeral input`

							`Enabled screen, microphone, system-audio, workspace, calendar, and terminal Collectors run continuously and adapt to power and thermal pressure. Raw frames, audio, OCR, and full transcripts remain ephemeral while only structured local derivations persist; this trades recoverability for a strict local data-minimization boundary, so processor outages are recorded as Gaps rather than buffered raw content.`
		`@@ -0,0 +1,3 @@`
							`# Defer Codex until a no-tools boundary exists`

							`Codex integration is excluded from the MVP even though it remains a future Provider direction. The official app-server is an agent protocol and its read-only sandbox does not provide a documented no-tools guarantee, so Mastermind will not ship OAuth, app-server code, or a hidden experimental path until a supported draft-only boundary can enforce the product's no-action contract.`