ezscreen 0.1.0__tar.gz

ezscreen-0.1.0/.ai_context/00_PROJECT_VIBE.md

@@ -0,0 +1,72 @@
+# 00 — Project Vibe
+
+> **STATUS: INITIALIZED FROM HANDOFF DOCUMENT**
+
+---
+
+## Core Vision
+
+**ezscreen** is a command-line tool that makes GPU-accelerated virtual screening accessible to researchers who do not have access to high-performance computing hardware. It automates the entire molecular docking pipeline — from receptor and ligand preparation through docking, hit filtering, and pose validation — using Kaggle's free T4 GPU infrastructure as the compute backend.
+
+---
+
+## The Problem We Are Solving
+
+Computational chemists and pharmacologists at under-resourced institutions spend hours configuring docking tools, managing file formats, and debugging prep pipelines before any science gets done. ezscreen collapses this into an interactive CLI with sensible defaults and a guided decision tree.
+
+---
+
+## Target Users
+
+Researchers and students in molecular biology, pharmacology, and computational chemistry who are:
+- Comfortable with a terminal
+- Not necessarily expert computational chemists
+- Using Kaggle or Google Colab for GPU access
+- At institutions without dedicated HPC infrastructure
+
+---
+
+## The North Star Statement
+
+> *"A researcher with a PDB code and a ligand library should be able to run GPU-accelerated virtual screening in under 10 minutes, with no HPC access and no configuration expertise."*
+
+---
+
+## Non-Negotiable Core Features (v1 MVP)
+
+1. **`ezscreen run`** — Full interactive guided pipeline: receptor prep → binding site detection → ligand prep → ADMET pre-filter → docking on Kaggle T4 → results
+2. **`ezscreen auth`** — Credential wizard for Kaggle API + NVIDIA NIM (optional)
+3. **`ezscreen status`** — Live job monitor with auto-refresh, attach/resume/delete actions
+4. **`ezscreen resume [run-id]`** — Checkpoint-based resume for interrupted runs (SQLite state)
+5. **`ezscreen validate`** — Stage 2 DiffDock-L hit validation via NVIDIA NIM API
+6. **`ezscreen admet`** — Standalone ADMET filtering on any CSV or SDF
+7. **`ezscreen view`** — Rich table + py3Dmol self-contained HTML results viewer
+8. **`ezscreen clean [run-id]`** — Remove Kaggle dataset + kernel artifacts for a run
+
+---
+
+## UX Non-Negotiables
+
+- Every screen has a `← Back` option
+- Breadcrumb trail always shown at top of every screen
+- Never exit to a bare terminal prompt — always offer next logical action
+- Full raw parameter set always shown on confirmation screen (for citation)
+- No silent defaults on consequential decisions
+- ctrl+c detaches gracefully — Kaggle kernel continues running
+- No emoji in terminal output — color-coded with specific hex palette (see `01_TECH_ARCHITECTURE.md`)
+
+---
+
+## Scope — v1 Only
+
+> ⚠️ Features marked v2 in the handoff are **explicitly deferred** and must not be implemented in v1.
+
+**Out of scope for v1:**
+- Local compute backend (no Kaggle)
+- Google Colab backend
+- `ezscreen refine` — MD / MMGBSA post-docking
+- Web dashboard (Gradio / Streamlit)
+- Multi-target screening (one library vs N receptors)
+- Deep ADMET (ADMET-AI, pkCSM)
+- Collaboration / team hit lists
+- Consensus docking (UniDock-Pro + Gnina)

ezscreen-0.1.0/.ai_context/01_TECH_ARCHITECTURE.md

