@redaksjon/protokoll 1.0.12 → 1.0.13

package/docs/MCP_SERVER_MODES.md

@@ -0,0 +1,146 @@
+# MCP Server Modes: Local vs Remote
+
+Protokoll's MCP server can operate in two distinct modes that affect how directory parameters are handled.
+
+## Server Modes
+
+### Remote Mode
+
+**When:** HTTP server (`protokoll-mcp-http`) with pre-configured workspace
+
+**Characteristics:**
+- Server is initialized with a workspace root and `protokoll-config.yaml`
+- All directory paths (`inputDirectory`, `outputDirectory`, `contextDirectories`) are pre-configured
+- Tools **DO NOT** accept `contextDirectory` parameters
+- Attempting to provide directory parameters will result in an error
+
+**Use Case:** Production deployments where the server manages a specific workspace
+
+**Example:**
+```bash
+# Server starts with workspace at /path/to/workspace
+PORT=4000 protokoll-mcp-http
+
+# Tools use pre-configured directories automatically
+# No contextDirectory parameter needed or accepted
+```
+
+### Local Mode
+
+**When:** stdio server (`protokoll-mcp`) or dynamic discovery
+
+**Characteristics:**
+- Server performs dynamic configuration discovery
+- Tools **MAY** accept optional `contextDirectory` parameters
+- If no directory is provided, falls back to current working directory or discovery
+
+**Use Case:** Development, CLI usage, or environments without fixed workspace
+
+**Example:**
+```bash
+# Server runs without pre-configured workspace
+protokoll-mcp
+
+# Tools can optionally specify contextDirectory
+# Falls back to discovery if not provided
+```
+
+## Checking Server Mode
+
+Use the `protokoll_info` tool to determine the server's mode:
+
+```json
+{
+  "mode": "remote",
+  "modeDescription": "Server is running in remote mode with pre-configured workspace directories",
+  "acceptsDirectoryParameters": false,
+  "workspaceRoot": "/path/to/workspace",
+  "inputDirectory": "/path/to/workspace/recordings",
+  "outputDirectory": "/path/to/workspace/notes",
+  "contextDirectories": ["/path/to/workspace/context"]
+}
+```
+
+## Tool Behavior
+
+### In Remote Mode
+
+All tools that would normally accept `contextDirectory` will:
+1. Use the pre-configured workspace directories
+2. Reject any `contextDirectory` parameter with an error message
+3. Direct users to check `protokoll_info` for configuration
+
+**Error Example:**
+```
+Error: contextDirectory parameter is not accepted in remote mode. 
+This server is pre-configured with workspace directories from protokoll-config.yaml. 
+Use the protokoll_info tool to check server configuration.
+```
+
+### In Local Mode
+
+Tools accept optional `contextDirectory` parameters:
+- If provided: Use the specified directory
+- If not provided: Fall back to discovery or current working directory
+
+## Implementation Details
+
+### Server Initialization
+
+**HTTP Server (Remote Mode):**
+```typescript
+await ServerConfig.initializeServerConfig(initialRoots, 'remote');
+```
+
+**stdio Server (Local Mode):**
+```typescript
+await ServerConfig.initializeServerConfig(initialRoots, 'local');
+// or defaults to 'local' if not specified
+```
+
+### Tool Validation
+
+Tools validate the mode before processing:
+
+```typescript
+// In remote mode, this throws an error if contextDirectory is provided
+await validateNotRemoteMode(args.contextDirectory);
+```
+
+### Context Instance Resolution
+
+The `getContextInstance` helper prioritizes server context:
+
+```typescript
+async function getContextInstance(contextDirectory?: string): Promise<ContextInstance> {
+    // Validate remote mode
+    if (contextDirectory && ServerConfig.isRemoteMode()) {
+        throw new Error('contextDirectory not accepted in remote mode');
+    }
+    
+    // Use server context if available
+    const serverContext = ServerConfig.getContext();
+    if (serverContext) {
+        return serverContext;
+    }
+    
+    // Fallback to new context (local mode)
+    return Context.create({
+        startingDir: contextDirectory || process.cwd(),
+    });
+}
+```
+
+## Best Practices
+
+1. **Always check `protokoll_info` first** when connecting to a new server
+2. **In remote mode:** Don't provide directory parameters
+3. **In local mode:** Provide directory parameters only when needed
+4. **Error handling:** Catch and display mode-related errors to users clearly
+
+## Migration Notes
+
+Existing tools continue to work:
+- Remote mode servers ignore the `contextDirectory` parameter (with error)
+- Local mode servers accept it as optional (backwards compatible)
+- The `protokoll_info` tool provides clear guidance to clients

