@redaksjon/protokoll 0.0.14 → 0.1.0

package/docs/entity-metadata.md

@@ -0,0 +1,416 @@
+# Entity Metadata in Transcripts
+
+## Overview
+
+Every transcript generated by Protokoll includes structured entity metadata in a footer section. This machine-readable metadata records all entities (people, projects, terms, companies) that were referenced or used during transcript processing, enabling powerful querying and indexing capabilities.
+
+## Format
+
+Entity metadata appears at the bottom of each transcript in this format:
+
+```markdown
+---
+
+## Entity References
+
+<!-- Machine-readable entity metadata for indexing and querying -->
+
+### People
+
+- `priya-sharma`: Priya Sharma
+- `john-smith`: John Smith
+
+### Projects
+
+- `project-alpha`: Project Alpha
+- `client-beta`: Client Beta
+
+### Terms
+
+- `kubernetes`: Kubernetes
+- `docker`: Docker
+- `graphql`: GraphQL
+
+### Companies
+
+- `acme-corp`: Acme Corp
+```
+
+## How Entities Are Tracked
+
+Entities are automatically tracked during the transcription process whenever:
+
+1. **lookup_person tool** finds a person in your context
+2. **lookup_project tool** matches a project
+3. **verify_spelling tool** corrects a term
+4. **route_note tool** routes to a project
+
+Every successful entity lookup adds that entity to the transcript's metadata.
+
+## Example Transcript
+
+Here's a complete example showing how entity metadata appears in context:
+
+```markdown
+# Meeting with Priya about Kubernetes Deployment
+
+## Metadata
+
+**Date**: January 18, 2026
+**Time**: 02:30 PM
+
+**Project**: Project Alpha
+**Project ID**: `project-alpha`
+
+### Routing
+
+**Destination**: ~/work/project-alpha/notes
+**Confidence**: 95.0%
+
+**Tags**: `kubernetes`, `deployment`, `infrastructure`
+
+**Duration**: 15m 30s
+
+---
+
+## Content
+
+We discussed the Kubernetes deployment strategy for Project Alpha with Priya Sharma. 
+Key points:
+
+- Use Docker containers for microservices
+- Deploy to AWS EKS cluster
+- Set up CI/CD with GitHub Actions
+
+Priya will follow up with the infrastructure team at Acme Corp next week.
+
+---
+
+## Entity References
+
+<!-- Machine-readable entity metadata for indexing and querying -->
+
+### People
+
+- `priya-sharma`: Priya Sharma
+
+### Projects
+
+- `project-alpha`: Project Alpha
+
+### Terms
+
+- `kubernetes`: Kubernetes
+- `docker`: Docker
+- `aws`: AWS
+- `eks`: EKS
+
+### Companies
+
+- `acme-corp`: Acme Corp
+```
+
+## Benefits
+
+### 1. Queryable Knowledge Base
+
+Find all transcripts that mention a specific entity:
+
+```bash
+# All transcripts mentioning Priya
+protokoll transcript list ~/notes --search "priya-sharma"
+
+# All Project Alpha transcripts
+protokoll transcript list ~/notes --search "project-alpha"
+
+# All transcripts discussing Kubernetes
+protokoll transcript list ~/notes --search "kubernetes"
+```
+
+### 2. Knowledge Graphs
+
+Build relationships between entities:
+
+```typescript
+// Parse all transcripts
+const transcripts = await listTranscripts({ directory: '~/notes' });
+
+// Build person-to-project mapping
+const personProjects = new Map();
+for (const t of transcripts.transcripts) {
+  for (const person of t.entities?.people || []) {
+    for (const project of t.entities?.projects || []) {
+      // person.id worked on project.id
+      addRelationship(personProjects, person.id, project.id);
+    }
+  }
+}
+```
+
+### 3. Context Discovery
+
+See which entities appear most frequently in your transcripts:
+
+```typescript
+// Count entity references
+const entityCounts = countEntities(transcripts);
+// Result: { 'kubernetes': 24, 'docker': 18, 'priya-sharma': 12, ... }
+```
+
+### 4. Automated Indexing
+
+Build search indexes for fast lookup:
+
+```typescript
+// Create inverted index
+const index = {
+  'priya-sharma': ['transcript1.md', 'transcript5.md', 'transcript12.md'],
+  'kubernetes': ['transcript2.md', 'transcript5.md', 'transcript8.md'],
+  ...
+};
+```
+
+### 5. Cross-Referencing
+
+Find related transcripts based on shared entities:
+
+```typescript
+// Find transcripts that share entities with a given transcript
+const related = findRelatedTranscripts(transcript1, allTranscripts);
+// Returns transcripts mentioning same people/projects/terms
+```
+
+## Programmatic Access
+
+### Reading Entity Metadata
+
+```typescript
+import { parseEntityMetadata } from '@/util/metadata';
+import { readFile } from 'fs/promises';
+
+const content = await readFile('transcript.md', 'utf-8');
+const entities = parseEntityMetadata(content);
+
+if (entities?.people) {
+  console.log('People mentioned:', entities.people.map(p => p.name));
+}
+```
+
+### Querying Transcripts
+
+```typescript
+import { listTranscripts } from '@/cli/transcript';
+
+// Find all transcripts about a person
+const results = await listTranscripts({
+  directory: '~/notes',
+  search: 'priya-sharma',
+  sortBy: 'date',
+  limit: 100
+});
+
+// Filter by entity
+const priyaTranscripts = results.transcripts.filter(t => 
+  t.entities?.people?.some(p => p.id === 'priya-sharma')
+);
+```
+
+### Building Custom Tools
+
+```typescript
+// Example: Find collaboration patterns
+function findCollaborations(transcripts) {
+  const collaborations = new Map();
+  
+  for (const t of transcripts) {
+    const people = t.entities?.people || [];
+    if (people.length < 2) continue;
+    
+    // Record all pairs of people appearing together
+    for (let i = 0; i < people.length; i++) {
+      for (let j = i + 1; j < people.length; j++) {
+        const key = [people[i].id, people[j].id].sort().join(':');
+        collaborations.set(key, (collaborations.get(key) || 0) + 1);
+      }
+    }
+  }
+  
+  return collaborations;
+}
+```
+
+## Entity Types
+
+### People
+
+Referenced when:
+- lookup_person tool finds them in context
+- Name correction happens
+- Interactive wizard creates new person
+
+**Structure:**
+```typescript
+{
+  id: string;    // e.g., "priya-sharma"
+  name: string;  // e.g., "Priya Sharma"
+  type: 'person';
+}
+```
+
+### Projects
+
+Referenced when:
+- lookup_project tool matches a project
+- route_note tool routes to a project
+- Transcript is explicitly assigned to a project
+
+**Structure:**
+```typescript
+{
+  id: string;    // e.g., "project-alpha"
+  name: string;  // e.g., "Project Alpha"
+  type: 'project';
+}
+```
+
+### Terms
+
+Referenced when:
+- verify_spelling tool corrects technical term
+- Term is looked up in context
+- Interactive wizard creates new term
+
+**Structure:**
+```typescript
+{
+  id: string;    // e.g., "kubernetes"
+  name: string;  // e.g., "Kubernetes"
+  type: 'term';
+}
+```
+
+### Companies
+
+Referenced when:
+- Company is mentioned and found in context
+- Person's company is looked up
+- Interactive wizard creates new company
+
+**Structure:**
+```typescript
+{
+  id: string;    // e.g., "acme-corp"
+  name: string;  // e.g., "Acme Corp"
+  type: 'company';
+}
+```
+
+## Advanced Use Cases
+
+### Building a Personal CRM
+
+Track all interactions with people:
+
+```bash
+# Find all conversations with Priya
+protokoll transcript list ~/notes --search "priya-sharma"
+
+# Export for analysis
+protokoll transcript list ~/notes \
+  --search "priya-sharma" \
+  --limit 1000 > priya-transcripts.json
+```
+
+### Project Knowledge Base
+
+Collect all knowledge about a project:
+
+```bash
+# All Project Alpha transcripts
+protokoll transcript list ~/notes --search "project-alpha"
+
+# Combine them into project documentation
+protokoll action --combine "$(protokoll transcript list ~/notes --search 'project-alpha' --limit 100 | grep '.md' | awk '{print $NF}')"
+```
+
+### Technology Research
+
+Track discussions about specific technologies:
+
+```bash
+# All Kubernetes discussions
+protokoll transcript list ~/notes --search "kubernetes"
+
+# Time-based analysis
+protokoll transcript list ~/notes --search "kubernetes" --start-date 2026-01-01
+protokoll transcript list ~/notes --search "kubernetes" --start-date 2025-01-01 --end-date 2025-12-31
+```
+
+### Meeting Participant Analysis
+
+See who you've met with most:
+
+```bash
+# Export all transcripts with entity data
+protokoll transcript list ~/notes --limit 10000 > all-transcripts.json
+
+# Analyze in your favorite tool
+cat all-transcripts.json | jq '.transcripts[].entities.people[].name' | sort | uniq -c | sort -rn
+```
+
+## Migration Notes
+
+### Existing Transcripts
+
+Transcripts created before this feature won't have entity metadata. To add it:
+
+1. **Reprocess**: Re-run through Protokoll (will regenerate with metadata)
+2. **Use feedback**: `protokoll feedback` can add entities to existing transcripts
+3. **Manual addition**: Add the section manually following the format above
+
+### Backward Compatibility
+
+The entity metadata section is optional and won't break:
+- Existing tools that read transcripts
+- Markdown renderers
+- Search tools
+- Version control systems
+
+It's just additional structured data at the end.
+
+## Best Practices
+
+1. **Regular Reprocessing**: Periodically reprocess old transcripts to add entity metadata
+2. **Use Search**: Leverage entity IDs (e.g., `priya-sharma`) for precise searches
+3. **Export for Analysis**: Use `--limit 10000` to export large datasets
+4. **Build Indexes**: Create custom indexes for frequent queries
+5. **Cross-Reference**: Use entity data to find related transcripts
+
+## Technical Details
+
+### Storage Format
+
+Entity metadata is stored as Markdown at the end of each transcript file:
+- **Human-readable**: You can read and edit it
+- **Machine-parseable**: Structured format for programmatic access
+- **Version-controllable**: Works with Git
+- **Future-proof**: Plain text, no proprietary format
+
+### Parsing Implementation
+
+The `parseEntityMetadata()` function:
+1. Finds the "## Entity References" section
+2. Extracts each entity type section (People, Projects, Terms, Companies)
+3. Parses list items in format: `` - `entity-id`: Entity Name ``
+4. Returns structured object or undefined if no entities
+
+Available in: `@/util/metadata`
+
+## Future Enhancements
+
+Planned improvements:
+- **Entity-specific list filters**: `--entity-type person --entity-id priya-sharma`
+- **Relationship queries**: "Find transcripts where Person X and Project Y appear together"
+- **Timeline views**: See entity mentions over time
+- **Export to database**: SQLite/PostgreSQL with entity tables and relationships
+- **Graph visualization**: Visual knowledge graph from entity relationships

package/docs/examples.md

@@ -146,6 +146,27 @@ protokoll --input-directory ~/backlog \
 protokoll --input-directory ~/backlog --batch
 ```
 
+## Scenario 20: Non-Interactive Project Creation
+
+Add projects automatically without confirming AI suggestions.
+
+```bash
+# Trust AI suggestions completely
+protokoll project add --name "FjellGrunn" --yes
+
+# With a source URL
+protokoll project add https://github.com/myorg/myproject --name "My Project" --yes
+
+# With local README
+protokoll project add /path/to/README.md --name "Documentation" --yes
+```
+
+Result:
+- AI generates phonetic variants automatically
+- Trigger phrases generated without prompts
+- Topics and description extracted (if source provided)
+- Project saved immediately with all AI suggestions
+
 ## Scenario 8: Quality Review
 
 Review transcription quality after processing.