reprompt-cli 1.2.0__tar.gz → 1.4.0__tar.gz

{reprompt_cli-1.2.0 → reprompt_cli-1.4.0}/CLAUDE.md

@@ -18,7 +18,7 @@ uv run python -m build                     # build wheel
 
 ```
 src/reprompt/
-├── cli.py              # Typer CLI (scan, import, report, search, library, recommend, demo, status, purge, install-hook, install-extension, extension-status, score, compare, insights, digest, style, use, privacy, compress) + plugin loading
+├── cli.py              # Typer CLI (scan, import, report, search, library, recommend, demo, status, purge, install-hook, install-extension, extension-status, score, compare, insights, digest, style, template [save|list|use], privacy, compress, distill) + plugin loading
 ├── config.py           # pydantic-settings, env vars (REPROMPT_ prefix) + TOML config
 ├── demo.py             # Built-in demo data generator (no network required)
 ├── core/
@@ -40,9 +40,12 @@ src/reprompt/
 │   ├── persona.py       # 6 prompt personas (Architect/Debugger/Explorer/Novelist/Sniper/Teacher)
 │   ├── wrapped.py       # WrappedReport dataclass + build_wrapped(db) aggregation
 │   ├── privacy.py       # Privacy metadata registry + exposure summary per adapter
-│   └── compress.py      # 4-layer prompt compression (char norm + phrase simplify + filler delete + structure cleanup)
+│   ├── compress.py      # 4-layer prompt compression (char norm + phrase simplify + filler delete + structure cleanup)
+│   ├── suggestions.py   # Command journey suggestions ("→ Try:" hints for 5 core commands)
+│   ├── conversation.py  # ConversationTurn, Conversation, DistillResult dataclasses
+│   └── distill.py       # 6-signal importance scoring + filtering + summary generation
 ├── adapters/
-│   ├── base.py         # BaseAdapter ABC
+│   ├── base.py         # BaseAdapter ABC + parse_conversation() default
 │   ├── claude_code.py  # Claude Code JSONL parser
 │   ├── openclaw.py     # OpenClaw JSON parser (supports ~/.openclaw/ + legacy ~/.opencode/)
 │   ├── cursor.py       # Cursor IDE .vscdb parser (cursorDiskKV + legacy ItemTable)
@@ -83,7 +86,8 @@ src/reprompt/
     ├── markdown.py         # Markdown export
     ├── wrapped_terminal.py # Rich Prompt Wrapped report rendering
     ├── wrapped_html.py     # Self-contained HTML share card (dark theme)
-    └── compress_terminal.py # Rich output for compress command
+    ├── compress_terminal.py # Rich output for compress command
+    └── distill_terminal.py  # Rich output for distill command
 ```
 
 ## Data Flow
@@ -120,7 +124,7 @@ reprompt-extension (private)   ← Browser extension: Chrome/Firefox prompt capt
 - Pattern upsert (not clear+re-insert) for stable IDs
 - Prompts starting with `<` are filtered (system-injected XML)
 - Config: env vars (REPROMPT_ prefix) > TOML (~/.config/reprompt/config.toml) > defaults
-- Tests: pytest, 1153 tests, 95% coverage target
+- Tests: pytest, 1295 tests, 95% coverage target
 
 ## Prompt Science Engine
 
@@ -144,3 +148,15 @@ Rule-based prompt optimization (added v1.2.0):
 - `compressibility` field in PromptDNA, visible in insights + HTML dashboard
 
 Sources: LLMLingua (Microsoft), CompactPrompt, TSC, stopwords-iso/zh, Prompt Report 2406.06608.
