@redaksjon/protokoll 0.0.7 → 0.0.9

package/guide/configuration.md

@@ -0,0 +1,199 @@
+# Configuration Guide
+
+## Configuration Files
+
+### Main Config: `~/.protokoll/config.yaml`
+
+```yaml
+# Model settings
+model: "gpt-5.2"                   # Reasoning model (default)
+transcriptionModel: "whisper-1"    # Audio transcription
+
+# Context
+context:
+  directory: "~/.protokoll"
+  autoCreate: true
+
+# Routing
+routing:
+  default:
+    path: "~/notes"
+    structure: "month"
+    filename:
+      - date
+      - time
+      - subject
+  
+  projects:
+    - projectId: "work"
+      destination:
+        path: "~/work/notes"
+        structure: "month"
+      triggers:
+        - "work note"
+        - "about work"
+
+# Output
+output:
+  intermediateDir: "./output/protokoll"
+  keepIntermediates: true
+
+# Features
+features:
+  interactive: false               # Disabled by default
+  selfReflection: true            # Enabled by default
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `OPENAI_API_KEY` | OpenAI API key (required) |
+| `ANTHROPIC_API_KEY` | Anthropic API key (for Claude models) |
+| `PROTOKOLL_MODEL` | Override default model |
+| `PROTOKOLL_CONFIG_DIR` | Config directory |
+
+## Command Line Options
+
+### Basic Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--input-directory <dir>` | Directory with audio files | Required |
+| `--output-directory <dir>` | Default output directory | `~/notes` |
+| `--model <model>` | Reasoning model | `gpt-5.2` |
+| `--transcription-model <model>` | Whisper model | `whisper-1` |
+
+### Mode Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--interactive` | Enable interactive clarifications | `false` |
+| `--self-reflection` | Generate reflection reports | `true` |
+| `--no-self-reflection` | Disable reflection reports | - |
+| `--dry-run` | Show what would happen | `false` |
+| `--verbose` | Enable verbose logging | `false` |
+| `--debug` | Enable debug mode | `false` |
+
+### Advanced Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--context-directories <dirs...>` | Additional context locations | `[]` |
+| `--max-audio-size <bytes>` | Maximum audio file size | `26214400` (25MB) |
+| `--temp-directory <dir>` | Temporary file storage | OS temp dir |
+| `--processed-directory <dir>` | Move processed files here | - |
+| `--overrides` | Allow config overrides | `false` |
+
+## Routing Structures
+
+Protokoll uses Dreadcabinet structure codenames:
+
+| Structure | Example Path |
+|-----------|--------------|
+| `none` | `notes/meeting.md` |
+| `year` | `notes/2026/meeting.md` |
+| `month` | `notes/2026/01/meeting.md` |
+| `day` | `notes/2026/01/11/meeting.md` |
+
+## Filename Options
+
+| Option | Example |
+|--------|---------|
+| `date` | `260111` (YYMMDD format) |
+| `time` | `1430` (HHmm format) |
+| `subject` | `meeting-notes` |
+
+Combined: `260111-1430-meeting-notes.md`
+
+## Hierarchical Configuration
+
+Protokoll walks up the directory tree looking for `.protokoll/` directories:
+
+```
+~/work/project-a/recordings/
+  ↓ looks for .protokoll/ in:
+~/work/project-a/.protokoll/    # Project-specific
+~/work/.protokoll/               # Work-specific  
+~/.protokoll/                    # Global
+```
+
+Lower directories take precedence for conflicting settings.
+
+## Model Selection
+
+### Reasoning Models
+
+| Model | Provider | Notes |
+|-------|----------|-------|
+| `gpt-5.2` | OpenAI | **Default** - High reasoning capability |
+| `gpt-5.1` | OpenAI | High reasoning, balanced |
+| `gpt-5` | OpenAI | Fast and capable |
+| `gpt-4o` | OpenAI | Previous gen, still capable |
+| `gpt-4o-mini` | OpenAI | Fast, lower cost |
+| `o1` | OpenAI | Reasoning-focused |
+| `o1-mini` | OpenAI | Faster reasoning |
+| `claude-3-5-sonnet` | Anthropic | Recommended for complex transcripts |
+| `claude-3-opus` | Anthropic | Highest capability |
+| `claude-3-haiku` | Anthropic | Fast, cost-effective |
+
+### Transcription Models
+
+| Model | Notes |
+|-------|-------|
+| `whisper-1` | Standard Whisper (default) |
+| `gpt-4o-transcribe` | Newer model with prompting support |
+
+> **Note**: Protokoll accepts any model string without restrictions. Model validation happens at the API level, ensuring future compatibility.
+
+## Example Configurations
+
+### Personal Notes
+
+```yaml
+model: "gpt-5.2"
+routing:
+  default:
+    path: "~/notes"
+    structure: "month"
+```
+
+### Work Projects
+
+```yaml
+model: "claude-3-5-sonnet"
+routing:
+  default:
+    path: "~/notes/personal"
+    structure: "month"
+  projects:
+    - projectId: "work"
+      destination:
+        path: "~/work/notes"
+        structure: "day"
+      triggers:
+        - "work"
+        - "office"
+        - "meeting"
+```
+
+### Team Shared Context
+
+```yaml
+# ~/team-project/.protokoll/config.yaml
+context:
+  directory: "./.protokoll"
+routing:
+  default:
+    path: "./notes"
+    structure: "month"
+```
+
+### Batch Processing (No Self-Reflection)
+
+```yaml
+features:
+  selfReflection: false
+  interactive: false
+```
+

