docopt2 1.2.0__tar.gz → 1.3.0__tar.gz

{docopt2-1.2.0 → docopt2-1.3.0}/.github/workflows/ci.yml

@@ -33,15 +33,22 @@ jobs:
           - os: macos-latest
             python-version: "3.14"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        # Turned off on every setup-uv step in this repo, because `enable-cache` defaults to
+        # "auto", which means ON for hosted runners. It buys nothing here: `uv sync --locked`
+        # takes about 2s in every job, so a restore/save cycle costs the same or more. It also
+        # costs posture, since restoring a previous run's artifacts is the supply-chain surface
+        # zizmor's cache-poisoning rule is about, and this repo SHA-pins its actions.
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: false
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
@@ -62,7 +69,7 @@ jobs:
 
       - name: Upload coverage to Codecov
         if: matrix.coverage
-        uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
+        uses: codecov/codecov-action@303a32d7a59b442fa8d48b6a1cc6825c09c847a5 # v7.1.1
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage.xml
@@ -70,15 +77,17 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: false
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.14"
 
@@ -106,6 +115,19 @@ jobs:
       - name: Type check (pyright, floor target 3.10)
         run: uv run pyright --pythonversion 3.10 src/docopt2
 
+      - name: Type check (pyrefly)
+        run: uv run pyrefly check
+
+      - name: Type check (pyrefly, floor target 3.10)
+        run: uv run pyrefly check --python-version 3.10
+
+      - name: Type coverage (pyrefly, every annotation in the package)
+        run: uv run pyrefly coverage check src/docopt2
+
+      # --ignoreexternal: without it one symbol is short, `argv_strategy`, on hypothesis's own `SearchStrategy`
+      - name: Type completeness (pyright, the exported surface)
+        run: uv run pyright --verifytypes docopt2 --ignoreexternal
+
   # The unit tests pin what the generated completion SCRIPTS say; they never run them, and that is exactly
   # where a completion bug hides. This drives real shells through a pty and a real Tab keypress, and holds
   # what they offer against the grammar. It is known to fail on an unfixed script, so it guards rather than
@@ -117,12 +139,14 @@ jobs:
       matrix:
         os: [ubuntu-latest, windows-latest]
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: false
 
       - name: Install zsh and fish
         if: runner.os == 'Linux'

{docopt2-1.2.0 → docopt2-1.3.0}/.github/workflows/codeql.yml

@@ -17,10 +17,10 @@ jobs:
     permissions:
       security-events: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+      - uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         with:
           languages: python
-      - uses: github/codeql-action/analyze@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+      - uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2

{docopt2-1.2.0 → docopt2-1.3.0}/.github/workflows/codspeed.yml

@@ -26,15 +26,17 @@ jobs:
       contents: read
       id-token: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: false
 
       - name: Run benchmarks under CodSpeed
-        uses: CodSpeedHQ/action@f99becdce5e5d51fd556489ebef684f4ecfd6286 # v4.18.5
+        uses: CodSpeedHQ/action@c4fd08a3a159bd0cc208da1e0edf32b8c47d75e5 # v5.4.0
         with:
           mode: simulation
           run: uv run --locked --group benchmark pytest benchmarks/ --codspeed --no-cov

{docopt2-1.2.0 → docopt2-1.3.0}/.github/workflows/docs.yml

@@ -17,15 +17,17 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: false
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.14"
 
@@ -54,4 +56,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

docopt2-1.3.0/.github/workflows/fuzz.yml

