inbox-processing-expert

# Inbox Processing Expert

Build security-hardened inbox automation with AI-powered metadata extraction following the Para Obsidian inbox processing framework.

## Quick Navigation

- **[Architecture Overview](#architecture-overview)** - Engine/interface separation, suggestion-based design
- **[Security Patterns](#security-patterns)** - P0 critical protections (TOCTOU, command injection, atomic writes)
- **[Core Concepts](#core-concepts)** - Suggestions, confidence scoring, idempotency
- **[Performance Characteristics](#performance-characteristics)** - Timing, concurrency limits, optimization
- **[Interactive CLI](#interactive-cli)** - Terminal UI, command parsing, user feedback
- **[Error Handling](#error-handling)** - 23-error taxonomy across 7 categories
- **[Testing Strategy](#testing-strategy)** - 246 tests, coverage patterns
- **[Common Questions](#common-questions)** - FAQ and troubleshooting
- **[Related Skills](#related-skills)** - Bun CLI, Bun FS Helpers

---

## Architecture Overview

### Engine/Interface Separation

**Core principle:** Engine logic is UI-agnostic. Same core powers CLI, web app, or API.

```typescript
// Engine returns suggestions - never mutates state directly
const engine = createInboxEngine({ vaultPath: "/path/to/vault" });

// 1. Scan inbox → generate suggestions
const suggestions = await engine.scan();

// 2. Edit suggestion with custom prompt
const updated = await engine.editWithPrompt("abc123", "put in Health area instead");

// 3. Execute approved suggestions
const results = await engine.execute(["abc123", "def456"]);

// 4. Generate markdown report
const report = engine.generateReport(suggestions);
```

**Benefits:**
- UI can be replaced without touching core logic
- Easy to test (engine is pure logic, no console.log or process.exit)
- Multiple interfaces (CLI, web, CI/CD) share same engine

### Suggestion-Based Architecture

**Never mutate state directly.** All operations return suggestions that require human approval.

```types