package/docs/QUICK_REFERENCE_AI_ASSISTANTS.md

@@ -0,0 +1,81 @@
+# Quick Reference for AI Assistants
+
+## 🚨 CRITICAL: Read This First
+
+When working with Protokoll transcripts, you MUST use Protokoll MCP tools, NOT direct file editing tools.
+
+## ✅ DO Use These Tools
+
+| Operation | Correct Tool | URI/Resource |
+|-----------|-------------|--------------|
+| Read transcript | `protokoll_read_transcript` | `protokoll://transcript/{path}` |
+| List transcripts | `protokoll_list_transcripts` | `protokoll://transcripts/list` |
+| Edit content | `protokoll_provide_feedback` | - |
+| Change title | `protokoll_edit_transcript` (with `title` param) | - |
+| Update metadata | `protokoll_edit_transcript` (title/project/tags/status) | - |
+| Change date | `protokoll_change_transcript_date` | - |
+| Create transcript | `protokoll_create_note` | - |
+| Combine transcripts | `protokoll_combine_transcripts` | - |
+
+## ❌ DO NOT Use These Tools on Transcripts
+
+- ❌ Read
+- ❌ Write
+- ❌ StrReplace
+- ❌ Glob
+- ❌ Grep
+
+## 📖 Get Detailed Instructions
+
+Invoke the `how_to_use_protokoll` prompt for comprehensive guidance:
+
+```
+Prompt: how_to_use_protokoll
+Arguments: (none)
+```
+
+## 🔍 Common Scenarios
+
+### User asks to read a transcript
+```
+✅ Use: protokoll_read_transcript
+❌ Don't: Read tool on file path
+```
+
+### User asks to change title
+```
+✅ Use: protokoll_edit_transcript with title parameter
+❌ Don't: StrReplace on file
+```
+
+### User asks to fix names/terms
+```
+✅ Use: protokoll_provide_feedback with natural language corrections
+❌ Don't: StrReplace for each fix
+```
+
+### User asks to update metadata (project, tags, status)
+```
+✅ Use: protokoll_edit_transcript with appropriate parameters
+❌ Don't: Write to rewrite file
+```
+
+## 🎯 Why This Matters
+
+Using Protokoll tools ensures:
+- ✅ Proper validation and formatting
+- ✅ Metadata consistency
+- ✅ File naming conventions
+- ✅ Resource change notifications
+- ✅ Context integration
+
+## 🆘 If You're Unsure
+
+1. Invoke `how_to_use_protokoll` prompt
+2. Check tool descriptions with `tools/list`
+3. Ask the user for clarification
+4. When in doubt, use Protokoll tools!
+
+## 📚 More Information
+
+See `docs/CURSOR_INTEGRATION.md` for complete documentation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redaksjon/protokoll",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "Focused audio transcription with intelligent context integration",
   "main": "dist/index.js",
   "type": "module",
@@ -56,7 +56,9 @@
     "@google/generative-ai": "^0.24.1",
     "@kjerneverk/riotprompt": "^1.0.6",
     "@modelcontextprotocol/sdk": "^1.25.2",
-    "@redaksjon/context": "^0.0.6",
+    "@redaksjon/context": "^0.0.7",
+    "@redaksjon/protokoll-engine": "^0.1.3",
+    "@redaksjon/protokoll-format": "^0.1.1",
     "@types/fluent-ffmpeg": "^2.1.28",
     "@utilarium/cardigantime": "^0.0.24",
     "@utilarium/dreadcabinet": "^0.0.16",
@@ -70,7 +72,7 @@
     "js-yaml": "^4.1.1",
     "luxon": "^3.7.2",
     "moment-timezone": "^0.6.0",
-    "openai": "^6.9.0",
+    "openai": "^6.22.0",
     "winston": "^3.18.3",
     "zod": "^4.3.6"
   },

package/vite.config.ts

