arxivdigest 0.4.1__tar.gz

arxivdigest-0.4.1/.dockerignore

@@ -0,0 +1,6 @@
+.venv
+.git
+tests
+docs
+__pycache__
+*.egg-info

arxivdigest-0.4.1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e '.[dev]'
+      - run: python -m ruff check .
+      - run: python -m pytest -q --cov=paperdigest --cov-report=term-missing --cov-fail-under=93
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build

arxivdigest-0.4.1/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write # required for PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[dev]'
+      - run: python -m ruff check .
+      - run: python -m pytest -q --cov=paperdigest --cov-report=term-missing --cov-fail-under=93
+      - name: Check tag matches pyproject.toml version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PROJECT_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PROJECT_VERSION" ]; then
+            echo "Tag version ($TAG_VERSION) does not match pyproject.toml version ($PROJECT_VERSION)" >&2
+            exit 1
+          fi
+      - run: pip install build
+      - run: python -m build
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*.whl
+            dist/*.tar.gz
+      - name: Publish to PyPI (trusted publishing — no stored credentials)
+        uses: pypa/gh-action-pypi-publish@release/v1

arxivdigest-0.4.1/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+config.toml
+.coverage

arxivdigest-0.4.1/CHANGELOG.md

@@ -0,0 +1,132 @@
+# Changelog
+
+## 0.4.1 — 2026-10-13
+
+### Added
+- Published to PyPI as **`arxivdigest`**: `pipx install arxivdigest` (or
+  `pip install arxivdigest`) installs the CLI without cloning the repo.
+  The `paperdigest` distribution name was unavailable — PyPI's name-similarity
+  guard reserves it for an unrelated, dormant `paper-digest` project.
+  The command remains `paperdigest`.
+- The release workflow publishes to PyPI via GitHub **trusted publishing**
+  (OIDC) — no API tokens or passwords are stored on any machine.
+
+### Changed
+- README quick start leads with the packaged install; source-install
+  instructions moved below it.
+
+### Fixed
+- `__version__` now resolves package metadata under the `arxivdigest`
+  distribution name (with `paperdigest` as fallback for stale dev environments);
+  previously it looked only for the old name and reported `0.0.0` on clean
+  installs, which failed the release test gate.
+
+## 0.4.0 — 2026-07-25
+
+### Added
+- `digest --project-dir` (or the `project_dir` config key) links notes to the
+  scaffolded project for the same paper: the overview gains a `## Build it`
+  section, and concept notes link the stub module(s) whose cited `§x.y`
+  paper sections match the concept, resolved by scanning the project on disk.
+- Scaffold projects now include a generated `AGENTS.md` coding-agent brief
+  (dependency-ordered implementation plan, TODO counts, definition of done,
+  ground rules), assembled deterministically with no extra LLM call;
+  `scaffold --vault` links it back to the paper's Obsidian notes.
+- Figures: paper figures are downloaded and explained by a vision-capable
+  model, with the image and explanation embedded in the matching concept
+  note. `--figures/--no-figures` and the `max_figures` config key (default
+  8) control it; backends without vision skip figures after one warning.
+- `--version` flag; the scaffold failure debug dump now includes the version.
+- `--quiet` flag on both commands to suppress progress output.
+- `--max-input-chars`, `--max-tokens`, and `--cache-dir` CLI overrides for
+  their config keys.
+- Concept explanations and module stubs are generated with up to 4 parallel
+  requests on cloud backends (local servers stay serial).
+- CI and the release workflow enforce a 93% test-coverage floor.
+- `max_tokens` config option: the LLM output-token cap is now set explicitly
+  on both backends instead of hard-coded (Anthropic) or left to the server
+  default (OpenAI-compatible). See Changed for the current default.
+- Scaffold stages now get the same one-shot JSON repair round-trip as digest:
+  a malformed response is sent back to the model once for correction before
+  the run aborts.
+- Tag-triggered release workflow: pushing a `v*` tag lints, tests, builds,
+  verifies the tag matches `pyproject.toml`, and attaches the wheel and sdist
+  to a GitHub Release.
+- `examples/9b-attention-is-all-you-need/`: real, unedited output from a live
+  end-to-end run of both pipelines against arXiv:1706.03762 using a local 9B
+  model (Qwen3.5-9B-Instruct, NVFP4), with the run logs, as a worked example of
+  what paperdigest produces on self-hostable hardware.
+
+### Changed
+- Default `max_tokens` raised from 8192 to 16384 so mid-size local models
+  (e.g. a 9B) don't truncate long generated code files; still overridable
+  per run with `--max-tokens` or the config key.
+
+### Fixed
+- `__version__` is now derived from package metadata instead of a hard-coded
+  string that had drifted behind `pyproject.toml`.
+- `~` in `vault`/`cache_dir` config values is now expanded.
+- Concept-to-section matching is tiered (number-stripped exact, exact, then
+  longest-overlap containment), so short or numeric section titles can no
+  longer attach the wrong section's text to a concept.
+- Generated code that imported sibling/infra modules by bare name (e.g.
+  `from attention import ...`) is now deterministically rewritten to the full
+  package path, so a scaffolded project's own smoke test imports correctly once
+  the project is installed.
+- Generated `EXPERIMENTS.md` no longer fabricates benchmark result numbers;
+  targets are cited to the paper's own tables instead.
+- The scaffold dependency scanner no longer lists the project's own modules as
+  pip dependencies in the generated `pyproject.toml`.
+- The config loader generated into scaffolded projects now accepts
+  `key = value` as well as `key: value`, matching either separator the model
+  may emit. (This is the *generated project's* loader; paperdigest's own
+  `config.toml` remains strict TOML.)
+
+## 0.3.0 — 2026-07-15
+
+Robustness and safety hardening.
+
+### Added
+- Safety scan of all LLM-generated Python in `scaffold`: imports of
+  `subprocess`/`socket`/`ctypes`/`urllib`/`requests` and friends, calls to
+  `eval`/`exec`/`compile`/`__import__`, and dangerous attribute calls
+  (`os.system`, `pickle.load`, `shutil.rmtree`, ...) abort the pipeline
+  loudly with filename and line numbers.
+- `--refresh` flag on `digest` and `scaffold` to re-fetch a paper, bypassing
+  the HTML cache.
+- CI now runs ruff lint, reports test coverage, and verifies the package
+  builds (sdist + wheel).
+
+### Changed
+- LLM calls have a 300 s request timeout (previously unbounded).
+- Responses truncated at the token limit now raise a clear error instead of
+  being silently written as complete notes.
+- Only transient errors (connection, timeout, rate limit, 5xx) are retried;
+  permanent errors fail immediately with the original cause preserved.
+- Module planning rejects duplicate filenames instead of silently
+  overwriting one generated module with another.
+- Scaffold debug dumps are written to the cache directory (keyed by paper id
+  and stage) instead of the current working directory.
+
+### Fixed
+- HTML cache writes are atomic; an interrupted fetch can no longer leave a
+  corrupt cache file that is served forever.
+- A failure partway through rendering removes the half-written paper folder
+  (existing glossary notes are never touched).
+- Mermaid fence sanitization and validation now handle CRLF line endings and
+  trailing whitespace instead of silently skipping those blocks.
+- Concurrent runs against the same paper report a clean error instead of a
+  traceback.
+
+## 0.2.0 — 2026-07-12
+
+- Mermaid diagrams by default with sanitizer and optional node-based
+  validation; `--diagram` option.
+- JSON-mode structured output with trailing-junk-tolerant parsing.
+- Prompt-echo rejection in generated scaffold code.
+
+## 0.1.0 — 2026-07-11
+
+- Initial release: `digest` (arXiv paper to plain-English Obsidian notes)
+  and `scaffold` (paper to git-initialized research project skeleton),
+  local-first with optional Anthropic/OpenAI backends.

arxivdigest-0.4.1/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY paperdigest ./paperdigest
+RUN pip install --no-cache-dir .
+
+VOLUME /vault
+
+ENTRYPOINT ["paperdigest"]
+CMD ["--help"]

arxivdigest-0.4.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thad Reber
+
+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.

arxivdigest-0.4.1/PKG-INFO

@@ -0,0 +1,283 @@
+Metadata-Version: 2.5
+Name: arxivdigest
+Version: 0.4.1
+Summary: Turn AI/ML papers into plain-English Obsidian notes and reproduction-ready project scaffolds — local-first, runs on a 9B model
+Project-URL: Repository, https://github.com/thadreber-web/paperdigest
+Author: Thad Reber
+License: MIT License
+        
+        Copyright (c) 2026 Thad Reber
+        
+        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.
+License-File: LICENSE
+Keywords: arxiv,llama-cpp,llm,local-llm,obsidian,papers,research
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.40
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.50
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# paperdigest
+
+Read any AI/ML arXiv paper without having every piece of jargon memorized.
+paperdigest turns a paper into a folder of plain-English, wikilinked Obsidian
+notes — concept-by-concept explainers, Mermaid diagrams, equations walked
+through line by line, and a vault-wide glossary that defines the terms as you
+hit them.
+
+<p align="center">
+  <img src="docs/images/concept-note.png" alt="A generated concept note open in Obsidian, showing a plain-English analogy, an auto-generated Mermaid flowchart, and the paper's equation" width="620">
+</p>
+<p align="center">
+  <em>One generated note in Obsidian: a plain-English analogy for the concept, an
+  auto-generated Mermaid diagram of the computation, and the paper's equation
+  walked through line by line. Everything below is produced from the arXiv source
+  — no hand-editing.</em>
+</p>
+
+Built for the reader who follows AI/ML advances but isn't a specialist in every
+subfield: instead of bouncing between the PDF and ten browser tabs, you get the
+paper's ideas explained in your own vault, each unfamiliar term a click away.
+
+## See a full example
+
+[`examples/9b-attention-is-all-you-need/`](examples/9b-attention-is-all-you-need)
+is a complete run on *Attention Is All You Need*, checked into the repo — the
+generated Obsidian [vault](examples/9b-attention-is-all-you-need/vault) (concept
+notes + glossary), a
+[scaffolded project](examples/9b-attention-is-all-you-need/scaffold-project), and
+the [run logs](examples/9b-attention-is-all-you-need/logs). It was produced
+entirely by a local 9B model — no cloud, no API key.
+
+**Local-first.** By default paperdigest talks to a local OpenAI-compatible
+server (llama.cpp, Ollama, vLLM) on your own machine — no API key, no cost.
+Cloud backends (Anthropic, OpenAI) are opt-in for those who want them.
+
+## Quick start (local, free)
+
+Install the CLI (Python 3.11+; `pipx` keeps it in an isolated environment):
+
+```bash
+pipx install arxivdigest      # or: pip install arxivdigest
+```
+
+(The PyPI package is named `arxivdigest`; the command you run is
+`paperdigest`, unchanged.)
+
+Have a llama.cpp server running (`llama-server -m model.gguf` serves
+`http://localhost:8080/v1` by default), then:
+
+```bash
+paperdigest https://arxiv.org/abs/1706.03762 --vault ~/ObsidianVault
+```
+
+Installing from a clone instead? `python3 -m venv .venv && .venv/bin/pip
+install -e .`, then use `.venv/bin/paperdigest …` for every command below.
+
+Non-default port or engine? Point at it:
+
+```bash
+# llama.cpp on another port
+.venv/bin/paperdigest 1706.03762 --vault ~/ObsidianVault --base-url http://localhost:8001/v1
+# Ollama (needs the real model name)
+.venv/bin/paperdigest 1706.03762 --vault ~/ObsidianVault \
+  --base-url http://localhost:11434/v1 --model llama3.1
+```
+
+Output lands in `<vault>/Papers/<year>-<title-slug>/` plus new term notes in
+`<vault>/Glossary/`. Re-running the same paper refuses to overwrite unless you
+pass `--force`. Glossary term notes are never overwritten. Pass `--quiet` to
+suppress progress output, or `--max-input-chars`/`--max-tokens`/`--cache-dir`
+to override those config keys per run (both `digest` and `scaffold` accept
+these). `paperdigest --version` prints the installed version — it is a
+top-level flag, not available on the subcommands.
+
+### Choosing a model & context window
+
+Use a capable instruct model (~7B+); the pipeline needs structured JSON
+output, and very small models fail cleanly with an `error:` message. Set
+`max_input_chars` in `config.toml` to fit your model's context window (e.g.
+24000 for ~8k-token contexts) — long papers are trimmed with a warning; set
+`max_tokens` alongside it to cap output length for the same small context.
+Big *thinking* models need the opposite: reasoning tokens count against the
+output cap, so if a run aborts with a `truncated at max_tokens` error, raise
+it (e.g. `--max-tokens 32768` — see `docs/smoke-test-crosslinks.md` for a
+live example on a 122B).
+
+## How it works
+
+```mermaid
+flowchart TD
+    A["arXiv paper<br>(HTML, fetched &amp; cached)"] --> B["parse into<br>sections + figures"]
+    B --> C["outline (LLM):<br>concepts, jargon, TL;DR"]
+    C --> D["per-concept note (LLM):<br>plain-English + equation walk-through<br>+ embedded Mermaid / ASCII diagram"]
+    B --> E["figures explained<br>by a vision model"]
+    C --> F["glossary (LLM):<br>define jargon not already in your vault"]
+    D --> G["Obsidian vault:<br>Papers/ + Glossary/"]
+    E --> G
+    F --> G
+```
+
+The outline and glossary stages ask the server for JSON (`response_format:
+json_object`) when it's supported — that's what makes small local models
+reliable here. Each concept's diagram is generated as part of its note, then
+sanitized deterministically before it's written; figures are embedded next to
+the concept they illustrate.
+
+### Diagrams: Mermaid or ASCII
+
+Structural concepts get a diagram. The default is **Mermaid** (renders
+natively in Obsidian); pass `--diagram ascii` (or set `diagram = "ascii"` in
+`config.toml`) for plain-text diagrams that can never have syntax errors.
+Small local models sometimes emit Mermaid with unquoted special characters in
+node labels, so every diagram goes through a deterministic sanitizer that
+auto-quotes them. Optionally, if `node` is on your PATH and the `mermaid` npm
+package is importable from the directory you run paperdigest in
+(`npm install mermaid jsdom global-jsdom`), each diagram is also parse-checked
+and a warning names any note whose diagram still fails. No node? Validation is
+skipped silently — the worst case is one diagram rendering as an error box in
+Obsidian instead of a picture.
+
+### Figures
+
+By default, figures are downloaded from the paper and explained by a
+vision-capable model, with the image and its explanation embedded together
+in the matching concept note (or the overview, if unmatched). This needs a
+vision-capable backend — for local llama.cpp, serve with an `--mmproj`
+projector file. Backends without vision skip figures automatically after a
+warning on the first figure, and the rest of the digest completes normally.
+Pass `--no-figures` (or set `figures = false` in `config.toml`) to turn this
+off; it's also the budget option on cloud backends, where images are
+token-expensive. `max_figures` (default 8) caps how many figures per paper
+are explained, by document order.
+
+### Linking to a scaffolded project
+
+Pass `--project-dir` (or set `project_dir` in `config.toml`) and notes gain a
+`## Build it` section pointing at `<project-dir>/<year>-<title-slug>` — the
+project `scaffold` would create for the same paper. If that project exists on
+disk, concept notes also get a `*Build it: …*` line linking the stub module(s)
+whose cited `§x.y` paper sections match the concept, so you can jump straight
+from the explanation to the code that implements it.
+
+## Scaffold a research project
+
+Turn a paper into a standalone, git-initialized project skeleton (Cookiecutter-DS-style
+layout, JSONL experiment tracking, stub modules mapped to paper sections):
+
+```bash
+.venv/bin/paperdigest scaffold https://arxiv.org/abs/1706.03762 --dest ~/projects
+```
+
+Output lands in `<dest>/<year>-<title-slug>/` with its own git history. The code is a
+*skeleton*: module stubs with `TODO(paper §x.y)` markers plus a complete train/evaluate
+harness and a toy smoke experiment — not a working reimplementation. Any generation
+failure aborts loudly (nothing half-written); the raw model output is saved to
+`scaffold-debug-<stage>.txt` for inspection. Re-running refuses to overwrite an
+existing project unless you pass `--force`.
+
+You don't need a big model: scaffolding is tested live end-to-end on a 9B via
+llama.cpp (see `docs/smoke-test-scaffold.md`; the cross-linking features are
+live-tested on a 122B via vLLM in `docs/smoke-test-crosslinks.md`). JSON
+stages request structured
+output (`response_format: json_object`) from the server when supported, which
+is what makes small local models reliable here; generated code is validated
+(syntax + prompt-echo rejection) before anything is written. Besides
+`log_run()` for JSONL experiment tracking, the scaffolded `tracking.py` has
+`get_logger()` for per-run log files under `logs/`.
+
+**A note on trust:** every generated `.py` file is still LLM output. Before writing it,
+paperdigest checks it parses, rejects leftover prompt-echo lines, and scans it for
+dangerous calls (`subprocess`, `socket`, `eval`/`exec`, `os.system`, `pickle.load`,
+`shutil.rmtree`, and similar) plus networking/FFI imports (`urllib`, `requests`,
+`ctypes`, and similar) — aborting loudly if it finds any. That scan catches obviously
+hazardous patterns, not everything — read the scaffolded code before you run it.
+
+Every project also gets a generated `AGENTS.md` — a coding-agent brief with a
+dependency-ordered implementation plan, a TODO count and cited paper sections per
+module, a definition of done, and ground rules for the harness. It's assembled
+deterministically from the same stage data, no extra LLM call. Pass `--vault` (or set
+`vault` in your config file) and it links back to the paper's Obsidian notes so an
+agent can read the plain-English explanation before touching code.
+
+## Cloud backends (optional, cost money)
+
+| Backend | Flags | Key (env var only) |
+|---|---|---|
+| Local (default) | `--base-url http://localhost:8080/v1 --model local` | none |
+| OpenAI | `--backend openai --model gpt-5` | `OPENAI_API_KEY` |
+| Anthropic | `--backend anthropic --model claude-sonnet-5` | `ANTHROPIC_API_KEY` |
+
+Every LLM call is retried up to 2 more times with exponential backoff on
+transient errors (connection drops, timeouts, rate limits, 5xx); malformed
+JSON gets one repair round-trip; other errors fail immediately. Requests
+time out after 300s. On cloud backends, concept and module-stub generation
+runs a few requests in parallel to cut wall-clock time; against a local
+server it stays serial, since a single llama.cpp instance generally can't
+service concurrent requests.
+
+## Docker
+
+```bash
+docker build -t paperdigest .
+docker run --rm -v ~/ObsidianVault:/vault \
+  --add-host=host.docker.internal:host-gateway \
+  paperdigest https://arxiv.org/abs/1706.03762 \
+  --base-url http://host.docker.internal:8080/v1
+```
+
+(`--add-host` is needed on Linux to reach the host-side local server; for a
+cloud backend pass `-e ANTHROPIC_API_KEY` or `-e OPENAI_API_KEY` instead.)
+
+## Config
+
+Copy `config.example.toml` to `config.toml` (or pass `--config`) so you don't
+retype flags. CLI flags override config values. API keys are env-only and
+never read from config files.
+
+## Inputs
+
+v1 accepts arXiv URLs (`abs`/`pdf`/`html`) or bare IDs (`1706.03762`). It uses
+the paper's arXiv HTML rendering (ar5iv as fallback); papers with no HTML
+rendering fail with a clear message. Fetched papers are cached in
+`~/.cache/paperdigest/` (configurable via `cache_dir` in `config.toml`); pass
+`--refresh` to re-fetch and overwrite the cached HTML, e.g. after arXiv
+publishes a revision.
+
+## Development
+
+```bash
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest          # fully offline: fixtures + fake LLM backend
+```
+
+Known minor cleanups (all reviewed, none load-bearing) are tracked in `TODOS.md`.