@redaksjon/protokoll 0.0.14 → 0.1.0

package/guide/index.md

@@ -21,7 +21,8 @@ Protokoll transforms audio recordings into intelligent, context-enhanced transcr
 - [**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.)
+- [**Transcript Listing**](./transcript-listing.md): Browse, search, and filter transcripts
+- [**Transcript Actions**](./action.md): Edit, combine, and manage transcripts
 - [**Feedback**](./feedback.md): Intelligent feedback for corrections
 
 ### AI Integration
@@ -97,6 +98,21 @@ protokoll context status
 protokoll context search <query>
 ```
 
+### Transcript Management
+
+```bash
+# List transcripts with search and filtering
+protokoll transcript list <directory>
+protokoll transcript list ~/notes --search "kubernetes"
+protokoll transcript list ~/notes --start-date 2026-01-01 --limit 25
+
+# Compare raw vs enhanced
+protokoll transcript compare <file>
+
+# Show transcript info
+protokoll transcript info <file>
+```
+
 ### Transcript Actions
 
 ```bash
@@ -142,7 +158,7 @@ protokoll feedback --help-me
 
 ### MCP / AI Integration
 
-Instead of CLI commands, you can talk to an AI assistant:
+Instead of CLI commands, you can use natural language with an AI assistant:
 
 ```
 "Can you transcribe ~/Downloads/meeting.m4a?"
@@ -189,6 +205,8 @@ If you're an AI helping someone use Protokoll:
 3. **Interactive Learning**: Asks questions, remembers answers
 4. **Self-Reflection**: Reports on tool effectiveness (enabled by default)
 5. **Full Preservation**: Not a summarizer - keeps all content
+6. **Smart Projects**: AI-assisted project configuration with phonetic variants
+7. **Proactive Phonetic**: Integration with Observasjon for improved transcription accuracy
 
 ## Current Defaults
 
@@ -199,5 +217,50 @@ If you're an AI helping someone use Protokoll:
 | Transcription Model | `whisper-1` |
 | Self-Reflection | `true` (enabled) |
 | Interactive Mode | `true` (enabled, use `--batch` to disable) |
+| Smart Projects | `true` (enabled) |
 | Output Structure | `month` |
 
+## Integration with Observasjon
+
+Protokoll's project data is automatically used by [Observasjon](https://github.com/redaksjon/observasjon) to improve transcription accuracy through **Proactive Phonetic Enhancement**:
+
+### How It Works
+
+1. **You define projects in Protokoll** with names and phonetic variations:
+   ```bash
+   protokoll project add
+   # Name: "Observasjon"
+   # Sounds like: "observation", "observashun"
+   ```
+
+2. **Observasjon automatically detects your projects** from `~/.protokoll/context/projects/`
+
+3. **Project names are sent during transcription** (not after) so Whisper gets them right from the start
+
+4. **Results**: "Observasjon" transcribed correctly instead of "observation"
+
+### Benefits
+
+- **Better accuracy**: Project names spelled correctly in initial transcription
+- **Lower cost**: Fix names during transcription, not in post-processing
+- **No configuration**: Works automatically if you use both tools
+
+### Smart Projects Feature
+
+The Smart Projects feature (enabled by default) helps you configure projects with AI assistance:
+
+```bash
+# Interactive mode (review AI suggestions)
+protokoll project add
+
+# Non-interactive mode (trust AI suggestions)
+protokoll project add --name "My Project" --yes
+
+# AI automatically suggests:
+# - Phonetic variations for the project name
+# - Classification signals (trigger phrases)
+# - Common mishearings to watch for
+```
+
+This makes it easy to set up proactive phonetic enhancement without manually thinking through all the ways Whisper might mishear your project names. Use `--yes` for automation or when you trust the AI completely.
+

package/guide/interactive.md

@@ -172,12 +172,218 @@ type ClarificationType =
   | 'general';
 ```
 
