cellproof 0.2.0__tar.gz

cellproof-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install
+        run: python -m pip install -e ".[dev,dbt]"
+      - name: Test
+        run: python -m pytest tests -q
+        env:
+          DBT_SEND_ANONYMOUS_USAGE_STATS: "False"

cellproof-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: publish
+
+# Publishing a GitHub release tagged vX.Y.Z uploads that version to PyPI.
+# Uses PyPI trusted publishing: no token is stored anywhere.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+      - name: Tag must match the version in pyproject.toml
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "${GITHUB_REF_NAME}" = "v${version}" || { echo "tag ${GITHUB_REF_NAME} != v${version}"; exit 1; }
+      - name: Test
+        run: |
+          python -m pip install -e ".[dev]"
+          python -m pytest tests -q
+      - name: Build
+        run: |
+          python -m pip install build
+          python -m build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

cellproof-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+.pytest_cache/
+*_dbt/
+*.duckdb
+target/
+logs/
+examples/commission_unsaved.xlsx
+examples/errors_unsaved.xlsx
+.superpowers/
+*.egg-info/
+dist/
+build/

cellproof-0.2.0/AGENTS.md

@@ -0,0 +1,46 @@
+# cellproof: guide for coding agents and contributors
+
+The project was called `unexcel` until 0.2.0; the older plans and specs still use that name.
+
+Read `README.md` first (what the tool does, limits), then `PROGRESS.md` (current state and next steps). `DESIGN.md` is
+the original spec; `docs/superpowers/specs/` and `docs/superpowers/plans/` hold the design and plan of each later
+piece. `PLAN*.md` are the early plans, kept for history.
+
+## Setup
+
+```bash
+python -m venv .venv && . .venv/bin/activate       # Windows: .venv\Scripts\activate
+pip install -e ".[dev,dbt,compute]"
+python -m pytest tests -q                            # dbt must be on PATH (activate the venv) or the dbt tests skip
+CELLPROOF_PERF=1 python -m pytest tests/test_perf.py -s  # 200k-formula benchmark
+```
+
+## Code map (`src/cellproof/`)
+
+| Module | Job |
+|---|---|
+| `model.py` | `Cell`, `Book`, `Verdict`, `Unsupported` (its message becomes the UNRESOLVED reason) |
+| `reader.py` | loads the workbook twice with openpyxl (formulas, saved values); refuses zip bombs |
+| `parser.py`, `refs.py` | formula text -> AST with Excel precedence; reference text -> `Area` |
+| `r1c1.py` | how a reference behaves when a formula is pasted down (same row, absolute, previous row, growing range) |
+| `regions.py` | finds regions (columns repeating one formula over the same rows), running totals, splits on cycles |
+| `graph.py`, `fenwick.py`, `rangeindex.py` | dependency order without expanding ranges; cycle detection |
+| `expr.py` | `Expr` (SQL value + SQL error code), Excel coercions |
+| `compiler.py` | cell mode: formula -> SQL in batches |
+| `region.py` | a region -> one set-based statement (window functions for running totals) |
+| `functions.py`, `fn/` | the 93 Excel functions |
+| `verifier.py` | runs everything on DuckDB and compares with Excel's saved values |
+| `emitter.py` | writes the dbt project; `--dbt` runs `dbt build` |
+| `report.py`, `cli.py`, `compute.py` | REPORT.md/report.json, the CLI, the optional `formulas` answer key |
+
+## Rules
+
+- **Never guess a value.** Anything not translated exactly raises `Unsupported("<reason a user understands>")`.
+- **A false PASS is the worst bug.** When unsure, produce an honest FAIL or UNRESOLVED.
+- **No DuckDB exception may escape from a supported function.** Guard every domain with `CASE`.
+- **Regions must equal cell mode.** `compile_book(book, regions=False)` is the reference; region tests compare against it.
+- **Runtime dependencies stay `openpyxl` and `duckdb`.** Anything else goes in an optional extra.
+- **Cell values never leave the machine.** No network calls with workbook data.
+- **Tests first**, console output ASCII-only (Windows consoles), measure before claiming speed.
+- **Real Excel is the ground truth**; the `formulas` library is only a labelled fallback answer key.
+- Commits made by an agent end with a `Co-Authored-By:` trailer for the agent.

