meeting-assistant/openspec/changes/archive/2026-05-19-define-meeting-assistant-v1/design.md

## Context

Meeting Assistant is a local/server-side .NET 10 application that helps capture and process meetings. It should work for any meeting format, including in-person conversations, and should not require direct APIs from meeting products such as Teams or Zoom.

The central artifact is an Obsidian markdown note created before transcription begins. The user can add attendees, project context, and live notes while the meeting is happening. Meeting Assistant can add discovered context to the linked assistant-context note, then later append or link summaries, next steps, and knowledge base updates.

## Goals / Non-Goals

**Goals:**

- Establish a .NET 10 application skeleton and OpenSpec workflow.
- Model a platform-independent meeting session flow.
- Toggle recording/transcription mode through a configurable hotkey.
- Capture microphone input and computer output for transcription.
- Stream audio into a provider-independent speech recognition pipeline.
- Use FunASR for speaker-attributed transcription, while keeping local Whisper as a fallback provider.
- Write transcript text into the configured vault folder.
- Create a meeting note before transcription starts.
- Preserve user-authored notes as first-class input to summarization.
- Transcribe meeting audio with speaker attribution.
- Generate summaries, decisions, and next steps.
- Maintain project knowledge from meeting output and additional future sources.
- Let agents retrieve project context and keyword context.
- Allow agents to update files in existing project folders through explicit overwrite, replace, and insert tool modes.

**Non-Goals:**

- Require a Teams, Zoom, or calendar-specific integration in version 1.
- Require cloud transcription APIs.
- Define the final Obsidian vault path or note template completely in this first change.
- Implement unrestricted autonomous file edits.

## Decisions

1. Build the source application as ASP.NET Core on .NET 10.
   - Rationale: It matches the requested runtime and keeps the application service-oriented.

2. Make the Obsidian markdown note the session anchor.
   - Rationale: The user can enrich the meeting context before and during transcription, and agents can work from a durable human-readable artifact.

3. Treat meeting-platform APIs as optional augmentation.
   - Rationale: The assistant must be usable for in-person meetings and for platforms where no integration is available or desired.

4. Keep project knowledge as a generic capability.
   - Rationale: Meeting-derived knowledge should later combine with other sources without coupling the design to transcripts only.

5. Keep project file mutation simple in version 1.
   - Rationale: Agents may update files in existing project folders, but project creation and scaffolded project templates are future work.

6. Use the normal .NET options configuration model for hotkey, vault, recording, and provider settings.
   - Rationale: These settings will need machine-specific values and should work through `appsettings.json`, environment variables, and future deployment configuration.

7. Model ASR backends as speech recognition pipelines.
   - Rationale: The application must not assume file-only transcription or split live transcription from final diarization at the coordinator boundary. A pipeline can initialize, wait for readiness, accept captured audio chunks, emit live transcript segments, and produce a finished transcript. FunASR consumes PCM over WebSocket, Whisper.NET remains available as a local windowed fallback with pyannote post-processing, and the app can replace either backend later without changing recording control or persistence.

8. Capture computer output through WASAPI loopback and microphone input through WASAPI capture, then mix PCM chunks before transcription.
   - Rationale: WASAPI loopback is the Windows-supported way to capture the system mix, and tests can cover the mixer without depending on live devices.

9. Gate Windows-only capture, hotkey, and Outlook Classic COM enrichment behind the Windows target.
   - Rationale: The portable build should continue to compile without Windows APIs, while the Windows build can augment meeting notes from the current Teams appointment when Outlook Classic is available.

## Risks / Trade-offs

- [Risk] Speaker attribution quality depends on the selected transcription pipeline. -> Mitigation: keep attribution requirements observable and provider-independent.
- [Risk] FunASR speaker metadata depends on the runtime/model configuration and may be absent. -> Mitigation: preserve speaker fields when returned and fall back to `Unknown` instead of dropping transcript text.
- [Risk] Whisper.NET is windowed rather than a dedicated real-time recognizer. -> Mitigation: keep it as a configurable fallback and make the window size configurable.
- [Risk] WASAPI loopback may not emit chunks when no system audio is playing. -> Mitigation: isolate the system-audio source so silence insertion can be added without changing the coordinator.
- [Risk] The Obsidian note may become too dense. -> Mitigation: separate metadata, user notes, assistant context, transcript references, and generated outputs into clear sections.
- [Risk] Agent file updates could affect the wrong project. -> Mitigation: restrict writes to existing project folders and prevent target paths from escaping the selected project.
- [Risk] Retrieval can surface stale or irrelevant project context. -> Mitigation: include source references and update timestamps in retrieved context.

## Open Questions

- Should transcript text files eventually be merged into the meeting note, linked from it, or remain separate artifacts?
- What metadata fields are required before transcription can start?
- Which storage backend should hold embeddings and project knowledge?
- What approval model should govern agent project file edits?