+## Session Tracking & Progress
+
+### Per-File Progress Monitoring
+
+Every interactive prompt now shows your progress:
+
+```
+[File: recording1.m4a] [Prompts: 5]
+(Type 'S' to skip remaining prompts for this file)
+```
+
+This helps you understand:
+- Which file you're currently working on
+- How many questions you've answered for this file
+- The option to skip ahead
+
+### Skip Rest of File
+
+When you've had enough prompts for a particular file:
+
+```bash
+> S   # or "skip"
+
+[Skipping remaining prompts for this file...]
+```
+
+**When to use:**
+- File has too many unknown terms
+- You want to process it later
+- You've answered enough questions already
+
+The file will still be transcribed fully - you just won't get more prompts for it.
+
+### Session Summary Report
+
+At the end of every interactive session, you get a comprehensive summary:
+
+```
+═══════════════════════════════════════════════════════════
+  INTERACTIVE SESSION SUMMARY
+═══════════════════════════════════════════════════════════
+
+Duration: 12m 34s
+Total prompts answered: 18
+
+────────────────────────────────────────────────────────────
+  FILES PROCESSED
+────────────────────────────────────────────────────────────
+
+1. /recordings/meeting1.m4a
+   Prompts answered: 8
+   Status: Completed
+   Transcript: ~/notes/2026/01/2026-01-18_Meeting_Notes.md
+   Audio moved to: ~/archive/2026/01/meeting1.m4a
+
+2. /recordings/ideas.m4a
+   Prompts answered: 5
+   Status: SKIPPED (user requested)
+   Transcript: ~/notes/2026/01/2026-01-18_Quick_Ideas.md
+
+3. /recordings/project-update.m4a
+   Prompts answered: 5
+   Status: Completed
+   Transcript: ~/notes/2026/01/2026-01-18_Project_Update.md
+
+────────────────────────────────────────────────────────────
+  CHANGES MADE
+────────────────────────────────────────────────────────────
+
+✓ Terms added (5):
+  - Kubernetes
+  - Docker
+  - GraphQL
+  - React
+  - PostgreSQL
+
+✓ Terms updated (2):
+  - AWS
+  - API
+
+✓ Projects added (2):
+  - Project Alpha
+  - Client Beta
+
+✓ Aliases created (3):
+  - "K8s" → "Kubernetes"
+  - "Postgres" → "PostgreSQL"
+  - "Chronology" → "Kronologi"
+
+✓ People added (1):
+  - Priya Sharma
+
+═══════════════════════════════════════════════════════════
+```
+
+**Summary includes:**
+- Session duration and total prompts
+- Each file with prompt counts, status, and output paths
+- All changes made to context (terms, projects, people, aliases)
+
+### Mid-Session Stop
+
+Press `Ctrl+C` at any time to stop and see the summary:
+
+```bash
+^C
+[Session interrupted by user]
+
+═══════════════════════════════════════════════════════════
+  INTERACTIVE SESSION SUMMARY
+═══════════════════════════════════════════════════════════
+...
+```
+
+All progress is automatically saved. Resume processing later.
+
+## Streamlined Learning Flow
+
+### Smart Similarity Matching
+
+Protokoll automatically detects similar existing terms:
+
+```
+────────────────────────────────────────────────────────────
+[Unknown: "Chronology"]
+────────────────────────────────────────────────────────────
+
+Found similar term(s): Kronologi
+Is "Chronology" the same as "Kronologi"? (Y/N): Y
+
+info: Added alias "Chronology" → "Kronologi"
+```
+
+Prevents duplicate entries for similar spellings!
+
+### Automated Content Analysis
+
+Instead of answering multiple questions manually, provide documentation:
+
+```
+────────────────────────────────────────────────────────────
+[Unknown: "Cursor"]
+────────────────────────────────────────────────────────────
+
+[How should I learn about this?]
+Options:
+  1. Provide a file path
+  2. Provide a URL
+  3. Paste text directly
+  4. Enter details manually
+
+Enter 1-4, or paste path/URL directly: https://cursor.com
+
+Fetching and analyzing...
+
+────────────────────────────────────────────────────────────
+[Analysis Results]
+Type: TERM
+Name: Cursor
+Description: AI-powered code editor built on VS Code
+Topics: ai, code-editor, vscode, development
+Confidence: high
+────────────────────────────────────────────────────────────
+
+Use this? (Y/N): Y
+
+Which project(s)?
+  1. FjellGrunn
+  2. Redaksjon
+  3. Grunnverk
+  
+Enter numbers: 2
+
+info: Added term "Cursor" to Redaksjon
+```
+
+**Three input methods:**
+
+1. **File path**: `~/docs/project-info.md`
+2. **URL**: `https://kubernetes.io/docs`
+3. **Paste text**: Multi-line input
+
+AI automatically extracts:
+- Entity type (Project/Term)
+- Correct name
+- Description
+- Topics
+- Acronym expansions (if any)
+
+**95% automated** - just point to documentation!
+
+### Clean Project Selection
+
+Project lists show only names:
+
+```
+Which project(s) is this related to?
+  1. FjellGrunn
+  2. Grunnverk
+  3. Redaksjon
+  N. Create new project
+```
+
+Much cleaner than long descriptions!
+
 ## Best Practices
 
 1. **Start with interactive mode**: Build context quickly
-2. **Review session files**: See what was learned
-3. **Switch to default**: Once context is established
-4. **Periodic interactive runs**: Catch new names
+2. **Use URL/file analysis**: Point to docs instead of typing
+3. **Skip when overwhelmed**: Use 'S' to skip rest of file
+4. **Review session summary**: See what was learned
+5. **Periodic interactive runs**: Catch new names and terms
 
 ## Troubleshooting
 
@@ -189,12 +395,21 @@ type ClarificationType =
 
 ### Too Many Prompts
 
