@redaksjon/protokoll 0.0.11 → 0.0.13

package/guide/feedback.md

@@ -0,0 +1,335 @@
+# Feedback Command
+
+Protokoll includes an intelligent `feedback` command that uses an agentic model to understand natural language feedback about your transcripts and take appropriate actions automatically.
+
+## Overview
+
+The feedback command allows you to describe problems with a transcript in plain English, and Protokoll will:
+
+1. **Understand your feedback** using a reasoning model
+2. **Take corrective actions** like fixing text, adding terms/people to context, or changing project assignments
+3. **Learn for the future** by updating your context to prevent similar issues
+
+## Basic Usage
+
+```bash
+protokoll feedback /path/to/transcript.md
+```
+
+This prompts you interactively:
+
+```
+────────────────────────────────────────────────────────────
+[Feedback for: transcript.md]
+────────────────────────────────────────────────────────────
+
+Describe what needs to be corrected in natural language.
+Examples:
+  - "YB should be Wibey"
+  - "San Jay Grouper is actually Sanjay Gupta"
+  - "This should be in the Quantum Readiness project"
+  - "What feedback can I give?" (for help)
+
+What is your feedback? 
+```
+
+### Non-Interactive Mode
+
+Provide feedback directly on the command line:
+
+```bash
+protokoll feedback /path/to/transcript.md -f "YB should be spelled Wibey"
+```
+
+### Preview Changes (Dry Run)
+
+See what would happen without making changes:
+
+```bash
+protokoll feedback /path/to/transcript.md --dry-run -v
+```
+
+## What You Can Do
+
+### 1. Fix Terms & Abbreviations
+
+When you notice a term or abbreviation was transcribed incorrectly:
+
+```bash
+protokoll feedback /path/to/transcript.md
+# "Everywhere it says WCMP, that should be WCNP - Walmart's Native Cloud Platform"
+```
+
+**What happens:**
+1. Replaces "WCMP" with "WCNP" throughout the transcript
+2. Adds "WCNP" to your context vocabulary with:
+   - The correct spelling
+   - The full expansion ("Walmart's Native Cloud Platform")
+   - Phonetic variants so it won't be misheard again
+
+### 2. Fix Names
+
+When a person's name was transcribed incorrectly:
+
+```bash
+protokoll feedback /path/to/transcript.md
+# "San Jay Grouper is actually Sanjay Gupta"
+```
+
+**What happens:**
+1. Replaces "San Jay Grouper" with "Sanjay Gupta" throughout
+2. Looks for variations like "San Jay", "Sanjay Grouper" and fixes those too
+3. Adds "Sanjay Gupta" to your people context with phonetic variants
+
+### 3. Change Project Assignment
+
+When a transcript was routed to the wrong project:
+
+```bash
+protokoll feedback /path/to/transcript.md
+# "This should be in the Quantum Readiness project"
+```
+
+**What happens:**
+1. Updates the project metadata in the transcript
+2. Moves the file to the project's configured destination
+3. Renames the file according to the project's filename rules
+
+### 4. Change Title
+
+When you want a more descriptive title:
+
+```bash
+protokoll feedback /path/to/transcript.md
+# "Change the title to Q1 Planning Session"
+```
+
+**What happens:**
+1. Updates the document heading to `# Q1 Planning Session`
+2. Renames the file to include the slugified title
+
+### 5. General Text Corrections
+
+For any other text that needs fixing:
+
+```bash
+protokoll feedback /path/to/transcript.md
+# "Replace 'gonna' with 'going to' everywhere"
+```
+
+### 6. Get Help
+
+If you're not sure what feedback you can give:
+
+```bash
+protokoll feedback --help-me
+```
+
+Or ask the system during an interactive session:
+
+```bash
+protokoll feedback /path/to/transcript.md
+# "What kinds of feedback can I give?"
+```
+
+## Command Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--feedback <text>` | `-f` | Provide feedback directly (non-interactive) |
+| `--model <model>` | `-m` | Reasoning model to use (default: gpt-5.2) |
+| `--dry-run` | | Show what would happen without making changes |
+| `--verbose` | `-v` | Show detailed output of each action |
+| `--help-me` | | Show examples of feedback you can provide |
+
+## How It Works
+
+The feedback command uses an **agentic architecture** with specialized tools:
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌────────────────┐
+│  Your Feedback  │ ──▶ │  Reasoning Model │ ──▶ │  Tool Calls    │
+│  (plain text)   │     │  (understands)   │     │  (executes)    │
+└─────────────────┘     └──────────────────┘     └────────────────┘
+                                                        │
+                        ┌───────────────────────────────┘
+                        ▼
+         ┌──────────────────────────────────────────────────┐
+         │  Available Tools:                                 │
+         │  • correct_text - Replace text in transcript     │
+         │  • add_term - Add term to context                │
+         │  • add_person - Add person to context            │
+         │  • change_project - Update project assignment    │
+         │  • change_title - Update document title          │
+         │  • provide_help - Show helpful information       │
+         └──────────────────────────────────────────────────┘
+```
+
+### Tool Execution Order
+
+For comprehensive corrections, the system typically:
+
+1. **First**: Makes text corrections (`correct_text`)
+2. **Then**: Adds entities to context (`add_term`, `add_person`)
+3. **Finally**: Updates metadata if needed (`change_project`, `change_title`)
+
+### Example: Complete Term Correction
+
+When you say: *"WCMP should be WCNP - Walmart's Native Cloud Platform"*
+
+The model executes:
+
+```
+1. correct_text(find="WCMP", replace="WCNP", replace_all=true)
+   → Replaced 3 occurrences
+
+2. add_term(term="WCNP", definition="Walmart's Native Cloud Platform", 
+            sounds_like=["WCMP", "W C M P", "double-u see em pee"])
+   → Added term to context
+
+3. complete(summary="Fixed WCMP→WCNP (3 occurrences) and added term to vocabulary")
+   → Done
+```
+
+## Context Learning
+
+When the feedback system adds entities to your context, they're stored in your `.protokoll` directory:
+
+### Terms
+
+```yaml
+# ~/.protokoll/terms/wcnp.yaml
+id: wcnp
+name: WCNP
+type: term
+expansion: "Walmart's Native Cloud Platform"
+sounds_like:
+  - WCMP
+  - W C M P
+  - double-u see en pee
+```
+
+### People
+
+```yaml
+# ~/.protokoll/people/sanjay-gupta.yaml
+id: sanjay-gupta
+name: Sanjay Gupta
+type: person
+sounds_like:
+  - San Jay Grouper
+  - Sanjay Grouper
+  - San Jay
+role: Engineer
+company: Acme Corp
+```
+
+## Verbose Mode
+
+Use `-v` or `--verbose` to see what the system is doing:
+
+```bash
+protokoll feedback /path/to/transcript.md -f "YB should be Wibey" -v
+
+[Processing feedback...]
+
+[Executing: correct_text]
+  ✓ Replaced "YB" → "Wibey" (2x)
+
+[Executing: add_term]
+  ✓ Added term: Wibey = "Correct spelling of YB"
+    sounds_like: YB, Y B
+
+[Executing: complete]
+
+────────────────────────────────────────────────────────────
+[Changes Applied]
+────────────────────────────────────────────────────────────
+  ✓ Replaced "YB" with "Wibey" (2 occurrences)
+  ✓ Added term "Wibey" to context
+
+File updated: /path/to/transcript.md
+```
+
+## Use Cases
+
+### Fixing Common Transcription Errors
+
+```bash
+# API pronounced letter-by-letter
+protokoll feedback notes.md -f "API should be written as A-P-I"
+
+# Acronyms
+protokoll feedback notes.md -f "AWS was transcribed as 'ay double-u ess', fix it"
+
+# Technical terms
+protokoll feedback notes.md -f "Kubernetes was written as 'Cooper Netties'"
+```
+
+### Fixing Names
+
+```bash
+# Full name correction
+protokoll feedback notes.md -f "Priya was transcribed as 'pre a'"
+
+# Name with title
+protokoll feedback notes.md -f "Doctor Smith was written as 'Doc Tor Smith'"
+
+# International names
+protokoll feedback notes.md -f "Mikhail was transcribed as 'Me Kyle'"
+```
+
+### Project Reorganization
+
+```bash
+# Simple reassignment
+protokoll feedback notes.md -f "This belongs in the Q4-planning project"
+
+# With explanation
+protokoll feedback notes.md -f "This was incorrectly classified as personal, it's actually work related to the Sales project"
+```
+
+## Troubleshooting
+
+### "Text not found in transcript"
+
+The exact text you specified doesn't exist. Try:
+- Checking the exact spelling/capitalization in the transcript
+- Using a shorter, more unique phrase
+- Looking at the transcript preview shown when running the command
+
+### "Project not found"
+
+The project ID you specified doesn't exist. List available projects:
+
+```bash
+protokoll project list
+```
+
+### Changes Not Taking Effect
+
+Make sure you're not running in `--dry-run` mode. Remove that flag to apply changes.
+
+### Model Not Understanding Feedback
+
+Try being more explicit:
+- Instead of: "Fix the name"
+- Try: "Replace 'San Jay' with 'Sanjay' everywhere"
+
+## Best Practices
+
+1. **Be specific**: "Replace X with Y" is clearer than "fix X"
+
+2. **Include context**: "WCNP is Walmart's Native Cloud Platform" helps the model add useful metadata
+
+3. **Use --dry-run first**: Preview changes before applying them
+
+4. **Check with --verbose**: See exactly what actions are being taken
+
+5. **Review context files**: Check `~/.protokoll/` to see what was added
+
+## See Also
+
+- [Context System](./context-system.md) - How context storage works
+- [Transcript Actions](./action.md) - Other ways to edit transcripts
+- [Context Commands](./context-commands.md) - Managing entities directly

package/guide/index.md

@@ -13,12 +13,16 @@ Protokoll transforms audio recordings into intelligent, context-enhanced transcr
 ### Getting Started
 - [**Quick Start**](./quickstart.md): Get Protokoll working in 5 minutes
 - [**Configuration**](./configuration.md): All configuration options
+- [**Config Command**](./config.md): Interactive configuration editor
 
 ### Understanding Protokoll
 - [**Architecture**](./architecture.md): System design and data flow
 - [**Context System**](./context-system.md): How context storage works
+- [**Context Commands**](./context-commands.md): CLI for managing entities
 - [**Routing**](./routing.md): Intelligent note routing
 - [**Reasoning**](./reasoning.md): Reasoning model integration
+- [**Transcript Actions**](./action.md): Post-processing commands (combine, etc.)
+- [**Feedback**](./feedback.md): Intelligent feedback for corrections
 
 ### Development
 - [**Development**](./development.md): Building and testing
@@ -29,11 +33,11 @@ Protokoll transforms audio recordings into intelligent, context-enhanced transcr
 ### Essential Commands
 
 ```bash