@@ -62,14 +62,19 @@ export default defineConfig({
                 '@modelcontextprotocol/sdk/server/stdio.js',
                 '@modelcontextprotocol/sdk/types.js',
                 '@kjerneverk/riotprompt',
+                '@redaksjon/context',
+                '@redaksjon/protokoll-format',
                 '@utilarium/cardigantime',
                 '@utilarium/dreadcabinet',
+                '@utilarium/overcontext',
                 '@types/fluent-ffmpeg',
+                // Native modules - must not be bundled
+                'better-sqlite3',
                 'dayjs',
                 'dotenv',
                 'fluent-ffmpeg',
                 'glob',
-                'gray-matter',
+                'html-to-text',
                 'js-yaml',
                 'luxon',
                 'moment-timezone',
@@ -83,10 +88,6 @@ export default defineConfig({
                 index: 'src/index.ts',
                 'mcp/server': 'src/mcp/server.ts',
                 'mcp/server-http': 'src/mcp/server-http.ts',
-                'scripts/fix-duplicate-delimiters': 'scripts/fix-duplicate-delimiters.ts',
-                'scripts/migrate-titles-to-frontmatter': 'scripts/migrate-titles-to-frontmatter.ts',
-                'scripts/migrate-transcripts-2025': 'scripts/migrate-transcripts-2025.ts',
-                'scripts/verify-migration-2025': 'scripts/verify-migration-2025.ts',
             },
             output: {
                 format: 'esm',

package/vitest.config.ts

@@ -32,32 +32,15 @@ export default defineConfig({
                 'node_modules/**/*', 
                 'tests/**/*', 
                 'src/**/*.md', 
-                'src/**/.DS_Store', 
-                // API-dependent modules excluded from coverage
-                'src/transcription/service.ts', 
-                'src/transcription/index.ts', 
-                'src/reasoning/client.ts', 
-                'src/reasoning/index.ts', 
-                'src/reasoning/strategy.ts', 
-                'src/agentic/executor.ts', 
-                'src/agentic/index.ts',
-                // Integration modules - tested via integration tests
-                'src/output/manager.ts',
-                'src/output/index.ts',
-                'src/reflection/collector.ts',
-                'src/reflection/reporter.ts',
-                'src/reflection/index.ts',
-                'src/pipeline/orchestrator.ts',
-                'src/pipeline/index.ts',
-                // Interactive CLI modules - require TTY interaction
-                'src/cli/context.ts',
-                'src/cli/index.ts',
+                'src/**/.DS_Store',
+                // Most logic moved to @redaksjon/protokoll-engine
+                // Only MCP server shell remains
             ],
             thresholds: {
-                lines: 60,
-                statements: 60,
-                branches: 50,
-                functions: 60,
+                lines: 35,
+                statements: 35,
+                branches: 30,
+                functions: 40,
             },
         },
     },

package/BUG_FIX_CONTEXT_DIRECTORY.md

@@ -1,147 +0,0 @@
-# Bug Fix: Context Directory Discovery Issue
-
-## Problem
-
-The Protokoll MCP tools were not finding context entities (projects, people, terms) even though they existed in the repository.
-
-### Symptoms
-
-- Context files exist in: `/path/to/repo/context/projects/*.yaml`
-- `.protokoll/config.yaml` exists but has no `contextDirectory` setting
-- MCP tools look for context in: `/path/to/repo/.protokoll/` (the config directory)
-- Result: `protokoll_list_projects` returns 0 projects even though 11 project YAML files exist
-
-### Expected Behavior
-
-The context discovery should default to looking in `./context/` relative to the repository root, NOT in `.protokoll/context/`.
-
-## Root Cause
-
-The context discovery logic in both `src/context/discovery.ts` and `src/overcontext/discovery.ts` was hardcoded to look for context in `.protokoll/context/`, but the actual context structure is:
-
-```
-repo/
-  .protokoll/
-    config.yaml          # Configuration file
-  context/               # Context entities (should be default)
-    projects/
-    people/
-    terms/
-    companies/
-```
-
-## Solution
-
-Changed the default context discovery logic to:
-
-1. **Priority 1**: Use explicit `contextDirectory` from `config.yaml` if specified
-2. **Priority 2**: Look for `./context/` at repository root (sibling to `.protokoll/`)
-3. **Priority 3**: Fall back to `.protokoll/context/` for backward compatibility
-
-### Configuration Option
-
-Added support for `contextDirectory` in `.protokoll/config.yaml`:
-
-```yaml
-# Use a custom context directory
-contextDirectory: ./my-custom-context
-
-# Or use an absolute path
-contextDirectory: /absolute/path/to/context
-```
-
-If not specified, defaults to `./context/` at the repository root.
-
-## Changes Made
-
-### Files Modified
-
-1. **src/context/discovery.ts**
-   - Added `resolveContextDirectory()` function to implement the new priority logic
-   - Updated `loadHierarchicalConfig()` to use the new resolution logic
-
-2. **src/overcontext/discovery.ts**
-   - Added `resolveContextDirectory()` function (same implementation)
-   - Updated `loadHierarchicalConfig()` to use the new resolution logic
-
-3. **src/overcontext/adapter.ts**
-   - Updated `load()` method to work with the new context directory resolution
-   - Fixed import to include `redaksjonPluralNames`
-
-### Tests Added
-
-1. **tests/context/discovery.test.ts**
-   - Added test: "should prefer ./context/ at repository root over .protokoll/context/"
-   - Added test: "should use explicit contextDirectory from config.yaml"
-   - Added test: "should handle absolute contextDirectory path in config.yaml"
-   - Added test: "should fall back to default when explicit contextDirectory does not exist"
-   - Added test: "should handle no context directory found"
-
-2. **tests/context/bug-context-directory.test.ts** (new file)
-   - Comprehensive end-to-end tests for the bug fix
-   - Tests all three priority levels
-   - Tests backward compatibility
-
-## Test Results
-
-All tests passing:
-- 19/19 tests in `tests/context/discovery.test.ts`
-- 4/4 tests in `tests/context/bug-context-directory.test.ts`
-- All existing tests continue to pass (no regressions)
-
-## Backward Compatibility
-
-The fix maintains full backward compatibility:
-- Existing repositories with context in `.protokoll/context/` will continue to work
-- No configuration changes required for existing setups
-- New repositories can use the simpler `./context/` structure
-
-## Migration Guide
-
-### For New Repositories
-
-Create context at the repository root:
-
-```bash
-mkdir -p context/{projects,people,terms,companies}
-```
-
-### For Existing Repositories
-
-Option 1: Move context to repository root (recommended):
-
-```bash
-mv .protokoll/context ./context
-```
-
-Option 2: Keep existing structure (no changes needed):
-
-```bash
-# Context remains in .protokoll/context/
-# Everything continues to work as before
-```
-
-Option 3: Use custom location:
-
-```yaml
-# .protokoll/config.yaml
-contextDirectory: ./my-custom-location
-```
-
-## Verification
-
-To verify the fix works:
-
-```bash
-# List projects (should now find entities in ./context/)
-protokoll list-projects
-
-# Or via MCP
-protokoll_list_projects()
-```
-
-## Related Issues
-
-- Fixes context discovery for MCP tools
-- Improves developer experience by supporting standard repository structure
-- Maintains backward compatibility with existing setups

package/MIGRATION_2025_SUMMARY.md

@@ -1,215 +0,0 @@
-# 2025 Transcript Migration Summary
-
-## Overview
-
-Successfully migrated all 233 transcript files in `/Users/tobrien/gitw/tobrien/activity/notes/2025` from the old format (with `## Metadata` and `## Entity References` sections in the body) to the new YAML frontmatter format.
-
-## Migration Date
-
-February 7, 2026
-
-## Results
-
-- **Total files found**: 233
-- **Successfully migrated**: 226
-- **Already in new format**: 7
-- **Errors**: 0
-- **Verification**: ✅ All 233 files verified as properly migrated
-
-## What Changed
-
-### Old Format
-
-```markdown
-# Title of Transcript
-
-## Metadata
-
-**Date**: December 22, 2025
-**Time**: 01:55 PM
-
-**Project**: ProjectName
-**Project ID**: `project-id`
-
-**Tags**: `tag1`, `tag2`
-
-### Routing
-
-**Destination**: ./activity/notes
-**Confidence**: 85.0%
-
----
-
-Transcript content here...
-
----
-
-## Entity References
-
-### Projects
-
-- `project-id`: Project Name
-
-### People
-
-- `person-id`: Person Name
-```
-
-### New Format
-
-```markdown
----
-title: Title of Transcript
-date: '2025-12-22T00:00:00.000Z'
-recordingTime: '01:55 PM'
-project: ProjectName
-projectId: project-id
-tags:
-  - tag1
-  - tag2
-routing:
-  destination: ./activity/notes
-  confidence: 0.85
-  signals: []
-  reasoning: ''
-status: reviewed
-entities:
-  people:
-    - id: person-id
-      name: Person Name
-      type: person
-  projects:
-    - id: project-id
-      name: Project Name
-      type: project
-  terms: []
-  companies: []
----
-Transcript content here...
-```
-
-## Key Improvements
-
-1. **All metadata in frontmatter**: Machine-readable YAML frontmatter instead of markdown sections
-2. **No duplicate titles**: Title only appears in frontmatter, not as H1 in body
-3. **Clean body content**: No more `## Metadata` or `## Entity References` sections
-4. **Consistent format**: All files now use the same structure
-5. **Lifecycle support**: Default `status: reviewed` and empty `history` and `tasks` arrays
-
-## Migration Process
-
-### 1. Enhanced Frontmatter Parser
-
-Updated `/Users/tobrien/gitw/redaksjon/protokoll/src/util/frontmatter.ts` to:
-- Parse old `## Metadata` sections and extract all fields
-- Parse old `## Entity References` sections
-- Strip legacy sections from body
-- Merge old and new metadata correctly
-
-### 2. Created Migration Script
-
-`/Users/tobrien/gitw/redaksjon/protokoll/scripts/migrate-transcripts-2025.ts`:
-- Scans all markdown files recursively
-- Detects files in old format
-- Converts to new format
-- Verifies conversion success
-- Provides detailed progress and summary
-
-### 3. Created Verification Script
-
-`/Users/tobrien/gitw/redaksjon/protokoll/scripts/verify-migration-2025.ts`:
-- Verifies all files are in new format
-- Checks for legacy sections
-- Ensures frontmatter is present
-- Validates no duplicate titles
-
-### 4. Added Tests
-
-`/Users/tobrien/gitw/redaksjon/protokoll/tests/scripts/migrate-transcripts-2025.test.ts`:
-- 19 comprehensive tests
-- Tests old format detection
-- Tests metadata extraction
-- Tests content cleaning
-- Tests round-trip conversion
-- Tests edge cases
-
-## NPM Scripts
-
-Added the following scripts to `package.json`:
-
-```json
-{
-  "migrate:2025": "npm run build && node dist/scripts/migrate-transcripts-2025.js",
-  "migrate:2025:dry-run": "npm run build && node dist/scripts/migrate-transcripts-2025.js --dry-run",
-  "migrate:2025:test": "npm run build && node dist/scripts/migrate-transcripts-2025.js --dry-run --limit 10 --verbose",
-  "migrate:2025:verify": "npm run build && node dist/scripts/verify-migration-2025.js"
-}
-```
-
-## Usage
-
-### Run Migration
-
-```bash
-npm run migrate:2025
-```
-
-### Dry Run (Preview Changes)
-
-```bash
-npm run migrate:2025:dry-run
-```
-
-### Test on First 10 Files
-
-```bash
-npm run migrate:2025:test
-```
-
-### Verify Migration
-
-```bash
-npm run migrate:2025:verify
-```
-
-## Verification Results
-
-All 233 files passed verification:
-- ✅ All files have YAML frontmatter
-- ✅ No files have `## Metadata` sections
-- ✅ No files have `## Entity References` sections
-- ✅ No duplicate titles in body
-- ✅ All metadata preserved correctly
-
-## Files Modified
-
-### Core Code
-
-- `src/util/frontmatter.ts` - Enhanced to parse old format
-- `src/util/metadata.ts` - Removed debug logging
-
-### Scripts
-
-- `scripts/migrate-transcripts-2025.ts` - Migration script
-- `scripts/verify-migration-2025.ts` - Verification script
-
-### Tests
-
-- `tests/scripts/migrate-transcripts-2025.test.ts` - Comprehensive test suite
-
-### Configuration
-
-- `package.json` - Added migration scripts
-- `vite.config.ts` - Added script builds
-
-## Notes
-
-- The migration is **idempotent** - running it multiple times is safe
-- Files already in the new format are skipped
-- The migration preserves all metadata and content
-- Body content is cleaned of legacy sections
-- Lifecycle defaults are applied (`status: reviewed`, empty `history` and `tasks`)
-
-## Next Steps
-
-The migration is complete and verified. All 233 transcript files are now in the new YAML frontmatter format and ready to use with the updated Protokoll tools.