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

{reprompt_cli-0.9.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.9.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-0.9.2 → reprompt_cli-1.0.0}/CHANGELOG.md

@@ -2,6 +2,94 @@
 
 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

reprompt_cli-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: reprompt-cli
+Version: 1.0.0
+Summary: Discover, analyze, and evolve your best prompts from AI coding sessions
+Project-URL: Homepage, https://github.com/reprompt-dev/reprompt
+Project-URL: Repository, https://github.com/reprompt-dev/reprompt
+Project-URL: Issues, https://github.com/reprompt-dev/reprompt/issues
+Project-URL: Changelog, https://github.com/reprompt-dev/reprompt/blob/main/CHANGELOG.md
+License: MIT
+License-File: LICENSE
+Keywords: ai,analytics,claude-code,cli,llm,prompt
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: scikit-learn>=1.4
+Requires-Dist: typer>=0.9
+Provides-Extra: chinese
+Requires-Dist: jieba>=0.42; extra == 'chinese'
+Provides-Extra: dev
+Requires-Dist: jieba>=0.42; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: local
+Requires-Dist: sentence-transformers>=2.0; extra == 'local'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0; extra == 'mcp'
+Provides-Extra: ollama
+Requires-Dist: requests>=2.31; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# `re:prompt`
+
+**Grammarly for Prompts** -- analyze your AI conversations with research-backed scoring.
+
+[![PyPI version](https://img.shields.io/pypi/v/reprompt-cli)](https://pypi.org/project/reprompt-cli/)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/reprompt-cli)](https://pypi.org/project/reprompt-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-923-brightgreen)](https://github.com/reprompt-dev/reprompt)
+[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](https://github.com/reprompt-dev/reprompt)
+
+---
+
+## See it in action
+
+```bash
+$ pip install reprompt-cli
+$ reprompt scan --source claude-code
+  Scanning 890 sessions... Found 1,063 prompts (295 unique)
+
+$ reprompt score "Fix the auth bug in src/login.ts where JWT expires"
+  Score: 74/100
+  Structure: 18/25 | Context: 22/25 | Position: 15/20 | Repetition: 9/15 | Clarity: 10/15
+  Tip: Add the error message for +15% accuracy
+
+$ reprompt wrapped --share
+  Your Prompt DNA: Architect (Score 78, better than 72% of prompters)
+  Share link: https://getreprompt.dev/w/abc123
+```
+
+## What it does
+
+| Command | Description |
+|---------|-------------|
+| `reprompt scan` | Scan 8+ AI tools for prompts (Claude Code, Cursor, Aider, Gemini CLI, Cline, OpenClaw, ChatGPT, Claude.ai) |
+| `reprompt score` | Instant 0-100 scoring with 30+ research-backed features |
+| `reprompt compare` | Side-by-side analysis of two prompts |
+| `reprompt wrapped` | Your Prompt DNA report -- persona, scores, shareable card |
+| `reprompt insights` | Personal patterns vs research-optimal |
+| `reprompt digest` | Weekly summary comparing current vs previous period |
+| `reprompt report` | Full analytics with hot terms, clusters, patterns |
+| `reprompt library` | Auto-extracted prompt patterns and templates |
+
+## Prompt Science
+
+Scoring is based on 4 research papers (Google, Stanford, EMNLP, Prompt Report) covering 30+ features across 5 dimensions:
+
+| Dimension | What it measures |
+|-----------|-----------------|
+| **Structure** | Markdown formatting, code blocks, explicit constraints |
+| **Context** | File paths, error messages, technical specificity |
+| **Position** | Instruction placement relative to context |
+| **Repetition** | Redundancy that degrades model attention |
+| **Clarity** | Readability, sentence length, ambiguity |
+
+All analysis runs locally in <1ms per prompt. No LLM calls, no network requests.
+
+## Supported AI tools
+
+| Tool | Format | Session location |
+|------|--------|-----------------|
+| Claude Code | JSONL | `~/.claude/projects/` |
+| Cursor | .vscdb | `~/Library/Application Support/Cursor/User/` |
+| Aider | Markdown | `.aider.chat.history.md` |
+| Gemini CLI | JSON | `~/.gemini/tmp/` |
+| Cline (VS Code) | JSON | `globalStorage/saoudrizwan.claude-dev/` |
+| OpenClaw / OpenCode | JSON | `~/.openclaw/` / `~/.opencode/sessions/` |
+| ChatGPT | JSON | `conversations.json` export |
+| Claude.ai | JSON/ZIP | Web chat export |
+
+## Installation
+
+```bash
+pip install reprompt-cli          # core
+pip install reprompt-cli[chinese] # + Chinese prompt support
+pip install reprompt-cli[mcp]     # + MCP server for Claude Code / Continue.dev / Zed
+```
+
+## Privacy
+
+- All analysis runs locally. No prompts leave your machine.
+- Optional telemetry sends only anonymous 26-dimension feature vectors -- never prompt text.
+- Open source: audit exactly what's collected.
+
+[Privacy policy](https://getreprompt.dev/privacy)
+
+## Links
+
+- **Website:** [getreprompt.dev](https://getreprompt.dev)
+- **PyPI:** [reprompt-cli](https://pypi.org/project/reprompt-cli/)
+- **Privacy:** [getreprompt.dev/privacy](https://getreprompt.dev/privacy)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT

reprompt_cli-1.0.0/README.md

@@ -0,0 +1,98 @@
+# `re:prompt`
+
+**Grammarly for Prompts** -- analyze your AI conversations with research-backed scoring.
+
+[![PyPI version](https://img.shields.io/pypi/v/reprompt-cli)](https://pypi.org/project/reprompt-cli/)
+[![Python 3.10+](https://img.shields.io/pypi/pyversions/reprompt-cli)](https://pypi.org/project/reprompt-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Tests](https://img.shields.io/badge/tests-923-brightgreen)](https://github.com/reprompt-dev/reprompt)
+[![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)](https://github.com/reprompt-dev/reprompt)
+
+---
+
+## See it in action
+
+```bash
+$ pip install reprompt-cli
+$ reprompt scan --source claude-code
+  Scanning 890 sessions... Found 1,063 prompts (295 unique)
+
+$ reprompt score "Fix the auth bug in src/login.ts where JWT expires"
+  Score: 74/100
+  Structure: 18/25 | Context: 22/25 | Position: 15/20 | Repetition: 9/15 | Clarity: 10/15
+  Tip: Add the error message for +15% accuracy
+
+$ reprompt wrapped --share
+  Your Prompt DNA: Architect (Score 78, better than 72% of prompters)
+  Share link: https://getreprompt.dev/w/abc123
+```
+
+## What it does
+
+| Command | Description |
+|---------|-------------|
+| `reprompt scan` | Scan 8+ AI tools for prompts (Claude Code, Cursor, Aider, Gemini CLI, Cline, OpenClaw, ChatGPT, Claude.ai) |
+| `reprompt score` | Instant 0-100 scoring with 30+ research-backed features |
+| `reprompt compare` | Side-by-side analysis of two prompts |
+| `reprompt wrapped` | Your Prompt DNA report -- persona, scores, shareable card |
+| `reprompt insights` | Personal patterns vs research-optimal |
+| `reprompt digest` | Weekly summary comparing current vs previous period |
+| `reprompt report` | Full analytics with hot terms, clusters, patterns |
+| `reprompt library` | Auto-extracted prompt patterns and templates |
+
+## Prompt Science
+
+Scoring is based on 4 research papers (Google, Stanford, EMNLP, Prompt Report) covering 30+ features across 5 dimensions:
+
+| Dimension | What it measures |
+|-----------|-----------------|
+| **Structure** | Markdown formatting, code blocks, explicit constraints |
+| **Context** | File paths, error messages, technical specificity |
+| **Position** | Instruction placement relative to context |
+| **Repetition** | Redundancy that degrades model attention |
+| **Clarity** | Readability, sentence length, ambiguity |
+
+All analysis runs locally in <1ms per prompt. No LLM calls, no network requests.
+
+## Supported AI tools
+
+| Tool | Format | Session location |
+|------|--------|-----------------|
+| Claude Code | JSONL | `~/.claude/projects/` |
+| Cursor | .vscdb | `~/Library/Application Support/Cursor/User/` |
+| Aider | Markdown | `.aider.chat.history.md` |
+| Gemini CLI | JSON | `~/.gemini/tmp/` |
+| Cline (VS Code) | JSON | `globalStorage/saoudrizwan.claude-dev/` |
+| OpenClaw / OpenCode | JSON | `~/.openclaw/` / `~/.opencode/sessions/` |
+| ChatGPT | JSON | `conversations.json` export |
+| Claude.ai | JSON/ZIP | Web chat export |
+
+## Installation
+
+```bash
+pip install reprompt-cli          # core
+pip install reprompt-cli[chinese] # + Chinese prompt support
+pip install reprompt-cli[mcp]     # + MCP server for Claude Code / Continue.dev / Zed
+```
+
+## Privacy
+
+- All analysis runs locally. No prompts leave your machine.
+- Optional telemetry sends only anonymous 26-dimension feature vectors -- never prompt text.
+- Open source: audit exactly what's collected.
+
+[Privacy policy](https://getreprompt.dev/privacy)
+
+## Links
+
+- **Website:** [getreprompt.dev](https://getreprompt.dev)
+- **PyPI:** [reprompt-cli](https://pypi.org/project/reprompt-cli/)
+- **Privacy:** [getreprompt.dev/privacy](https://getreprompt.dev/privacy)
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT

reprompt_cli-1.0.0/docs/roadmap.md

@@ -0,0 +1,74 @@
+# reprompt Roadmap
+
+> Last updated: 2026-03-16 · Current version: v1.0.0
+
+## Vision
+
+reprompt is the **prompt analytics** tool for AI sessions — understand your patterns, improve your prompting, 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.0.0) — Production Stable
+
+### Adapters (8)
+Claude Code · OpenClaw · Cursor IDE · Aider · Gemini CLI · Cline · ChatGPT · Claude.ai
+
+### Commands (23)
+`scan` · `import` · `report` · `library` · `trends` · `recommend` · `effectiveness` · `merge-view` · `save` · `templates` · `use` · `lint` · `search` · `demo` · `status` · `purge` · `install-hook` · `install-extension` · `extension-status` · `score` · `compare` · `insights` · `digest` · `style` · `wrapped` · `telemetry` · `mcp-serve`
+
+### 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
+
+### v1.0.0 Hardening (this release)
+- Empty-state UX guidance for `report` and `digest`
+- Scan "Try next" onboarding hints for new users
+- Feature extraction errors logged (no more silent swallowing)
+- DB schema versioning via `PRAGMA user_version`
+- CI: ≥90% coverage gate, pre-publish test step
+- Stable public API (`score_prompt`, `compare_prompts`, `extract_features`)
+- 935+ tests, ≥90% coverage
+
+---
+
+## v1.1+ — Future Work
+
+| Feature | Description |
+|---------|-------------|
+| `reprompt consolidate` | Automated prompt merging (currently read-only `merge-view` is sufficient) |
+| Homebrew formula | `brew install reprompt` via `homebrew-reprompt` tap |
+| SSE transport for MCP | Alternative to stdio for remote IDE setups |
+| More adapters | Perplexity, Mistral, Grok, Gemini Takeout |
+| `reprompt suggest` | Ollama-powered prompt improvement suggestions |
+| `.repromptignore` | Per-project filtering rules |
+| Team features | Anonymized pattern sharing, CI lint standards |
+| Windows Native Messaging | Extension support on Windows |
+
+Nothing beyond v1.1 is formally scheduled.
+
+---
+
+## 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-0.9.2 → reprompt_cli-1.0.0}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "reprompt-cli"
-version = "0.9.2"
+version = "1.0.0"
 description = "Discover, analyze, and evolve your best prompts from AI coding sessions"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"
 keywords = ["prompt", "llm", "ai", "cli", "analytics", "claude-code"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
@@ -32,8 +32,7 @@ local = ["sentence-transformers>=2.0"]
 openai = ["openai>=1.0"]
 mcp = ["fastmcp>=2.0"]
 chinese = ["jieba>=0.42"]
-science = ["textstat>=0.7", "yake>=0.4", "spacy>=3.7"]
-dev = ["pytest>=8.0", "ruff>=0.4", "mypy>=1.0", "pytest-cov>=5.0"]
+dev = ["pytest>=8.0", "ruff>=0.4", "mypy>=1.0", "pytest-cov>=5.0", "jieba>=0.42"]
 
 [project.scripts]
 reprompt = "reprompt.cli:app"
@@ -58,6 +57,13 @@ line-length = 100
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP"]
 
+[tool.coverage.run]
+omit = [
+    "src/reprompt/mcp.py",
+    "src/reprompt/mcp_main.py",
+    "src/reprompt/embeddings/ollama.py",
+]
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 

reprompt_cli-1.0.0/src/reprompt/__init__.py

@@ -0,0 +1,88 @@
+"""reprompt — Discover, analyze, and evolve your best prompts from AI coding sessions."""
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    # Core analysis
+    "score_prompt",
+    "compare_prompts",
+    "extract_features",
+    # Data access
+    "PromptDB",
+    "Prompt",
+    "PromptDNA",
+]
+
+
+def _grade(total: float) -> str:
+    """Map 0-100 score to letter grade."""
+    if total >= 85:
+        return "A"
+    if total >= 70:
+        return "B"
+    if total >= 55:
+        return "C"
+    if total >= 40:
+        return "D"
+    return "F"
+
+
+def score_prompt(text: str) -> dict:
+    """Score a prompt and return breakdown dict. Public API."""
+    from reprompt.core.extractors import extract_features as _extract
+    from reprompt.core.scorer import score_prompt as _score
+
+    dna = _extract(text, source="api", session_id="")
+    breakdown = _score(dna)
+    return {
+        "total": breakdown.total,
+        "dimensions": {
+            "structure": breakdown.structure,
+            "context": breakdown.context,
+            "position": breakdown.position,
+            "repetition": breakdown.repetition,
+            "clarity": breakdown.clarity,
+        },
+        "grade": _grade(breakdown.total),
+    }
+
+
+def compare_prompts(a: str, b: str) -> dict:
+    """Compare two prompts and return comparison dict. Public API."""
+    from reprompt.core.extractors import extract_features as _extract
+    from reprompt.core.scorer import score_prompt as _score
+
+    dna_a = _extract(a, source="api", session_id="")
+    dna_b = _extract(b, source="api", session_id="")
+    score_a = _score(dna_a)
+    score_b = _score(dna_b)
+    return {
+        "a": score_a.total,
+        "b": score_b.total,
+        "winner": "a" if score_a.total >= score_b.total else "b",
+    }
+
+
+def extract_features(text: str):
+    """Extract PromptDNA features. Public API."""
+    from reprompt.core.extractors import extract_features as _extract
+
+    return _extract(text, source="api", session_id="")
+
+
+# Lazy imports for type access
+def __getattr__(name):
+    if name == "PromptDB":
+        from reprompt.storage.db import PromptDB
+
+        return PromptDB
+    if name == "Prompt":
+        from reprompt.core.models import Prompt
+
+        return Prompt
+    if name == "PromptDNA":
+        from reprompt.core.prompt_dna import PromptDNA
+
+        return PromptDNA
+    raise AttributeError(f"module 'reprompt' has no attribute {name!r}")

{reprompt_cli-0.9.2 → reprompt_cli-1.0.0}/src/reprompt/cli.py

@@ -101,6 +101,13 @@ def scan(
                 "after every Claude Code session.[/dim]"
             )
 
+    # Next steps for new users (show once, on first scan with data)
+    if result.new_stored > 0 and stats.get("total_prompts", 0) <= result.new_stored + 10:
+        console.print("\n[bold]Try next:[/bold]")
+        console.print('  reprompt score [dim]"your prompt"[/dim]   — instant quality score')
+        console.print("  reprompt library              — see your prompt patterns")
+        console.print("  reprompt insights             — personal analysis")
+
 
 def _hook_registered() -> bool:
     """Check if reprompt hook is registered in Claude Code settings."""
@@ -223,7 +230,11 @@ def import_file(
             dna.overall_score = breakdown.total
             db.store_features(dna.prompt_hash, dna.to_dict())
         except Exception:
-            pass
+            import logging
+
+            logging.getLogger("reprompt.cli").debug(
+                "Feature extraction failed during import: %s", exc_info=True
+            )
 
     # Mark file as processed
     db.mark_session_processed(str(path), source=adapter.name)
@@ -242,6 +253,9 @@ def report(
     output: str = typer.Option("", "--output", "-o", help="Output file path (for --html)"),
     top: int = typer.Option(20, help="Number of top terms to show"),
     clusters: int = typer.Option(0, "--clusters", help="Number of clusters (0 = auto-select)"),
+    source: str = typer.Option(
+        "", "--source", "-s", help="Filter by source (e.g. chatgpt-ext, claude-ext, claude-code)"
+    ),
 ) -> None:
     """Generate analytics report."""
     from reprompt.config import Settings
@@ -249,7 +263,16 @@ def report(
 
     settings = Settings()
     n_clusters_arg = clusters if clusters > 0 else None
-    data = build_report_data(settings=settings, n_clusters=n_clusters_arg)
+    source_filter = source if source else None
+    data = build_report_data(settings=settings, n_clusters=n_clusters_arg, source=source_filter)
+
+    # Early exit with guidance when DB is empty
+    total = data.get("overview", {}).get("total_prompts", 0)
+    if total == 0:
+        console.print(
+            "No prompts found. Run [bold]reprompt scan[/bold] to analyze your AI sessions."
+        )
+        return
 
     if html:
         import webbrowser
@@ -345,6 +368,9 @@ def library(
 def search(
     query: str = typer.Argument(..., help="Search term (case-insensitive)"),
     limit: int = typer.Option(20, help="Maximum results to show"),
+    source: str = typer.Option(
+        "", "--source", "-s", help="Filter by source (e.g. chatgpt-ext, claude-ext, claude-code)"
+    ),
 ) -> None:
     """Search your prompt history by keyword."""
     from reprompt.config import Settings
@@ -352,7 +378,8 @@ def search(
 
     settings = Settings()
     db = PromptDB(settings.db_path)
-    results = db.search_prompts(query, limit=limit)
+    source_filter = source if source else None
+    results = db.search_prompts(query, source=source_filter, limit=limit)
 
     if not results:
         console.print(f"No prompts matching [bold]{query}[/bold]")
@@ -959,6 +986,20 @@ def digest(
             print(render_digest_history(rows, period), end="")
         return
 
+    stats = db.get_stats()
+
+    # Early guidance when DB is empty (after history check)
+    if stats.get("total_prompts", 0) == 0:
+        if quiet:
+            print("reprompt: no data yet — run reprompt scan")
+        elif format == "json":
+            print(json_mod.dumps({"error": "no data", "hint": "run reprompt scan"}))
+        else:
+            console.print(
+                "No prompt data yet. Run [bold]reprompt scan[/bold] first to populate the database."
+            )
+        return
+
     data = build_digest(db, period=period)
 
     if quiet: