@redaksjon/protokoll 0.0.11 → 0.0.13

package/guide/action.md

@@ -0,0 +1,375 @@
+# Transcript Actions
+
+Protokoll includes the `action` command for editing and combining existing transcripts. These capabilities help you organize, merge, and manage your transcript library after the initial transcription.
+
+## Overview
+
+The `action` command provides two modes:
+
+| Mode | Usage | Description |
+|------|-------|-------------|
+| **Edit** | `protokoll action [options] <file>` | Edit a single transcript (title, project) |
+| **Combine** | `protokoll action --combine "<files>"` | Merge multiple transcripts into one |
+
+## Edit Mode
+
+Edit a single transcript to change its title and/or project.
+
+### Basic Usage
+
+```bash
+protokoll action [options] <file>
+```
+
+Where `<file>` is the path to the transcript to edit.
+
+### Examples
+
+#### Change the Title
+
+```bash
+protokoll action --title "Time to Celebrate" /path/to/transcript.md
+```
+
+This will:
+1. Update the document heading to `# Time to Celebrate`
+2. Rename the file to `15-1412-time-to-celebrate.md` (preserving timestamp)
+
+#### Change the Project
+
+```bash
+protokoll action --project client-alpha /path/to/transcript.md
+```
+
+This will:
+1. Update the project metadata in the document
+2. Move the file to the project's configured destination
+
+#### Change Both Title and Project
+
+```bash
+protokoll action --title "Q1 Planning Session" --project quarterly-planning /path/to/transcript.md
+```
+
+#### Preview Changes (Dry Run)
+
+```bash
+protokoll action --title "New Title" /path/to/transcript.md --dry-run --verbose
+```
+
+Shows what would happen without making any changes.
+
+## Combine Mode
+
+Merge multiple related transcripts into a single document. When combining, source files are **automatically deleted** after the combined file is created.
+
+### Basic Usage
+
+```bash
+protokoll action --combine "<files>"
+```
+
+Where `<files>` is a newline-separated list of transcript file paths.
+
+### Examples
+
+#### Combine with Custom Title
+
+```bash
+protokoll action --title "Time to Celebrate" --combine "/path/to/part1.md
+/path/to/part2.md
+/path/to/part3.md"
+```
+
+This creates a combined transcript and deletes the source files.
+
+#### Combine and Change Project
+
+```bash
+protokoll action --title "Full Meeting Notes" --project client-alpha --combine "/path/to/part1.md
+/path/to/part2.md"
+```
+
+This will:
+1. Combine the transcripts
+2. Set the custom title
+3. Update the metadata to reflect the new project
+4. Route the output to the project's configured destination
+5. Delete the source files
+
+#### Preview Changes (Dry Run)
+
+```bash
+protokoll action --combine "/path/to/files..." --dry-run --verbose
+```
+
+Shows what would happen without making any changes.
+
+### Command Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--title <title>` | `-t` | Set a custom title for the document and filename |
+| `--project <id>` | `-p` | Change to a different project (updates metadata and routing) |
+| `--combine <files>` | `-c` | Combine multiple files (newline-separated list) |
+| `--dry-run` | | Show what would happen without making changes |
+| `--verbose` | `-v` | Show detailed output |
+
+## How It Works
+
+### Edit Mode
+
+1. **Parses the transcript**: Extracts title, metadata, and content
+2. **Updates title**: If `--title` is provided, changes the document heading
+3. **Updates project**: If `--project` is provided, updates metadata and destination
+4. **Renames/moves file**: If title or project changed, moves to new location
+5. **Deletes original**: If file was renamed, removes the old file
+
+### Combine Mode
+
+1. **Parses all transcripts**: Extracts metadata, title, and content from each file
+2. **Sorts chronologically**: Orders transcripts by filename (which includes timestamp)
+3. **Merges metadata**: Uses the first transcript's date/time, combines durations, deduplicates tags
+4. **Creates sections**: Each source transcript becomes a section with its original title
+5. **Routes intelligently**: If `--project` is specified, uses that project's routing configuration
+6. **Cleans up**: Automatically deletes source files after successful combine
+
+### Title Slugification
+
+When you provide a custom title, it's converted to a filename-safe format:
+
+| Title | Filename |
+|-------|----------|
+| `Time to Celebrate` | `time-to-celebrate` |
+| `Meeting: Q1 Planning & Review!` | `meeting-q1-planning-review` |
+| `Sprint 42 Retrospective` | `sprint-42-retrospective` |
+
+The slug is limited to 50 characters and preserves the timestamp prefix from the original file.
+
+## Output Format
+
+### Edit Mode Output
+
+When editing a single transcript:
+
+```markdown
+# New Title Here
+
+## Metadata
+
+**Date**: January 15, 2026
+**Time**: 02:12 PM
+
+**Project**: New Project Name
+**Project ID**: `new-project-id`
+
+### Routing
+...
+
+---
+
+[Original content preserved]
+```
+
+### Combine Mode Output
+
+When combining transcripts:
+
+```markdown
+# Combined Title
+
+## Metadata
+
+**Date**: January 15, 2026
+**Time**: 02:12 PM
+
+**Project**: Project Name
+**Project ID**: `project-id`
+
+### Routing
+...
+
+**Tags**: `tag1`, `tag2`, `tag3`
+
+**Duration**: 15m 30s
+
+---
+
+## First Part Title
+*Source: 15-1412-first-part.md*
+
+First part content...
+
+## Second Part Title
+*Source: 15-1421-second-part.md*
+
+Second part content...
+```
+
+## Project Routing
+
+When using `--project`, the action command leverages Protokoll's routing system:
+
+### Project Configuration
+
+Projects are configured in `.protokoll/projects/`:
+
+```yaml
+# ~/.protokoll/projects/client-alpha.yaml
+id: client-alpha
+name: Client Alpha
+type: project
+
+classification:
+  context_type: work
+  explicit_phrases:
+    - "client alpha"
+
+routing:
+  destination: "~/clients/alpha/notes"
+  structure: "month"
+  filename_options:
+    - date
+    - time
+    - subject
+  auto_tags:
+    - client
+    - alpha
+
+active: true
+```
+
+### Routing Behavior
+
+When you specify `--project client-alpha`:
+
+1. **Metadata Update**: Project name and ID are updated in the transcript
+2. **Destination**: Output goes to `~/clients/alpha/notes/2026/01/` (based on structure)
+3. **Filename**: Built using the project's filename options (or slugified title if provided)
+4. **Tags**: Project's `auto_tags` are added to the combined tags
+
+## Use Cases
+
+### 1. Rename a Transcript
+
+You want to give a transcript a more meaningful title:
+
+```bash
+protokoll action --title "Q1 Budget Review Meeting" /path/to/15-1412-meeting.md
+```
+
+### 2. Move to Different Project
+
+You realize a transcript belongs to a different project:
+
+```bash
+protokoll action --project client-beta /path/to/15-1412-meeting.md
+```
+
+### 3. Consolidate Meeting Notes
+
+You recorded a long meeting in multiple segments:
+
+```bash
+protokoll action --title "Full Team Standup" --combine "/path/to/part1.md
+/path/to/part2.md
+/path/to/part3.md"
+```
+
+### 4. Reorganize by Project
+
+Combine transcripts that were initially routed to the default location:
+
+```bash
+protokoll action --title "Sprint 42 Planning" --project sprint-42 --combine "/path/to/misc1.md
+/path/to/misc2.md"
+```
+
+## Troubleshooting
+
+### File Not Found
+
+```
+Error: File not found: /path/to/file.md
+```
+
+Ensure the file path is correct and accessible. Use absolute paths to avoid ambiguity.
+
+### Project Not Found
+
+```
+Error: Project not found: my-project
+```
+
+Verify the project exists:
+
+```bash
+protokoll project list
+protokoll project show my-project
+```
+
+### Must Specify Title or Project
+
+```
+Error: Must specify --title and/or --project when editing a single file.
+```
+
+When editing a single file (not combining), you must provide at least one of `--title` or `--project`.
+
+### At Least 2 Files Required
+
+```
+Error: At least 2 transcript files are required for --combine.
+```
+
+The combine mode requires at least 2 transcripts. For single files, use edit mode instead.
+
+## Best Practices
+
+1. **Use `--dry-run` first**: Always preview changes before committing
+
+2. **Verify project routing**: Check project configuration before using `--project`
+
+3. **Use absolute paths**: Avoid relative paths to prevent confusion
+
+4. **Meaningful titles**: When combining, provide a descriptive title that captures the full session
+
+## API Reference
+
+For programmatic use, the action module exports:
+
+```typescript
+import {
+  parseTranscript,
+  combineTranscripts,
+  editTranscript,
+  parseFilePaths,
+  extractTimestampFromFilename,
+  formatMetadataMarkdown,
+  slugifyTitle,
+} from '@redaksjon/protokoll/cli/action';
+
+// Parse a single transcript
+const parsed = await parseTranscript('/path/to/transcript.md');
+
+// Edit a transcript
+const edited = await editTranscript('/path/to/file.md', {
+  title: 'New Title',
+  projectId: 'my-project',
+});
+
+// Combine multiple transcripts
+const combined = await combineTranscripts(
+  ['/path/to/file1.md', '/path/to/file2.md'],
+  { title: 'Combined Title', projectId: 'my-project' }
+);
+
+// Slugify a title for use in filenames
+const slug = slugifyTitle('New Approach to Life'); // 'new-approach-to-life'
+```
+
+## See Also
+
+- [Routing System](./routing.md) - How project routing works
+- [Context Commands](./context-commands.md) - Managing projects and entities
+- [Configuration](./configuration.md) - Setting up Protokoll

