release: v0.2.1 — packaging hotfix

Bumps version. Adds RELEASE_NOTES_v0.2.1.md (consumed by release.yml).
Includes two follow-ups that got lost in the squash of PR #9:
  - gitignore docs/planning/ (internal recall worklist)
  - drop two stale docs/planning/ links from recall-investigation.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: arnav2

.gitignore

@@ -71,5 +71,8 @@ rust/**/Cargo.lock.bak
 # Downloaded benchmark corpora (see scripts/download_corpora.sh)
 data/corpora/
 
+# Internal planning notes (kept locally, not published to the open-source repo)
+docs/planning/
+
 # Conductor / Claude Code transient state
 .claude/

CHANGELOG.md

@@ -45,6 +45,8 @@ Template for a new release (copy this block, fill in, move Unreleased items in):
 
 ## [Unreleased]
 
+## [0.2.1] — 2026-05-19
+
 ### ⚠️ BREAKING (Fixed — see also #ks-xlsx-parser channel report)
 - Repository layout flattened on `src/` was leaking 13 generic top-level
   packages (`models`, `utils`, `parsers`, …) into installed wheels and

docs/launch/RELEASE_NOTES_v0.2.1.md

@@ -0,0 +1,92 @@
+# ks-xlsx-parser v0.2.1 — Packaging hotfix 📦
+
+**Headline:** v0.2.0 shipped a broken wheel. `from ks_xlsx_parser.pipeline import parse_workbook` (and every public entry point that depends on it) raised `ModuleNotFoundError` for everyone who installed from PyPI. **v0.2.1 fixes it.**
+
+If you're on 0.2.0:
+
+```bash
+pip install --upgrade ks-xlsx-parser   # or: uv pip install --upgrade ks-xlsx-parser
+python -c "from ks_xlsx_parser.pipeline import parse_workbook; print('ok')"
+```
+
+## What was broken
+
+The source tree was laid out flat under `src/` — `pipeline.py` and `api.py` as top-level *modules*, with 13 sibling *packages* (`models`, `utils`, `parsers`, `analysis`, …) next to them. The setuptools build picked up the packages but **silently dropped the top-level modules**, because `[tool.setuptools.packages.find]` only finds packages, never modules. The published wheel's `top_level.txt`:
+
+```
+analysis annotation charts chunking comparison export formula
+ks_xlsx_parser models parsers rendering storage utils verification
+```
+
+— 14 top-level entries, 13 of them generic. Two consequences:
+
+1. `from ks_xlsx_parser.pipeline import ...` failed because `pipeline.py` was never copied into the wheel.
+2. Anyone with an unrelated `models` / `utils` / `parsers` package in `site-packages` had it shadowed by ks-xlsx-parser's internal ones.
+
+CI couldn't catch this because the test matrix used an editable install — `src/` lives on `sys.path` and the wheel-packaging defect is invisible.
+
+## What changed in 0.2.1
+
+* **Proper nested package.** Everything now lives under `src/ks_xlsx_parser/`. The wheel's `top_level.txt` contains only `ks_xlsx_parser`. Imports inside the package switched from `from pipeline import …` to relative / fully-qualified `ks_xlsx_parser.pipeline`.
+* **`scripts/verify_wheel.py`** — builds the wheel, installs it in a clean venv, asserts the public import surface resolves and there's no namespace pollution. Wired into both `ci.yml` (new `wheel-check` job — required) and `release.yml` (a `Verify wheel` step that runs before PyPI publish). The class of bug that produced 0.2.0 cannot recur.
+* **CI overhaul** — separate `test` / `wheel-check` / `lint` / `typecheck` jobs; `uv`-backed installs (faster); `make install-dev` alias.
+* **Docker benchmark + accuracy tracking** — `Dockerfile.bench` reproduces the SpreadsheetBench retrieval benchmark; a new `.github/workflows/benchmark.yml` runs a 60-instance sample on every PR touching the parser and the full 912-corpus weekly. `scripts/append_bench_history.py` keeps a commit-over-commit history file. (Goal: text recall@5 > 0.90.)
+* **Recall failure triage** — `eval_retrieval.py --emit-failures` + `scripts/triage_recall.py` turn "recall@5 = X" into a bucket histogram with exemplar failures. `docs/recall-investigation.md` documents the diagnosis framework.
+
+## ⚠️ Breaking — if you depended on the leaked top-level packages
+
+Anyone whose downstream code did:
+
+```python
+from models import WorkbookDTO          # ← used to "work" because of the leak
+from parsers.workbook_parser import …
+```
+
+must update to:
+
+```python
+from ks_xlsx_parser.models import WorkbookDTO
+from ks_xlsx_parser.parsers.workbook_parser import …
+```
+
+If you only used the documented public surface (`from ks_xlsx_parser import parse_workbook` and `ks_xlsx_parser.pipeline.parse_workbook`), nothing changes — those names still resolve, and now they actually *load*.
+
+## Upgrade
+
+```bash
+pip install --upgrade ks-xlsx-parser
+# or
+uv pip install --upgrade ks-xlsx-parser
+```
+
+Then:
+
+```python
+from ks_xlsx_parser import parse_workbook
+result = parse_workbook(path="report.xlsx")
+print(result.workbook.total_cells)
+for chunk in result.chunks:
+    print(chunk.source_uri, chunk.render_text[:120])
+```
+
+## Verification used to ship this release
+
+```
+1041 passed, 11 deselected           # full test suite
+verifying ks_xlsx_parser-0.2.1-py3-none-any.whl
+wheel contents OK (61 entries, top-level: ks_xlsx_parser)
+clean-venv import OK
+wheel verification PASSED
+```
+
+`scripts/verify_wheel.py` ran as a release-workflow step before the PyPI publish, with the wheel that's now on PyPI.
+
+## Thanks
+
+Frank for the bug report — the channel screenshot was the right level of detail to reproduce in five minutes.
+
+## See also
+
+* [CHANGELOG.md](https://github.com/knowledgestack/ks-xlsx-parser/blob/main/CHANGELOG.md) — full diff log.
+* [`docs/recall-investigation.md`](https://github.com/knowledgestack/ks-xlsx-parser/blob/main/docs/recall-investigation.md) — diagnosis framework for the recall→0.90 roadmap.
+* [`docs/benchmark-local-setup.md`](https://github.com/knowledgestack/ks-xlsx-parser/blob/main/docs/benchmark-local-setup.md) — reproduce the benchmark on your laptop.

docs/recall-investigation.md

@@ -43,9 +43,11 @@ failures in the seed=1337 sample:
   `answer_position` cell range in `input.xlsx` is empty by design. A
   parser cannot retrieve what isn't there. These instances need to be
   filtered from the headline metric (TODO 05).
-* **30 are truly actionable** parser failures, clustering into 4 named
-  buckets (TODOs 00, 01, 02, 03, 04 in
-  [docs/planning/recall-90/](./planning/recall-90/)).
+* **30 are truly actionable** parser failures, clustering into a small
+  number of named buckets (benchmark-spec parser bugs in
+  `scripts/eval_retrieval.py`; array-formula rendering; chunk range vs
+  text mismatch; cell-drop / uncached-formula rendering; single-chunk
+  dilution).
 * Zero of the 30 are `present_but_ranked_low`. Chunk-size dilution
   may matter on the full 912-corpus but is NOT the dominant problem
   on the 200-sample.
@@ -60,9 +62,6 @@ When the in-scope filter is applied, real `recall_text@5` is
 **0.59**, not 0.635. Closing the 30 actionable failures gets us
 near 0.90 on the in-scope metric.
 
-See [docs/planning/recall-90/](./planning/recall-90/) for the
-ranked TODO list.
-
 ## A priori hypotheses (now confirmed/refuted; left as history)
 
 ### H1 — `present_but_ranked_low` is the biggest bucket

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ks-xlsx-parser"
-version = "0.2.0"
+version = "0.2.1"
 description = "Production-grade Excel Workflow Parser for RAG + auditability systems"
 readme = "README.md"
 license = {text = "MIT"}

src/ks_xlsx_parser/__init__.py

@@ -13,7 +13,7 @@
 """
 from __future__ import annotations
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 from .pipeline import (  # noqa: F401
     ParseResult,