-# Basic transcription (self-reflection enabled by default)
+# Basic transcription (interactive and self-reflection enabled by default)
 protokoll --input-directory ./recordings
 
-# Interactive mode for learning
-protokoll --input-directory ./recordings --interactive
+# Disable interactive mode (for automation/cron)
+protokoll --input-directory ./recordings --batch
 
 # Disable self-reflection
 protokoll --input-directory ./recordings --no-self-reflection
@@ -42,6 +46,97 @@ protokoll --input-directory ./recordings --no-self-reflection
 protokoll --input-directory ./recordings --debug --verbose
 ```
 
+### Configuration Commands
+
+```bash
+# Interactive configuration editor
+protokoll config
+
+# List all settings
+protokoll config --list
+
+# View a specific setting
+protokoll config model
+
+# Set a specific value
+protokoll config model gpt-4o-mini
+protokoll config debug true
+protokoll config outputDirectory ~/my-notes
+```
+
+### Context Management Commands
+
+```bash
+# List entities
+protokoll project list
+protokoll person list
+protokoll term list
+protokoll company list
+protokoll ignored list
+
+# Show entity details
+protokoll project show <id>
+protokoll person show <id>
+
+# Add new entities (interactive)
+protokoll project add
+protokoll person add
+protokoll term add
+protokoll company add
+protokoll ignored add
+
+# Delete entities
+protokoll project delete <id>
+protokoll person delete <id> --force
+
+# Context overview
+protokoll context status
+protokoll context search <query>
+```
+
+### Transcript Actions
+
+```bash
+# Edit a single transcript - change title
+protokoll action --title "Time to Celebrate" /path/to/transcript.md
+
+# Edit a single transcript - change project
+protokoll action --project client-alpha /path/to/transcript.md
+
+# Combine multiple transcripts (source files are auto-deleted)
+protokoll action --title "Full Meeting Notes" --combine "/path/to/file1.md
+/path/to/file2.md
+/path/to/file3.md"
+
+# Combine and change project
+protokoll action --title "Sprint Planning" --project my-project --combine "/path/to/files..."
+
+# Preview without making changes
+protokoll action --title "New Title" /path/to/file.md --dry-run --verbose
+```
+
+### Feedback
+
+```bash
+# Provide feedback interactively
+protokoll feedback /path/to/transcript.md
+
+# Provide feedback directly
+protokoll feedback /path/to/transcript.md -f "YB should be Wibey"
+
+# Fix a name and add to context
+protokoll feedback /path/to/transcript.md -f "San Jay Grouper is actually Sanjay Gupta"
+
+# Change project assignment
+protokoll feedback /path/to/transcript.md -f "This should be in the Quantum Readiness project"
+
+# Preview changes
+protokoll feedback /path/to/transcript.md -f "WCMP should be WCNP" --dry-run -v
+
+# Get help on feedback options
+protokoll feedback --help-me
+```
+
 ### Key Directories
 
 ```
