@redaksjon/protokoll 0.0.12 → 0.0.14

package/guide/mcp-integration.md

@@ -0,0 +1,341 @@
+# MCP Integration Guide
+
+Protokoll exposes its capabilities as an MCP (Model Context Protocol) server, allowing AI assistants to directly transcribe audio, manage context, and work with transcripts through natural conversation.
+
+## Why MCP?
+
+Traditional CLI usage requires you to:
+1. Open a terminal
+2. Navigate to the right directory  
+3. Remember command syntax
+4. Run commands manually
+
+With MCP, you can simply say:
+- "Hey, can you transcribe this recording?"
+- "Add Sanjay Gupta as a person - Whisper keeps mishearing it as 'San Jay Grouper'"
+- "This transcript should be in the Quantum Readiness project"
+
+The AI assistant handles all the details.
+
+## Setup
+
+### 1. Install Protokoll
+
+```bash
+npm install -g @redaksjon/protokoll
+```
+
+### 2. Configure Your AI Assistant
+
+Add the Protokoll MCP server to your AI tool's configuration.
+
+**For Cursor (Claude)**
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "protokoll": {
+      "command": "protokoll-mcp"
+    }
+  }
+}
+```
+
+**For Claude Desktop**
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your platform:
+
+```json
+{
+  "mcpServers": {
+    "protokoll": {
+      "command": "protokoll-mcp"
+    }
+  }
+}
+```
+
+### 3. Set Environment Variables
+
+The MCP server needs API keys to function:
+
+```bash
+export OPENAI_API_KEY="sk-..."        # Required for transcription & enhancement
+export ANTHROPIC_API_KEY="sk-ant-..." # Optional, for Claude-based enhancement
+```
+
+## Project-Aware Configuration
+
+**Important**: Protokoll supports multiple project configurations. When you have different `.protokoll` directories for different projects, the MCP server needs to know which configuration to use.
+
+### How Configuration Discovery Works
+
+When you ask to transcribe a file, the MCP server:
+
+1. **Walks up the directory tree** from the audio file's location
+2. **Finds all `.protokoll` directories** in the hierarchy
+3. **Analyzes projects** to suggest which one the file belongs to
+4. **Asks for clarification** if there's ambiguity
+
+### Example Scenarios
+
+**Scenario 1: File in a Project Directory**
+
+```
+~/projects/
+├── client-alpha/
+│   ├── .protokoll/           # Client Alpha's config
+│   │   ├── config.yaml
+│   │   ├── people/
+│   │   └── projects/
+│   └── recordings/
+│       └── meeting.m4a       # ← You ask to transcribe this
+```
+
+The AI will automatically use `client-alpha/.protokoll` configuration.
+
+**Scenario 2: Ambiguous Location**
+
+```
+~/Documents/
+├── .protokoll/               # Global config with multiple projects
+│   ├── projects/
+│   │   ├── client-alpha.yaml
+│   │   └── internal-notes.yaml
+│   └── ...
+└── Downloads/
+    └── recording.m4a         # ← Where does this go?
+```
+
+The AI will ask: *"I found 2 projects in your configuration. Which project is this recording for?"*
+
+**Scenario 3: No Configuration Found**
+
+If no `.protokoll` directory exists in the hierarchy, the AI will:
+1. Explain that no configuration was found
+2. Offer to help you set one up
+3. Process with defaults if you prefer
+
+## Available MCP Tools
+
+### Discovery Tools
+
+| Tool | Description |
+|------|-------------|
+| `protokoll_discover_config` | Find and analyze .protokoll configurations |
+| `protokoll_suggest_project` | Determine which project a file belongs to |
+
+### Transcription Tools
+
+| Tool | Description |
+|------|-------------|
+| `protokoll_process_audio` | Process a single audio file |
+| `protokoll_batch_process` | Process all audio files in a directory |
+
+### Context Management Tools
+
+| Tool | Description |
+|------|-------------|
+| `protokoll_context_status` | Get overview of context (projects, people, terms) |
+| `protokoll_list_projects` | List all configured projects |
+| `protokoll_list_people` | List all people in context |
+| `protokoll_list_terms` | List all technical terms |
+| `protokoll_list_companies` | List all companies |
+| `protokoll_search_context` | Search across all context types |
+| `protokoll_get_entity` | Get details of a specific entity |
+
+### Entity Management Tools
+
+| Tool | Description |
+|------|-------------|
+| `protokoll_add_person` | Add a new person to context |
+| `protokoll_add_project` | Add a new project |
+| `protokoll_add_term` | Add a technical term |
+| `protokoll_add_company` | Add a company |
+| `protokoll_add_ignored_term` | Add a term to ignore |
+| `protokoll_delete_entity` | Remove an entity |
+
+### Transcript Tools
+
+| Tool | Description |
+|------|-------------|
+| `protokoll_edit_transcript` | Change transcript title or project |
+| `protokoll_combine_transcripts` | Merge multiple transcripts |
+| `protokoll_provide_feedback` | Correct transcription errors |
+
+## Example Conversations
+
+### Basic Transcription
+
+**You**: "Can you transcribe the meeting recording at ~/Downloads/standup.m4a?"
+
+**AI**: *Calls `protokoll_discover_config` to find configuration*
+*Calls `protokoll_suggest_project` to determine project*
+
+"I found your Protokoll configuration at `~/.protokoll`. You have 3 projects configured. Based on the file location, I'm not sure which project this belongs to. Is this for:
+1. Client Alpha
+2. Internal Notes  
+3. Personal"
+
+**You**: "It's for Client Alpha"
+
+**AI**: *Calls `protokoll_process_audio` with projectId: "client-alpha"*
+
+"Done! I've transcribed the standup recording. The transcript is saved at `~/notes/client-alpha/2026-01/standup-a3f2b1c8.md`. 
+
+Key highlights:
+- Discussed sprint progress with Sarah and Marcus
+- Mentioned the API integration deadline
+- Applied 4 name corrections using your context
+
+Would you like me to make any changes to the transcript?"
+
+### Adding Context
+
+**You**: "Whisper keeps mishearing 'Priya Sharma' as 'pre a Sharma'. Can you add her to my context?"
+
+**AI**: *Calls `protokoll_add_person`*
+
+"I've added Priya Sharma to your context with the phonetic variant 'pre a'. Future transcripts will automatically correct this. Would you like to add any other information about Priya (role, company, etc.)?"
+
+### Providing Feedback
+
+**You**: "In the transcript at ~/notes/meeting.md, 'WCMP' should be 'WCNP' and this should be in the Infrastructure project"
+
+**AI**: *Calls `protokoll_provide_feedback`*
+
+"I've made the corrections:
+1. Changed 'WCMP' to 'WCNP' (2 occurrences)
+2. Moved the transcript to the Infrastructure project at `~/notes/infrastructure/meeting.md`
+
+I also noticed 'WCNP' isn't in your terms. Would you like me to add it so future transcripts get it right?"
+
+### Combining Transcripts
+
+**You**: "Can you combine all the meeting parts in ~/notes/client-alpha/2026-01/ into a single transcript?"
+
+**AI**: *Lists files, then calls `protokoll_combine_transcripts`*
+
+"I found 3 meeting parts. Combined them into 'Full Meeting Notes' at `~/notes/client-alpha/2026-01/full-meeting-notes.md`. The original part files have been removed."
+
+## Best Practices
+
+### 1. Set Up Project Configurations
+
+Create `.protokoll` directories at appropriate levels:
+
+```
+~/work/
+├── .protokoll/              # Shared work context (common terms, companies)
+│   ├── config.yaml
+│   ├── terms/               # Industry terminology
+│   └── companies/           # All clients
+│
+├── client-alpha/
+│   └── .protokoll/          # Client-specific context
+│       ├── people/          # Client Alpha contacts
+│       └── projects/        # Client Alpha projects
+│
+└── client-beta/
+    └── .protokoll/          # Client Beta context
+```
+
+### 2. Use Project Routing
+
+Configure projects with destinations so transcripts automatically land in the right place:
+
+```yaml
+# .protokoll/projects/client-alpha.yaml
+id: client-alpha
+name: Client Alpha
+routing:
+  destination: ~/notes/client-alpha
+classification:
+  explicit_phrases:
+    - "alpha"
+    - "Project Alpha"
+```
+
+### 3. Build Context Incrementally
+
+When the AI asks about corrections:
+- Accept suggestions to add names to people context
+- Accept suggestions to add terms
+- This improves future transcriptions automatically
+
+### 4. Use Feedback for Corrections
+
+Instead of manually editing transcripts:
+- Tell the AI what's wrong in natural language
+- It will fix the transcript AND update context to prevent future errors
+
+## Troubleshooting
+
+### "No configuration found"
+
+Create a `.protokoll` directory:
+```bash
+mkdir ~/.protokoll
+protokoll config  # Interactive setup
+```
+
+Or ask the AI to help set one up.
+
+### "Multiple projects - which one?"
+
+This is expected behavior. The AI needs clarification when:
+- File location doesn't clearly belong to one project
+- Multiple projects could apply
+
+Just tell it which project to use.
+
+### "API key not set"
+
+Ensure your shell exports the necessary keys:
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+The MCP server inherits environment from how it was launched.
+
+### Slow First Transcription
+
+The first transcription may be slower because:
+1. Whisper model loads
+2. Context files are parsed
+3. LLM connections initialize
+
+Subsequent transcriptions are faster.
+
+## Advanced: Multiple Workspaces
+
+If you work across completely separate contexts (e.g., work vs personal), you have options:
+
+### Option A: Nested Configurations
+
+```
+~/.protokoll/                # Base config (shared terms)
+~/work/.protokoll/           # Work overlay
+~/personal/.protokoll/       # Personal overlay
+```
+
+The nearest `.protokoll` takes precedence.
+
+### Option B: Environment-Based Switching
+
+```bash
+# Work profile
+export PROTOKOLL_CONFIG=~/.protokoll-work
+
+# Personal profile  
+export PROTOKOLL_CONFIG=~/.protokoll-personal
+```
+
+## See Also
+
+- [Configuration](./configuration.md) - All configuration options
+- [Context System](./context-system.md) - How context storage works
+- [Routing](./routing.md) - Project routing configuration
+- [Feedback](./feedback.md) - How feedback corrections work

package/guide/quickstart.md

@@ -43,10 +43,8 @@ mkdir -p ~/.protokoll
 ```yaml
 # ~/.protokoll/config.yaml
 model: "gpt-5.2"
-routing:
-  default:
-    path: "~/notes"
-    structure: "month"
+outputDirectory: "~/notes"
+outputStructure: "month"
 ```
 
 ## First Transcription
@@ -59,12 +57,24 @@ protokoll --input-directory ~/recordings
 # Self-reflection report is generated by default
 ```
 
+When processing multiple files, you'll see progress indicators:
+
+```
+Found 11 file(s) to process in ~/recordings
+[1/11] Starting: ~/recordings/meeting.m4a
+[1/11] Transcribing audio...
+[1/11] Enhancing with gpt-5.2...
+[1/11] Output: ~/notes/2026/01/260115-meeting.md (7.3s total)
+[2/11] Starting: ~/recordings/quick-thought.m4a
+...
+```
+
 ## Interactive Mode
 
-Learn names and projects as you go:
+Interactive mode is **enabled by default**. Protokoll will ask questions to learn names and projects as you go:
 
 ```bash
-protokoll --input-directory ~/recordings --interactive
+protokoll --input-directory ~/recordings
 ```
 
 Protokoll will ask:
@@ -111,6 +121,9 @@ protokoll --input-directory ~/recordings --debug
 # Disable self-reflection (enabled by default)
 protokoll --input-directory ~/recordings --no-self-reflection
 
+# Disable interactive mode (for automation/cron jobs)
+protokoll --input-directory ~/recordings --batch
+
 # Dry run (show what would happen)
 protokoll --input-directory ~/recordings --dry-run
 