package/guide/context-system.md

@@ -0,0 +1,215 @@
+# Context System
+
+The context system is Protokoll's knowledge base for improving transcription accuracy.
+
+## Overview
+
+Protokoll uses hierarchical configuration discovery to find context:
+
+1. Walks up directory tree from input location
+2. Finds all `.protokoll/` directories
+3. Merges context with local taking precedence
+
+## Directory Structure
+
+```
+~/.protokoll/
+├── config.yaml          # Main configuration
+├── people/              # Person definitions
+│   └── *.yaml
+├── projects/            # Project definitions
+│   └── *.yaml
+├── companies/           # Company definitions
+│   └── *.yaml
+└── terms/               # Terminology definitions
+    └── *.yaml
+```
+
+## Entity Types
+
+### People
+
+```yaml
+# ~/.protokoll/people/priya-sharma.yaml
+id: priya-sharma
+name: Priya Sharma
+firstName: Priya
+lastName: Sharma
+company: acme-corp
+role: Engineering Manager
+sounds_like:
+  - "pre a"
+  - "pria"
+  - "preeya sharma"
+context: "Colleague from engineering team"
+```
+
+### Projects
+
+```yaml
+# ~/.protokoll/projects/quarterly-planning.yaml
+id: quarterly-planning
+name: Quarterly Planning
+category: work
+destination: "~/work/planning/notes"
+structure: "month"
+triggers:
+  - "quarterly planning"
+  - "Q1 planning"
+  - "Q2 planning"
+active: true
+```
+
+### Companies
+
+```yaml
+# ~/.protokoll/companies/acme-corp.yaml
+id: acme-corp
+name: Acme Corporation
+sounds_like:
+  - "acme"
+  - "acme corp"
+  - "a.c.m.e."
+context: "Client company in manufacturing"
+```
+
+### Terms
+
+```yaml
+# ~/.protokoll/terms/kubernetes.yaml
+id: kubernetes
+term: Kubernetes
+sounds_like:
+  - "kube"
+  - "k8s"
+  - "kuber netties"
+  - "kubernetes"
+context: "Container orchestration platform"
+```
+
+## Phonetic Aliases (sounds_like)
+
+The `sounds_like` field maps common mishearings to correct spellings:
+
+```yaml
+sounds_like:
+  - "pre a"         # Whisper might hear "Priya" as "pre a"
+  - "pria"          # Or as "pria"
+  - "preeya"        # Or as "preeya"
+```
+
+When Protokoll sees any of these in a transcript, it knows to correct them.
+
+## Hierarchical Discovery
+
+Context is discovered by walking up the directory tree:
+
+```
+~/work/project-a/recordings/audio.m4a
+  ↓
+~/work/project-a/.protokoll/     # Project-specific context
+~/work/.protokoll/                # Work-specific context
+~/.protokoll/                     # Global context
+```
+
+### Merge Behavior
+
+- **People, Companies, Terms**: All are loaded, local IDs override global
+- **Projects**: All are loaded, local definitions take precedence
+- **Config**: Deep merged, local settings override global
+
+## API
+
+### ContextInstance
+
+```typescript
+interface ContextInstance {
+  // Get merged configuration
+  getConfig(): HierarchicalConfig;
+  
+  // Entity lookup
+  getPerson(id: string): Person | undefined;
+  getProject(id: string): Project | undefined;
+  getCompany(id: string): Company | undefined;
+  getTerm(id: string): Term | undefined;
+  
+  // Get all entities
+  getAllPeople(): Person[];
+  getAllProjects(): Project[];
+  getAllCompanies(): Company[];
+  getAllTerms(): Term[];
+  
+  // Phonetic lookup
+  findByPhonetic(sounds_like: string): Entity | undefined;
+  
+  // State
+  hasContext(): boolean;
+  
+  // Persistence
+  savePerson(person: Person): Promise<void>;
+  saveProject(project: Project): Promise<void>;
+}
+```
+
+## Usage in Agentic Tools
+
+### lookup_person
+
+```typescript
+// Tool looks up person by name or phonetic
+const person = context.findByPhonetic("pre a");
+// Returns: { id: "priya-sharma", name: "Priya Sharma", ... }
+```
+
+### lookup_project
+
+```typescript
+// Tool finds project by trigger phrase
+const projects = context.getAllProjects();
+const match = projects.find(p => 
+  p.triggers?.some(t => text.toLowerCase().includes(t))
+);
+```
+
+### store_context
+
+```typescript
+// Tool saves new person to context
+await context.savePerson({
+  id: "new-person",
+  name: "New Person",
+  sounds_like: ["new per son"]
+});
+```
+
+## Best Practices
+
+1. **Use descriptive IDs**: `priya-sharma` not `person1`
+2. **Add multiple sounds_like**: Cover common mishearings
+3. **Include context**: Helps with disambiguation
+4. **Organize by project**: Use project-specific `.protokoll/` directories
+5. **Keep global context minimal**: Only truly global entities
+
+## Troubleshooting
+
+### Context Not Found
+
+```bash
+# Check discovery with verbose mode
+protokoll --verbose --input-directory ./recordings
+
+# Look for: "Found .protokoll at: ..."
+```
+
+### Wrong Entity Matched
+
+1. Check `sounds_like` for conflicts
+2. Add more specific phonetic patterns
+3. Use `--debug` to see matching decisions
+
+### Performance Issues
+
+1. Keep context files small
+2. Use project-specific context
+3. Avoid duplicate entries
+

