reprompt-cli 0.3.2__tar.gz → 1.0.0__tar.gz

reprompt_cli-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

reprompt_cli-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

{reprompt_cli-0.3.2 → reprompt_cli-1.0.0}/.github/workflows/ci.yml

@@ -28,7 +28,7 @@ jobs:
       - name: Format check
         run: ruff format --check src/ tests/
       - name: Test
-        run: pytest tests/ -v --cov=reprompt --cov-report=xml
+        run: pytest tests/ -v --cov=reprompt --cov-report=xml --cov-fail-under=88
       - name: Upload coverage
         if: matrix.python-version == '3.12' && matrix.os == 'ubuntu-latest'
         uses: codecov/codecov-action@v5

{reprompt_cli-0.3.2 → reprompt_cli-1.0.0}/.github/workflows/publish.yml

@@ -15,6 +15,14 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+      - name: Install dependencies
+        run: uv pip install --system -e ".[dev]"
+      - name: Lint
+        run: ruff check src/ tests/
+      - name: Test
+        run: pytest tests/ -v --cov=reprompt --cov-fail-under=88
       - name: Install build tools
         run: pip install build
       - name: Build

reprompt_cli-1.0.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project
+*.db
+.env
+
+# Local memory / session context (never commit)
+thoughts/
+.claude/
+.tldr/
+.tldrignore
+.worktrees/
+
+# Launch / marketing drafts (not part of the codebase)
+docs/launch/
+
+# Brand assets & design tools (local reference only)
+docs/brand-system.html
+docs/logo-proposals.html
+docs/icon-*
+docs/logo-*
+
+# Implementation plans (local reference only)
+docs/superpowers/plans/
+
+# Generated outputs
+reprompt-report.html
+*-hot-phrases-tf-idf.txt

reprompt_cli-1.0.0/CHANGELOG.md