@@ -124,8 +137,9 @@ protokoll --input-directory ~/recordings --model claude-3-5-sonnet
 |--------|---------|
 | `--model` | `gpt-5.2` |
 | `--transcription-model` | `whisper-1` |
+| `--reasoning-level` | `medium` |
 | `--self-reflection` | `true` (enabled) |
-| `--interactive` | `false` (disabled) |
+| Interactive mode | `true` (enabled, use `--batch` to disable) |
 | Output structure | `month` |
 | Filename options | `date`, `time`, `subject` |
 

package/guide/reasoning.md

@@ -45,14 +45,27 @@ The reasoning system:
 ```yaml
 # ~/.protokoll/config.yaml
 model: "gpt-5.2"
+reasoningLevel: "medium"  # low, medium, or high
 ```
 
 Or via command line:
 
 ```bash
-protokoll --model claude-3-5-sonnet --input-directory ./recordings
+protokoll --model claude-3-5-sonnet --reasoning-level medium --input-directory ./recordings
 ```
 
+## Reasoning Levels
+
+For models that support the `reasoning_effort` parameter (gpt-5.1, gpt-5.2, o1, o1-mini, o3, o3-mini), you can control how much reasoning effort the model expends:
+
+| Level | Description | Best For |
+|-------|-------------|----------|
+| `low` | Quick processing, minimal reasoning | Simple transcripts with few corrections needed |
+| `medium` | **Default** - Balanced reasoning | Standard transcription with context lookup |
+| `high` | Maximum reasoning effort | Unusual or highly technical content |
+
+The default is `medium` because transcript enhancement benefits from balanced reasoning: looking up names, correcting spellings, and categorizing content requires moderate context analysis. Use `low` for simple transcripts with few corrections needed, or `high` for complex technical content.
+
 ## Reasoning Strategies
 
 ### Simple
@@ -175,9 +188,10 @@ interface ReasoningResponse {
 
 ### Slow Processing
 
-1. Use faster model: `--model gpt-4o-mini`
-2. Check self-reflection for bottlenecks
-3. Add more context to reduce iterations
+1. Use lower reasoning level: `--reasoning-level low`
+2. Use faster model: `--model gpt-4o-mini`
+3. Check self-reflection for bottlenecks
+4. Add more context to reduce iterations
 
 ### Poor Quality