-1. Add more context entries
-2. Run with `--batch` for known content
-3. Add sounds_like mappings
+1. Use 'S' to skip rest of current file
+2. Add more context entries beforehand
+3. Run with `--batch` for known content
+4. Use URL/file analysis for bulk additions
+
+### Session Summary Not Showing
+
+1. Summary prints automatically at end of session
+2. Press `Ctrl+C` to trigger summary mid-session
+3. Check that interactive mode is enabled
 
-### Prompts Timing Out
+### Analysis Failing
 
-1. Increase timeout in config
-2. Run without interactive mode and review manually
+1. Ensure OPENAI_API_KEY is set
+2. Check URL/file is accessible
+3. Verify file format is supported (.md, .txt, .yaml, etc.)
+4. Fall back to manual entry if needed
 

package/guide/mcp-integration.md

@@ -10,8 +10,8 @@ Traditional CLI usage requires you to:
 3. Remember command syntax
 4. Run commands manually
 
-With MCP, you can simply say:
-- "Hey, can you transcribe this recording?"
+With MCP, you can use natural language:
+- "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"
 
@@ -109,7 +109,7 @@ The AI will automatically use `client-alpha/.protokoll` configuration.
     └── recording.m4a         # ← Where does this go?
 ```
 
-The AI will ask: *"I found 2 projects in your configuration. Which project is this recording for?"*
+The AI will ask: *I found 2 projects in your configuration. Which project is this recording for?*
 
 **Scenario 3: No Configuration Found**
 
@@ -151,8 +151,13 @@ If no `.protokoll` directory exists in the hierarchy, the AI will:
 | 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_project` | Add a new project with smart assistance |
+| `protokoll_suggest_project_metadata` | Generate project suggestions without creating |
+| `protokoll_update_project` | Update project by regenerating from source URL/file |
+| `protokoll_add_term` | Add a technical term with smart assistance |
+| `protokoll_suggest_term_metadata` | Generate term suggestions without creating |
+| `protokoll_update_term` | Update term by regenerating from source URL/file |
+| `protokoll_merge_terms` | Merge duplicate terms into one |
 | `protokoll_add_company` | Add a company |
 | `protokoll_add_ignored_term` | Add a term to ignore |
 | `protokoll_delete_entity` | Remove an entity |
@@ -161,64 +166,106 @@ If no `.protokoll` directory exists in the hierarchy, the AI will:
 
 | Tool | Description |
 |------|-------------|
+| `protokoll_list_transcripts` | List/search transcripts with pagination and filtering |
+| `protokoll_read_transcript` | Read a transcript and parse its metadata |
 | `protokoll_edit_transcript` | Change transcript title or project |
 | `protokoll_combine_transcripts` | Merge multiple transcripts |
 | `protokoll_provide_feedback` | Correct transcription errors |
 
+#### protokoll_list_transcripts
+
+Browse and search your transcript library with pagination, sorting, and filtering.
+
+**Parameters:**
+- `directory` (required): Directory to search (recursive)
+- `limit` (optional): Max results to return (default: 50)
+- `offset` (optional): Skip N results for pagination (default: 0)
+- `sortBy` (optional): Sort by "date" (default), "filename", or "title"
+- `startDate` (optional): Filter from date (YYYY-MM-DD)
+- `endDate` (optional): Filter to date (YYYY-MM-DD)
+- `search` (optional): Search text in filename and content
+
+**Returns:**
+- `transcripts[]`: Array of transcript items with:
+  - `path`: Full file path
+  - `filename`: File name
+  - `date`: Date from filename (YYYY-MM-DD)
+  - `time`: Time from filename if present (HH:MM)
+  - `title`: Extracted from `# heading`
+  - `hasRawTranscript`: Whether raw Whisper output exists
+- `pagination`: Total count, limit, offset, hasMore, nextOffset
+- `filters`: Applied filters
+
+**Example:**
+```typescript
+// List recent transcripts
+const result = await use_mcp_tool('protokoll_list_transcripts', {
+  directory: '/Users/me/notes',
+  limit: 10
+});
+
+// Search for specific content
+const meetings = await use_mcp_tool('protokoll_list_transcripts', {
+  directory: '/Users/me/notes',
+  search: 'kubernetes deployment',
+  startDate: '2026-01-01'
+});
+```
+
 ## Example Conversations
 
 ### Basic Transcription
 
-**You**: "Can you transcribe the meeting recording at ~/Downloads/standup.m4a?"
+**User**: 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:
+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"
+3. Personal
 
-**You**: "It's for Client Alpha"
+**User**: 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`. 
+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?"
+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?"
+**User**: 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.)?"
+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"
+**User**: 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:
+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?"
+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?"
+**User**: 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."
+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
 
@@ -289,7 +336,7 @@ 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.
+Simply specify which project to use.
 
 ### "API key not set"