reprompt-cli 1.3.0__tar.gz → 1.4.1__tar.gz

{reprompt_cli-1.3.0 → reprompt_cli-1.4.1}/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, distill) + 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/
@@ -41,6 +41,7 @@ src/reprompt/
 │   ├── 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)
+│   ├── 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/
@@ -123,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, 1217 tests, 95% coverage target
+- Tests: pytest, 1295 tests, 95% coverage target
 
 ## Prompt Science Engine
 

{reprompt_cli-1.3.0 → reprompt_cli-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reprompt-cli
-Version: 1.3.0
+Version: 1.4.1
 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.1/docs/roadmap.md

@@ -0,0 +1,97 @@
+# reprompt Roadmap
+
+> Last updated: 2026-03-25 · Current version: v1.4.1
+
+## 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) |
+| v1.4.1 | Compare + style polish | `compare --best-worst` auto-pick, `style --trends` period-over-period deltas |
+
+### Quality
+- 1316 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 | **DONE** — `--trends` flag with period-over-period deltas |
+| P4 | `distill --show-weights` / `--weights` signal transparency | Community request for weight visibility |
+| P5 | `compare --best-worst` auto-pick | **DONE** — auto-selects from DB scores |
+| P5 | `--copy` as standard option on remaining commands | Decided against — no clear paste destination for analysis commands |
+
+**Status: 27 → 23 visible commands. P1+P2+P3+P5 shipped.**
+
+---
+
+## v1.5+ — Future Work
+
+| Feature | Description |
+|---------|-------------|
+| Distill false positive reduction | Position signal breaks on small-talk openers / "thanks bye" closers; long error dumps score high on length+uniqueness but aren't decision points; "ok try again" triggers error_recovery but is noise. Community feedback from r/LLMDevs. |
+| 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.1/docs/superpowers/specs/2026-03-23-v131-suggestions-source-design.md

@@ -0,0 +1,179 @@
+# v1.3.1 — Actionable Suggestions + `--source` Consistency
+
+## Goal
+
+Two improvements: (1) guide users to the next useful command after each analysis, (2) make `--source` filtering available on all data-querying commands.
+
+## P2: Actionable Suggestions
+
+### Problem
+
+Commands show data but don't tell users what to do next. New users run `reprompt scan`, see results, and don't know to try `reprompt report` or `reprompt insights`. The "展示 → 行动" gap reduces retention.
+
+### Design
+
+A single dim "Next step" line appended to 5 core commands:
+
+| Command | Suggestion |
+|---------|-----------|
+| `scan` | `reprompt report (see results) · reprompt insights (personal patterns)` |
+| `report` | `reprompt insights (patterns) · reprompt distill --last (session review)` |
+| `score` | `reprompt compress "..." (optimize) · reprompt insights (all patterns)` |
+| `insights` | `reprompt compress "..." (verbose prompts) · reprompt distill --last (sessions)` |
+| `distill` | `reprompt compress "..." (shorten turns) · reprompt report (full analytics)` |
+
+### Implementation
+
+**New file:** `src/reprompt/core/suggestions.py`
+
+```python
+"""Command journey suggestions — guide users to the next useful action."""
+
+from __future__ import annotations
+
+SUGGESTIONS: dict[str, str] = {
+    "scan": "reprompt report (see results) · reprompt insights (personal patterns)",
+    "report": "reprompt insights (patterns) · reprompt distill --last (session review)",
+    "score": 'reprompt compress "..." (optimize) · reprompt insights (all patterns)',
+    "insights": 'reprompt compress "..." (verbose prompts) · reprompt distill --last (sessions)',
+    "distill": 'reprompt compress "..." (shorten turns) · reprompt report (full analytics)',
+}
+
+
+def get_suggestion(command: str) -> str | None:
+    """Return the suggestion line for a command, or None."""
+    return SUGGESTIONS.get(command)
+```
+
+**CLI integration pattern** (same for all 5 commands):
+
+```python
+# At the end of the command function, before return:
+from reprompt.core.suggestions import get_suggestion
+hint = get_suggestion("command_name")
+if hint and not json_output:
+    console.print(f"\n  [dim]→ Try: {hint}[/dim]")
+```
+
+### Display Rules
+
+- Only in terminal mode — suppressed when `--json` or `--copy` is used
+- `[dim]` Rich styling — visible but not distracting
+- Not shown when the command produces no output (e.g. `scan` with 0 new sessions, `distill` with no sessions found)
+- Single line — power users can ignore it instantly
+
+### `scan` Conflict Resolution
+
+`scan` already has a "Try next" block (cli.py:109-114) that shows when new prompts are imported and the DB is small. The new suggestion line must NOT duplicate this. Rule: **only show the dim suggestion when the existing "Try next" block does NOT fire** — i.e. when `result.new_stored == 0` or the DB already has substantial data.
+
+### Why Only 5 Commands
+
+These are the commands users hit in their first session and on return visits. Adding suggestions to all 27 commands would be noise. The 5 form a natural discovery loop:
+
+```
+scan → report → insights → compress/distill → report (loop)
+```
+
+## P3: `--source` Filter Consistency
+
+### Problem
+
+`report`, `search`, `scan`, `lint`, `distill` support `--source` to filter by adapter. But `insights`, `trends`, `digest`, `style` don't — users with multiple tools (e.g. Claude Code + Cursor) can't analyze them separately.
+
+### Current State
+
+| Has `--source` | Missing (should have) | N/A (single-prompt commands) |
+|---|---|---|
+| `scan`, `report`, `search`, `lint`, `distill` | `insights`, `trends`, `digest`, `style` | `score`, `compare`, `compress`, `privacy` |
+
+### Design
+
+Add `--source` / `-s` to the 4 missing commands. Each uses existing DB query functions that already support source filtering, except `get_all_features()`.
+
+#### DB Change: `get_all_features(source=None)`
+
+```python
+def get_all_features(self, source: str | None = None) -> list[dict[str, Any]]:
+    """Return all stored feature vectors, optionally filtered by source."""
+    conn = self._conn()
+    try:
+        if source:
+            rows = conn.execute(
+                """SELECT pf.features_json FROM prompt_features pf
+                   JOIN prompts p ON pf.prompt_hash = p.hash
+                   WHERE p.source = ?
+                   ORDER BY pf.overall_score DESC""",
+                (source,),
+            ).fetchall()
+        else:
+            rows = conn.execute(
+                "SELECT features_json FROM prompt_features ORDER BY overall_score DESC"
+            ).fetchall()
+        return [json.loads(r["features_json"]) for r in rows]
+    finally:
+        conn.close()
+```
+
+#### Per-Command Changes
+
+| Command | Data function | Change needed |
+|---------|--------------|---------------|
+| `insights` | `db.get_all_features()` | Add `source` CLI param, pass to `get_all_features(source=)` |
+| `style` | `db.get_all_prompts()` | Add `source` CLI param, pass to `get_all_prompts(source=)` (NOTE: `style` uses `get_all_prompts`, not `get_all_features`) |
+| `trends` | `db.get_all_prompts()` | `get_all_prompts()` already accepts `source` — add CLI param and pass through |
+| `digest` | `build_digest()` → `compute_window_snapshot()` → `db.get_prompts_in_range()` | Full call chain needs `source` threaded through (see below) |
+
+#### `digest` Call Chain Fix
+
+`digest` has a 3-function call chain that all need `source` added:
+
+```
+CLI digest(source=) → build_digest(db, period, source=) → compute_window_snapshot(db, window, period, source=) → db.get_prompts_in_range(start, end, source=)
+```
+
+**Files to modify:**
+- `src/reprompt/core/digest.py`: add `source: str | None = None` param to `build_digest()`, pass to `compute_window_snapshot()`
+- `src/reprompt/core/trends.py`: add `source: str | None = None` param to `compute_window_snapshot()`, pass to `db.get_prompts_in_range()`
+- `db.get_prompts_in_range()` already accepts `source` — no change needed
+
+**Digest log edge case:** When `source` is set, skip `db.log_digest()` — a source-filtered digest run should not overwrite the unfiltered digest history.
+
+#### CLI Parameter Pattern
+
+Standardize on `None` default (matching `distill`), not empty string:
+```python
+source: str | None = typer.Option(
+    None, "--source", "-s", help="Filter by source (e.g. claude-code, cursor, aider)"
+)
+```
+
+## Files Changed
+
+| File | Action | What |
+|------|--------|------|
+| `src/reprompt/core/suggestions.py` | Create | Suggestion map + `get_suggestion()` |
+| `src/reprompt/storage/db.py` | Modify | Add `source` param to `get_all_features()` |
+| `src/reprompt/core/digest.py` | Modify | Add `source` param to `build_digest()` |
+| `src/reprompt/core/trends.py` | Modify | Add `source` param to `compute_window_snapshot()` |
+| `src/reprompt/cli.py` | Modify | Suggestions on 5 commands + `--source` on 4 commands |
+| `tests/test_suggestions.py` | Create | Suggestion map tests |
+| `tests/test_source_filter.py` | Create | `--source` CLI + behavioral tests (seeded DB with 2 sources) |
+
+## DB Changes
+
+**None.** No schema changes, no migrations. Only a query modification in `get_all_features()`.
+
+## Testing Strategy
+
+| Test file | Coverage |
+|-----------|----------|
+| `tests/test_suggestions.py` | All 5 commands return suggestions, unknown command returns None, suggestions contain valid command names |
+| `tests/test_source_filter.py` | CLI `--source` flag on insights/trends/digest/style (`--help` shows flag), behavioral test with seeded DB (2 sources, verify filtered count != total count), `get_all_features(source=)` JOIN returns correct subset, digest source-filtered run skips log_digest |
+
+## Success Criteria
+
+1. `reprompt report` ends with a dim suggestion line pointing to `insights` and `distill`
+2. `reprompt insights --source claude-code` shows patterns only from Claude Code sessions
+3. `reprompt style --source cursor` shows style fingerprint from Cursor-only prompts
+4. Suggestions suppressed in `--json` mode
+5. Zero regressions in existing tests

reprompt_cli-1.4.1/docs/superpowers/specs/2026-03-24-v14-context-recovery-design.md

@@ -0,0 +1,342 @@
+# v1.4 Design Spec: Context Recovery + Consolidation
+
+> **Version:** v1.4.0
+> **Date:** 2026-03-24
+> **Status:** Draft
+> **Community signal:** pvdyck (r/ClaudeAI), LLMDevs commenters, LeadingFarmer3923 (r/ClaudeAI)
+
+---
+
+## Problem
+
+AI coding sessions lose context through compaction, timeouts, and tool-switching. Users are forced to re-explain what they were doing, what decisions were made, and where they left off. This is a daily pain point for every Claude Code, Cursor, and Aider power user.
+
+No tool produces a structured, portable, human-readable distillation of a coding session optimized for re-injection into a new session.
+
+## Solution
+
+Add `--export` flag to the existing `reprompt distill` command. Produces a markdown context document designed to be pasted into any AI tool as session resumption context.
+
+```bash
+# Primary workflow
+reprompt distill --last 1 --export | pbcopy
+# → paste into new Claude Code / Cursor / ChatGPT session
+
+# With clipboard shortcut
+reprompt distill --last 1 --export --copy
+
+# Full mode (includes assistant responses)
+reprompt distill --last 1 --export --full
+```
+
+## Design Principles
+
+1. **Generic markdown** — works in any AI tool, not coupled to one platform
+2. **User turns only** by default — the goal is "what the human decided and did," not replaying the conversation
+3. **~500 tokens default** — fits comfortably in any context window alongside other context
+4. **Lost-in-the-Middle aware** — actionable sections at top and bottom, reference material in the middle (Stanford 2307.03172, MIT 2025 follow-up)
+5. **Cache-friendly header** — stable identifiers first, volatile metadata second (arXiv 2601.06007)
+6. **Zero-config** — no LLM required, rule-based extraction from existing distill engine
+
+## Export Document Structure
+
+```markdown
+# Session Context: <project>
+
+**Source:** <adapter> | **Date:** <YYYY-MM-DD> | **Duration:** <N>min
+**Turns:** <total> → <kept> key turns | **~<N> tokens**
+
+## Goal
+
+<first user turn, compressed via compress_text()>
+
+## Current State
+
+<last high-importance user turn, compressed>
+
+## Key Decisions
+
+1. <turn with high semantic_shift — why a choice was made>
+2. <turn with high semantic_shift — why a choice was made>
+3. ...
+
+## What Was Done
+
+- <turn with high tool_trigger — what was implemented/changed>
+- ...
+
+## Files Changed
+
+`file1.py`, `file2.py`, `file3.py`
+
+## Resume
+
+<last turn with forward-looking intent, if detected; omitted otherwise>
+```
+
+### Section Design Details
+
+#### Header
+- Project name first (stable, cache-friendly), volatile metadata on second line.
+- Token count is approximate: `len(output) // 4`. No external tokenizer dependency.
+
+#### Goal
+- Source: first user turn (`user_turns[0]`), processed through `compress_text()`.
+- Truncated to 200 chars max.
+- Always present (every conversation has a first turn).
+
+#### Current State
+- Source: last user turn with `importance >= threshold`, compressed.
+- Represents where the session ended up, not where it started.
+- If same as Goal (single-turn session), this section is omitted.
+
+#### Key Decisions
+- Source: user turns sorted by `semantic_shift` signal (descending), top 5.
+- These are turns where the user changed direction or made a choice.
+- Each entry compressed and truncated to 150 chars.
+- Deduplicated against Goal and Current State (no repeats).
+
+#### What Was Done
+- Source: user turns sorted by `tool_trigger` signal (descending), top 5.
+- These are turns that caused the most tool activity (implementation work).
+- Each entry compressed and truncated to 150 chars.
+- Deduplicated against Key Decisions (a turn appears in only one section).
+
+#### Files Changed
+- Source: existing `_extract_files_changed()` from distill engine.
+- Displayed as inline code, comma-separated. Max 10 files shown (aligned with existing `generate_summary()` cap).
+
+#### Resume
+- Source: last 3 user turns, checked for forward-looking keywords.
+- Keywords: `next`, `todo`, `now let's`, `then`, `after that`, `move on`, `接下来`, `然后`, `下一步`.
+- If no forward-looking turn found, section is omitted entirely.
+- Not fabricated — only extracted from actual user text.
+
+### Turn Classification Logic
+
+A user turn's primary section is determined by its highest-scoring signal:
+
+| Highest signal | Section |
+|---------------|---------|
+| `semantic_shift` | Key Decisions |
+| `tool_trigger` | What Was Done |
+| Both equal | Key Decisions (decision > action) |
+
+Turns used for Goal, Current State, or Resume are excluded from both lists to avoid repetition.
+
+## `--full` Mode
+
+When `--full` is passed, each user turn in Key Decisions and What Was Done includes the paired assistant response summary:
+
+```markdown
+## Key Decisions
+
+1. **User:** Used TF-IDF cosine distance for semantic_shift instead of embeddings
+   **Result:** Implemented in `_compute_semantic_signals()`, 4 helper functions added
+```
+
+Assistant response is summarized as: first sentence of the response text, or "N tool calls, M files changed" if the response is primarily tool use. This roughly doubles token count (~1000-1500 tokens).
+
+## Weight Transparency Flags
+
+Two separate flags (Typer does not support a single option that acts as both bool flag and string option):
+
+```bash
+# Show current weights
+reprompt distill --show-weights
+# position=0.15, length=0.15, tool_trigger=0.20,
+# error_recovery=0.15, semantic_shift=0.20, uniqueness=0.15
+
+# Override weights (advanced)
+reprompt distill --last 1 --export --weights "semantic_shift=0.4,tool_trigger=0.3"
+```
+
+**`--show-weights`** (bool flag): Prints current signal weights and exits. Ignores all other flags.
+
+**`--weights TEXT`** (string option): Parses comma-separated `key=value` pairs, merges with defaults for unspecified keys. Validation:
+- Unknown keys (typos like `tool_tigger`) → error with "unknown weight key" message listing valid keys
+- Sum != 1.0 → warning printed to stderr, execution continues
+- Override applies to this invocation only, does not persist
+
+## Open/Pro Boundary
+
+| Feature | Layer | Rationale |
+|---------|-------|-----------|
+| `--export` markdown output | **Open** | Rule-based, zero-config, individual tool |
+| `--full` user+assistant pairs | **Open** | Same data, different format |
+| `--weights` transparency | **Open** | Transparency builds trust |
+| LLM-powered semantic summary | **Pro** | Requires Ollama, clear upgrade path |
+| Cross-session memory ("what did I discuss about auth across 100 sessions?") | **Pro** | Needs persistent index + embeddings |
+
+If Pro plugin is installed, `--export --summary` uses LLM to produce a condensed 3-sentence brief instead of rule-based extraction. Graceful degradation message if Pro is not installed.
+
+## Architecture
+
+### New Files
+
+| File | Purpose | ~Lines |
+|------|---------|--------|
+| `output/export.py` | `generate_export(result, full=False) → str` | ~120 |
+
+### Modified Files
+
+| File | Change |
+|------|--------|
+| `cli.py` | Add `--export`, `--full`, `--show-weights`, `--weights` flags to `distill` command |
+| `core/distill.py` | Expose per-signal scores on `ConversationTurn` for section classification; accept optional `weights` dict |
+| `core/conversation.py` | Add `signal_scores: dict[str, float]` field to `ConversationTurn` |
+| `core/suggestions.py` | Update distill suggestion to mention `--export` |
+
+### Data Flow
+
+```
+Session files → Adapter.parse_conversation() → Conversation
+  → distill_conversation(conv, threshold, weights?) → DistillResult
+    (turns now have per-signal scores in signal_scores dict)
+  → generate_export(result, full=False) → str (markdown)
+  → stdout / clipboard / file
+```
+
+### Key Implementation Details
+
+1. **Per-signal scores on ConversationTurn:** Currently `importance` is a single float (weighted sum). To classify turns into "Key Decisions" vs "What Was Done," we need access to individual signal scores. Add `signal_scores: dict[str, float] = field(default_factory=dict)` to `ConversationTurn`. Populate during scoring inside `distill_conversation()`:
+
+    ```python
+    # Inside the user turn scoring loop (after computing all 6 scores):
+    user_turn.signal_scores = {
+        "position": pos_score,
+        "length": len_score,
+        "tool_trigger": tool_score,
+        "error_recovery": error_score,
+        "semantic_shift": shift_score,
+        "uniqueness": unique_score,
+    }
+    user_turn.importance = (
+        weights["position"] * pos_score
+        + weights["length"] * len_score
+        + ...
+    )
+    ```
+
+2. **`distill_conversation()` new signature:**
+
+    ```python
+    def distill_conversation(
+        conversation: Conversation,
+        threshold: float = 0.3,
+        weights: dict[str, float] | None = None,
+    ) -> DistillResult:
+    ```
+
+    When `weights` is None, use the existing `W_*` module constants as defaults. When provided, merge: `effective = {**DEFAULT_WEIGHTS, **weights}`. Unknown keys are already rejected at the CLI layer (see `--weights` validation).
+
+3. **Forward-looking detection for Resume:** Simple keyword match on last 3 high-importance user turns. Bilingual (en + zh). No NLP dependency.
+
+4. **Token estimation:** `len(output_text) // 4` — rough but sufficient. No external tokenizer.
+
+5. **Deduplication across sections:** Goal turn, Current State turn, and Resume turn are tracked by `turn_index`. Excluded from Key Decisions and What Was Done candidate pools.
+
+6. **`--full` mode assistant summary:** An assistant turn is "primarily tool use" when `tool_calls > 0 and len(text.strip()) < 200`. In that case, summarize as `"{N} tool calls, {M} files changed"`. Otherwise, use the first sentence of the response text (split on `. ` or `\n`, take first element, truncate to 150 chars).
+
+7. **`--export` restricted to single session:** `--export` requires `--last 1` (or a specific session_id). If `--last N` with N > 1 is combined with `--export`, print error: `"--export works with a single session. Use --last 1 or specify a session ID."` and exit.
+
+8. **`--export --json` envelope:** Outputs `{"export": "<markdown string>", "session_id": "...", "source": "...", "tokens": N}`. The markdown is a single string field, not the raw DistillResult.
+
+9. **Empty filtered_turns fallback:** When `filtered_turns` is empty (threshold too high), `generate_export()` falls back to a minimal document using the first and last raw user turns from `conversation.turns`, with a note: `"(No turns above threshold {threshold}. Showing first and last turns.)"`.
+
+10. **Suggestions update:** Replace the `distill` entry in `SUGGESTIONS` dict (`core/suggestions.py` line 10) with: `'reprompt distill --export --copy (context recovery) · reprompt compress "..." (shorten turns)'`. This replaces the current `report` hint (less relevant after distill) with the new `--export` hint, keeping `compress` as the second option.
+
+11. **`--full` without `--export` warning:** If `--full` is passed without `--export`, print a warning to stderr: `"--full has no effect without --export"` and continue normally. Do not error.
+
+## CLI Interface
+
+```
+reprompt distill [SESSION_ID] [OPTIONS]
+
+Existing flags (unchanged):
+  --last N          Distill N most recent sessions (default: 1)
+  --source TEXT     Filter by adapter name
+  --summary         Show compressed summary
+  --json            Output as JSON
+  --copy            Copy to clipboard
+  --threshold FLOAT Importance cutoff 0.0-1.0 (default: 0.3)
+
+New flags (v1.4):
+  --export          Output as markdown context document for session resumption
+  --full            Include assistant responses in export (requires --export)
+  --show-weights    Print current signal weights and exit
+  --weights TEXT    Override signal weights, e.g. "semantic_shift=0.4,tool_trigger=0.3"
+```
+
+Flag interactions:
+- `--export` and `--summary` are mutually exclusive (both produce text, different formats)
+- `--export` requires single session: `--last 1` or a session_id. Error if `--last N` with N > 1.
+- `--export --json` outputs `{"export": "<markdown>", "session_id": "...", "source": "...", "tokens": N}`
+- `--export --copy` copies the markdown to clipboard
+- `--full` without `--export` is ignored (only affects export format)
+- `--show-weights` prints weights and exits (ignores all other flags)
+- `--weights "k=v,..."` overrides weights for the current invocation; unknown keys → error
+
+## v1.4 Full Scope (Context Recovery + Consolidation)
+
+| Priority | Item | Type |
+|----------|------|------|
+| **P1** | `distill --export` context recovery | New feature |
+| **P2** | Command consolidation: `save`/`templates`/`use` → `template [save\|list\|use]` | UX cleanup |
+| **P2** | Command consolidation: `effectiveness`/`merge-view` → subcommands of `insights` | UX cleanup |
+| **P3** | `style` change trends ("specificity +12% this week") | Enhancement |
+| **P4** | `distill --weights` signal transparency | Enhancement |
+| **P5** | `compare --best-worst` auto-pick | Enhancement |
+| **P5** | `--copy` as standard option on remaining commands | Consistency |
+
+**Target: 27 → ~21 commands after consolidation. 1 new flag (`--export`), not 1 new command.**
+
+## Testing Strategy
+
+| Layer | Tests | What |
+|-------|-------|------|
+| Unit | ~20 | `generate_export()` with various DistillResult shapes (empty, single turn, many turns, no forward-looking, etc.) |
+| Unit | ~10 | Per-signal score classification (semantic_shift dominant → Key Decisions, tool_trigger dominant → What Was Done) |
+| Unit | ~5 | Forward-looking keyword detection (en + zh) |
+| Unit | ~5 | `--weights` parsing and validation |
+| Unit | ~5 | Token estimation accuracy |
+| Integration | ~5 | `distill --export` end-to-end through CLI |
+| Integration | ~3 | `--export --full` vs default comparison |
+| Integration | ~2 | `--export --copy` clipboard integration |
+| Unit | ~3 | Empty filtered_turns fallback behavior |
+| Snapshot | ~3 | Golden file tests for export format stability (fixtures in `tests/fixtures/export/`) |
+
+**~61 new tests. Target: 1298+ total (currently 1237).**
+
+### Snapshot Test Strategy
+
+Golden file fixtures live in `tests/fixtures/export/`. Each fixture is a `.md` file containing the expected export output for a specific DistillResult shape. Tests compare `generate_export()` output against these files. When the export format intentionally changes, fixtures are regenerated with `pytest --update-snapshots` (custom marker).
+
+## Competitive Position
+
+| Tool | What it does | How reprompt differs |
+|------|-------------|---------------------|
+| continues (`npx continues`) | Cross-tool session handoff (14 tools) | reprompt adds *importance scoring* — not all turns are equal |
+| claude-session-restore | Rust-based extraction of everything | reprompt extracts *what matters*, not everything |
+| open-mem | LLM-compressed tool outputs | reprompt is rule-based, zero-config, tool-agnostic |
+| Cline Memory Bank | Persistent project memory across tasks | reprompt is retrospective analysis, not live state |
+| Cognetivy | Structured prompt creation templates | Complementary: Cognetivy = before, reprompt = after |
+
+**Unique value:** reprompt is the only tool that produces an importance-scored, research-calibrated, portable context recovery document from any AI coding session without requiring an LLM.
+
+## Success Criteria
+
+1. `reprompt distill --last 1 --export` produces a markdown document under 600 tokens for a typical 50-turn session
+2. The document, when pasted into a new AI session, gives the model enough context to continue the previous task without the user re-explaining
+3. Export format is stable (golden file tests prevent accidental changes)
+4. Works with all 8 adapters that support `parse_conversation()`
+
+## References
+
+- Stanford "Lost in the Middle" (arXiv 2307.03172) — U-shaped attention, critical info at top/bottom
+- "Don't Break the Cache" (arXiv 2601.06007) — stable prefixes for prompt caching
+- Anthropic Context Engineering Guide — compaction + structured notes pattern
+- OpenAI GPT-4.1 Prompting Guide — section ordering best practices
+- Cline new_task tool — structured handoff format (Completed/Current/Next)
+- td (marcus/td) — minimalist handoff: done/remaining/decisions/uncertain
+- CONTINUITY (duke-of-beans) — decisions as first-class objects