@@ -0,0 +1,80 @@
+name: Fuzz
+
+# Coverage-guided fuzzing of the public API with atheris, off the PR path. The invariant is the one
+# tests/test_robustness.py states and Hypothesis checks on grammar-shaped input: no entry point may raise
+# anything but DocoptExit / DocoptLanguageError for any input. The Nightly job explores well-formed usage
+# with Hypothesis; this reaches the malformed byte shapes it cannot, under coverage feedback, and a
+# per-input -timeout turns a runaway (a pathological slowdown or an outright hang) into a finding. Unlike
+# Mutation (report-only), a crash or timeout here is a real bug: the job fails and uploads the reproducer,
+# which becomes a committed regression test.
+#
+# Linux only: atheris ships no Windows wheel. Pinned to Python 3.12, which has a prebuilt manylinux wheel.
+
+on:
+  schedule:
+    - cron: "41 4 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  actions: read # the corpus of the last run is an artifact of it
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  fuzz:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: false
+
+      # An artifact and not a cache: a cache is evicted after seven days unread, and this job comes back on the eighth.
+      - name: Start from the corpus of the last run
+        continue-on-error: true # the first run has none
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          last=$(gh run list --repo "$GITHUB_REPOSITORY" --workflow fuzz.yml --status success --limit 1 --json databaseId --jq '.[0].databaseId')
+          gh run download "$last" --repo "$GITHUB_REPOSITORY" --name fuzz-corpus --dir corpus
+
+      # shell: bash turns pipefail on, so a finding fails the step through the tee.
+      - name: Fuzz the public API for ten minutes
+        shell: bash
+        run: |
+          mkdir -p fuzz-findings corpus
+          cp fuzz/corpus/* corpus/
+          uv run --locked --no-dev --python 3.12 --with atheris \
+            python fuzz/fuzz_docopt.py corpus -dict=fuzz/docopt.dict -max_len=512 \
+            -max_total_time=600 -timeout=30 -rss_limit_mb=4096 -artifact_prefix=fuzz-findings/ \
+            2>&1 | tee fuzz.log
+
+      # Run with no dictionary, this job covered 76 edges a week and was green: no input ever spelled "usage:".
+      - name: Hold the run to a coverage floor
+        run: |
+          covered=$(grep -oE 'DONE +cov: [0-9]+' fuzz.log | grep -oE '[0-9]+$')
+          echo "edges covered: ${covered:-none}"
+          test "${covered:-0}" -ge 1000
+
+      # Whole: libFuzzer writes an input only where it covers something new, and its -merge does not run under atheris.
+      - name: Upload the corpus for the next run
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: fuzz-corpus
+          path: corpus/
+
+      - name: Upload any crash or timeout reproducer
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: fuzz-findings
+          path: fuzz-findings/
+          if-no-files-found: ignore

{docopt2-1.2.0 → docopt2-1.3.0}/.github/workflows/mutation.yml

@@ -34,12 +34,14 @@ jobs:
       # more, and those 3 come back as survivors to look at. It over-reports suspects, never hides one.
       PYTEST_ADDOPTS: "--no-cov --hypothesis-profile=mutation"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: false
 
       - name: Baseline suite must pass before any mutant is judged
         # A red baseline would make mutmut score every mutant killed, and the report would read as a

{docopt2-1.2.0 → docopt2-1.3.0}/.github/workflows/nightly.yml

@@ -21,12 +21,14 @@ jobs:
   explore:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          enable-cache: false
 
       - name: Property tests, wide and randomised
         run: uv run --locked pytest --hypothesis-profile=explore -q --no-cov

{docopt2-1.2.0 → docopt2-1.3.0}/.github/workflows/publish.yml

@@ -16,17 +16,17 @@ jobs:
       contents: write # upload artifacts to the GitHub Release
       attestations: write # actions/attest-build-provenance
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Install uv
-        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           enable-cache: false
 
       - name: Set up Python
-        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
         with:
           python-version: "3.15"
           allow-prereleases: true
@@ -36,13 +36,13 @@ jobs:
 
       - name: Attest wheel provenance
         id: attest-wheel
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
         with:
           subject-path: dist/*.whl
 
       - name: Attest sdist provenance
         id: attest-sdist
-        uses: actions/attest-build-provenance@0f67c3f4856b2e3261c31976d6725780e5e4c373 # v4.1.1
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
         with:
           subject-path: dist/*.tar.gz
 
@@ -59,13 +59,13 @@ jobs:
           test -s provenance/provenance.intoto.jsonl
 
       - name: Install syft
-        uses: anchore/sbom-action/download-syft@e22c389904149dbc22b58101806040fa8d37a610 # v0.24.0
+        uses: anchore/sbom-action/download-syft@66cbf4bc1f1c0d2edc94016e65bc221b6bb0ad6c # v0.24.3
 
       - name: Generate SBOM (CycloneDX)
         run: syft scan dir:dist -o "cyclonedx-json=provenance/docopt2.sbom.cdx.json"
 
       - name: Publish to PyPI (Trusted Publishing + PEP 740 attestations)
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
 
       - name: Upload artifacts and provenance to the GitHub Release
         env:

{docopt2-1.2.0 → docopt2-1.3.0}/.github/workflows/scorecard.yml

@@ -16,10 +16,10 @@ jobs:
       security-events: write
       id-token: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
+      - uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
         with:
           results_file: results.sarif
           results_format: sarif
@@ -29,6 +29,6 @@ jobs:
           name: SARIF file
           path: results.sarif
           retention-days: 5
-      - uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
+      - uses: github/codeql-action/upload-sarif@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4.38.2
         with:
           sarif_file: results.sarif

{docopt2-1.2.0 → docopt2-1.3.0}/.github/workflows/zizmor.yml

@@ -19,7 +19,7 @@ jobs:
     permissions:
       security-events: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: zizmorcore/zizmor-action@192e21d79ab29983730a13d1382995c2307fbcaa # v0.5.7
+      - uses: zizmorcore/zizmor-action@cc914d7f3750a2d13d75c7f184a1060aa0e9d482 # v0.6.4

{docopt2-1.2.0 → docopt2-1.3.0}/CONTRIBUTING.md

@@ -39,8 +39,19 @@ uv run ty check src/docopt2
 uv run pytest
 ```
 
-CI requires 100% code coverage (line and branch); a PR that drops below it fails. It also runs
-`mypy --strict` and `pyright` on the typed surface, across Python 3.10 - 3.15.
+CI requires 100% code coverage (line and branch), and a PR that drops below it fails. It also runs
+`mypy --strict`, `pyright` and `pyrefly` on the typed surface, across Python 3.10 - 3.15.
+
+Type annotations are held at 100% too. Both checks need the extra checkers, installed with
+`uv sync --group typecheck`:
+
+```bash
+# every annotation in the package
+uv run pyrefly coverage check src/docopt2
+
+# every exported symbol has a type a checker can name
+uv run pyright --verifytypes docopt2 --ignoreexternal
+```
 
 ## Commit style
 

{docopt2-1.2.0 → docopt2-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: docopt2
-Version: 1.2.0
+Version: 1.3.0
 Summary: Typed successor to docopt: the usage message is the parser spec.
 Project-URL: Homepage, https://github.com/Solganis/docopt2
 Project-URL: Repository, https://github.com/Solganis/docopt2
@@ -53,17 +53,15 @@ Description-Content-Type: text/markdown
   <a href="https://pypi.org/project/docopt2/"><img src="https://img.shields.io/pypi/pyversions/docopt2" alt="Python"></a>
   <a href="https://pepy.tech/projects/docopt2"><img src="https://static.pepy.tech/badge/docopt2/month" alt="Downloads"></a>
   <br>
-  <a href="https://solganis.github.io/docopt2/concepts/design-boundaries/"><img src="https://img.shields.io/badge/runtime%20deps-0-2ea043" alt="zero runtime dependencies, pydantic support optional"></a>
-  <a href="https://solganis.github.io/docopt2/guides/typed-results/"><img src="https://img.shields.io/badge/type--checked-ty%20%7C%20mypy%20%7C%20pyright-2ea043" alt="the typed API is checked by ty, mypy --strict, and pyright"></a>
+  <a href="https://solganis.github.io/docopt2/concepts/design-boundaries/#zero-runtime-dependencies"><img src="https://img.shields.io/badge/runtime%20deps-0-2ea043" alt="zero runtime dependencies, pydantic support optional"></a>
+  <a href="https://solganis.github.io/docopt2/guides/typed-results/"><img src="https://img.shields.io/badge/type--checked-ty%20%7C%20mypy%20%7C%20pyright%20%7C%20pyrefly-2ea043" alt="the typed API is checked by ty, mypy --strict, pyright and pyrefly"></a>
   <a href="https://solganis.github.io/docopt2/"><img src="https://img.shields.io/badge/docs-online-black" alt="Documentation"></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/Solganis/docopt2"><img src="https://img.shields.io/ossf-scorecard/github.com/Solganis/docopt2?label=OpenSSF%20Scorecard" alt="OpenSSF Scorecard"></a>
 </p>
 
----
-
 <h2 align="center">What is docopt2?</h2>
 
-docopt2 is a command-line argument parser for Python. Most CLI libraries have you build the parser in code and generate a `--help`; docopt2 inverts that: **you write the usage message, and that message *is* the parser.**
+docopt2 is a command-line argument parser for Python. Most CLI libraries have you build the parser in code and generate a `--help`. docopt2 inverts that: **you write the usage message, and that message *is* the parser.**
 
 Put the `Usage:` and `Options:` text in your docstring - the help you would write anyway - and docopt2 parses the command line against it. The help users read and the parser that runs are the same, and cannot drift.
 
@@ -71,7 +69,7 @@ Put the `Usage:` and `Options:` text in your docstring - the help you would writ
 The <a href="https://solganis.github.io/docopt2/">full documentation</a> walks through <a href="https://solganis.github.io/docopt2/getting-started/">Getting started</a> and the guides.
 </p>
 
-<h2 align="center">Features</h2>
+<h3 align="center">Features</h3>
 
 <table>
 <tr>
@@ -176,13 +174,13 @@ docopt2 reads the same usage DSL as docopt - the `Usage:` and `Options:` blocks
 <tr><td><code>a | b</code></td><td>Mutually exclusive: choose one.</td></tr>
 <tr><td><code>element...</code></td><td>Repeatable: one or more.</td></tr>
 <tr><td><code>[options]</code></td><td>Stands in for every option listed under <code>Options:</code>.</td></tr>
-<tr><td><code>--</code></td><td>Ends option parsing; the rest is positional.</td></tr>
+<tr><td><code>--</code></td><td>Ends option parsing. The rest is positional.</td></tr>
 <tr><td><code>[default: &lt;val&gt;]</code></td><td>An option's default value, declared under <code>Options:</code>.</td></tr>
 <tr><td><code>[env: &lt;var&gt;]</code></td><td>An option's environment-variable fallback.</td></tr>
 <tr><td><code>[config: &lt;key&gt;]</code></td><td>An option's config-file fallback (CLI &gt; env &gt; config &gt; default).</td></tr>
 </table>
 
-The legend covers the essentials; precedence and edge cases are in the [full usage grammar](https://solganis.github.io/docopt2/guides/usage-dsl/).
+The legend covers the essentials. Precedence and edge cases are in the [full usage grammar](https://solganis.github.io/docopt2/guides/usage-dsl/).
 
 <a name="typed-results"></a>
 <h2 align="center"><a href="https://solganis.github.io/docopt2/guides/typed-results/">Why typed docopt?</a></h2>
@@ -224,7 +222,7 @@ Usage:
   git push [--force] <remote>
 ```
 
-**docopt2** [points at it](https://solganis.github.io/docopt2/guides/diagnostics/#a-mismatch-at-parse-time) - in the argv *and* the usage that rejected it. The "did you mean" hint is opt-in: pass `suggest=True`.
+**docopt2** [points at it](https://solganis.github.io/docopt2/guides/diagnostics/#a-mismatch-at-parse-time) - in the argv *and* the usage that rejected it. A mistyped option or command also gets a "did you mean" hint.
 
 <p align="center">
   <img src="docs/assets/diagnostic.png" width="620" alt="A docopt2 error: 'unknown option --forcce' with a caret under the token in the argument vector and a second caret under --force in the usage, plus a 'did you mean --force?' hint">
@@ -262,6 +260,8 @@ def commit(args):
 app.run()   # parse argv, call the matched command's handler
 ```
 
+[`app.check()`](https://solganis.github.io/docopt2/guides/dispatch/#checking-the-table) lints the table before any run.
+
 <a name="shell-completion"></a>
 <h2 align="center"><a href="https://solganis.github.io/docopt2/guides/completion/">Shell completion</a></h2>
 
@@ -273,8 +273,8 @@ app.run()   # parse argv, call the matched command's handler
   <a href="https://www.nushell.sh/"><img src="https://img.shields.io/badge/nushell-4E9A06?logo=nushell&logoColor=white" alt="nushell"></a>
 </p>
 
-Generate the completion script for your shell; Tab then narrows to exactly what is valid at the cursor -<br>
-commands and options, never positional values - straight from the usage:
+Generate the completion script for your shell. Tab then narrows to exactly what is valid at the cursor,<br>
+straight from the usage:
 
 ```console
 $ naval <TAB>
@@ -285,6 +285,10 @@ $ naval ship titanic move 1 2 <TAB>
 --speed
 ```
 
+With a schema, Tab also [completes the values](https://solganis.github.io/docopt2/guides/completion/#completing-values) of a `Literal` or an `Enum` field and the [file names](https://solganis.github.io/docopt2/guides/completion/#completing-file-names) of a `Path` field.
+
+A program [prints its own script](https://solganis.github.io/docopt2/guides/completion/#installing-it): `eval "$(_DOCOPT2_COMPLETE=bash naval)"`.
+
 <a name="schema-codegen"></a>
 <h2 align="center"><a href="https://solganis.github.io/docopt2/guides/stub/">Generate the schema from the usage</a></h2>
 
@@ -313,7 +317,7 @@ Widen a field by hand (`speed: int`) and the coercion is automatic.
 <a name="layered-fallback"></a>
 <h2 align="center"><a href="https://solganis.github.io/docopt2/guides/usage-dsl/#environment-and-config-fallback">Layered value resolution</a></h2>
 
-Declare an option's fallback sources in the usage with `[env: VAR]` and `[config: key]`; docopt2 resolves each -<br>
+Declare an option's fallback sources in the usage with `[env: VAR]` and `[config: key]`. docopt2 resolves each -<br>
 the command-line argument first, then the environment, then a config mapping you pass, then the `[default: ...]`:
 
 ```python
@@ -344,7 +348,7 @@ port = 80  # --port, env APP_PORT
 <a name="rich-help"></a>
 <h2 align="center"><a href="https://solganis.github.io/docopt2/guides/help/">Self-documenting <code>--help</code></a></h2>
 
-`--help` prints your usage verbatim by default. Opt into `help_style="rich"` for an aligned, colored screen that documents **where each value resolves from** - the `[env, config, default]` chain no other CLI library surfaces:
+`--help` prints your usage verbatim by default. Opt into `help_style="rich"` for an aligned, colored screen that documents **where each value resolves from**, reading the `[env, config, default]` chain straight out of the usage you already wrote:
 
 <p align="center">
   <img src="docs/assets/rich-help.png" width="878" alt="A docopt2 rich --help: a bold Usage, then Options with green option names, aligned descriptions, and a dimmed source chain per option - '[env: PORT, config: server.port, default: 8080]' - documenting the resolution order">
@@ -383,6 +387,10 @@ catching defects the parser would otherwise accept in silence:
 It flags dead `[default: ...]` values, options declared but never usable,<br>
 ambiguous variadic positionals, and redundant alternatives.
 
+A usage that does not parse is reported as the error `docopt()` would raise, and `docopt2 check` exits 1.
+
+With `check(doc, schema=Args)` it also reports where the [schema disagrees with the usage](https://solganis.github.io/docopt2/guides/check/#checking-a-schema).
+
 <a name="usage-formatter"></a>
 <h2 align="center"><a href="https://solganis.github.io/docopt2/guides/fmt/">Format the usage</a></h2>
 
@@ -410,7 +418,7 @@ The change is layout-only and idempotent. `docopt2 fmt` prints to stdout - pipe
 <a name="round-trip"></a>
 <h2 align="center"><a href="https://solganis.github.io/docopt2/guides/round-trip/">Round-trip: results back to argv</a></h2>
 
-`docopt` parses an argv into a result; `format_argv` does the inverse - the same usage message drives *both* directions:
+`docopt` parses an argv into a result. `format_argv` does the inverse - the same usage message drives *both* directions:
 
 ```python
 doc = "Usage: prog <src> <dst> [--force]"