package/guide/development.md

@@ -0,0 +1,273 @@
+# Development Guide
+
+Guide for developing and extending Protokoll.
+
+## Setup
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+
+### Clone and Install
+
+```bash
+git clone https://github.com/redaksjon/protokoll.git
+cd protokoll
+npm install
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Test
+
+```bash
+npm test
+```
+
+### Lint
+
+```bash
+npm run lint
+npm run lint:fix  # Auto-fix issues
+```
+
+## Project Structure
+
+```
+protokoll/
+├── src/
+│   ├── agentic/           # Agentic tool system
+│   │   ├── tools/         # Individual tools
+│   │   │   ├── lookup-person.ts
+│   │   │   ├── lookup-project.ts
+│   │   │   ├── route-note.ts
+│   │   │   ├── store-context.ts
+│   │   │   └── verify-spelling.ts
+│   │   ├── registry.ts    # Tool registry
+│   │   ├── executor.ts    # Execution loop
+│   │   └── types.ts
+│   ├── context/           # Context system
+│   │   ├── discovery.ts   # Hierarchical discovery
+│   │   ├── storage.ts     # Entity storage
+│   │   └── types.ts
+│   ├── interactive/       # Interactive mode
+│   │   ├── handler.ts     # Clarification handling
+│   │   ├── onboarding.ts  # First-run setup
+│   │   └── types.ts
+│   ├── output/            # Output management
+│   │   ├── manager.ts     # File management
+│   │   └── types.ts
+│   ├── pipeline/          # Processing pipeline
+│   │   ├── orchestrator.ts
+│   │   └── types.ts
+│   ├── phases/            # Processing phases
+│   │   ├── locate.ts
+│   │   ├── transcribe.ts
+│   │   └── complete.ts
+│   ├── prompt/            # Prompt templates
+│   │   ├── personas/
+│   │   │   └── transcriber.md
+│   │   └── instructions/
+│   │       └── transcribe.md
+│   ├── reasoning/         # Reasoning integration
+│   │   ├── client.ts      # LLM client
+│   │   ├── strategy.ts    # Strategy selection
+│   │   └── types.ts
+│   ├── reflection/        # Self-reflection
+│   │   ├── collector.ts   # Metrics collection
+│   │   ├── reporter.ts    # Report generation
+│   │   └── types.ts
+│   ├── routing/           # Routing system
+│   │   ├── classifier.ts  # Signal classification
+│   │   ├── router.ts      # Path building
+│   │   └── types.ts
+│   ├── transcription/     # Transcription service
+│   │   ├── service.ts     # Whisper integration
+│   │   └── types.ts
+│   ├── util/              # Utilities
+│   │   ├── child.ts
+│   │   ├── dates.ts
+│   │   ├── general.ts
+│   │   ├── media.ts
+│   │   ├── metadata.ts
+│   │   ├── openai.ts
+│   │   └── storage.ts
+│   ├── error/             # Error types
+│   │   └── ArgumentError.ts
+│   ├── arguments.ts       # CLI arguments
+│   ├── constants.ts       # Constants
+│   ├── logging.ts         # Logging
+│   ├── main.ts            # Entry point
+│   ├── processor.ts       # File processor
+│   └── protokoll.ts       # Main types
+├── tests/                 # Test files (mirrors src/)
+├── guide/                 # AI guide documentation
+├── docs/                  # User documentation site
+└── output/                # Intermediate files (gitignored)
+```
+
+## Adding a New Tool
+
+### 1. Create Tool File
+
+```typescript
+// src/agentic/tools/my-tool.ts
+import { TranscriptionTool, ToolContext, ToolResult } from '../types';
+
+export const createMyTool = (): TranscriptionTool => ({
+  name: 'my_tool',
+  description: 'Description for the reasoning model',
+  parameters: {
+    type: 'object',
+    properties: {
+      param1: { type: 'string', description: 'Parameter description' }
+    },
+    required: ['param1']
+  },
+  execute: async (args: { param1: string }, context: ToolContext): Promise<ToolResult> => {
+    // Implementation
+    return {
+      success: true,
+      data: { result: 'value' }
+    };
+  }
+});
+```
+
+### 2. Register Tool
+
+```typescript
+// src/agentic/registry.ts
+import { createMyTool } from './tools/my-tool';
+
+export const create = (context: ToolContext): RegistryInstance => {
+  const tools: TranscriptionTool[] = [
+    // ... existing tools
+    createMyTool(),
+  ];
+  // ...
+};
+```
+
+### 3. Add Tests
+
+```typescript
+// tests/agentic/tools.test.ts
+describe('my_tool', () => {
+  it('should do something', async () => {
+    const tool = createMyTool();
+    const result = await tool.execute({ param1: 'test' }, mockContext);
+    expect(result.success).toBe(true);
+  });
+});
+```
+
+## Testing
+
+### Run All Tests
+
+```bash
+npm test
+```
+
+### Run Specific Tests
+
+```bash
+npm test -- tests/context/
+npm test -- --grep "should discover"
+```
+
+### Coverage
+
+```bash
+npm run test:coverage
+```
+
+## Code Style
+
+### ESLint
+
+```bash
+npm run lint
+npm run lint:fix
+```
+
+### TypeScript
+
+- Strict mode enabled
+- No implicit any
+- Use interfaces for public APIs
+- Use types for internal structures
+
+### Conventions
+
+- Use `create()` factory functions
+- Export interfaces from index files
+- Keep modules focused
+- Document public APIs
+
+## Dependencies
+
+### Core
+
+| Package | Purpose |
+|---------|---------|
+| `@theunwalked/dreadcabinet` | Filesystem patterns |
+| `@theunwalked/cardigantime` | Hierarchical config discovery |
+| `@riotprompt/riotprompt` | Prompt building and agentic execution |
+| `openai` | OpenAI API (Whisper and GPT) |
+| `@anthropic-ai/sdk` | Anthropic API (Claude) |
+| `@google/generative-ai` | Google API (Gemini) |
+
+### Dev
+
+| Package | Purpose |
+|---------|---------|
+| `vitest` | Testing |
+| `typescript` | Type checking |
+| `eslint` | Linting |
+| `vite` | Building |
+
+## Release Process
+
+1. Update version in `package.json`
+2. Run tests: `npm test`
+3. Build: `npm run build`
+4. Commit: `git commit -m "Release vX.Y.Z"`
+5. Tag: `git tag vX.Y.Z`
+6. Push: `git push && git push --tags`
+7. Publish: `npm publish`
+
+## Debugging
+
+### Verbose Mode
+
+```bash
+protokoll --verbose --input-directory ./recordings
+```
+
+### Debug Mode
+
+```bash
+protokoll --debug --input-directory ./recordings
+```
+
+Keeps intermediate files in `output/protokoll/`:
+- `*-transcript.json` - Raw Whisper output
+- `*-context.json` - Context snapshot
+- `*-request.json` - LLM request
+- `*-response.json` - LLM response
+- `*-reflection.md` - Self-reflection report
+- `*-session.json` - Interactive session log
+
+### Node Debugging
+
+```bash
+node --inspect-brk dist/main.js --input-directory ./recordings
+```
+