package/guide/config.md

@@ -0,0 +1,207 @@
+# Configuration Command
+
+The `config` command provides an easy way to view and edit Protokoll's configuration without manually editing YAML files.
+
+## Basic Usage
+
+### Interactive Mode
+
+Running `protokoll config` without arguments opens an interactive configuration editor:
+
+```bash
+protokoll config
+```
+
+The editor walks through each setting category, showing:
+- Current value (or default if not set)
+- Description of what the setting does
+- Allowed values or examples
+- Prompt to enter a new value
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║           PROTOKOLL CONFIGURATION EDITOR                       ║
+╚════════════════════════════════════════════════════════════════╝
+
+Config file: ~/.protokoll/config.yaml
+
+Press Enter to keep current value, or type a new value.
+Type 'q' to quit, 's' to save and exit.
+
+── AI Models ──
+
+  model
+  AI model for transcription enhancement
+  Examples: gpt-5.2, gpt-4o, gpt-4o-mini, claude-3-5-sonnet
+  Current: gpt-5.2
+  New value (Enter to skip): gpt-4o
+  ✓ Set to: gpt-4o
+```
+
+### List All Settings
+
+View all configuration options and their current values:
+
+```bash
+protokoll config --list
+```
+
+Output:
+```
+Protokoll Configuration
+Config file: ~/.protokoll/config.yaml
+
+  model                    gpt-5.2
+  transcriptionModel       whisper-1 (default)
+  reasoningLevel           medium (default)
+  inputDirectory           ./recordings
+  outputDirectory          ~/notes
+  ...
+```
+
+### View a Specific Setting
+
+Check the current value of any setting:
+
+```bash
+protokoll config model
+```
+
+Output:
+```
+model
+AI model for transcription enhancement
+
+Value: gpt-5.2
+Examples: gpt-5.2, gpt-4o, gpt-4o-mini, claude-3-5-sonnet
+```
+
+### Set a Specific Value
+
+Change any setting with a one-line command:
+
+```bash
+protokoll config model gpt-4o-mini
+```
+
+Output:
+```
+✓ model = gpt-4o-mini
+Saved to: ~/.protokoll/config.yaml
+```
+
+### Show Config File Path
+
+Find where your configuration is stored:
+
+```bash
+protokoll config --path
+```
+
+## Available Settings
+
+### AI Models
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `model` | string | `gpt-5.2` | AI model for transcription enhancement |
+| `transcriptionModel` | string | `whisper-1` | Model for audio transcription |
+| `reasoningLevel` | string | `medium` | Reasoning effort: `low`, `medium`, or `high` |
+
+### Directories
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `inputDirectory` | path | `./` | Where to read audio files from |
+| `outputDirectory` | path | `~/notes` | Where to write transcripts |
+| `processedDirectory` | path | `./processed` | Where to move processed audio files |
+| `tempDirectory` | path | `/tmp` | Temporary directory for processing |
+
+### Output Format
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `outputStructure` | string | `month` | Directory structure: `none`, `year`, `month`, `day` |
+| `outputFilenameOptions` | array | `date,time,subject` | Components in output filenames |
+| `timezone` | string | `Etc/UTC` | Timezone for date/time operations |
+
+### Behavior
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `interactive` | boolean | `true` | Enable interactive prompts |
+| `selfReflection` | boolean | `true` | Generate self-reflection reports |
+| `silent` | boolean | `false` | Disable sound notifications |
+| `verbose` | boolean | `false` | Enable verbose logging |
+| `debug` | boolean | `false` | Enable debug mode |
+| `dryRun` | boolean | `false` | Show what would happen without changes |
+
+### Limits
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `maxAudioSize` | number | `26214400` | Maximum audio file size in bytes (25MB) |
+
+## Examples
+
+### Setting Up for Work
+
+```bash
+# Set a work-appropriate model
+protokoll config model gpt-4o-mini
+
+# Output to work notes folder
+protokoll config outputDirectory ~/work/notes
+
+# Organize by month
+protokoll config outputStructure month
+```
+
+### Disabling Interactive Mode for Automation
+
+```bash
+# Disable interactive prompts (use in cron jobs)
+protokoll config interactive false
+
+# Disable sounds
+protokoll config silent true
+```
+
+### Debugging Issues
+
+```bash
+# Enable debug output
+protokoll config debug true
+
+# Enable verbose logging
+protokoll config verbose true
+```
+
+### Configuring Array Values
+
+For array settings like `outputFilenameOptions`, use comma-separated values:
+
+```bash
+# Just date and subject (no time)
+protokoll config outputFilenameOptions "date,subject"
+
+# All options
+protokoll config outputFilenameOptions "date,time,subject"
+```
+
+## Configuration Hierarchy
+
+Protokoll uses hierarchical configuration:
+
+1. **Default values** - Built into Protokoll
+2. **Global config** - `~/.protokoll/config.yaml`
+3. **Project config** - `.protokoll/config.yaml` in any parent directory
+4. **Command-line arguments** - Highest priority
+
+The `config` command edits either the global config or the closest project config, depending on which exists.
+
+## See Also
+
+- [Quick Start Guide](./quickstart.md) - Getting started with Protokoll
+- [Routing System](./routing.md) - Configure project-specific routing
+- [Context System](./context-system.md) - Add people, terms, and projects