cellproof-0.2.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 0.2.0 (2026-10-19)
+
+- **Renamed** from `unexcel` to `cellproof` (the old name clashed with an R package): `pip install cellproof`, command
+  `cellproof convert`, import `cellproof`, `CELLPROOF_PERF` for the benchmark, dbt project and database `cellproof`.
+- **Lookups row-wise:** VLOOKUP, HLOOKUP, MATCH, INDEX and XLOOKUP pasted down a column compile into one statement.
+  1,000 VLOOKUPs: verify 5.7 s -> 0.1 s.
+- **Criteria row-wise:** COUNTIFS (and SUMIF/AVERAGEIF(S) over a range holding an error) with a criterion from the row
+  no longer fall back to cell mode. 1,000 COUNTIFS: verify 29 s -> 0.1 s.
+- **Faster compile:** a pasted-down formula is tokenized once per run. 200k-formula benchmark 31 s -> 26 s; 50k
+  VLOOKUPs 8.9 s -> 4.6 s.
+- A lookup outside a region is about 20% slower than in 0.1.0 (one SQL form for both modes).
+
+## 0.1.0 (2026-10-18)
+
+First release, as `unexcel`.

cellproof-0.2.0/DESIGN.md

@@ -0,0 +1,117 @@
+# unexcel — Design (v1)
+
+> Status: **ACCEPTED 2026-10-11** (architecture, error handling, testing validated with user).
+> Working name. `unexcel` clashes with a CRAN R package / `drhrf/unexcel` repo — rename before launch.
+> Date: 2026-10-11
+
+---
+
+## 1. Understanding summary
+
+- **What:** `pip install` CLI. Input: Excel workbook (`.xlsx` / `.xlsm`). Output: dbt project that recomputes the workbook's numbers + a report proving every output cell matches.
+- **Why:** Business logic trapped in workbooks one person understands. Manual migration takes weeks, and nobody proves the numbers still match. Verified 2026-10-11: no open-source tool compiles Excel *formulas* to SQL/dbt. Existing tools copy *data*, not logic.
+- **Who:** Analysts, finance/ops teams, analytics engineers moving off Excel.
+- **Requirements from the user:** runs in anyone's environment, fast, reliable.
+- **Non-goals (v1):** VBA/macros, pivot tables, Power Query, charts, external links, Power BI output, web UI, `.xls`/`.xlsb`.
+
+## 2. Assumptions
+
+1. Workbooks up to ~50 sheets / ~200k formula cells. Target: under 5 min on a laptop. Measure it, don't promise it.
+2. v1 supports the ~80 most common functions. Every unsupported cell is reported as `UNRESOLVED`, never silently skipped.
+3. Match rule: numbers within 1e-9 relative, text exact, blank vs. 0 vs. error compared explicitly.
+4. Answer key = the cached values Excel saved in the file. If they're missing (file written by a script), compute them with the `formulas` library and label them `computed`, not `excel-saved`.
+5. Deterministic: same workbook in, same output out. AI answers are cached on disk.
+6. Solo maintainer, 4 weeks × ~15 h. Interview 5 analysts first; continue if at least 2 want to try it.
+
+## 3. Decision log
+
+| # | Decision | Alternatives | Why |
+|---|---|---|---|
+| D1 | Build unexcel | MetricProof, sqlport, whydrop-crew, pbi-doctor, onemetric | Verified gap, exact answer key, biggest audience |
+| D2 | Output a dbt project | plain SQL, pandas, PBI model | What teams ship; dbt runs on every warehouse |
+| D3 | CLI core, Hermes optional | Hermes required; two repos | Anyone can try it in a minute |
+| D4 | Rules first, AI for the rest | LLM-first; no AI | Fast, repeatable, free |
+| D5 | AI sees structure only | full values; opt-in flag | Finance data never leaves the machine |
+| D6 | Laya (local, Apache-2.0) default; Jev optional | Jev default | Jev is a closed, early-access cloud API |
+| D7 | Max 3 retries + no-progress stop + `UNRESOLVED` | max 5; loop until pass | Bounded and honest |
+| D8 | **Approach A:** deterministic compiler + thin captain loop on failures; cell-mode (C) fallback for non-table regions | B agent-native; C cell-only | B fails fast/reliable/portable; C alone gives unreadable SQL |
+| D9 | Verify loop on DuckDB directly; `dbt build` once at the end | dbt on every retry | dbt start-up costs seconds per call; the loop must be fast |
+
+## 4. Architecture
+
+```
+ .xlsx ─► reader ─► graph ─► regions ─► compiler ─► emitter ─► verifier ─► report
+                                 ▲          ▲                      │
+                                 │          └──── captain ◄────────┘ (failed / unsupported cells)
+                                 └── Decider adapter (Laya/Jev)  └── Translator adapter (any LLM)
+```
+
+Plain-code pipeline. The captain only wakes for cells the rules can't handle. Agents get narrow, typed jobs.
+
+### Components (one module each)
+
+| Module | Job | Built on |
+|---|---|---|
+| `reader` | Load the workbook twice: formulas + cached values. Resolve named ranges. List hidden sheets and merged cells. | `openpyxl` |
+| `graph` | Tokenize formulas → cell dependency graph → topological order. Circular refs → `UNRESOLVED`. | `openpyxl.formula.Tokenizer`, stdlib `graphlib` |
+| `regions` | Find tables: contiguous block, header row, same formula shape down a column (R1C1-equal). Ambiguous → ask the Decider. Low confidence → abstain → cell mode. | rules + Decider |
+| `compiler` | Formula AST → SQL expression. One registry entry per function (`SUMIFS` → grouped aggregate/join, `IF` → `CASE`, `VLOOKUP`/`XLOOKUP` → left join). | `sqlglot` expression builders |
+| `emitter` | Write the dbt project: input tables as seeds, one model per region, `schema.yml` tests, docs, lineage. Transpile to the target dialect. | `sqlglot`, Jinja-free string templates |
+| `verifier` | Run the compiled SQL on DuckDB and map result rows/cols back to cell addresses. Compare with the answer key → `PASS` / `FAIL(evidence)` / `UNRESOLVED(reason)`. | `duckdb` |
+| `captain` | For each failed group: build a task {formula, neighbour schema, failing evidence} → Translator → recompile → re-verify **only that group**. Max 3 rounds; stop if a round fixes nothing. | plain Python loop |
+| `report` | `REPORT.md` + `report.json`: pass/fail/unresolved counts, per-cell status, findings. | stdlib |
+| `adapters` | `Decider` (choice + probability, can abstain): Laya local default, Jev optional. `Translator`: one HTTP call to any LLM. Installed only via extras. | `unexcel[laya]`, `unexcel[llm]` |
+
+Hermes: separate optional skill that shells out to `unexcel convert`, returns the zip + report over Telegram. Not in the core package.
+
+## 5. Data flow (one run)
+
+1. `unexcel convert model.xlsx --out model_dbt/ [--target snowflake]`
+2. `reader` → in-memory cells (formula, cached value, type).
+3. `graph` → order + cycles.
+4. `regions` → tables + leftover cells (cell mode).
+5. `compiler` → SQL per region; unsupported cells queued.
+6. `verifier` → per-cell verdicts on DuckDB (seconds).
+7. `captain` → retries on queued/failed groups (≤3 rounds).
+8. `emitter` → dbt project; final `dbt build` on DuckDB as an end-to-end check.
+9. `report` → summary printed; the user reviews `REPORT.md` (the human gate). Nothing is pushed anywhere.
+
+Privacy: only formula text, headers, sheet names and types go to the adapters. Cell values never leave the process.
+
+## 6. Error handling & edge cases
+
+| Case | Behaviour |
+|---|---|
+| `.xls`, `.xlsb`, encrypted, corrupt | Clear error naming the format; exit code 2 |
+| Volatile `NOW`, `TODAY`, `RAND`, `OFFSET`, `INDIRECT` | `UNRESOLVED` (non-deterministic or dynamic reference) |
+| External links `[Book2.xlsx]` | `UNRESOLVED` |
+| Circular references | `UNRESOLVED`, cycle listed |
+| Excel errors `#N/A`, `#DIV/0!` | SQL `NULL` + error-kind column; compared by kind |
+| Numbers stored as text | Copy Excel semantics (`SUMIFS` skips them) + **finding** in the report |
+| Hard-coded value inside a formula column | Kept as an `overrides` seed + **finding** |
+| Dates | Excel serial → date with the 1900 leap-year bug (serial 60) handled; 1904 date system detected |
+| Whole-column refs `C:C` | Bound to the detected table's rows |
+| Merged cells, hidden sheets | Read normally; listed in the report |
+| No cached values | Compute with `formulas`, label `computed` |
+
+## 7. Testing strategy
+
+- **Fixtures:** small workbooks, one per function/edge case. Cached values come from a real recalculation (LibreOffice headless `--convert-to xlsx`), not hand-typed. LibreOffice differs from Excel on some functions, so a core set of ~20 fixtures is saved once in real Excel and treated as ground truth.
+- **Golden test:** for every fixture, `convert` → every cell `PASS` or the expected `UNRESOLVED`.
+- **Unit tests:** compiler registry (formula → SQL), region detection, date conversion.
+- **Rules-only baseline:** the full suite passes with no AI installed. An AI adapter stays only if it measurably lowers `UNRESOLVED` on the fixtures.
+- **Perf check:** one generated 200k-formula workbook, timed in CI.
+- **CI:** GitHub Actions on Windows, macOS, Linux × Python 3.10–3.13.
+
+## 8. Risks
+
+1. Excel function long tail (500+) → mitigated by honest `UNRESOLVED` + a contributor-friendly function registry.
+2. Region detection on messy sheets → cell-mode fallback; Decider abstains instead of guessing.
+3. Dialect drift (verified on DuckDB, shipped as Snowflake/BigQuery) → `--verify-on target` (post-v1).
+4. Name clash → rename before the PyPI publish.
+
+## 9. Open questions
+
+- License: MIT or Apache-2.0?
+- Demo workbook: a public financial model, or build a messy realistic one?
+- Final name.