@@ -0,0 +1,240 @@
+# 01 — Tech Architecture
+
+> **STATUS: ALL DECISIONS FINAL — from handoff document**
+
+---
+
+## Tech Stack
+
+| Layer | Technology | Rationale |
+|---|---|---|
+| CLI framework | **Typer** | Cleaner nested subcommands than Click; type-hint driven; less boilerplate |
+| Terminal output | **Rich** | Progress bars, styled tables, panels, syntax highlighting |
+| Interactive prompts | **Questionary** | Styled select menus, checkboxes, text inputs via prompt-toolkit |
+| Config format | **TOML** | No YAML Norway-problem bugs; `tomllib` in stdlib (3.11+); `tomli-w` for writing |
+| Python floor | **3.10 minimum** | 3.11+ preferred; compatibility matrix must be verified before finalising |
+| Package distribution | **pip first** | `pyproject.toml`; conda-forge recipe filed after stable v1 release |
+| Checkpointing | **SQLite** | Run state, shard status, resume by run-id |
+| Notebook templating | **Jinja2** | Renders complete `.ipynb` from template variables |
+
+---
+
+## Docking Engines
+
+| Stage | Engine | Notes |
+|---|---|---|
+| Stage 1 primary | **UniDock-Pro** | SBVS + LBVS + Hybrid; Apache 2.0; built from source on Kaggle (CUDA ≥ 11.8 + Boost) |
+| Stage 1 fallback | **UniDock** | `pip install unidock-tools`; used when no reference ligand is available |
+| Stage 2 validation | **DiffDock-L** | Via NVIDIA NIM API; free; called locally (not on Kaggle) |
+| v2 (deferred) | Local backend, Colab backend, MD/MMGBSA | Do not implement |
+
+> ⚠️ UniDock-Pro build from source happens in notebook template Cell 2 on Kaggle.
+
+---
+
+## Prep Pipeline
+
+| Step | Tool | Notes |
+|---|---|---|
+| Receptor prep | pdbfixer → Meeko `mk_prepare_receptor` | Missing residues, waters, alternates, hydrogens |
+| Ligand prep | scrub.py → RDKit ETKDG → Meeko | Protonation, 3D conformers, PDBQT output |
+| Pocket detection | Tiered (see below) | co-crystal → residues → P2Rank → blind |
+| ADMET filtering | RDKit | Ro5, PAINS, toxicophores, Veber, Egan BBB |
+| Molscrub install | `git+https://github.com/forlilab/scrubber` | Not on PyPI — pinned in pyproject.toml |
+
+---
+
+## Package Structure
+
+```
+ezscreen/
+├── cli.py                  # Typer entry points — all subcommands
+├── state.py                # State machine — BACK sentinel, context dict
+├── config.py               # TOML loader/writer — ~/.ezscreen/config.toml
+├── auth.py                 # Credential management — ~/.ezscreen/credentials
+├── backends/
+│   └── kaggle/
+│       ├── runner.py       # Orchestrates dataset push + kernel + poll + download
+│       ├── dataset.py      # Kaggle datasets API wrapper
+│       ├── kernel.py       # Kaggle kernels API wrapper
+│       ├── poller.py       # Status polling — Rich progress, retry logic
+│       └── templates/
+│           └── vina_shard.ipynb.j2   # Jinja2 notebook template
+├── prep/
+│   ├── receptor.py         # pdbfixer + Meeko receptor prep
+│   └── ligands.py          # scrub.py + RDKit + Meeko ligand prep
+├── pocket/
+│   └── detect.py           # Tiered pocket detection
+├── admet/
+│   └── filter.py           # RDKit ADMET filters
+├── results/
+│   ├── merger.py           # Merge shard CSVs, global re-rank
+│   └── viewer.py           # Rich table + py3Dmol HTML generator
+├── checkpoint.py           # SQLite run state — create, update, resume
+├── report.py               # Prep report — .txt + .json writer
+├── errors.py               # Error taxonomy — all error classes
+└── vendor/
+    └── scrubber/           # Vendored molscrub (if vendoring decided)
+```
+
+---
+
+## Config Files
+
+### `~/.ezscreen/config.toml` — preferences only, never secrets
+
+```toml
+[run]
+auto_resume_threshold = 10   # auto-resume if failure % >= this
+shard_retry_limit = 3        # retries before prompting user
+default_search_depth = "Balanced"
+default_ph = 7.4
+admet_pre_filter = true
+
+[kaggle]
+default_dataset = "username/ezscreen-workspace"
+
+[defaults]
+box_padding = 5.0
+enumerate_tautomers = false
+```
+
+### `~/.ezscreen/credentials` — chmod 600 enforced — NEVER in config.toml
+
+```
+kaggle_json_path = "~/.kaggle/kaggle.json"
+nim_api_key = "nvapi-xxxxxxxxxxxx"
+```
+
+---
+
+## Kaggle Dataset Strategy
+
+- Single persistent dataset: `ezscreen-workspace` per user
+- Local manifest at `~/.ezscreen/manifest.json` — SHA-256 hash dedup
+- Receptor: uploaded once, reused across runs if hash matches
+- Ligand shards: always new per run
+- Dataset structure: `receptor_{hash8}.pdb`, `shard_{run_id}_{n}.sdf`
+- `ezscreen clean [run-id]` → deletes entire dataset + kernel artifacts
+
+---
+
+## Notebook Template Structure (Jinja2 → .ipynb)
+
+| Cell | Purpose |
+|---|---|
+| Cell 1 | Auto-generated header — do not edit |
+| Cell 2 | Install deps — UniDock-Pro build or UniDock pip, Meeko, RDKit |
+| Cell 3 | Environment check — GPU? CUDA version? Disk space? |
+| Cell 4 | Load inputs from `/kaggle/input/ezscreen-{run_id}/` |
+| Cell 5 | Receptor prep — pdbfixer → Meeko |
+| Cell 6 | Ligand prep — scrub.py → Meeko, batch processing |
+| Cell 7 | Docking loop — UniDock-Pro, writes checkpoint per shard |
+| Cell 8 | Collect results — write `scores.csv` + `poses.sdf` to `/kaggle/working/` |
+| Cell 9 | Write `done.flag` — signals clean completion to poller |
+
+> Every cell writes a structured `error.json` before raising. Poller distinguishes: timeout / prep failure / GPU OOM / clean completion.
+
+### Jinja2 Template Variables
+
+```python
+{
+  "run_id": "ezs-4f2a8c",
+  "engine": "unidock-pro",       # or "unidock"
+  "mode": "hybrid",              # sbvs | lbvs | hybrid
+  "box_center": [x, y, z],
+  "box_size": [sx, sy, sz],
+  "exhaustiveness": 8,
+  "num_modes": 3,
+  "refine_step": 5,
+  "max_step": 0,
+  "ph": 7.4,
+  "shard_index": 2,
+  "total_shards": 10,
+  "enumerate_tautomers": false,
+  "receptor_dataset_path": "/kaggle/input/ezscreen-abc123/receptor.pdb",
+  "ligand_dataset_path": "/kaggle/input/ezscreen-abc123/shard_02.sdf"
+}
+```
+
+---
+
+## State Machine (Back Button)
+
+```python
+BACK = object()  # sentinel
+
+def screen_binding_site(ctx):
+    choice = questionary.select(..., choices=[..., "← Back"]).ask()
+    if choice == "← Back":
+        return BACK
+    ctx["binding_site"] = choice
+    return ctx
+```
+
+---
+
+## Pocket Detection — Box Size Rules
+
+| Method | Box Definition |
+|---|---|
+| Co-crystal ligand | Envelope ligand atoms + 5Å padding per side |
+| Residue-defined | Convex hull of residue Cα atoms + 8Å padding |
+| P2Rank | Predicted pocket volume + 6Å padding |
+| Blind | Whole-protein bounding box + 4Å padding |
+
+⚠️ Warn if box volume > 30,000 ų (too large) or < 1,500 ų (too small).
+
+---
+
+## Search Depth Presets
+
+| Preset | Exhaustiveness | Poses | Description |
+|---|---|---|---|
+| Fast | 4 | 1 | triage only · misses ~25% best poses |
+| Balanced ★ | 8 | 3 | standard VS · good for rigid pockets |
+| Thorough | 16 | 5 | flexible ligands · induced-fit targets |
+| Exhaustive | 32 | 9 | allosteric/cryptic pockets · pub quality |
+| Expert | custom | custom | all params set manually |
+
+LBVS mode: Fast preset quietly sets `--no_refine` — not exposed to user.
+
+---
+
+## Terminal Color Palette
+
+| Color | Hex | Used for |
+|---|---|---|
+| Cyan | `#79c0ff` | Prompts, input fields, highlights |
+| Amber | `#e3b341` | Warnings, ETA, quota usage |
+| Green | `#3fb950` | Success states |
+| Red | `#f85149` | Errors, failures |
+| Gray | `#8b949e` | Secondary text, unselected options |
+| White bold | `#f0f6fc` | Primary text, headings |
+| Muted | `#6e7681` | Descriptions, supplementary info |
+| Dim | `#484f58` | Dividers, structural chrome |
+
+---
+
+## Shard & Retry Logic
+
+- Shard size: ~2,000 compounds per Kaggle kernel
+- `shard_retry_limit`: 3 (configurable)
+- `auto_resume_threshold`: 10% (configurable)
+- If `failure_pct < threshold`: prompt user (continue partial / resume / change threshold)
+- If `failure_pct >= threshold`: auto-resume without prompt
+- If auto-resume also fails: prompt permanently (continue partial / try later with checkpoint)
+
+---
+
+## Environment Variables (`.env.example`)
+
+```env
+# ezscreen does NOT use .env files for runtime config.
+# All user preferences → ~/.ezscreen/config.toml
+# All credentials    → ~/.ezscreen/credentials (chmod 600)
+#
+# For development/testing only:
+EZSCREEN_DEV_MODE=false
+EZSCREEN_LOG_LEVEL=INFO
+```