+
+## Conversation Distillation Engine
+
+Conversation-level analysis (added v1.3.0):
+- `reprompt distill` — extract important turns from AI conversations
+  - 6-signal importance scoring: position, length, tool_trigger, error_recovery, semantic_shift, uniqueness
+  - Hybrid data source: raw session files (full conversation) + DB enrichment
+  - `parse_conversation()` on adapters returns both user and assistant turns
+  - Claude Code and ChatGPT adapters have full implementations; others fall back to user-only
+- `--last N` for recent sessions, `--summary` for compressed output, `--json`, `--copy`
+- `--threshold` to control importance cutoff (default 0.3)
+- Pro plugin interface: `reprompt.distill_backends` entry point for LLM summarization (future)

{reprompt_cli-1.2.0 → reprompt_cli-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reprompt-cli
-Version: 1.2.0
+Version: 1.4.0
 Summary: Discover, analyze, and optimize your prompts from AI coding sessions
 Project-URL: Homepage, https://github.com/reprompt-dev/reprompt
 Project-URL: Repository, https://github.com/reprompt-dev/reprompt

reprompt_cli-1.4.0/docs/roadmap.md

@@ -0,0 +1,95 @@
+# reprompt Roadmap
+
+> Last updated: 2026-03-24 · Current version: v1.4.0
+
+## Vision
+
+reprompt is the **prompt intelligence** tool for AI sessions — distill your conversations, compress your prompts, score them against research, and track your progress. Zero-config, privacy-first, CLI-first.
+
+**Category definition:** reprompt analyzes *human inputs* (how you prompt), not *LLM outputs* (how models respond). Every other tool in the eval/observability space — Promptfoo, Braintrust, DeepEval, Langfuse — answers "did my AI system answer correctly?" reprompt answers "am I asking well?" This is an unoccupied category.
+
+---
+
+## Current State (v1.4.0) — Production Stable
+
+### Adapters (8)
+Claude Code · OpenClaw · Cursor IDE · Aider · Gemini CLI · Cline · ChatGPT · Claude.ai
+
+### Commands (23 visible, 5 deprecated)
+`scan` · `import` · `report` · `library` · `trends` · `recommend` · `template [save|list|use]` · `lint` · `search` · `demo` · `status` · `purge` · `install-hook` · `install-extension` · `extension-status` · `score` · `compare` · `insights` · `digest` · `style` · `wrapped` · `telemetry` · `mcp-serve` · `compress` · `distill` · `privacy`
+
+### Integrations
+- MCP server (`reprompt mcp-serve`) for IDE integration
+- GitHub Action (`action.yml`) for CI prompt quality checks
+- HTML dashboard (`reprompt report --html`)
+- Browser extension (Chrome/Firefox) via Native Messaging bridge
+- JSON output on all commands for pipeline integration
+
+### Key Features by Version
+
+| Version | Feature | Description |
+|---------|---------|-------------|
+| v1.0.0 | Core platform | Scoring, dedup, report, trends, digest, style, effectiveness, templates, MCP, HTML dashboard |
+| v1.1.0 | Privacy exposure | `reprompt privacy` — where your prompts went, training risk analysis |
+| v1.2.0 | Prompt compression | `reprompt compress` — 4-layer rule-based compression (43 zh + 51 en rules) |
+| v1.3.0 | Conversation distillation | `reprompt distill` — 6-signal importance scoring for conversation turns |
+| v1.3.1 | UX polish | Actionable suggestions on 5 commands, `--source` filter on all data commands |
+| v1.4.0 | Context recovery + consolidation | `distill --export` context document, signal transparency, command consolidation (27→23) |
+
+### Quality
+- 1295 tests, ≥90% coverage
+- Strict mypy, ruff lint/format
+- CI: coverage gate + pre-publish test step
+- Stable public API (`score_prompt`, `compare_prompts`, `extract_features`)
+
+---
+
+## v1.4 — Context Recovery + Command Consolidation
+
+| Priority | Item | Rationale |
+|----------|------|-----------|
+| P1 | `distill --export` context recovery | **DONE** — community signal: resume sessions after compaction/timeout |
+| P2 | Command consolidation: `save`/`templates`/`use` → `template [save\|list\|use]` | **DONE** — 3 commands doing 1 thing = cognitive overload |
+| P2 | Command consolidation: `effectiveness`/`merge-view` → `insights` sub-insights | **DONE** — concepts unclear to users |
+| P3 | `style` shows change trends | "specificity +12% this week" drives revisits |
+| P4 | `distill --show-weights` / `--weights` signal transparency | Community request for weight visibility |
+| P5 | `compare --best-worst` auto-pick | Auto-pick best/worst from DB |
+| P5 | `--copy` as standard option on remaining commands | Consistency |
+
+**Status: 27 → 23 visible commands. P1+P2 shipped. Context recovery + consolidation done.**
+
+---
+
+## v1.5+ — Future Work
+
+| Feature | Description |
+|---------|-------------|
+| Sensitive content detection | Privacy narrative; PII in prompts |
+| Agent workflow analysis | Multi-step agent session patterns |
+| `.reprompt.yml` configurable lint | Team/Pro direction |
+| `reprompt suggest` (Ollama rewrite) | LLM-powered prompt improvement |
+| Homebrew formula | `brew install reprompt` |
+| More adapters | Perplexity, Mistral, Grok, Gemini Takeout |
+| Windows Native Messaging | Extension support on Windows |
+
+---
+
+## Architecture Principles
+
+1. **Zero-config first** — Every feature works without LLM by default
+2. **Privacy by design** — All data stays local; extension has zero server
+3. **Adapter pattern** — New AI tools supported by adding ~50 lines
+4. **Input not output** — We analyze human prompts (inputs); LLM eval tools analyze model responses (outputs)
+5. **CLI first, GUI second** — Terminal is primary, HTML dashboard is secondary
+6. **Composable** — Every command supports JSON output for piping
+
+---
+
+## How to Contribute
+
+- **New adapter** (~50 lines) — see `src/reprompt/adapters/base.py`
+- **New lint rules** — see `src/reprompt/core/lint.py`
+- **Better categorization** — improve keyword rules in `core/library.py`
+- **Browser extension** — see `reprompt-extension` repo
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for details.

reprompt_cli-1.4.0/docs/superpowers/specs/2026-03-23-distill-design.md

@@ -0,0 +1,375 @@
+# `reprompt distill` — Conversation Distillation Design
+
+## Goal
+
+Extract the most important turns from an AI coding conversation, filtering noise and surfacing key decisions. Rule-based (Layer 1, open-source), with a plugin interface for future LLM-powered summarization (Layer 2, Pro).
+
+## Problem Statement
+
+AI power users run 20–50+ turn conversations daily. When context windows fill up, they need to know: "What actually mattered in this session?" No existing tool provides conversation-level distillation locally, without sending data to a server.
+
+**User stories:**
+- "I had a 40-turn Claude Code session. What were the key decisions?"
+- "Copy the important parts of my last conversation so I can paste them into a new session."
+- "Show me which turns triggered the most work."
+
+## Architecture
+
+```
+Raw session file → parse_conversation() → list[ConversationTurn]
+                                              ↓
+                              DB enrichment (scores, dedup status)
+                                              ↓
+                              Turn importance scoring (6 signals)
+                                              ↓
+                              Filtering (threshold ≥ 0.3)
+                                              ↓
+                              Turn pairing (user + assistant pairs)
+                                              ↓
+                              Output (filtered / summary / json / clipboard)
+```
+
+### Data Source: Hybrid Approach
+
+- **Raw session files** provide full conversation (user + assistant turns, tool_use, timestamps).
+- **DB tables** provide enrichment (prompt scores from `prompt_features`, dedup status from `prompts`, session metadata from `session_meta`).
+- Session files are located via the `processed_sessions` table which maps `file_path → source`.
+
+This avoids storing conversation data twice while getting the full picture.
+
+## Data Model
+
+### ConversationTurn
+
+```python
+@dataclass
+class ConversationTurn:
+    role: str              # "user" | "assistant"
+    text: str              # The actual content
+    timestamp: str         # ISO timestamp
+    turn_index: int        # 0-based position in conversation
+
+    # Assistant-specific (0/False for user turns)
+    tool_calls: int = 0    # Number of tool_use blocks in this turn
+    has_error: bool = False # Whether turn contains error/failure
+    tool_use_paths: list[str] = field(default_factory=list)  # File paths from tool_use blocks
+
+    # Enrichment (populated by distill engine, not adapter)
+    score: float | None = None         # Display-only, from prompt_features (see Enrichment)
+    is_duplicate: bool = False          # Cross-referenced with dedup
+    importance: float = 0.0            # Computed by distill scoring (6 signals only)
+```
+
+**Note on `score` field:** This is **display-only enrichment data** — it does NOT feed into the 6-signal importance calculation. It is populated opportunistically from `prompt_features` (see Enrichment section) and shown in JSON output for reference. The `importance` field is the sole ranking signal.
+
+### Conversation
+
+```python
+@dataclass
+class Conversation:
+    session_id: str
+    source: str
+    project: str | None
+    turns: list[ConversationTurn]
+    start_time: str | None = None
+    end_time: str | None = None
+    duration_seconds: int | None = None  # Computed from timestamps (see Duration)
+```
+
+### DistillResult
+
+```python
+@dataclass
+class DistillResult:
+    conversation: Conversation       # Original full conversation
+    filtered_turns: list[ConversationTurn]  # Turns above threshold
+    threshold: float                 # Importance threshold used
+    summary: str | None = None       # Generated if --summary
+    files_changed: list[str] = field(default_factory=list)  # Extracted from tool_use
+    stats: DistillStats = field(default_factory=DistillStats)
+
+@dataclass
+class DistillStats:
+    total_turns: int = 0
+    kept_turns: int = 0
+    retention_ratio: float = 0.0     # kept/total (0.26 = kept 26% of turns)
+    total_duration_seconds: int = 0
+```
+
+## Turn Importance Scoring
+
+Six weighted signals, all rule-based (no LLM):
+
+| Signal | Weight | Computation | Rationale |
+|--------|--------|-------------|-----------|
+| **Position** | 0.15 | First turn = 1.0, last turn = 0.8, others = 0.3 + 0.2 * recency | First turn sets context, last is conclusion |
+| **Length** | 0.15 | `min(char_count / median_length, 1.0)` | Longer turns tend to be more substantive |
+| **Tool trigger** | 0.20 | `min(tool_calls / 5, 1.0)` on the assistant turn following this user turn | Turns causing lots of tool use = key decisions |
+| **Error recovery** | 0.15 | 1.0 if previous assistant turn has `has_error=True` | User correcting course = high-value context |
+| **Semantic shift** | 0.20 | TF-IDF cosine distance from previous user turn; 0.5 (neutral) if first turn | Topic changes mark decision boundaries |
+| **Uniqueness** | 0.15 | 1.0 - (similarity to most similar earlier turn via TF-IDF) | Novel instructions > repetitive ones |
+
+**Scoring rules:**
+- User turns: scored by all 6 signals → `importance = weighted sum`
+- Assistant turns: derived score = average of adjacent user turns' importance
+- Minimum threshold: 0.3 (configurable via `--threshold`)
+
+### Tool Trigger Pairing
+
+The tool_trigger signal requires pairing user turns with their assistant responses. For user turn at index `i`, the tool_calls come from the assistant turn at index `i+1` (if it exists and role == "assistant").
+
+### Semantic Shift Computation
+
+Uses scikit-learn `TfidfVectorizer` (already a dependency) fitted on all user turn texts in the conversation. Cosine distance between consecutive user turns. First user turn gets semantic_shift = 0.5 (neutral).
+
+## DB Enrichment
+
+Enrichment is **opportunistic** — it enhances output when data exists, but distill works fully without it.
+
+**Score enrichment:** For each user turn, compute `hashlib.sha256(text.strip().encode()).hexdigest()` (same algorithm as `Prompt.__post_init__`). Look up the hash in `prompt_features`. If found, populate `ConversationTurn.score` with `overall_score`. If not found (user never ran `reprompt score` on this text), leave as `None`. This field is display-only and does NOT affect the 6-signal importance calculation.
+
+**Dedup enrichment:** Same hash lookup in `prompts` table. If `duplicate_of IS NOT NULL`, set `is_duplicate = True`. This is informational — the uniqueness signal in scoring uses TF-IDF similarity within the conversation, not the DB dedup status.
+
+### Duration Computation
+
+`Conversation.duration_seconds` is derived from the first and last timestamps in `turns`:
+```python
+from datetime import datetime
+start = datetime.fromisoformat(turns[0].timestamp.replace("Z", "+00:00"))
+end = datetime.fromisoformat(turns[-1].timestamp.replace("Z", "+00:00"))
+duration_seconds = int((end - start).total_seconds())
+```
+This follows the same `fromisoformat` + Z-replacement pattern used in `claude_code.py:parse_session_meta()`.
+
+## Turn Pairing in Output
+
+Filtered output shows **user-assistant pairs**, not isolated turns. When a user turn passes the threshold, its corresponding assistant response is always included (preserves conversation coherence). Assistant-only turns below threshold are dropped only if their adjacent user turns are also below threshold.
+
+## Adapter Integration
+
+### Base class (additive, non-breaking)
+
+```python
+# adapters/base.py
+class BaseAdapter(ABC):
+    @abstractmethod
+    def parse_session(self, path: Path) -> list[Prompt]: ...
+
+    def parse_conversation(self, path: Path) -> list[ConversationTurn]:
+        """Parse full conversation with both roles.
+        Default: user-only turns from parse_session()."""
+        prompts = self.parse_session(path)
+        return [
+            ConversationTurn(
+                role="user", text=p.text, timestamp=p.timestamp, turn_index=i
+            )
+            for i, p in enumerate(prompts)
+        ]
+```
+
+### v1.3.0 adapters with full parse_conversation()
+
+| Adapter | Approach |
+|---------|----------|
+| **claude-code** | Iterate JSONL entries. `type=user` + `role=user` → user turn. `type=assistant` → assistant turn. Count `tool_use` content blocks. Detect errors from `is_error` field or error-related content. |
+| **chatgpt-export** | Walk `mapping` tree in order for a single conversation (selected by `conv_id`). `author.role=user` → user turn. `author.role=assistant` → assistant turn. No tool_calls data (set to 0). Accepts optional `conv_id` parameter; if None, parses first conversation in file. |
+
+### Future adapters (v1.3.1+)
+
+claude-chat, aider, gemini, openclaw, cline — implement `parse_conversation()` as data becomes available. They fall back to user-only via base class until then.
+
+## Session Resolution
+
+How `distill` finds which session file to parse:
+
+| Input | Resolution |
+|-------|-----------|
+| `--last N` | Query `processed_sessions` ordered by `processed_at DESC`, take first N. Return list of `(file_path, source)`. |
+| `<session_id>` | Query `prompts` for matching `session_id`, get `source`. Reconstruct file path: `adapter.default_session_path / session_id + ext` (e.g. `.jsonl` for claude-code). Verify file exists. If not, fall back to `processed_sessions WHERE file_path LIKE '%' || session_id || '%'`. |
+| `--source X` | Filter `processed_sessions` by source, then apply `--last` logic. |
+
+**Edge case — file deleted:** If session file no longer exists on disk, distill falls back to DB-only mode: query `prompts WHERE session_id = ?` for user turns (no assistant turns, no tool_use data). Warn user: "Session file not found, showing user turns only."
+
+### ChatGPT Session Resolution
+
+ChatGPT exports contain multiple conversations in one `conversations.json` file. The `session_id` for ChatGPT prompts is a hash-based string (e.g. `chatgpt-20260323T100000-ab1c2d3e`). When `distill` receives a ChatGPT session_id:
+
+1. Look up `source = "chatgpt-export"` from `prompts` table
+2. Find the `conversations.json` file path from `processed_sessions`
+3. Parse the file, iterate conversation objects, match by `conv_id` (computed same way as in `chatgpt.py:_make_session_id()`)
+4. Call `parse_conversation()` on that single conversation object
+
+The ChatGPT `parse_conversation()` accepts an optional `conv_id` parameter to select a specific conversation from the file.
+
+## Output Modes
+
+### Tier 1 — Filtered conversation (default)
+
+```
+╭─ Distill: session abc123 (claude-code) ─╮
+│ Project: reprompt | 45min | 47 → 12 turns │
+╰──────────────────────────────────────────╯
+
+★★★ [T1] User:
+  根据我们的设计文档继续我们的任务
+  Assistant: I'll read the spec and continue with Task 5...
+
+★★☆ [T8] User:
+  不对，用approach B，parse_session不要改
+  Assistant: You're right, creating separate parse_conversation()...
+
+★★★ [T15] User:
+  测试通过了，commit吧
+  Assistant: Committed: feat: add conversation parser
+```
+
+Stars: ★★★ = importance ≥ 0.7, ★★☆ = ≥ 0.5, ★☆☆ = ≥ 0.3
+
+Assistant text truncated to first 80 chars in terminal mode (full in JSON).
+
+### Tier 2 — Summary (`--summary`)
+
+```
+╭─ Session Summary: abc123 ─╮
+
+This session implemented the conversation parser for the distill feature.
+
+Key decisions:
+  • Created separate parse_conversation() instead of modifying parse_session()
+  • Used weighted scoring with 6 signals for turn importance
+  • Threshold set at 0.3 for filtering
+
+Files changed: core/distill.py, adapters/base.py, tests/test_distill.py
+
+47 turns → 12 key turns | 45min | claude-code
+╰───────────────────────────╯
+```
+
+Summary is rule-based:
+1. **Description**: First user turn text (compressed via `compress_text()`) + project name
+2. **Key decisions**: Top 5 user turns by importance, each compressed
+3. **Files changed**: Flattened from `tool_use_paths` across all assistant turns (deduplicated, sorted). Only Edit/Write paths included (Read paths are noise).
+4. **Stats**: Turn counts + duration + source
+
+### Tier 3 — JSON (`--json`)
+
+```json
+{
+  "session_id": "abc123",
+  "source": "claude-code",
+  "project": "reprompt",
+  "duration_seconds": 2700,
+  "total_turns": 47,
+  "kept_turns": 12,
+  "retention_ratio": 0.26,
+  "threshold": 0.3,
+  "summary": "...",
+  "files_changed": ["core/distill.py", "adapters/base.py"],
+  "turns": [
+    {
+      "turn_index": 0,
+      "role": "user",
+      "text": "...",
+      "timestamp": "2026-03-23T10:00:00Z",
+      "importance": 0.85,
+      "tool_calls": 0
+    }
+  ]
+}
+```
+
+## CLI Interface
+
+```
+reprompt distill                           # Default: most recent session
+reprompt distill --last 3                  # Last 3 sessions
+reprompt distill --summary                 # Key decisions only
+reprompt distill --copy                    # Filtered → clipboard
+reprompt distill --json                    # Machine-readable
+reprompt distill abc123                    # By session ID
+reprompt distill --source chatgpt-export   # Filter by adapter
+reprompt distill --threshold 0.5           # Stricter filtering
+reprompt distill --last 3 --copy           # Last 3, concatenated to clipboard
+```
+
+### Flag Details
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--last` | `int` | 1 | Most recent N sessions. Always requires explicit value. |
+| `--source` | `str` | None | Filter by adapter name |
+| `--summary` | `bool` | False | Tier 2 compressed output |
+| `--json` | `bool` | False | JSON output |
+| `--copy` | `bool` | False | Copy to clipboard |
+| `--threshold` | `float` | 0.3 | Importance cutoff (0.0–1.0) |
+| `session_id` | `str` (positional, optional) | None | Specific session |
+
+`session_id` and `--last` are mutually exclusive. If neither is provided, default behavior is `--last 1` (most recent session).
+
+**Multi-session behavior (`--last N`):** Each session is distilled independently. Terminal output separates sessions with a horizontal rule. `--copy` concatenates all sessions (separated by `---`). `--json` outputs a JSON array of DistillResult objects.
+
+## File Structure
+
+| File | Responsibility |
+|------|----------------|
+| `core/conversation.py` | `ConversationTurn`, `Conversation`, `DistillResult`, `DistillStats` dataclasses |
+| `core/distill.py` | `distill_conversation(conv, threshold) → DistillResult` — scoring engine, filtering, summary |
+| `adapters/base.py` | Add `parse_conversation()` default method |
+| `adapters/claude_code.py` | Override `parse_conversation()` with full JSONL parsing |
+| `adapters/chatgpt.py` | Override `parse_conversation()` with tree-walk parsing |
+| `output/distill_terminal.py` | `render_distill(result) → str` Rich terminal output |
+| `cli.py` | `distill` command registration |
+
+## DB Changes
+
+**None.** Distill reads from existing tables:
+- `processed_sessions` — file path + source lookup
+- `prompt_features` — optional score enrichment
+- `prompts` — dedup status, fallback if file missing
+
+No new tables, no migrations.
+
+## Pro Plugin Interface (Layer 2, future)
+
+```python
+# Entry point group: "reprompt.distill_backends"
+# Interface:
+def distill_llm(conversation: Conversation) -> str:
+    """Returns LLM-generated semantic summary.
+    Example: '20 turns about auth → decided JWT with refresh tokens'
+    """
+```
+
+When `reprompt-pro` is installed and user passes `--mode llm`:
+- Plugin registered via `entry_points`
+- Falls back gracefully: "LLM distillation requires reprompt-pro. Install: pip install reprompt-pro"
+
+## Testing Strategy
+
+| Test file | Coverage |
+|-----------|----------|
+| `tests/test_conversation.py` | Dataclass construction, field defaults, validation |
+| `tests/test_distill.py` | Scoring signals (each independently), filtering, summary generation, edge cases (empty conversation, single turn, all below threshold) |
+| `tests/test_distill_cli.py` | CLI invocation, --last, --json, --summary, --copy, --threshold, session_id |
+| `tests/test_parse_conversation_claude.py` | Claude Code parse_conversation() with sample JSONL |
+| `tests/test_parse_conversation_chatgpt.py` | ChatGPT parse_conversation() with sample JSON, conv_id selection |
+
+**Additional edge case tests (in test_distill.py and test_distill_cli.py):**
+- Session file deleted → DB-only fallback (user turns only, warning message)
+- `--last 3` multi-session → each session distilled independently, separated output
+- `--copy` with `--last 3` → concatenated with `---` separator
+- Empty conversation (0 turns) → graceful empty result
+- Single-turn conversation → that turn always passes threshold
+- All turns below threshold → empty filtered_turns with stats showing 0 kept
+
+**Test data:** Synthetic JSONL/JSON fixtures embedded in test files (same pattern as existing adapter tests).
+
+## Success Criteria
+
+1. `reprompt distill --last` produces a useful filtered view of the most recent session
+2. 47-turn conversation distilled to ~10-15 key turns (70-80% reduction)
+3. Error-recovery turns and topic-shift turns are consistently ranked high
+4. `--copy` puts clipboard-ready text that can be pasted into a new AI session
+5. Works with both Claude Code and ChatGPT exports
+6. Zero new dependencies (uses existing scikit-learn for TF-IDF)
+7. All tests pass, no regressions in existing 1153 tests