@redaksjon/protokoll 0.0.8 → 0.0.10

package/docs/package.json

@@ -1,11 +1,12 @@
 {
-    "name": "matnava-docs",
+    "name": "protokoll-docs",
+    "private": true,
     "version": "1.0.0",
-    "description": "Documentation site for Matnava - a focused transcription tool",
+    "description": "Documentation site for Protokoll - intelligent audio transcription",
     "type": "module",
     "scripts": {
         "dev": "vite",
-        "build": "vite build",
+        "build": "vite build && cp dist/index.html dist/404.html",
         "preview": "vite preview"
     },
     "dependencies": {
@@ -16,6 +17,6 @@
         "@types/react": "^18.2.0",
         "@types/react-dom": "^18.2.0",
         "@vitejs/plugin-react": "^4.0.0",
-        "vite": "^5.0.0"
+        "vite": "^7.3.1"
     }
 }

package/docs/troubleshooting.md

@@ -0,0 +1,257 @@
+# Troubleshooting Guide
+
+## Common Issues
+
+### Names Still Misspelled
+
+**Problem**: Whisper keeps mishearing names even after adding context.
+
+**Solution**: Add phonetic aliases to your context files:
+
+```yaml
+# ~/.protokoll/people/priya-sharma.yaml
+id: priya-sharma
+name: Priya Sharma
+sounds_like:
+  - "pre a"
+  - "pria"
+  - "preeya sharma"
+  - "preya"
+```
+
+The `sounds_like` field helps Protokoll recognize common mishearings.
+
+### Notes Going to Wrong Directory
+
+**Problem**: Notes about Project A are going to default directory.
+
+**Solution**: Check your triggers in config:
+
+```yaml
+routing:
+  projects:
+    - projectId: "projectA"
+      triggers:
+        - "project a"       # Case insensitive
+        - "projecta"        # No space version
+        - "this is about project a"
+        - "project alpha"   # Alternative names
+```
+
+Also check that your project context file exists:
+
+```yaml
+# ~/.protokoll/projects/project-a.yaml
+id: project-a
+name: Project A
+triggers:
+  - "project a"
+  - "project alpha"
+active: true
+```
+
+### Slow Processing
+
+**Problem**: Each file takes too long.
+
+**Solutions**:
+
+1. Use a faster model:
+```bash
+protokoll --model gpt-4o-mini --input-directory ./recordings
+```
+
+2. Check your audio file sizes - large files take longer to transcribe.
+
+3. Review self-reflection reports to identify bottlenecks:
+```bash
+protokoll --self-reflection --input-directory ./recordings
+cat output/protokoll/*-reflection.md
+```
+
+### API Rate Limits
+
+**Problem**: Getting rate limit errors.
+
+**Solutions**:
+
+1. Use batch mode with fewer concurrent requests:
+```bash
+protokoll --batch --input-directory ./recordings
+```
+
+2. Process files one at a time:
+```bash
+for f in ./recordings/*.m4a; do
+  protokoll --input-directory "$(dirname "$f")" --file "$(basename "$f")"
+  sleep 2
+done
+```
+
+### Context Not Found
+
+**Problem**: Protokoll isn't finding your context files.
+
+**Solution**: Check the context directory structure:
+
+```
+~/.protokoll/
+├── config.yaml
+├── people/
+│   └── *.yaml
+├── projects/
+│   └── *.yaml
+├── companies/
+│   └── *.yaml
+└── terms/
+    └── *.yaml
+```
+
+Run with verbose mode to see context discovery:
+```bash
+protokoll --verbose --input-directory ./recordings
+```
+
+### Audio File Not Supported
+
+**Problem**: Protokoll skips certain audio files.
+
+**Solution**: Check supported formats:
+- mp3
+- mp4
+- mpeg
+- mpga
+- m4a
+- wav
+- webm
+
+Convert unsupported formats:
+```bash
+ffmpeg -i input.ogg -acodec libmp3lame output.mp3
+```
+
+### Large Audio Files Fail
+
+**Problem**: Files over 25MB fail to process.
+
+**Solution**: Protokoll automatically splits large files. If this fails:
+
+1. Check you have ffmpeg installed:
+```bash
+ffmpeg -version
+```
+
+2. Manually split large files:
+```bash
+ffmpeg -i large-file.m4a -f segment -segment_time 300 -c copy part%03d.m4a
+```
+
+### Interactive Mode Not Asking Questions
+
+**Problem**: Running with `--interactive` but no prompts appear.
+
+**Solution**: 
+
+1. Make sure you're not also using `--batch`:
+```bash
+# Wrong - batch overrides interactive
+protokoll --interactive --batch
+
+# Correct
+protokoll --interactive
+```
+
+2. Check if all entities are already in context (no questions needed).
+
+### Transcription Quality Issues
+
+**Problem**: Raw Whisper output has many errors.
+
+**Solutions**:
+
+1. Try the newer transcription model:
+```bash
+protokoll --transcription-model gpt-4o-transcribe
+```
+
+2. Ensure good audio quality:
+   - Reduce background noise
+   - Speak clearly
+   - Use a good microphone
+
+3. Add more context for domain-specific terms:
+```yaml
+# ~/.protokoll/terms/technical.yaml
+id: kubernetes
+term: Kubernetes
+sounds_like:
+  - "kube"
+  - "k8s"
+  - "kuber netties"
+```
+
+### Self-Reflection Reports Missing
+
+**Problem**: No reflection reports generated.
+
+**Solution**: Enable self-reflection explicitly:
+```bash
+protokoll --self-reflection --input-directory ./recordings
+```
+
+Check the output directory:
+```bash
+ls -la output/protokoll/*-reflection.md
+```
+
+### Permission Errors
+
+**Problem**: Can't write to output directory.
+
+**Solution**: Check directory permissions:
+```bash
+# Check permissions
+ls -la ~/notes
+
+# Fix permissions
+chmod 755 ~/notes
+```
+
+Or specify a different output directory:
+```bash
+protokoll --output-directory ./local-output --input-directory ./recordings
+```
+
+## Debug Mode
+
+For detailed troubleshooting, enable debug mode:
+
+```bash
+protokoll --debug --verbose --input-directory ./recordings
+```
+
+This will:
+- Show detailed logging
+- Keep all intermediate files
+- Display API requests/responses
+
+Check intermediate files in `output/protokoll/`:
+- `*-transcript.json` - Raw Whisper output
+- `*-context.json` - Context snapshot used
+- `*-request.json` - LLM request sent
+- `*-response.json` - LLM response received
+- `*-reflection.md` - Self-reflection report
+
+## Getting Help
+
+If you're still having issues:
+
+1. Check the [examples documentation](./examples.md)
+2. Run with `--debug --verbose` and review the output
+3. Check intermediate files for clues
+4. File an issue with:
+   - Command used
+   - Error message
+   - Relevant config (sanitized)
+   - Debug output
+