ezscreen-0.1.0/.ai_context/02_CODING_RULES.md

@@ -0,0 +1,143 @@
+# 02 — Coding Rules
+
+> **These rules are the non-negotiable law of this project. Every line of code must comply.**
+
+---
+
+## The 9 Operating Rules
+
+### Rule 1 — The Context Vault
+All project meta-knowledge lives in `/.ai_context/`. These 5 files are the absolute source of truth:
+- `00_PROJECT_VIBE.md` — Core vision and non-negotiable features
+- `01_TECH_ARCHITECTURE.md` — Tech stack, DB schemas, API routes
+- `02_CODING_RULES.md` — This file
+- `03_TASK_TRACKER.md` — Living checklist of features
+- `04_DECISION_LOG.md` — Running log of architectural decisions
+
+The AI must immediately output updated markdown for any file after a decision changes it.
+
+### Rule 2 — Human-Centric Commit Simulation
+- Write code in small, iterative, logically ordered pieces
+- Code must be clean, functional, and accurate
+- No intentional bugs, missing imports, or logical errors
+- No unsolicited comments in the code
+
+### Rule 3 — The State Tracker
+Every single response from the AI must end with a State Tracker block in this exact format:
+```
+---
+**STATE TRACKER**
+* **Current Phase:** [Name]
+* **Pending Tasks:**
+  - [ ] Task
+* **Completed Tasks:**
+  - [x] Task
+* **Recent Decisions:** [Brief summary]
+---
+```
+
+### Rule 4 — Test-Driven Vibe Validation
+Before writing logic for any complex module:
+1. The user provides the vibe/feature
+2. The AI writes edge cases and expected behavior
+3. The AI waits for explicit user approval before writing code
+
+### Rule 5 — Hard Checkpoints
+After every major component is complete:
+- Generate a summary of the current codebase state
+- Provide a simulated Git commit message as a mental fallback point
+
+### Rule 6 — The Scratchpad Pre-Computation Rule
+Before writing any code or vault file updates, the AI must use `<thinking> ... </thinking>` tags to:
+- Plan the architecture
+- Map out file dependencies
+- Catch logical flaws before outputting the final result
+
+### Rule 7 — The Devil's Advocate Clause
+Before implementing any new library, database, or major architectural change:
+- The AI must provide a strict 2-sentence warning detailing the biggest risk, bottleneck, or technical debt the choice might create
+
+### Rule 8 — `.env` / Secrets Guardrail
+- Never hardcode configuration values, API keys, database URIs, or sensitive data
+- All user preferences → `~/.ezscreen/config.toml`
+- All credentials → `~/.ezscreen/credentials` (chmod 600 enforced)
+- Keep `.env.example` updated in the Context Vault
+
+### Rule 9 — The Nuclear Reset Command
+If the user types `[SYSTEM RESET]`, the AI must:
+- Disregard all current conversational context and memory
+- Wipe its internal state entirely
+- Rely solely on the `.md` files in `/.ai_context/`
+- Await fresh instructions based only on those files
+
+---
+
+## Project-Specific Code Rules
+
+### Language & Version
+- Python 3.10 minimum (3.11+ preferred)
+- Type hints required on all function signatures
+- Use `tomllib` (stdlib 3.11+) or `tomli` (backport for 3.10) for TOML reads
+- Use `tomli-w` for TOML writes
+
+### CLI Architecture Rules
+- All Typer entry points live in `cli.py` only
+- Every screen function follows the BACK sentinel pattern from `state.py`
+- Context dict is passed forward through every prompt function — never use global state
+- Every questionary select must include `← Back` as the last choice
+
+### Error Handling Rules
+- All error classes defined in `errors.py` — never define inline
+- Error messages follow the 3-line format: what failed → why → exact fix/URL
+- Ligand prep failures: log to `failed.sdf`, never abort the run
+- Receptor prep failures: always fatal — clean message + exit
+- Kaggle transient errors: auto-retry with `⟳` indicator, up to `shard_retry_limit`
+
+### Security Rules
+- Credentials stored in `~/.ezscreen/credentials` only — chmod 600 enforced at write time
+- Warn if `config.toml` contains any string matching an API key pattern
+- Never log credentials — scrub from all log output
+
+### Output / UX Rules
+- No emoji in terminal output
+- Use the exact hex color palette defined in `01_TECH_ARCHITECTURE.md`
+- Breadcrumb trail must be rendered at the top of every screen
+- Confirmation screen must always show full raw parameter set (for citation)
+- Post-action routing: always offer viewer / next stage / main menu — never exit to bare prompt
+
+### Logging Rules
+- Every run writes to `~/.ezscreen/logs/ezs-{run_id}.log`
+- Log: full tracebacks, all API responses, every prep decision with timestamp, exact UniDock-Pro command, shard state transitions
+- Users never see logs unless something goes wrong
+
+---
+
+## Git Commit Convention
+
+Commit messages must sound like a real developer wrote them. No conventional commit prefixes. Natural English, lowercase, short and specific.
+
+```
+# Good — human, specific
+set up project layout and dependencies
+add all the error classes we'll need
+wire up the back button pattern
+stubbed out all 8 cli commands for now
+start on the kaggle dataset uploader
+got receptor prep working with pdbfixer and meeko
+fix auth wizard blowing up on missing kaggle.json
+add admet filter — ro5 and pains for now
+
+# Bad — robotic
+feat(errors): add full error taxonomy
+chore(scaffold): initialize package structure and pyproject.toml
+fix(backend): handle Kaggle 403 forbidden during kernel push
+```
+
+---
+
+## Code Style
+- Formatter: **black** (line length 88)
+- Linter: **ruff**
+- Import order: stdlib → third-party → local (enforced by ruff isort)
+- No unsolicited inline comments
+- Docstrings: Google style, only on public-facing functions

