feat!: ship a reader console script and target Python 3.14

[zyocum]

Why

reader shipped no console script, so other CLI/TUI tools could not reuse the extractor without sys.path surgery (see sandbox/tui.py). This adds a [project.scripts] entry point so it can be installed with uv tool install and imported as a library.

What changed

• Entry point. The argparse block moved out of if __name__ == "__main__": into cli(). main() remains the library API returning a ParseResult, so importing reader no longer risks parsing sys.argv.
• Build backend. Added a hatchling [build-system]. reader.py is a single top-level module rather than a package directory, so the wheel/sdist targets name it explicitly — a new file that must ship has to be added to those include lists.
• Shebang removed along with the executable bit. #!/usr/bin/env python3 resolved to whatever python3 came first on PATH, which silently required an activated venv; the console script carries an absolute shebang into its own environment instead.
• Python 3.14. requires-python = ">=3.14", [tool.pyright] pythonVersion in step, and .python-version is now tracked (un-ignored in .gitignore) so the interpreter pin travels with the repo. No dependency versions moved — requirements.txt regenerates identical.
• Docs. README covers the tool / library / development install paths; its -h block is regenerated from real output (it had drifted from argparse's 3.13 option formatting). AGENTS.md gains packaging and Python-version sections, including the fact that uv tool install resolves fresh from [project.dependencies] and ignores uv.lock unless given -c requirements.txt.

Breaking

Requires Python 3.14 or newer, and ./reader.py is no longer executable — use reader, uv run reader, or python reader.py. The CLI flags, the JSON output schema, and main()/ParseResult are unchanged, so downstream consumers of .title, .author, and .content.text are unaffected.

Verification

Locally on CPython 3.14.7: uv run ruff check . clean and basedpyright reports zero diagnostics for reader.py. All four formats (json, html, md, txt) plus -w wrapping and -t table formats verified against a local fixture and both reference pages — https://www.paulgraham.com/greatwork.html (table/br-based layout) and https://www.gnu.org/philosophy/free-sw.en.html. The wheel was checked to contain only reader.py plus metadata, and both install routes were exercised end to end in throwaway environments:

uv tool install --force -c requirements.txt -p 3.14 .
pip install -r requirements.txt && pip install --no-deps .

🤖 Generated with Claude Code