@@ -0,0 +1,294 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2026-03-16
+
+### Changed
+- **Stability release** — no new features, focused on reliability and trust
+- Empty-state guidance for `report` and `digest` commands
+- Scan shows "Try next" hints for new users
+- Feature extraction errors logged instead of silently swallowed
+
+### Infrastructure
+- DB schema versioning via `PRAGMA user_version` — ordered migrations, no more ad-hoc ALTER TABLE
+- CI enforces ≥90% test coverage; publish workflow runs tests before PyPI upload
+- Removed unused `[science]` optional dependency group
+- CHANGELOG backfill for all versions since v0.7.4
+
+## [0.9.3] - 2026-03-16
+
+### Added
+- `reprompt report --source` and `reprompt search --source` — filter by source adapter
+
+## [0.9.2] - 2026-03-15
+
+### Added
+- **Wrapped reports** — `reprompt wrapped` generates an annual Prompt DNA report (terminal, HTML, shareable)
+- **6 prompt personas** — Architect, Debugger, Explorer, Novelist, Sniper, Teacher (auto-classified)
+- **Telemetry** — opt-in anonymous 26-dimension feature vectors (no prompt text, no PII)
+- **Share** — HMAC-SHA256 signed upload to getreprompt.dev/api/share
+- Open-core plugin system: `entry_points(group="reprompt.plugins")` loaded at startup
+
+### Changed
+- Migrated wrapped, personas, telemetry, share into open-source CLI (from reprompt-pro)
+
+## [0.9.1] - 2026-03-14
+
+### Added
+- **Multi-language PromptDNA** — Chinese feature extraction via jieba (optional `[chinese]` extra)
+- **Native messaging bridge** — Chrome/Firefox extension support (`reprompt install-extension`)
+- **Style fingerprint** — `reprompt style` shows personal prompting patterns
+- **Template variables** — `reprompt use template_name key=value` with `{placeholder}` substitution
+- **Enhanced recommendations** — `reprompt recommend` uses effectiveness data
+
+### Infrastructure
+- Plugin system for open-core architecture (reprompt-pro registers via entry_points)
+- DB aggregation queries for plugin data access
+
+## [0.9.0] - 2026-03-13
+
+### Added
+- **ChatGPT import** — `reprompt import conversations.json` parses OpenAI export format
+- **Claude.ai import** — `reprompt import claude-export.zip` parses Claude web chat exports
+- **`reprompt import` command** — unified import with auto-detection of source format
+- 7 non-coding prompt categories for Chat AI support (brainstorm, summarize, explain, translate, roleplay, creative, casual)
+
+### Changed
+- Tests: 580 → 680+
+
+## [0.8.2] - 2026-03-13
+
+### Added
+- **Digest category deltas** — `reprompt digest` shows per-category % change with arrows
+- **`reprompt digest --history`** — view past digest log entries
+
+## [0.8.1] - 2026-03-12
+
+### Added
+- **HTML dashboard** — `reprompt report --html` generates interactive Chart.js dashboard
+- Digest + cluster data wired into HTML report
+
+## [0.8.0] - 2026-03-12
+
+### Added
+- **Effectiveness columns** — `prompts.effectiveness_score`, `prompt_patterns.effectiveness_avg`
+- **`reprompt library`** shows Eff column with score + star rating
+- **`reprompt digest`** shows avg session quality
+- **OpenClaw `parse_session_meta()`** — session quality scoring for OpenClaw/OpenCode sessions
+- `db.update_prompt_effectiveness()` and `db.compute_pattern_effectiveness()` methods
+- Pipeline: `run_scan()` propagates session scores to prompts; `build_report_data()` recomputes pattern averages
+
+### Infrastructure
+- `_migrate_v08()` adds effectiveness columns via safe ALTER TABLE
+
+### Changed
+- Tests: 480 → 510+
+
+## [0.7.5] - 2026-03-12
+
+### Added
+- Expanded Chinese stop words — 65 function words from stopwords-iso added
+
+## [0.7.4] - 2026-03-12
+
+### Improved
+- **Mixed Chinese/English tokenization** — Hot Phrases now uses a custom analyzer that handles code-switching text natively: Chinese character runs emit bigrams (报错, 修复, 自动化 etc.), ASCII words use standard tokenization. Zero extra dependencies (regex only)
+- **Chinese stop words** (~90 words, HIT + cn_stopwords) — common Chinese particles, pronouns, conjunctions, discourse markers (好的, 是否, 或者, 现在, 项目, 代码 etc.) are now filtered. Eliminates single-char noise like 们/现/个/么 from Hot Phrases
+- **English conversational stop words** (sklearn gap fill) — sklearn's built-in list (Stone 2010, formal text) misses common chat words: `does`, `yeah`, `ok`, `gotcha`, `doesn`, `wouldn`, `really`, `maybe`, `also` etc. These are now filtered
+- **AI tool names as stop words** — `claude`, `cursor`, `aider`, `gemini` are generic for their own users and no longer pollute Hot Phrases
+- **Chinese bigrams only** — single Chinese characters are almost always stop words or partial words (们 only in 我们, 么 only in 什么); removing unigram emission keeps the phrase table semantically meaningful
+
+## [0.7.3] - 2026-03-12
+
+### Improved
+- **Smarter prompt clustering** — K-means now runs on LSA-reduced (TruncatedSVD + L2-normalized) TF-IDF vectors instead of raw sparse vectors; eliminates the single-dominant-cluster problem where 95%+ of prompts collapsed into one bucket
+- **Auto-select optimal K** — cluster count is now determined automatically via silhouette score sweep (K=3..15) rather than a fixed K=5; pass `--clusters N` to `reprompt report` to override
+- **Cleaner Hot Phrases** — shell tool names (`cd`, `uv`, `pytest`, `git`, `bash`, etc.) added to domain stop word list; year-number bigrams (e.g. "2025 2026") filtered from n-gram extraction; n-gram range expanded to (1, 3) to surface meaningful single-word domain signals
+- **TF-IDF quality flags** — added `sublinear_tf=True` and `max_df=0.8` to dampen high-frequency noise and auto-remove corpus-ubiquitous terms
+
+## [0.7.2] - 2026-03-12
+
+### Added
+- **`skill_invocation` prompt category** — skill/workflow invocations (e.g. `superpowers:brainstorming`, `feature-dev:code-architect`) are now classified as their own category instead of polluting `other` or being silently filtered. Shows up in Prompt Categories so you can see what % of your sessions are workflow-driven vs content-driven
+- **`reprompt purge --all`** — wipes the entire database and resets session tracking (useful to remove demo data or start fresh). Follow with `reprompt scan` to reimport
+
+### Fixed
+- Skill invocations previously added to filter list (wrong approach) — they are analytically valuable and now correctly categorized instead of discarded
+- Regex detection covers any `namespace:skill-name` pattern (9+ char namespace) — future-proof, no hardcoded list required
+
+### Changed
+- Tests: 490 → 493
+
+## [0.7.1] - 2026-03-11
+
+### Added
+- **12 prompt categories** (was 8) — new: `document`, `run`, `query`, `generate`, `plan`; reduces the "other" bucket from ~56% to an estimated <15%
+- **Chinese language support** for all categories — bilingual keyword matching (e.g. "整理" → document, "启动" → run, "是否" → query)
+- **Coding domain stop words** for TF-IDF Hot Phrases — ~60 programming-specific terms filtered (generic verbs: write/create/implement; structure nouns: function/class/variable; LeetCode templates: given/input/output). Hot Phrases now surfaces meaningful domain signals instead of generic boilerplate
+- **Subagent session labeling** — Claude Code subagent sessions (stored under `{project}/{uuid}/subagents/`) are now correctly attributed to their parent project with a `[subagent]` tag (e.g. `claudeAutomation [subagent]`), instead of all appearing under a mystery "subagents" project
+
+### Fixed
+- `cluster_prompts()` previously used no stop words; now uses the same coding stop word list as `compute_tfidf_stats()` for consistent clustering quality
+- "write a function…" prompts were falling into `other`; now correctly categorized as `implement`
+- `not working`, `exception`, `fail` now correctly trigger the `debug` category
+
+### Changed
+- Tests: 478 → 489
+
+## [0.7.0] - 2026-03-11
+
+### Added
+- `reprompt digest` — weekly summary comparing current vs previous period: prompt volume, specificity score, avg length, category distribution with direction arrows
+- `reprompt digest --quiet` — one-line summary for use in hooks and cron jobs
+- `reprompt digest --format json` — machine-readable digest output
+- `reprompt digest --period 30d` — configurable comparison window (7d, 14d, 30d)
+- `reprompt install-hook --with-digest` — also registers `reprompt digest --quiet` as a Stop hook so every session ends with a summary
+- `digest_log` DB table — persists digest history for trend tracking
+
+### Changed
+- Tests: 454 → 478
+
+## [0.6.0] - 2026-03-11
+
+### Added
+- **Prompt Science Engine** — research-backed prompt analysis
+- `reprompt score "prompt"` — instant 0-100 quality score with breakdown (specificity, position bias, repetition, perplexity)
+- `reprompt compare "a" "b"` — side-by-side feature comparison of two prompts
+- `reprompt insights` — personal patterns vs research-optimal benchmarks, wired into `reprompt scan`
+- `PromptDNA` dataclass — 30+ features per prompt extracted at scan time
+- Tier 1 feature extractors — regex-based, <1ms per prompt
+- Research-calibrated scorer (Google 2512.14982, Stanford 2307.03172, SPELL EMNLP 2023, Prompt Report 2406.06608)
+- Three-pass prompt segmenter (Prompt Report taxonomy)
+- `prompt_features` DB table for PromptDNA storage
+
+### Changed
+- Tests: 371 → 454
+
+## [0.5.0] - 2026-03-11
+
+### Added
+- `reprompt lint` — prompt quality linter with GitHub Action integration
+- Gemini CLI adapter — parses `~/.gemini/tmp/` session files
+- Cline (VS Code) adapter — parses `globalStorage/saoudrizwan.claude-dev/` task files
+- Comprehensive prompt filters for all AI coding tools (slash commands, system injections, tool outputs)
+- Shared filter module (`adapters/filters.py`) extracted for reuse across all adapters
+
+### Changed
+- Tests: 331 → 371
+
+## [0.4.0] - 2026-03-11
+
+### Added
+- Cursor IDE adapter — parses `.vscdb` files (Composer `cursorDiskKV` + legacy `ItemTable` schemas)
+- Aider adapter — parses `.aider.chat.history.md` chat history files
+- HTML dashboard report — `reprompt report --html` renders interactive Chart.js charts
+- `reprompt merge-view` — clusters near-duplicate prompts and selects canonical versions
+- `reprompt templates` / `reprompt save` — save and reuse prompt templates
+- Auto-report after `reprompt scan` (skip with `--quiet`)
+- `reprompt install-hook` now prompts if not yet configured
+
+### Changed
+- Tests: 256 → 331
+
+## [0.3.2] - 2026-03-11
+
+### Fixed
+- Fix ANSI escape code leak in terminal report (double-render through Rich console)
+- Filter subagent/automation prompts ("You are implementing Task...", "## Task:", etc.)
+- Strip file paths from TF-IDF input to prevent path fragment n-grams
+- Filter noise phrases (username/path tokens) from Hot Phrases results
+
+### Added
+- `reprompt recommend` command — suggests better prompts based on effectiveness, category balance, and specificity
+- `reprompt demo` command — run a full report with built-in sample data, no session history needed
+- Cursor IDE adapter — parses `.vscdb` files from both Composer (cursorDiskKV) and legacy (ItemTable) schemas
+- `reprompt scan` now auto-shows report after scanning (skip with `--quiet`)
+- `reprompt scan` suggests `install-hook` if not yet configured
+- Demo data generator script (`scripts/generate_demo_data.py`) using CodeAlpaca-20K
+- VHS recording script for terminal demo GIF
+- Launch materials (Show HN, Reddit, Twitter, Dev.to, Chinese communities)
+
+## [0.3.1] - 2026-03-11
+
+### Added
+- MCP server (`reprompt mcp-serve`) for Claude Code, Continue.dev, and Zed integration
+- 6 MCP tools: search_prompts, get_prompt_library, get_best_prompts, get_trends, get_status, scan_sessions
+- 2 MCP resources: reprompt://status, reprompt://library
+- `fastmcp` optional dependency (`pip install reprompt-cli[mcp]`)
+- MCP setup guide in README
+
+### Changed
+- Tests: 246 → 256
+- Updated supported tools table (Codex CLI, Aider, Gemini CLI, Continue.dev, Zed)
+
+## [0.3.0] - 2026-03-11
+
+### Added
+- `reprompt trends` — prompt evolution tracking with specificity scoring, delta arrows, insights
+- `reprompt effectiveness` — session quality scoring (clean exit, error ratio, duration heuristics)
+- Session metadata extraction during scan (tool calls, errors, duration, final status)
+- Hot Phrases: TF-IDF now extracts bigram/trigram phrases instead of single words
+- Prompt snapshots table for time-series trend data
+- IDE prefix stripping (`<ide_opened_file>`, `<ide_selection>`) — preserves real user questions
+- Compact/continuation message filtering (blocks session compaction noise)
+- Troubleshooting FAQ in README (Anaconda NumPy conflict)
+
+### Changed
+- "Hot Terms" → "Hot Phrases" in terminal report (n-gram based, stopwords filtered)
+- Tests: 176 → 246
+
+## [0.2.0] - 2026-03-11
+
+### Added
+- `reprompt search <query>` command for keyword search across prompt history
+- Local embedding backend (`pip install reprompt-cli[local]`, sentence-transformers)
+- OpenAI embedding backend (`pip install reprompt-cli[openai]`)
+- TOML config file support (`~/.config/reprompt/config.toml`)
+- K-means clustering output in terminal report
+- TF-IDF hot terms table in terminal report
+- OpenClaw adapter supports new `~/.openclaw/` path (backward compatible)
+- Competitive comparison table in README
+
+### Fixed
+- `install-hook` now registers in Claude Code `settings.json` (was writing unregistered shell script)
+- `ollama_url` config setting now propagates to OllamaEmbedder
+- Pattern IDs are stable across report runs (upsert instead of clear+re-insert)
+- Text truncation in all outputs now shows `...` suffix
+- JSON output uses `print()` instead of Rich `console.print()` to avoid markup corruption
+
+### Changed
+- Tests: 118 → 176
+- OpenClaw adapter checks both `~/.openclaw/` (new) and `~/.opencode/` (legacy)
+
+## [0.1.1] - 2026-03-10
+
+### Fixed
+- Prevent connection leak in all database methods (try/finally)
+- Fix session marking for incremental scan accuracy
+- Fix purge validation for date format parsing
+- Fix pattern dedup to avoid duplicate entries
+- Improve Ollama error messages when server is unreachable
+- Fix JSON output (`--format json`) producing invalid escape sequences
+
+### Added
+- `--version` / `-V` flag to CLI
+- mypy strict mode compliance
+
+## [0.1.0] - 2026-03-10
+
+### Added
+
+- Initial release
+- Claude Code session adapter (JSONL format)
+- OpenClaw session adapter
+- Two-layer deduplication (SHA-256 exact + TF-IDF semantic)
+- TF-IDF hot terms analysis
+- K-means prompt clustering
+- Prompt pattern library with auto-categorization
+- Rich terminal reports with tables and bar charts
+- JSON output for CI/pipeline integration
+- Markdown export for prompt library
+- `install-hook` command for Claude Code automation
+- Ollama embedding backend (optional)
+- Zero-config defaults with env var and TOML override