ezscreen-0.1.0/.ai_context/03_TASK_TRACKER.md

@@ -0,0 +1,148 @@
+# 03 — Task Tracker
+
+> **The living checklist. Updated after every session.**  
+> `[ ]` = pending · `[/]` = in progress · `[x]` = done
+
+---
+
+## Phase 0 — Project Initialization ✅
+
+- [x] Establish the 9 Operating Rules
+- [x] Create the Context Vault (`.ai_context/` directory)
+- [x] Ingest full handoff document (ezscreen_handoff.md)
+- [x] Populate all 5 vault files from handoff
+- [x] Resolve 5 open discussion items (see `04_DECISION_LOG.md`)
+- [x] Finalize Python 3.11 floor decision
+
+---
+
+## Phase 1 — Project Scaffold
+
+> One unit of work per commit. Write → commit → next.
+
+### ~~"set up project layout and dependencies"~~ ✅ `b7afda3`
+- [x] `pyproject.toml` — Python 3.11+, all deps pinned, hatchling build, ruff + black config
+- [x] `ezscreen/__init__.py` — exposes `__version__`
+- [x] All subpackage `__init__.py` files
+- [x] `tests/__init__.py`
+
+### ~~"add all the error classes we'll need"~~ ✅ `591d532`
+- [x] `ezscreen/errors.py` — 18 classes across 7 categories
+
+### ~~"wire up the back button pattern"~~ ✅ `591d532`
+- [x] `ezscreen/state.py` — BACK sentinel + `make_context()` (swept into same commit)
+
+### ~~"stubbed out all 8 cli commands for now"~~ ✅ `9075f14`
+- [x] `ezscreen/cli.py` — Typer app + 8 subcommand stubs (no logic)
+
+---
+
+## Phase 2 — Core Foundation Modules
+
+### ~~"add config loading and writing"~~ ✅ `c2d9891`
+- [x] `ezscreen/config.py` — load/write `~/.ezscreen/config.toml`
+
+### ~~"got the auth wizard working"~~ ✅ `83bca34`
+- [x] `ezscreen/auth.py`
+  - [x] Kaggle: env var detection, validate kaggle.json, live API call
+  - [x] NIM: optional endpoint ping, skippable
+  - [x] Summary + write credentials (chmod 600)
+  - [x] Re-run mode: show existing state → ask which to update
+
+### ~~"add run checkpointing with sqlite"~~ ✅ `0c179bf`
+- [x] `ezscreen/checkpoint.py` — create run, update shard, increment retry, mark complete, resume by run-id
+
+---
+
+## Phase 3 — Prep Pipeline
+
+### ~~"got receptor prep working with pdbfixer and meeko"~~ ✅ `82206e2`
+- [x] `ezscreen/prep/receptor.py` — AF 4-tier, chain multi-select, RCSB fetch, pdbfixer, mk_prepare_receptor
+
+### ~~"ligand prep pipeline with fallback scrubber"~~ ✅ `82206e2`
+- [x] `ezscreen/prep/ligands.py` — scrubber fallback, SDF+SMILES recursive, ETKDG, Meeko, sharding, failed_prep.sdf
+
+### ~~"add tiered pocket detection"~~ ✅ `5aa5158`
+- [x] `ezscreen/pocket/detect.py` — co-crystal, residue Cα box, P2Rank top-3 + AF profile, blind, volume validation
+
+---
+
+## Phase 4 — ADMET Filtering
+
+### ~~"add admet filter — ro5 and pains for now"~~ ✅ `b6e7bde`
+- [x] `ezscreen/admet/filter.py` — Lipinski Ro5, PAINS, Brenk toxicophores, Veber, Egan BBB; per-filter config; library-level SDF pass-through with breakdown stats
+
+---
+
+## Phase 5 — Kaggle Backend
+
+### ~~"start on the kaggle dataset uploader"~~ ✅ `804e7bf`
+- [x] `dataset.py` — SHA-256 dedup, manifest, dataset create, delete support
+
+### ~~"add the kernel push wrapper"~~ ✅ `804e7bf`
+- [x] `kernel.py` — notebook push, exp backoff, kernel-metadata.json, delete
+
+### ~~"polling loop for running kaggle jobs"~~ ✅ `804e7bf`
+- [x] `poller.py` — 30s poll, Rich Live, error classification, retry signalling
+
+### ~~"kaggle runner that ties dataset and kernel together"~~ ✅ `804e7bf`
+- [x] `runner.py` — orchestrates full pipeline, retry loop, output download, clean_run()
+
+### ~~"jinja2 notebook template for kaggle"~~ ✅ `25a2602`
+- [x] `vina_shard.ipynb.j2` — 9 cells, UniDock-Pro/UniDock switch, scrubber fallback, error.json on every failure, done.flag
+
+---
+
+### ~~"start on the auth command"~~ ✅ `ed1f421`
+- [x] `commands/auth.py` — thin wrapper around auth.run_wizard()
+
+### ~~"add the status command"~~ ✅ `ecf1442`
+- [x] `commands/status.py` — Rich table, colour-coded status, run count
+
+### ~~"standalone admet command working"~~ ✅ `fefcfe6`
+- [x] `commands/admet.py` — interactive filter toggle, breakdown output
+
+### ~~"got the 3d viewer working"~~ ✅ `4316267`
+- [x] `commands/view.py` — Rich table + self-contained py3Dmol HTML viewer
+
+### ~~"validate command for diffdock nim"~~ ✅ `2e49e39`
+- [x] `commands/validate.py` — DiffDock-L REST, key guard, timeout/auth mapping
+
+### ~~"the big run command — full decision tree"~~ ✅ `bb58e91`
+- [x] `commands/run.py` — 8-step state machine (receptor→chains→AF→pocket→ligands→ADMET→depth→confirm→submit)
+
+### ~~"wire all commands into cli.py"~~ ✅ `cd8e472`
+- [x] `cli.py` — all 8 subcommands wired with typed Typer arguments
+
+---
+
+## Phase 7 — Results & Reporting
+
+### ~~"merge shard results and render the viewer"~~ ✅ `af6b008`
+- [x] `results/merger.py` — CSV merge, best-score dedup, global sort, SDF + failed_prep concat
+
+### ~~"prep report writer"~~ ✅ `2988862`
+- [x] `report.py` — Section 8.3 JSON schema, `.txt` human-readable, Rich summary panel
+
+---
+
+## Phase 8 — Status Screen & Version Check
+
+### ~~"ezscreen status with live refresh"~~ ✅ `388efb2`
+- [x] `ezscreen status` — 30s auto-refresh
+- [x] Version check async + PyPI banner ✅ `45a2986`
+
+---
+
+## Phase 9 — Polish & Packaging
+
+### ~~"final cleanup and readme"~~ ✅
+- [x] Smoke test — merger, report, version_check ✅ `9cdebb5`
+- [x] `README.md` — install + quickstart ✅ `3c2674a`
+- [ ] Conda-forge recipe (post pip release)
+
+---
+
+## Backlog / Nice-to-Have (Post v1)
+
+- All v2 features from handoff Section 16