@@ -84,8 +179,9 @@ If you're an AI helping someone use Protokoll:
 | Setting | Default Value |
 |---------|---------------|
 | Reasoning Model | `gpt-5.2` |
+| Reasoning Level | `medium` |
 | Transcription Model | `whisper-1` |
 | Self-Reflection | `true` (enabled) |
-| Interactive Mode | `false` (disabled) |
+| Interactive Mode | `true` (enabled, use `--batch` to disable) |
 | Output Structure | `month` |
 

package/guide/interactive.md

@@ -11,20 +11,21 @@ When enabled, Protokoll will:
 3. Offer to remember new entities
 4. Request routing clarification
 
-**Note**: Interactive mode is disabled by default. Use `--interactive` to enable it.
+**Note**: Interactive mode is **enabled by default**. Use `--batch` to disable it for automation.
 
-## Enabling Interactive Mode
+## Disabling Interactive Mode
+
+For automation or cron jobs, disable interactive prompts:
 
 ```bash
-protokoll --interactive --input-directory ./recordings
+protokoll --batch --input-directory ./recordings
 ```
 
 Or in config:
 
 ```yaml
 # ~/.protokoll/config.yaml
-features:
-  interactive: true
+interactive: false
 ```
 
 ## Clarification Types
@@ -93,15 +94,15 @@ All clarifications are recorded in the session file:
 }
 ```
 
-## Non-Interactive Mode (Default)
+## Non-Interactive Mode (Batch)
 
-By default, Protokoll runs without prompts:
+For automation, run without prompts using `--batch`:
 
 ```bash
-protokoll --input-directory ./recordings
+protokoll --batch --input-directory ./recordings
 ```
 
-In non-interactive mode:
+In non-interactive (batch) mode:
 - Uses suggestions when available
 - Skips unknown entities
 - Uses default routing
@@ -109,7 +110,7 @@ In non-interactive mode:
 
 ## First-Run Onboarding
 
-On first run with `--interactive` and no existing config:
+On first run with interactive mode (the default) and no existing config:
 
 ```
 Welcome to Protokoll!
@@ -182,14 +183,14 @@ type ClarificationType =
 
 ### No Prompts Appearing
 
-1. Check `--interactive` flag is set
-2. Verify terminal supports prompts
-3. Check if running in a non-TTY environment
+1. Check `--batch` flag is NOT set
+2. Check config doesn't have `interactive: false`
+3. Verify terminal supports prompts (TTY environment required)
 
 ### Too Many Prompts
 
 1. Add more context entries
-2. Run without `--interactive` for known content
+2. Run with `--batch` for known content
 3. Add sounds_like mappings
 
 ### Prompts Timing Out

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