prose-preflight 0.1.0__tar.gz

prose_preflight-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "prose-preflight",
+  "owner": {
+    "name": "Dominik Reisach"
+  },
+  "description": "Deterministic prose preflight checks for scientific writing, as an installable Claude Code plugin.",
+  "plugins": [
+    {
+      "name": "prose-preflight",
+      "source": "./",
+      "description": "Run deterministic prose checkers over a manuscript and fix what the JSON report reports.",
+      "category": "writing",
+      "keywords": ["prose", "writing", "proofreading", "scientific-writing"]
+    }
+  ]
+}

prose_preflight-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "prose-preflight",
+  "version": "0.1.0",
+  "description": "Deterministic prose checkers for scientific writing, plus a thin skill that drives them: one command, one compact JSON report.",
+  "author": {
+    "name": "Dominik Reisach"
+  },
+  "repository": "https://github.com/domrice/prose-preflight",
+  "license": "MIT",
+  "keywords": ["prose", "writing", "proofreading", "vale", "readability", "scientific-writing"],
+  "skills": ["./skills/prose-preflight", "./skills/prose-deepread"]
+}

prose_preflight-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: ci
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked
+      - run: uv run ruff check . && uv run ruff format --check .
+      - run: uv run pytest
+      - run: uv build
+      # Runs the package the way uvx will, with no repo on disk. A real
+      # invocation, not `--version`: that never loads default.yaml, so a config
+      # missing from the wheel would still pass. It also proves the bundled Vale
+      # binary resolves in a fresh environment.
+      - name: Smoke-test the wheel
+        run: |
+          uv run --isolated --with dist/*.whl \
+            prose-preflight tests/fixtures/units.md > report.json
+          jq -e '.total > 0 and (.counts.category | has("units"))' report.json

prose_preflight-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+# Publishes to PyPI when a v* tag is pushed. Uses trusted publishing, so there is no
+# API token to store: configure the publisher once at
+# https://pypi.org/manage/project/prose-preflight/settings/publishing/
+# (owner: domrice, repo: prose-preflight, workflow: release.yml, environment: pypi).
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --locked
+      - run: uv run pytest
+      - name: Check the tag matches the packaged version
+        run: |
+          test "v$(uv run python -c 'from importlib.metadata import version; print(version("prose-preflight"))')" = "${GITHUB_REF_NAME}"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

prose_preflight-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+dist/
+*.egg-info/

prose_preflight-0.1.0/CLAUDE.md

@@ -0,0 +1,142 @@
+# CLAUDE.md
+
+Guidance for Claude Code (claude.ai/code) when working in this repository.
+
+## What this repo is
+
+`prose-preflight` is an **agent skill**: deterministic CLI checkers plus a thin `SKILL.md`
+that tells an agent how to drive them. The scripts are the analyzer, not the agent.
+
+The agent runs one command, reads one compact JSON report, and reports it. It does **not**
+edit the document — not errors, not mechanical suggestions. Fixes happen only when the user
+asks for a specific one in a later turn. `skills/prose-preflight/SKILL.md` is the binding
+agent contract: report, never edit, never auto-apply `review`.
+
+No model is ever called from inside the Python — that would cost determinism, offline runs,
+and per-run money, which is the same trade that ruled out LanguageTool. Judgment lives in the
+agent turn: preflight gives `review` findings a verdict, and `prose-deepread` is the one
+opt-in exception to "never read the source", run only when the user asks for it by name.
+
+## The token-efficiency contract
+
+This is the reason the project exists. Violating it defeats the skill.
+
+- **One command, one report.** `run_all.py` once, one JSON document. Never invoke individual
+  checkers, never read Vale output, never pipe raw tool stdout into context.
+- **Never read the source document to find problems.** Findings carry `line`/`col` and a
+  short `excerpt`, so edits can be targeted without a full read.
+- **Reports are summarized by default.** Top level is counts by severity/category/section;
+  findings are capped (`--max-findings`, default 20), filled round-robin across categories so
+  one noisy category cannot crowd out the rest; `--max-findings 0` lifts the cap. Never let a
+  900-issue Vale run flood the transcript.
+- **`--md PATH` writes the full report to disk.** The agent summarizes stdout and links the
+  file; it never transcribes findings through context.
+- **`SKILL.md` stays short** (< 120 lines): the workflow and the JSON shape, nothing else.
+  Rule catalogs and rationale live in `README.md` and `default.yaml`'s comments.
+- **No checker prints prose.** Diagnostics to stderr; stdout is JSON only.
+
+## Layout
+
+```
+src/prose_preflight/
+  finding.py    the one record every checker emits
+  run_all.py    CLI: extract, fan out, aggregate, cap, serialize
+  default.yaml  the only config; package data, resolved via importlib.resources
+  extract/      document.py (Document + shared passes), markdown.py, latex.py
+  checks/       acronym claim readability sentence_length structure terminology units vale
+                + _text.py (shared helpers) + __init__.py (CHECKERS registry)
+skills/prose-preflight/SKILL.md   the agent-facing workflow
+skills/prose-deepread/SKILL.md    the opt-in full-read pass (the only thing allowed to read the source)
+.claude-plugin/                   plugin.json + marketplace.json
+```
+
+Four layers, each replaceable without touching the others. The constraints that make that
+true:
+
+1. **Extraction** — `extract/__init__.py` dispatches on file suffix (unknown suffix reads as
+   plain text). `Document.masked` is a character-for-character copy of the source with fenced
+   code, display math, inline code and inline math replaced by spaces, so a regex over
+   `masked` yields match offsets that *are* the source `line`/`col`. Every indexed element
+   keeps its 1-based source line. A reader that loses line numbers is not acceptable — every
+   downstream finding depends on it.
+
+2. **Checkers** — each module exposes exactly `check(doc: Document, rule: dict) ->
+   list[Finding]`. Pure, stateless, knowing nothing about each other. They receive their
+   slice of the resolved config; the runner does the lookup, the `enabled` gate, and the
+   sorting, so checkers may return findings in any order. Adding a checker is a module plus
+   one line in `CHECKERS` — never a change to the runner's logic.
+
+3. **Config** — one bundled `default.yaml`, shipped as package data (a repo-root `profiles/`
+   would be invisible to `uvx`, which runs from a cached wheel). `--config FILE` deep-merges
+   over it. **If a new document convention requires a code change, the design is wrong** —
+   generalize the checker and push the specifics into YAML.
+
+4. **Runner** — extracts, fans out, aggregates, caps, serializes. No domain knowledge.
+
+### The `Finding` record
+
+One dataclass, shared by every checker. Changing it is a breaking change across the repo.
+
+```
+check      str        stable rule id, e.g. "terminology.variant"
+category   str        grammar|style|readability|terminology|acronym|structure|units|claim
+severity   str        error | warning | review
+line, col  int        1-based
+excerpt    str        short, trimmed
+message    str        one line, imperative
+section    str|None   nearest enclosing heading
+suggestion str|None   the replacement, when mechanical and safe
+```
+
+`severity: review` is a load-bearing distinction, not a softer warning. Claim-calibration,
+hedging, and overclaiming checks emit **only** `review`. Nothing marked `review` is ever
+auto-applied — it is surfaced to a human or reasoned about by the agent in context. This is
+the boundary between deterministic checking and qualitative judgment, and it must never blur.
+
+## Scope discipline
+
+Each addition costs install weight, runtime, and report noise.
+
+**In:** Markdown/LaTeX/plain text · Vale · readability (`textstat`) · sentence-length outliers
+· terminology · acronyms · section structure · numbers and units · claim calibration · JSON
+and Markdown reports. The extractor also indexes citations and labels; no checker consumes
+them yet.
+
+**Deferred:** DOCX/PDF extraction (Pandoc/PyMuPDF weight); spaCy/Stanza (hundreds of MB for
+segmentation `textstat` plus a regex already handles); Pint (a unit *calculus*, where these
+checks are formatting — NBSP, `%` spacing, ranges, p-values — so regex is right); DOI network
+validation (breaks determinism and offline runs); statistical-reporting checks;
+figure/table cross-references; `--profile NAME` layering (one audience today; adding it later
+is a lookup returning a bundled path, purely additive).
+
+**Vale over LanguageTool:** a single static binary with YAML config, fully offline and
+deterministic, versus a Java server or API that makes runs non-reproducible. Vale is pinned in
+`pyproject.toml` and ships with the package, but the checker must still degrade around it: if
+the binary is unavailable, emit one `vale.unavailable` warning and continue. Never abort.
+
+## Commands
+
+Python is managed with `uv`; `uv.lock` is committed and `requires-python = ">=3.11"`.
+
+```bash
+uv sync                                                 # install, from the lockfile
+uvx prose-preflight FILE                                # the distributed invocation
+uv run prose-preflight FILE --md PREFLIGHT.md           # from source, full report to disk
+uv run prose-preflight FILE --checks terminology,acronym --max-findings 0
+uv run pytest                                           # all tests
+uv run pytest tests/test_checks.py -k units             # one test
+uv run ruff check . && uv run ruff format .
+```
+
+Pushing a `v*` tag publishes to PyPI via trusted publishing (`.github/workflows/release.yml`,
+which also asserts the tag matches the packaged version). CI smoke-tests the built wheel with
+`uv run --isolated`, so a `default.yaml` missing from the wheel or an unresolvable Vale binary
+fails there rather than in a user's environment.
+
+## Tests
+
+Fixtures in `tests/fixtures/` are intentionally flawed documents paired with expected-findings
+JSON. `tests/test_checks.py` parametrizes one pair per checker and asserts the exact set of
+`(check, line)` pairs — this is what keeps checkers from drifting into false positives, which
+are far more costly here than misses: every false positive burns agent tokens and erodes trust
+in the report. `tests/test_packaging.py` guards the package data and entry point.

prose_preflight-0.1.0/LICENSE

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

prose_preflight-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: prose-preflight
+Version: 0.1.0
+Summary: Deterministic prose checkers for scientific writing, driven by an agent skill.
+Project-URL: Homepage, https://github.com/domrice/prose-preflight
+Project-URL: Issues, https://github.com/domrice/prose-preflight/issues
+Author-email: Dominik Reisach <praises_sauces.0i@icloud.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent-skill,linter,proofreading,prose,scientific-writing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Requires-Dist: pyyaml
+Requires-Dist: textstat
+Requires-Dist: vale==3.21.0.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Prose Preflight
+
+**Your manuscript, checked by scripts, read by an agent.**
+
+[![PyPI](https://img.shields.io/pypi/v/prose-preflight?style=flat-square&logo=pypi&logoColor=white&color=fa934e&labelColor=121417)](https://pypi.org/project/prose-preflight/)
+[![Python](https://img.shields.io/badge/python-%E2%89%A5%203.11-fa934e?style=flat-square&logo=python&logoColor=white&labelColor=121417)](https://www.python.org)
+[![Vale](https://img.shields.io/badge/Vale-bundled-fa934e?style=flat-square&labelColor=121417)](https://vale.sh)
+[![uv](https://img.shields.io/badge/uv-managed-fa934e?style=flat-square&logo=uv&logoColor=white&labelColor=121417)](https://docs.astral.sh/uv/)
+[![License](https://img.shields.io/badge/license-MIT-fa934e?style=flat-square&labelColor=121417)](LICENSE)
+[![last commit](https://img.shields.io/github/last-commit/domrice/prose-preflight?style=flat-square&color=fa934e&labelColor=121417)](https://github.com/domrice/prose-preflight/commits/main)
+
+</div>
+
+---
+
+> No server. No API key. No network. No opinions about your argument.
+> Eight deterministic checkers read a Markdown, LaTeX, or plain-text manuscript and emit one
+> compact JSON report. The scripts analyze; the agent reports. Same input, same findings,
+> every time.
+
+An LLM asked to proofread a text will read all 9,000 words into its context, forget the
+middle, and confidently invent a citation error on page 4. This tool doesn't. The checkers
+find the problems and hand over line, column, and a short excerpt — the agent summarizes
+that and never reads the manuscript to find anything.
+
+## Install
+
+**1. Claude Code plugin**
+
+```
+/plugin marketplace add domrice/prose-preflight
+/plugin install prose-preflight
+```
+
+**2. Any other harness** (Cursor, Codex, Copilot, Gemini, Windsurf, …)
+
+```bash
+npx skills@latest add domrice/prose-preflight
+```
+
+**3. CLI only, no agent** — for CI or pre-commit
+
+```bash
+uvx prose-preflight text.md
+```
+
+**4. From source** (contributors)
+
+```bash
+git clone https://github.com/domrice/prose-preflight && cd prose-preflight
+uv sync && uv run pytest
+```
+
+Routes 1–3 resolve the package from PyPI, so none of them needs the repo on disk and
+`SKILL.md` carries no paths. Needs [Python ≥ 3.11](https://www.python.org); `uvx` supplies
+its own interpreter, so route 3 needs nothing but [uv](https://docs.astral.sh/uv/).
+
+## Use
+
+```bash
+uvx prose-preflight text.md
+```
+
+The full report is written to `PREFLIGHT_text.md` — one per document, so checking a second
+file never overwrites the first. A capped JSON summary goes to stdout, with `report` naming
+that file. That split is
+the whole point — the agent reads stdout, links the file, and stays small.
+
+| flag               | does                                             |
+| ------------------ | ------------------------------------------------ |
+| `--md PATH`        | move the report (default `PREFLIGHT_<file>.md`)  |
+| `--max-findings N` | cap stdout findings (default `20`; `0` lifts it) |
+| `--checks a,b`     | run a subset                                     |
+| `--config FILE`    | deep-merge a YAML file over the bundled config   |
+| `--version`        | the packaged version                             |
+
+Findings are capped round-robin across categories, so 400 Vale alerts cannot crowd out the
+one missing Methods section. `counts` and `total` always cover everything; `truncated` says
+what was dropped.
+
+## The two skills
+
+The CLI is deterministic on purpose — offline, no API key, same input same output. So
+nothing calls a model inside it. The judgment lives in the agent that drives it, where
+it is free, and it ships as two skills:
+
+- **`prose-preflight`** runs the command and reports it, but does not just print it. It
+  diagnoses what the counts mean, and gives every `severity: review` finding a verdict —
+  `keep`, `soften`, or `cut`, with a rewrite. The checker can see that a hedge is there;
+  only the agent can weigh it against the argument. It never edits the document.
+- **`prose-deepread`** is the opposite of preflight: it reads the manuscript end to end
+  and looks for what no regex can reach — claims the results do not support, terms used
+  before they are defined, sections that do not deliver what their heading promises, and
+  passages that can be cut without losing an argument. Expensive, so it runs only when
+  you ask for it by name. It never edits either.
+
+## Config
+
+Every check is configurable from one YAML file. Write it once per project:
+
+```bash
+uvx prose-preflight --init-config    # writes prose-preflight.yaml, every key commented
+uvx prose-preflight text.md         # picked up automatically from the working directory
+```
+
+A `prose-preflight.yaml` next to where you run is used without any flag; `--config FILE`
+points elsewhere. Keep only what you change — the rest falls back to the defaults. Lists are
+replaced, not appended, and unknown keys are reported on stderr, so a typo never fails
+silently.
+
+Two lists ship **empty**, because there is no universal right answer and a wrong entry costs
+you a false positive on every run: `terminology.terms` (your journal's preferred spellings)
+and `structure.required_sections` (most documents are fragments, not whole papers). Fill
+them in and those checks switch on.
+
+```yaml
+checks:
+  terminology:
+    terms:
+      finite element: [finite-element, FE]
+  sentence_length:
+    max_words: 32
+  structure:
+    required_sections:
+      [Abstract, Introduction, Methods, Results, Discussion, References]
+  units:
+    disabled_rules: [range_dash] # if your journal insists on hyphens
+```
+
+Everything a document convention needs lives in YAML. If a new convention would need a code
+change, that's a bug in the checker, not a missing feature.
+
+## Checks
+
+| check                                                                               | flags                                                             | severity      |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------- |
+| `vale.*`                                                                            | grammar, spelling, style — whatever your Vale config says         | error/warning |
+| `terminology.variant`                                                               | `dataset` where the config wants `data set` (opt-in: `terms`)     | warning       |
+| `acronym.undefined`                                                                 | used without expansion at first use                               | warning       |
+| `structure.missing_section` · `.section_order`                                      | required sections, absent or out of order (opt-in)                | error/warning |
+| `sentence_length.long`                                                              | sentences over `max_words`                                        | warning       |
+| `readability.flesch` · `.fog`                                                       | per section, skipping ones too short to score                     | warning       |
+| `units.space_before_unit` · `.percent_spacing` · `.range_dash` · `.p_value_spacing` | `12 mm` → NBSP, `5 %` → `5%`, `3-7` → `3–7`, `p<.05` → `p < 0.05` | warning       |
+| `claim.hedge` · `.booster`                                                          | "may possibly suggest", "clearly demonstrates"                    | **review**    |
+
+`review` is not a quieter warning. It is the line between what a script can decide and what
+it cannot: hedging and overclaiming are judgment calls about whether your evidence carries
+your claim. Nothing marked `review` is ever auto-applied, by either the tool or the agent.
+
+Code, math, verbatim blocks, and LaTeX command sequences are blanked before any regex runs —
+character-for-character, so every offset stays a true source position. Your equations are
+not prose and are not judged as such.
+
+## Vale
+
+[Vale](https://vale.sh) powers grammar and style and is pinned as a dependency — no
+`brew install`, no manual step. The binary is fetched once on first run and cached; after
+that, runs are offline.
+
+Vale has no LaTeX reader, so a `.tex` file is handed to it as masked prose — commands,
+preamble, math, and verbatim already blanked, line for line — and the alerts still carry true
+source positions. Markdown and plain text go to Vale directly, parsed by its own reader.
+
+If that download is blocked (air-gapped machine, proxy, locked-down CI), the run emits one
+`vale.unavailable` warning and the other seven checkers still report. Vale is never a hard
+prerequisite. Install it yourself and it's picked up from `PATH`:
+
+```bash
+brew install vale     # or: apt install vale / scoop install vale
+```
+
+## Develop
+
+```bash
+uv sync                                    # from the lockfile
+uv run prose-preflight text.md --md out.md
+uv run pytest                              # all tests
+uv run pytest tests/test_checks.py -k units
+uv run ruff check . && uv run ruff format .
+```
+
+Every checker has a fixture pair in `tests/fixtures/`: an intentionally flawed document and
+the exact set of `(check, line)` pairs it must produce. Pinning positions is deliberate —
+false positives cost more here than misses, since each one burns agent tokens and spends
+trust in the report.
+
+Adding a checker is one module exposing `check(doc, rule) -> list[Finding]` plus one line in
+the registry. If it also needs a change to the runner, the design was wrong.
+
+## License
+
+MIT

prose_preflight-0.1.0/README.md

@@ -0,0 +1,194 @@
+<div align="center">
+
+# Prose Preflight
+
+**Your manuscript, checked by scripts, read by an agent.**
+
+[![PyPI](https://img.shields.io/pypi/v/prose-preflight?style=flat-square&logo=pypi&logoColor=white&color=fa934e&labelColor=121417)](https://pypi.org/project/prose-preflight/)
+[![Python](https://img.shields.io/badge/python-%E2%89%A5%203.11-fa934e?style=flat-square&logo=python&logoColor=white&labelColor=121417)](https://www.python.org)
+[![Vale](https://img.shields.io/badge/Vale-bundled-fa934e?style=flat-square&labelColor=121417)](https://vale.sh)
+[![uv](https://img.shields.io/badge/uv-managed-fa934e?style=flat-square&logo=uv&logoColor=white&labelColor=121417)](https://docs.astral.sh/uv/)
+[![License](https://img.shields.io/badge/license-MIT-fa934e?style=flat-square&labelColor=121417)](LICENSE)
+[![last commit](https://img.shields.io/github/last-commit/domrice/prose-preflight?style=flat-square&color=fa934e&labelColor=121417)](https://github.com/domrice/prose-preflight/commits/main)
+
+</div>
+
+---
+
+> No server. No API key. No network. No opinions about your argument.
+> Eight deterministic checkers read a Markdown, LaTeX, or plain-text manuscript and emit one
+> compact JSON report. The scripts analyze; the agent reports. Same input, same findings,
+> every time.
+
+An LLM asked to proofread a text will read all 9,000 words into its context, forget the
+middle, and confidently invent a citation error on page 4. This tool doesn't. The checkers
+find the problems and hand over line, column, and a short excerpt — the agent summarizes
+that and never reads the manuscript to find anything.
+
+## Install
+
+**1. Claude Code plugin**
+
+```
+/plugin marketplace add domrice/prose-preflight
+/plugin install prose-preflight
+```
+
+**2. Any other harness** (Cursor, Codex, Copilot, Gemini, Windsurf, …)
+
+```bash
+npx skills@latest add domrice/prose-preflight
+```
+
+**3. CLI only, no agent** — for CI or pre-commit
+
+```bash
+uvx prose-preflight text.md
+```
+
+**4. From source** (contributors)
+
+```bash
+git clone https://github.com/domrice/prose-preflight && cd prose-preflight
+uv sync && uv run pytest
+```
+
+Routes 1–3 resolve the package from PyPI, so none of them needs the repo on disk and
+`SKILL.md` carries no paths. Needs [Python ≥ 3.11](https://www.python.org); `uvx` supplies
+its own interpreter, so route 3 needs nothing but [uv](https://docs.astral.sh/uv/).
+
+## Use
+
+```bash
+uvx prose-preflight text.md
+```
+
+The full report is written to `PREFLIGHT_text.md` — one per document, so checking a second
+file never overwrites the first. A capped JSON summary goes to stdout, with `report` naming
+that file. That split is
+the whole point — the agent reads stdout, links the file, and stays small.
+
+| flag               | does                                             |
+| ------------------ | ------------------------------------------------ |
+| `--md PATH`        | move the report (default `PREFLIGHT_<file>.md`)  |
+| `--max-findings N` | cap stdout findings (default `20`; `0` lifts it) |
+| `--checks a,b`     | run a subset                                     |
+| `--config FILE`    | deep-merge a YAML file over the bundled config   |
+| `--version`        | the packaged version                             |
+
+Findings are capped round-robin across categories, so 400 Vale alerts cannot crowd out the
+one missing Methods section. `counts` and `total` always cover everything; `truncated` says
+what was dropped.
+
+## The two skills
+
+The CLI is deterministic on purpose — offline, no API key, same input same output. So
+nothing calls a model inside it. The judgment lives in the agent that drives it, where
+it is free, and it ships as two skills:
+
+- **`prose-preflight`** runs the command and reports it, but does not just print it. It
+  diagnoses what the counts mean, and gives every `severity: review` finding a verdict —
+  `keep`, `soften`, or `cut`, with a rewrite. The checker can see that a hedge is there;
+  only the agent can weigh it against the argument. It never edits the document.
+- **`prose-deepread`** is the opposite of preflight: it reads the manuscript end to end
+  and looks for what no regex can reach — claims the results do not support, terms used
+  before they are defined, sections that do not deliver what their heading promises, and
+  passages that can be cut without losing an argument. Expensive, so it runs only when
+  you ask for it by name. It never edits either.
+
+## Config
+
+Every check is configurable from one YAML file. Write it once per project:
+
+```bash
+uvx prose-preflight --init-config    # writes prose-preflight.yaml, every key commented
+uvx prose-preflight text.md         # picked up automatically from the working directory
+```
+
+A `prose-preflight.yaml` next to where you run is used without any flag; `--config FILE`
+points elsewhere. Keep only what you change — the rest falls back to the defaults. Lists are
+replaced, not appended, and unknown keys are reported on stderr, so a typo never fails
+silently.
+
+Two lists ship **empty**, because there is no universal right answer and a wrong entry costs
+you a false positive on every run: `terminology.terms` (your journal's preferred spellings)
+and `structure.required_sections` (most documents are fragments, not whole papers). Fill
+them in and those checks switch on.
+
+```yaml
+checks:
+  terminology:
+    terms:
+      finite element: [finite-element, FE]
+  sentence_length:
+    max_words: 32
+  structure:
+    required_sections:
+      [Abstract, Introduction, Methods, Results, Discussion, References]
+  units:
+    disabled_rules: [range_dash] # if your journal insists on hyphens
+```
+
+Everything a document convention needs lives in YAML. If a new convention would need a code
+change, that's a bug in the checker, not a missing feature.
+
+## Checks
+
+| check                                                                               | flags                                                             | severity      |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ------------- |
+| `vale.*`                                                                            | grammar, spelling, style — whatever your Vale config says         | error/warning |
+| `terminology.variant`                                                               | `dataset` where the config wants `data set` (opt-in: `terms`)     | warning       |
+| `acronym.undefined`                                                                 | used without expansion at first use                               | warning       |
+| `structure.missing_section` · `.section_order`                                      | required sections, absent or out of order (opt-in)                | error/warning |
+| `sentence_length.long`                                                              | sentences over `max_words`                                        | warning       |
+| `readability.flesch` · `.fog`                                                       | per section, skipping ones too short to score                     | warning       |
+| `units.space_before_unit` · `.percent_spacing` · `.range_dash` · `.p_value_spacing` | `12 mm` → NBSP, `5 %` → `5%`, `3-7` → `3–7`, `p<.05` → `p < 0.05` | warning       |
+| `claim.hedge` · `.booster`                                                          | "may possibly suggest", "clearly demonstrates"                    | **review**    |
+
+`review` is not a quieter warning. It is the line between what a script can decide and what
+it cannot: hedging and overclaiming are judgment calls about whether your evidence carries
+your claim. Nothing marked `review` is ever auto-applied, by either the tool or the agent.
+
+Code, math, verbatim blocks, and LaTeX command sequences are blanked before any regex runs —
+character-for-character, so every offset stays a true source position. Your equations are
+not prose and are not judged as such.
+
+## Vale
+
+[Vale](https://vale.sh) powers grammar and style and is pinned as a dependency — no
+`brew install`, no manual step. The binary is fetched once on first run and cached; after
+that, runs are offline.
+
+Vale has no LaTeX reader, so a `.tex` file is handed to it as masked prose — commands,
+preamble, math, and verbatim already blanked, line for line — and the alerts still carry true
+source positions. Markdown and plain text go to Vale directly, parsed by its own reader.
+
+If that download is blocked (air-gapped machine, proxy, locked-down CI), the run emits one
+`vale.unavailable` warning and the other seven checkers still report. Vale is never a hard
+prerequisite. Install it yourself and it's picked up from `PATH`:
+
+```bash
+brew install vale     # or: apt install vale / scoop install vale
+```
+
+## Develop
+
+```bash
+uv sync                                    # from the lockfile
+uv run prose-preflight text.md --md out.md
+uv run pytest                              # all tests
+uv run pytest tests/test_checks.py -k units
+uv run ruff check . && uv run ruff format .
+```
+
+Every checker has a fixture pair in `tests/fixtures/`: an intentionally flawed document and
+the exact set of `(check, line)` pairs it must produce. Pinning positions is deliberate —
+false positives cost more here than misses, since each one burns agent tokens and spends
+trust in the report.
+
+Adding a checker is one module exposing `check(doc, rule) -> list[Finding]` plus one line in
+the registry. If it also needs a change to the runner, the design was wrong.
+
+## License
+
+MIT