reprompt_cli-1.0.0/CLAUDE.md

@@ -0,0 +1,130 @@
+# reprompt
+
+CLI tool that extracts, deduplicates, and analyzes prompts from AI coding sessions.
+
+## Build & Test
+
+```bash
+uv venv && uv pip install -e ".[dev]"
+uv run pytest tests/ -v                    # run tests
+uv run pytest tests/ -v --cov=reprompt     # with coverage
+uv run ruff check src/ tests/              # lint
+uv run ruff format src/ tests/             # format
+uv run mypy src/reprompt/                  # type check (strict)
+uv run python -m build                     # build wheel
+```
+
+## Architecture
+
+```
+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) + plugin loading
+├── config.py           # pydantic-settings, env vars (REPROMPT_ prefix) + TOML config
+├── demo.py             # Built-in demo data generator (no network required)
+├── core/
+│   ├── models.py       # Prompt dataclass (auto SHA-256 hash)
+│   ├── dedup.py        # Two-layer dedup: exact hash + TF-IDF cosine
+│   ├── analyzer.py     # TF-IDF hot terms + K-means clustering
+│   ├── library.py      # Pattern extraction + keyword categorization
+│   ├── recommend.py    # Prompt recommendations based on history + effectiveness
+│   ├── pipeline.py     # Orchestrator: scan → dedup → store → analyze → cluster
+│   ├── prompt_dna.py    # PromptDNA dataclass (30+ features per prompt)
+│   ├── extractors.py    # Tier 1 feature extraction (regex, <1ms)
+│   ├── scorer.py        # Research-calibrated scoring (0-100)
+│   ├── segmenter.py     # Three-pass prompt segmentation
+│   ├── insights.py      # Personal insights vs research-optimal
+│   ├── digest.py        # Two-window comparison for weekly digest
+│   ├── style.py         # Personal prompting style fingerprint
+│   ├── lang_detect.py   # Language detection (zh/ja/ko/en) via Unicode ranges
+│   ├── extractors_zh.py # Chinese feature extraction (jieba + Chinese regex)
+│   ├── persona.py       # 6 prompt personas (Architect/Debugger/Explorer/Novelist/Sniper/Teacher)
+│   └── wrapped.py       # WrappedReport dataclass + build_wrapped(db) aggregation
+├── adapters/
+│   ├── base.py         # BaseAdapter ABC
+│   ├── 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)
+│   ├── aider.py        # Aider markdown chat history parser (.aider.chat.history.md)
+│   ├── gemini.py       # Gemini CLI JSON session parser (~/.gemini/tmp/)
+│   ├── cline.py        # Cline VS Code agent task parser (globalStorage/saoudrizwan.claude-dev/)
+│   ├── chatgpt.py      # ChatGPT conversations.json export parser
+│   └── claude_chat.py  # Claude.ai web chat export parser (JSON/ZIP)
+├── embeddings/
+│   ├── base.py         # BaseEmbedder ABC
+│   ├── tfidf.py        # Default (sklearn, zero config)
+│   ├── ollama.py       # Optional: pip install reprompt-cli[ollama]
+│   ├── local_embed.py  # Optional: pip install reprompt-cli[local] (sentence-transformers)
+│   └── openai_embed.py # Optional: pip install reprompt-cli[openai]
+├── bridge/
+│   ├── protocol.py    # Native Messaging stdio protocol (4-byte length-prefixed JSON)
+│   ├── handler.py     # Message handler (ping, sync_prompts, get_status)
+│   ├── host.py        # Entry point launched by Chrome/Firefox as subprocess
+│   └── manifest.py    # Manifest generator for Chrome/Firefox/Chromium
+├── commands/
+│   ├── wrapped.py     # `reprompt wrapped` CLI command (--json, --html, --share)
+│   └── telemetry.py   # `reprompt telemetry on|off|status` subcommands
+├── telemetry/
+│   ├── consent.py     # TelemetryConsent enum, install_id, TOML persistence
+│   ├── events.py      # Pydantic TelemetryEvent model, bucketing helpers
+│   ├── queue.py       # SQLite telemetry_queue CRUD with 30-day TTL
+│   ├── sender.py      # HTTP batch sender (urllib, 2s timeout, fire-and-forget)
+│   ├── collector.py   # Orchestrator: consent → event → queue → sender
+│   └── prompt.py      # First-run consent prompt (Rich)
+├── sharing/
+│   ├── client.py      # HMAC-SHA256 signed upload to getreprompt.dev/api/share
+│   └── clipboard.py   # Cross-platform clipboard copy (pbcopy/xclip/xsel)
+├── storage/
+│   └── db.py           # SQLite: prompts, processed_sessions, prompt_patterns, term_stats
+└── output/
+    ├── terminal.py         # Rich tables + bar charts + hot terms + clusters
+    ├── json_out.py         # JSON for pipelines
+    ├── markdown.py         # Markdown export
+    ├── wrapped_terminal.py # Rich Prompt Wrapped report rendering
+    └── wrapped_html.py     # Self-contained HTML share card (dark theme)
+```
+
+## Data Flow
+
+```
+Session files → Adapter.parse() → list[Prompt]
+  → DedupEngine: SHA-256 exact → TF-IDF cosine similarity
+  → SQLite: insert unique prompts, mark dupes
+  → Analyzer: TF-IDF hot terms + K-means clusters
+  → Library: extract high-frequency patterns, auto-categorize
+  → Output: terminal / JSON / Markdown
+```
+
+## Open-Core Architecture (Three Repos)
+
+```
+reprompt (public)              ← THIS REPO: open-source CLI core, PyPI: reprompt-cli
+reprompt-pro (private)         ← Commercial plugin: persona, wrapped, telemetry
+reprompt-extension (private)   ← Browser extension: Chrome/Firefox prompt capture
+```
+
+- Plugin system: `cli.py` loads `entry_points(group="reprompt.plugins")` at startup
+- reprompt-pro registers via `[project.entry-points."reprompt.plugins"]` in its pyproject.toml
+- To enable pro features: `cd ~/projects/reprompt && uv pip install -e ../reprompt-pro`
+- Extension connects via Native Messaging bridge (`bridge/` module)
+- **Rule:** Commercial code never enters this repo. Pro features go to reprompt-pro.
+
+## Key Conventions
+
+- Package name: `reprompt-cli` (PyPI), CLI command: `reprompt`
+- Python >=3.10, type hints required, mypy strict
+- ruff for lint + format (line-length=100)
+- All db methods use try/finally for conn.close()
+- 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, 923 tests, 95% coverage target
+
+## Prompt Science Engine
+
+Research-backed prompt analysis (added v0.6.0):
+- `reprompt score "prompt"` — instant 0-100 scoring with breakdown
+- `reprompt compare "a" "b"` — side-by-side feature comparison
+- `reprompt insights` — personal patterns vs research-optimal
+
+Papers: Google 2512.14982 (repetition), Stanford 2307.03172 (position),
+SPELL EMNLP 2023 (perplexity), Prompt Report 2406.06608 (taxonomy).