Rewrite README for clarity: smoother, more scannable, current commands

Tighten the prose, lead with a single quickstart, collapse the transport
sections into a small table, and replace the stale --rootdir/--with pytest
invocation with 'uv run --frozen pytest'.

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

Author: rustyconover

README.md

@@ -9,164 +9,101 @@
 [![Python](https://img.shields.io/pypi/pyversions/vgi-easter.svg)](https://pypi.org/project/vgi-easter/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-A minimal [VGI (Vector Gateway Interface)](https://github.com/Query-farm) worker
-that computes the date of **Western (Gregorian) Easter Sunday** for a given year
-and exposes it to DuckDB as a SQL scalar function.
+A tiny [VGI (Vector Gateway Interface)](https://github.com/Query-farm) worker
+that gives DuckDB one SQL function — `easter_date(year)` — returning the date of
+Western (Gregorian) Easter Sunday. It has no external data and almost no code,
+which makes it a clean, copyable example of a VGI scalar-function worker.
+
+## Quick start
+
+In DuckDB:
 
 ```sql
 ATTACH 'easter' (TYPE 'vgi', LOCATION 'uvx vgi-easter');
 
-SELECT easter.easter_date(2025);
--- 2025-04-20
+SELECT easter.easter_date(2025);   -- 2025-04-20
 
 SELECT year, easter.easter_date(year) AS easter
-FROM range(2020, 2031) t(year);
--- 2020  2020-04-12
--- 2021  2021-04-04
--- ...
+FROM range(2020, 2025) t(year);
 ```
 
-The function `easter_date(year)` takes a `BIGINT` year and returns a `DATE`,
-computed with the Anonymous Gregorian algorithm (the Meeus/Jones/Butcher
-*Computus*). It is pure standard-library arithmetic — no network calls, no
-external data — which makes this repo a clean, self-contained example of a VGI
-scalar-function worker.
+DuckDB launches the worker for you, and `easter_date` then behaves like a native
+function (a null year yields a null date). The `uvx vgi-easter` location fetches
+the worker on demand; to keep it around, `pip install vgi-easter`.
 
 ## How it works
 
-VGI lets a worker process publish catalogs, schemas, and functions that DuckDB
-can `ATTACH` and query as if they were native. Data crosses the boundary as
-Apache Arrow IPC, so values stay columnar end to end.
+A VGI worker publishes catalogs, schemas, and functions that DuckDB can `ATTACH`
+and query as if they were built in. Values cross the boundary as Apache Arrow,
+so they stay columnar end to end.
 
-This worker publishes one catalog:
+This worker publishes a single function:
 
 ```
-easter            (catalog,  data version 1.0.0)
-└── main          (schema)
-    └── easter_date(year BIGINT) -> DATE
+easter                                  (catalog)
+└── main                                (schema)
+    └── easter_date(year BIGINT) → DATE
 ```
 
-`year` propagates nulls — a null year yields a null date.
-
-The entire implementation lives in [`easter_worker.py`](easter_worker.py):
-
-- `_easter_sunday(year)` — the Computus, returning a `datetime.date`.
-- `EasterDateFunction` — a `ScalarFunction` mapping an `Int64Array` of years to
-  a `date32` array, with metadata and SQL examples for catalog introspection.
-- `EasterCatalog` / `EasterWorker` — wire the function into a VGI catalog that
-  advertises a stable `data_version` (`1.0.0`) and a git-SHA
-  `implementation_version` (from `VGI_EASTER_GIT_COMMIT`).
+The whole implementation is ~160 lines in
+[`easter_worker.py`](easter_worker.py): the date calculation
+(`_easter_sunday`, the Anonymous Gregorian *Computus* — pure standard library),
+a `ScalarFunction` that maps an Arrow array of years to dates, and a few lines
+wiring it into a catalog.
 
-## Requirements
+## Running it
 
-- Python **3.13+**
-- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`
-
-The only dependency is [`vgi-python`](https://pypi.org/project/vgi-python/) (the
-`http` extra adds the HTTP-server transport); it is published on PyPI, so no
-sibling checkouts are needed.
-
-## Installing
-
-```bash
-# Install from PyPI (provides the vgi-easter and vgi-easter-http commands)
-pip install vgi-easter
-# or run it ad hoc without installing
-uvx vgi-easter
-```
-
-## Running
-
-The worker supports both VGI transports. Two console scripts are installed:
-`vgi-easter` (stdio) and `vgi-easter-http` (HTTP server).
-
-### stdio (DuckDB spawns the worker)
-
-DuckDB runs the worker as a subprocess and talks to it over stdin/stdout. No
-server to manage — point the LOCATION at the installed command (or `uvx
-vgi-easter` to fetch it on demand):
-
-```sql
-ATTACH 'easter' (TYPE 'vgi', LOCATION 'uvx vgi-easter');
-SELECT easter.easter_date(2025);
-DETACH easter;
-```
+Once installed, the package gives you one command per VGI transport:
 
-### HTTP
+| Command           | Transport | Use it when                                              |
+| ----------------- | --------- | -------------------------------------------------------- |
+| `vgi-easter`      | stdio     | DuckDB spawns the worker as a subprocess (the quickstart)|
+| `vgi-easter-http` | HTTP      | you want a long-running server to attach to              |
 
-Start the worker as an HTTP server (`vgi-easter-http` calls
-`EasterWorker.main_http()`):
+To run over HTTP, start the server and attach to its URL:
 
 ```bash
 VGI_SIGNING_KEY=dev vgi-easter-http --host 0.0.0.0 --port 8000
 ```
 
-Then attach over HTTP (the VGI extension auto-loads `httpfs`):
-
 ```sql
 ATTACH 'easter' (TYPE 'vgi', LOCATION 'http://localhost:8000');
-SELECT easter.easter_date(2025);
 ```
 
-### From a source checkout
-
-The two modules also carry inline [PEP 723](https://peps.python.org/pep-0723/)
-metadata, so you can run them directly without installing:
+Working from a checkout instead? Both modules carry
+[PEP 723](https://peps.python.org/pep-0723/) metadata, so `uv run
+easter_worker.py` (stdio) and `uv run serve.py` (HTTP) run without installing
+anything.
 
-```bash
-uv run --python 3.13 easter_worker.py            # stdio
-VGI_SIGNING_KEY=dev uv run --python 3.13 serve.py --host 0.0.0.0 --port 8000  # HTTP
-```
+## Configuration
 
-## Testing
+| Variable                          | Purpose                                                       |
+| --------------------------------- | ------------------------------------------------------------- |
+| `VGI_SIGNING_KEY`                 | Signing key for HTTP state tokens (required by the HTTP server).|
+| `VGI_HTTP_HOST` / `VGI_HTTP_PORT` | HTTP bind address (default: all interfaces / `8000`).         |
+| `VGI_EASTER_GIT_COMMIT`           | Reported as the catalog's `implementation_version`.           |
+| `VGI_WORKER_DEBUG`                | Set to `1` for debug logging.                                 |
 
-### Unit tests (pytest)
+## Development
 
-The `tests/` suite checks the Computus against known Easter dates (including the
-March 22 / April 25 extremes) and the Arrow `compute()` path including null
-propagation:
+Requires Python 3.13+ and [`uv`](https://docs.astral.sh/uv/); the only
+dependency is [`vgi-python`](https://pypi.org/project/vgi-python/).
 
 ```bash
-uv run --python 3.13 \
-  --with pytest --with vgi-python \
-  pytest tests/ --rootdir=. -o "addopts=" -q
+uv run --frozen pytest tests/ -q
 ```
 
-The `--rootdir=. -o "addopts="` flags keep pytest from picking up an upstream
-`pyproject.toml` that injects `--mypy --ruff`. `conftest.py` puts the repo root
-on `sys.path` so the tests can `import easter_worker`.
-
-### SQL integration tests (sqllogictest)
-
-`test/sql/` contains [sqllogictest](https://duckdb.org/dev/sqllogictest/intro)
-files that run against the worker through the real DuckDB VGI extension:
+The `tests/` suite covers the Easter calculation (including the March 22 /
+April 25 extremes) and the Arrow compute path. A separate
+[sqllogictest](https://duckdb.org/dev/sqllogictest/intro) suite in `test/sql/`
+drives the worker through the **real** DuckDB `vgi` extension. CI runs both on
+Linux, macOS, and Windows — see [`ci/README.md`](ci/README.md).
 
-- `easter_catalog.test` — catalog discovery, `data_version_spec`, `ATTACH` and
-  schema introspection.
-- `easter_function.test` — scalar evaluation, the `DATE` result type, and null
-  propagation.
+## Releasing
 
-Both are gated on `require-env VGI_EASTER_WORKER`, so point that at a worker
-LOCATION (a stdio command or an HTTP URL) and run them with the DuckDB
-`unittest` binary built with the VGI extension.
-
-## Environment variables
-
-| Variable                  | Purpose                                                              |
-| ------------------------- | ------------------------------------------------------------------- |
-| `VGI_SIGNING_KEY`         | Stable key for state-token signing (required for the HTTP server).  |
-| `VGI_EASTER_GIT_COMMIT`   | Git SHA reported as the catalog's `implementation_version`.         |
-| `VGI_HTTP_PORT` / `VGI_HTTP_HOST` | HTTP bind address (defaults: `8000` / all interfaces).      |
-| `VGI_WORKER_DEBUG`        | Set to `1` for debug logging.                                       |
-
-## Publishing
-
-This repo is a packaged distribution (`vgi-easter`) built with hatchling:
-
-```bash
-uv build                       # writes dist/*.whl and dist/*.tar.gz
-uv publish                     # upload to PyPI (needs a token)
-```
+`vgi-easter` is built with hatchling and published to PyPI by CI when a GitHub
+Release is created (it runs the test suites, then `uv build && uv publish`). To
+cut a release, bump `version` in `pyproject.toml` and publish a GitHub Release.
 
 ## License