1  # Conversational Copilot Feature
  2  
  3  Real-time video call assistant that transcribes conversations, performs semantic search, tracks DreamNode invocations, and generates AI-powered summaries with shareable exports.
  4  
  5  ## Purpose
  6  
  7  Transforms video calls into documented conversations by:
  8  - Real-time speech-to-text transcription (delegates to `realtime-transcription` feature)
  9  - Semantic search as you speak (finds relevant DreamNodes)
 10  - Recording DreamNode invocations during conversation
 11  - AI-powered post-call summaries with Claude Haiku
 12  - Beautiful PDF + email exports with deep links
 13  - Perspective creation (delegates to `songline` feature for audio clips)
 14  
 15  ## Directory Structure
 16  
 17  ```
 18  conversational-copilot/
 19  ├── store/
 20  │   └── slice.ts                        # Zustand state (copilot mode, shared nodes)
 21  ├── services/
 22  │   ├── transcription-service.ts        # Markdown file creation + semantic search monitoring
 23  │   ├── conversation-recording-service.ts  # DreamNode invocation tracking
 24  │   ├── conversation-summary-service.ts    # Claude API for AI summaries
 25  │   ├── email-export-service.ts            # Apple Mail draft generation
 26  │   ├── pdf-generator-service.ts           # PDF document creation
 27  │   └── llm-provider.ts                    # LLM provider abstraction
 28  ├── utils/
 29  │   └── open-node-content.ts            # Node content opening logic
 30  ├── commands.ts                         # Command palette registration
 31  └── README.md                           # This file
 32  ```
 33  
 34  ## Responsibility Boundaries
 35  
 36  ### What This Feature Owns
 37  - **Copilot mode state**: Active/inactive, conversation partner, shared node tracking
 38  - **Transcript file management**: Creates markdown file in `conversations/` directory
 39  - **Semantic search during conversation**: Monitors transcript changes, runs FIFO buffer search
 40  - **Invocation tracking**: Records which DreamNodes were clicked during conversation
 41  - **AI summary generation**: Calls Claude API to generate summaries and clip suggestions
 42  - **Export pipeline**: PDF generation, Apple Mail drafts, share link creation
 43  
 44  ### What This Feature Delegates
 45  
 46  **To `realtime-transcription` feature:**
 47  - Actual audio capture and transcription (Python whisper_streaming)
 48  - Audio file recording (MP3 output)
 49  
 50  **To `songline` feature:**
 51  - Perspective storage (`perspectives.json` in DreamNodes)
 52  - Audio clip trimming (ffmpeg integration)
 53  - Clip filename generation
 54  - Perspective service (CRUD operations)
 55  
 56  **To `social-resonance` feature:**
 57  - Radicle identity operations
 58  - Share link generation
 59  
 60  ## Data Flow
 61  
 62  ```
 63  ┌─────────────────────────────────────────────────────────────────┐
 64  │                    Start Conversation Mode                       │
 65  ├─────────────────────────────────────────────────────────────────┤
 66  │ 1. Create transcript file (this feature)                        │
 67  │ 2. Start Python transcription (realtime-transcription)          │
 68  │ 3. Start invocation recording (this feature)                    │
 69  └─────────────────────────────────────────────────────────────────┘
 70                                │
 71                                ▼
 72  ┌─────────────────────────────────────────────────────────────────┐
 73  │                      During Conversation                         │
 74  ├─────────────────────────────────────────────────────────────────┤
 75  │ • Python writes to transcript.md (realtime-transcription)       │
 76  │ • This feature monitors file changes → semantic search          │
 77  │ • User clicks DreamNodes → invocations recorded (this feature)  │
 78  │ • Invocation markers embedded in transcript (this feature)      │
 79  └─────────────────────────────────────────────────────────────────┘
 80                                │
 81                                ▼
 82  ┌─────────────────────────────────────────────────────────────────┐
 83  │                     End Conversation Mode                        │
 84  ├─────────────────────────────────────────────────────────────────┤
 85  │ 1. Stop Python transcription (realtime-transcription)           │
 86  │ 2. Generate AI summary + clip suggestions (this feature)        │
 87  │ 3. Create PDF with DreamNode images (this feature)              │
 88  │ 4. Generate share links (social-resonance)                      │
 89  │ 5. Open Apple Mail draft (this feature)                         │
 90  │ 6. Create perspectives from clip suggestions (songline)         │
 91  │ 7. Persist bidirectional relationships (this feature)           │
 92  └─────────────────────────────────────────────────────────────────┘
 93  ```
 94  
 95  ## File Storage
 96  
 97  ### Where Things Go
 98  
 99  | Content Type | Location | Owner |
100  |--------------|----------|-------|
101  | Transcript `.md` | `DreamerNode/conversations/` | This feature |
102  | Full audio `.mp3` | `DreamerNode/conversations/` | realtime-transcription |
103  | `perspectives.json` | `DreamNode/` (ideas) | songline |
104  | Trimmed clips `.mp3` | `DreamNode/perspectives/` | songline |
105  
106  ## Main Exports
107  
108  ### Commands
109  ```typescript
110  registerConversationalCopilotCommands(plugin, uiService)
111  ```
112  
113  ### State Management
114  ```typescript
115  copilotMode: {
116    isActive: boolean
117    conversationPartner: DreamNode | null
118    sharedNodeIds: string[]
119    frozenSearchResults: DreamNode[]
120  }
121  ```
122  
123  ### Services (Singleton Pattern)
124  ```typescript
125  getTranscriptionService()           // Markdown file + semantic search
126  getConversationRecordingService()   // Invocation tracking
127  getConversationSummaryService()     // AI summary generation
128  getEmailExportService()             // Apple Mail + PDF creation
129  getPDFGeneratorService()            // PDF document generation
130  ```
131  
132  ## Prerequisites
133  
134  ### Radicle Authentication
135  Email export requires Radicle authentication for share link generation:
136  ```bash
137  rad auth
138  ```
139  This registers your SSH key with ssh-agent. Without this, the email export will fail with:
140  ```
141  error: radicle key is not registered; run `rad auth` to register it with ssh-agent
142  ```
143  
144  ### Python Environment
145  Real-time transcription requires the Python environment from `realtime-transcription` feature.
146  
147  ### ffmpeg
148  Perspective clip creation requires ffmpeg:
149  - macOS: `brew install ffmpeg`
150  - Ubuntu/Debian: `sudo apt install ffmpeg`
151  - Windows: Download from ffmpeg.org
152  
153  ## Known Limitations
154  
155  - **macOS Only**: AppleScript for Apple Mail (no cross-platform email yet)
156  - **Python Dependency**: Requires Whisper transcription service running
157  - **Claude API Required**: No AI summary fallback if API key missing (graceful degradation in place)
158  
159  ## Notes
160  
161  - **Service Layer Pattern**: All business logic in singleton services
162  - **Zustand State Management**: Copilot mode state integrated with core store
163  - **Event-Driven**: File monitoring via Obsidian Vault events
164  - **Throttling**: 5-second cooldown on semantic search
165  - **FIFO Buffer**: Last 500 chars of transcript for search queries
166  - **Graceful Degradation**: Works without API key (basic email with no AI summary)