cellproof-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikhil414 and cellproof contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cellproof-0.2.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: cellproof
+Version: 0.2.0
+Summary: Turn an Excel workbook into SQL (a dbt project on DuckDB) and prove every number matches.
+Project-URL: Homepage, https://github.com/Nikhil414/cellproof
+Project-URL: Issues, https://github.com/Nikhil414/cellproof/issues
+Author: Nikhil414
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dbt,duckdb,excel,migration,spreadsheet,sql,xlsx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Python: >=3.10
+Requires-Dist: duckdb>=1.1
+Requires-Dist: openpyxl>=3.1
+Provides-Extra: compute
+Requires-Dist: formulas<1.4,>=1.3.4; extra == 'compute'
+Provides-Extra: dbt
+Requires-Dist: dbt-duckdb>=1.8; extra == 'dbt'
+Provides-Extra: dev
+Requires-Dist: jinja2>=3.1; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# cellproof
+
+**Turn an Excel workbook into SQL, and prove every number matches.**
+
+(Released as `unexcel` up to 0.1.0; renamed to cellproof in 0.2.0.)
+
+Business logic often lives in a spreadsheet that one person understands. Moving it into a database is risky because
+nobody can show the new numbers equal the old ones. cellproof translates every formula of an `.xlsx` into SQL, runs that
+SQL on [DuckDB](https://duckdb.org), and compares each result with the value Excel itself saved in the file. Excel's
+saved values are a free answer key.
+
+```
+$ cellproof convert examples/functions.xlsx
+72 pass, 0 fail, 4 unresolved -> examples/functions_dbt/REPORT.md
+```
+
+Every formula cell gets one verdict:
+
+| Verdict | Meaning |
+|---|---|
+| **PASS** | the SQL gives the value Excel saved |
+| **FAIL** | the SQL gives a different value; the report shows both |
+| **UNRESOLVED** | cellproof could not translate the formula exactly; the report says why. It never guesses. |
+
+Exit code: `0` no FAIL, `1` at least one FAIL (or `dbt build` failed), `2` the workbook could not be read, `3`
+DuckDB rejected SQL that cellproof generated (a bug in cellproof; the message names the cell, please report it).
+
+## Install
+
+Python 3.10 or newer.
+
+```bash
+pip install cellproof
+pip install "cellproof[dbt]"      # also run dbt build (--dbt)
+pip install "cellproof[compute]"  # answer key for files never saved in Excel
+```
+
+Runtime dependencies are only `openpyxl` and `duckdb`.
+
+## Use
+
+```bash
+cellproof convert book.xlsx                 # writes book_dbt/ next to the file
+cellproof convert book.xlsx --out out_dir   # choose the folder
+cellproof convert book.xlsx --dbt           # also run `dbt build` on the generated project
+```
+
+The output folder holds:
+
+- **`REPORT.md` / `report.json`**: every verdict, failed cells with both values, unresolved cells with the reason,
+  findings (for example a number stored as text, which Excel skips in SUM), and which blocks of rows became readable
+  table models.
+- **A dbt project** (`dbt_project.yml`, `models/`, `seeds/input_cells.csv`) that recomputes the workbook on DuckDB.
+  It runs exactly the SQL the verifier checked.
+
+The workbook must have been saved by Excel (so the file holds Excel's values). For a file generated by code and never
+opened in Excel, install the `compute` extra: the [`formulas`](https://pypi.org/project/formulas/) library then
+computes the expected values, and the report labels them `computed` (a weaker answer key than Excel).
+
+## How it works
+
+```
+reader -> regions -> dependency graph -> compiler -> verifier -> dbt emitter -> report
+```
+
+1. **Read** the file twice with openpyxl: the formulas, and the values Excel saved. Dates become Excel serial numbers.
+2. **Find regions.** A block of rows where columns repeat one formula down (`=A2*1.1`, `=IF(B2>100,B2,0)`) is a
+   *region*. Running totals in a region (`=C1+B2`, `=SUM($B$2:B2)`) become SQL window functions. A region compiles to
+   one readable statement (`amount * 1.1 AS tax`) instead of one statement per cell.
+3. **Order** every formula after the cells it reads. Circular references are UNRESOLVED.
+4. **Compile** each formula to SQL with Excel's rules: Excel's type conversions (`"3"+1 = 4`), its error codes
+   (`#DIV/0!`, `#N/A`, `#VALUE!` ...) which must match exactly, the left-to-right order in which Excel reports errors,
+   and DuckDB guards (division by zero, `ln(0)`, overflow of `POWER`) so DuckDB never fails where Excel returns an
+   error. Cells outside regions run in batches ("cell mode").
+5. **Verify** on DuckDB in memory: numbers must match within a relative 1e-9, text and booleans exactly, errors by
+   code.
+6. **Emit** the dbt project and the report.
+
+93 Excel functions are supported: ABS, AND, AVERAGE, AVERAGEIF(S), CEILING, CHAR, CHOOSE, CLEAN, CONCAT(ENATE),
+COUNT, COUNTA, COUNTBLANK, COUNTIF(S), DATE, DATEDIF, DAY, DAYS, DAYS360, EDATE, EOMONTH, EXACT, EXP, FIND, FLOOR,
+HLOOKUP, IF, IFERROR, IFNA, IFS, INDEX, INT, IS* (BLANK, ERR, ERROR, LOGICAL, NA, NUMBER, TEXT), LEFT, LEN, LN, LOG,
+LOG10, LOWER, MATCH, MAX, MAXIFS, MEDIAN, MID, MIN, MINIFS, MOD, MONTH, MROUND, NA, NOT, OR, PI, POWER, PRODUCT,
+PROPER, REPLACE, REPT, RIGHT, ROUND(UP/DOWN), SEARCH, SIGN, SQRT, SUBSTITUTE, SUBTOTAL, SUM, SUMIF(S), SUMPRODUCT,
+SWITCH, TEXT, TEXTJOIN, TRIM, TRUE/FALSE, TRUNC, UPPER, VALUE, VLOOKUP, WEEKDAY, XLOOKUP, XOR, YEAR.
+
+**Speed** (Windows 11 laptop, measured): a 200,000-formula workbook (four formula columns over 50,000 rows, one of them
+a running total) converts and verifies in 26 s, all PASS. 50,000 rows of VLOOKUP into a 1,000-row table: 4.6 s.
+COUNTIFS/SUMIFS with a criterion from the row run at the same speed.
+
+## Limitations
+
+cellproof prefers an honest UNRESOLVED or FAIL to a guess. Known limits, each reported with a reason:
+
+- **File formats:** `.xlsx` and `.xlsm` only (no `.xls`, `.xlsb`, `.ods`). Macros (VBA) are ignored.
+- **Not supported:** array formulas and dynamic arrays, volatile functions (`NOW`, `TODAY`, `RAND`, `OFFSET`,
+  `INDIRECT`), functions outside the list above, external workbooks, structured table references (`Table1[@Col]`),
+  INDEX used as a reference, the 1904 date system in TEXT date formats.
+- **Approximate lookups on unsorted data** (MATCH/VLOOKUP/HLOOKUP with match type 1/-1): UNRESOLVED, because Excel's
+  answer then depends on its binary search.
+- **Text to number:** only plain numbers convert (`"3"`, `" -1.5e3 "`). Excel also reads `"1,000"`, `"$5"`, `"50%"`;
+  cellproof gives `#VALUE!`, which shows as a FAIL.
+- **Some function options:** SUBTOTAL 101-111 (hidden rows), DATEDIF units MD/YM/YD, WEEKDAY types 11-17, TEXT formats
+  outside the supported table, COUNT or MEDIAN of values typed into the formula, criteria taken from an empty cell.
+- **Floating point:** a running total becomes a fast window function only when Excel's saved values prove the different
+  addition order cannot matter; balances that cancel back to zero (ledgers) are added in Excel's order instead, which
+  is slower. Elsewhere SQL can still differ from Excel in the last digits, which would show as an honest FAIL. A
+  number that overflows becomes `inf` instead of `#NUM!`.
+- **Speed:** regions cover columns that repeat one formula over the same rows, lookups and *IF(S) criteria included.
+  A formula that is not part of such a column runs cell by cell (a lookup alone: about 7 s per 1,000). Running totals
+  other than plain sums (`=C1*1.05+B2`, `=MAX(C1,B2)`) also run cell by cell.
+- **The answer key:** a workbook must have been saved by Excel; `formulas` (the `compute` extra) is a weaker fallback
+  and is known to disagree with Excel in places.
+- **dbt:** the generated project targets DuckDB (`dbt-duckdb`). Other warehouses are not generated yet.
+
+## Security and privacy
+
+- **No network.** cellproof never sends workbook data anywhere; everything runs locally in DuckDB.
+- **Untrusted files:** workbook text only ever reaches SQL as escaped string literals; headers become SQL names only
+  after being reduced to `[a-z0-9_]`; braces are escaped so dbt's Jinja cannot run workbook text. A file that unzips to
+  more than 2 GB is refused. For extra XML hardening on untrusted files, `pip install defusedxml` (openpyxl then uses it
+  automatically).
+- **Output folder:** a rerun deletes the old `*.sql` files in `<out>/models/cellproof_cells/` so stale models cannot
+  linger; point `--out` at a folder of its own.
+- **`--dbt`** runs your installed `dbt` on the generated project (no shell).
+
+See [SECURITY.md](SECURITY.md) to report a vulnerability.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
+pip install -e ".[dev,dbt,compute]"
+python -m pytest tests -q                          # ~8 min with dbt on PATH
+CELLPROOF_PERF=1 python -m pytest tests/test_perf.py -s   # the 200k-formula benchmark
+```
+
+Rules the code follows: never guess a value (anything not translated exactly is UNRESOLVED with a reason a user
+understands); a false PASS is the worst bug; no DuckDB exception may escape from a supported function; tests first; real
+Excel is the ground truth. Design notes: [DESIGN.md](DESIGN.md) and `docs/superpowers/specs/`.
+
+## License
+
+[MIT](LICENSE)