package/docs/vite.config.js

@@ -3,8 +3,14 @@ import react from '@vitejs/plugin-react'
 
 export default defineConfig({
     plugins: [react()],
-    base: '/matnava/',
+    base: '/protokoll/',  // GitHub Pages project path
+    publicDir: 'public',
     build: {
-        outDir: 'dist'
-    }
+        outDir: 'dist',
+        rollupOptions: {
+            output: {
+                manualChunks: undefined,
+            },
+        },
+    },
 }) 

package/eslint.config.mjs

@@ -19,6 +19,7 @@ const compat = new FlatCompat({
 export default defineConfig([
     globalIgnores([
         "dist/**",
+        "docs/**",
         "node_modules/**",
         "**/*.test.ts",
     ]),

package/guide/architecture.md

@@ -0,0 +1,217 @@
+# Protokoll Architecture
+
+## System Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        PROTOKOLL                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  ┌─────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
+│  │  INPUT  │──▶│ WHISPER  │──▶│ REASONING │──▶│  OUTPUT  │ │
+│  │  Audio  │   │Transcript│   │  Model    │   │ Markdown │ │
+│  └─────────┘   └──────────┘   └────┬─────┘   └──────────┘ │
+│                                    │                        │
+│                         ┌──────────┴──────────┐            │
+│                         ▼                      ▼            │
+│                    ┌─────────┐           ┌─────────┐       │
+│                    │ CONTEXT │           │ ROUTING │       │
+│                    │  System │           │ System  │       │
+│                    └─────────┘           └─────────┘       │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Core Components
+
+### 1. Context System (`src/context/`)
+
+Manages the knowledge base using hierarchical configuration discovery:
+
+- **Discovery**: Walks up directory tree finding `.protokoll/` directories
+- **People**: Named individuals with phonetic aliases
+- **Projects**: Work contexts with routing rules
+- **Companies**: Organizations
+- **Terms**: Domain-specific terminology
+
+```typescript
+interface ContextInstance {
+  getConfig(): HierarchicalConfig;
+  getPerson(id: string): Person | undefined;
+  getProject(id: string): Project | undefined;
+  getCompany(id: string): Company | undefined;
+  getTerm(id: string): Term | undefined;
+  findByPhonetic(sounds_like: string): Entity | undefined;
+  hasContext(): boolean;
+}
+```
+
+### 2. Routing System (`src/routing/`)
+
+Determines where notes go using multi-signal classification:
+
+- **Classifier**: Analyzes text for project signals
+- **Router**: Builds output paths using Dreadcabinet patterns
+- **Structures**: `none`, `year`, `month`, `day`
+
+```typescript
+interface RoutingInstance {
+  classify(text: string): ProjectClassification[];
+  route(text: string, config: RoutingConfig): RouteDestination;
+}
+```
+
+### 3. Transcription Service (`src/transcription/`)
+
+Handles audio-to-text conversion:
+
+- **Models**: whisper-1, gpt-4o-transcribe
+- **Capabilities**: Prompting support detection
+- **Formats**: JSON, text, verbose JSON
+
+```typescript
+interface TranscriptionInstance {
+  transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+  getModelCapabilities(model: string): ModelCapabilities;
+}
+```
+
+### 4. Reasoning System (`src/reasoning/`)
+
+Integrates reasoning models for enhancement:
+
+- **Models**: Claude, GPT-4o, GPT-5, GPT-5.2, O1
+- **Strategies**: Simple, investigate-then-respond, multi-pass, adaptive
+- **Token tracking**: Usage monitoring
+
+```typescript
+interface ReasoningInstance {
+  complete(request: ReasoningRequest): Promise<ReasoningResponse>;
+  getRecommendedStrategy(model: string): ReasoningStrategy;
+}
+```
+
+### 5. Agentic System (`src/agentic/`)
+
+Tool-based transcription enhancement:
+
+| Tool | Purpose |
+|------|---------|
+| `lookup_person` | Find person context by name |
+| `lookup_project` | Find routing rules |
+| `verify_spelling` | Ask user for clarification |
+| `route_note` | Determine destination |
+| `store_context` | Remember new information |
+
+```typescript
+interface AgenticInstance {
+  execute(state: TranscriptionState): Promise<TranscriptionState>;
+  getAvailableTools(): TranscriptionTool[];
+}
+```
+
+### 6. Interactive System (`src/interactive/`)
+
+User interaction for learning:
+
+- **Handler**: Manages clarification requests
+- **Onboarding**: First-run detection
+- **Session**: Tracks Q&A history
+
+```typescript
+interface InteractiveInstance {
+  handleClarification(request: ClarificationRequest): Promise<ClarificationResponse>;
+  checkNeedsOnboarding(): OnboardingState;
+}
+```
+
+### 7. Output System (`src/output/`)
+
+Manages intermediate and final files:
+
+- **Intermediate**: transcript, context, request, response, reflection, session
+- **Final**: Routed markdown file
+- **Cleanup**: Optional intermediate removal
+
+```typescript
+interface OutputInstance {
+  createOutputPaths(audioFile, destination, hash, date): OutputPaths;
+  writeIntermediate(paths, type, content): Promise<string>;
+  writeTranscript(paths, content): Promise<string>;
+}
+```
+
+### 8. Reflection System (`src/reflection/`)
+
+Self-assessment and reporting (enabled by default):
+
+- **Collector**: Gathers metrics during processing
+- **Reporter**: Generates quality reports
+- **Recommendations**: Suggests improvements
+
+```typescript
+interface ReflectionInstance {
+  collector: CollectorInstance;
+  generate(audioFile, outputFile, history?, output?): ReflectionReport;
+  save(report, path): Promise<void>;
+}
+```
+
+### 9. Pipeline System (`src/pipeline/`)
+
+Orchestrates the entire processing flow:
+
+- **Orchestrator**: Coordinates all phases
+- **Phases**: locate, transcribe, complete
+
+```typescript
+interface PipelineInstance {
+  process(audioFile: string): Promise<ProcessingResult>;
+}
+```
+
+## Data Flow
+
+```
+1. Audio File
+   ↓
+2. Whisper Transcription → Raw text with errors
+   ↓
+3. Context Discovery → Find .protokoll/ directories
+   ↓
+4. Context Analysis → Identify potential names, projects
+   ↓
+5. Tool Execution → lookup_person, lookup_project, etc.
+   ↓
+6. Interactive Clarification (if enabled) → Ask user about unknowns
+   ↓
+7. Route Detection → Determine destination
+   ↓
+8. Enhanced Transcript → Clean, corrected text
+   ↓
+9. Output → Write to routed destination
+   ↓
+10. Reflection (enabled by default) → Generate self-reflection report
+```
+
+## File Locations
+
+| Component | Location |
+|-----------|----------|
+| Global context | `~/.protokoll/` |
+| Project context | `./.protokoll/` |
+| Configuration | `~/.protokoll/config.yaml` |
+| Intermediate files | `./output/protokoll/` |
+| Final transcripts | Routed destination |
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@theunwalked/dreadcabinet` | Filesystem structure patterns |
+| `@theunwalked/cardigantime` | Hierarchical config discovery |
+| `@riotprompt/riotprompt` | Prompt building and agentic execution |
+| `openai` | Whisper and GPT APIs |
+| `@anthropic-ai/sdk` | Claude API |
+| `@google/generative-ai` | Gemini API |
+