docs: correct the same two claims where the README audit didn't reach

CLAUDE.md

@@ -61,8 +61,9 @@ npm run assistant:streaming         # src/assistant-streaming.ts — Part 10.3/1
 npm run models                       # src/models.ts — lists model IDs available to the API key
 ```
 
-The Python half runs the same lessons through `uv`, from the **repo root**, not
-from inside `pyweather/`:
+The Python half runs the same lessons through `uv`, and — unlike the npm
+scripts above — from any directory inside the repo: `pyweather/` resolves
+both the ledger and `.env` from its own location on disk, not from cwd.
 
 ```bash
 npm run typecheck:py          # pyright, strict — run this after any pyweather/ edit
@@ -200,12 +201,29 @@ with `404 not_found_error`, or pricing looks off, run `npm run models` to check
 what the live API actually returns rather than trusting this repo or the
 tutorial document.
 
-**`verify:docs` covers both documents.** `scripts/check-docs.ts` holds a
-`LANGUAGES` table: everything language-specific (fence names, marker comment
-syntax, comment stripping, how to typecheck, which directory) lives there, and
-the four gates — compile, ordering, diff, coverage — are shared. Adding a third
-language means adding a row, not a branch. Note the Python comment stripper
+**`verify:docs` covers both documents.** `scripts/check-docs.ts` runs six
+gates: two repo-wide ones first — structure (every Markdown file's fences
+balance and its links resolve) and command parity (every `package.json`
+script has a matching `uv run` entry point in `pyproject.toml`, and vice
+versa) — then, per document, the four code-coupling gates: compile, ordering,
+diff, coverage. A `LANGUAGES` table holds everything language-specific (fence
+names, marker comment syntax, comment stripping, how to typecheck, which
+directory); the six gates themselves are shared, so adding a third language
+means adding a row, not a branch. The command parity gate is why adding an
+npm script without a matching `[project.scripts]` entry in `pyproject.toml`
+fails `verify:docs` — three scripts are deliberately exempt from that check
+(`NPM_ONLY` in `check-docs.ts`): `typecheck`, `typecheck:py`, and
+`verify:docs` itself, since they're infrastructure, not lessons, and have no
+Python counterpart to pair with. Note the Python comment stripper
 also drops **docstrings** that sit alone on their own lines, because Python
 puts its teaching headers in docstrings where TypeScript puts them in `//`
 comments; without that the document would have to reproduce every docstring
 verbatim.
+
+**The stripping is also a blind spot, and it is the one to remember.** Because
+comments are removed from *both* sides before the diff gate compares them, a
+teaching comment can drift out of step with its listing in the document — or
+say something flatly untrue — while all six gates stay green. The comments are
+the teaching in this repo, so that is not a small hole: when you edit a comment
+in `src/` or `pyweather/`, sync the document's copy by hand, because nothing
+else will.

docs/setup-mac.md

@@ -89,7 +89,7 @@ git --version
 
 `npm` came with Node. It installs code libraries other people wrote. Git is already on your Mac.
 
-> **Why 20.6 specifically.** That's the release where Node learned to read a `.env` file by itself, via the `--env-file` flag every script in this project uses. On an older Node the scripts start and then fail to find your API key, which looks like a key problem and isn't.
+> **Why 20.6 specifically.** That's the release where Node learned to read a `.env` file by itself, via the `--env-file` flag every script that needs a key uses. On an older Node the scripts start and then fail to find your API key, which looks like a key problem and isn't.
 
 ## 0.5 Git and GitHub
 

pyproject.toml

@@ -2,10 +2,14 @@
 # for one specific reason: usage.csv.
 #
 # src/usage.ts writes 'usage.csv' as a RELATIVE path, resolved against the
-# process's working directory. npm runs its scripts from the project root, so
-# that is where the ledger lands. If the Python lessons ran from inside
-# pyweather/, they would quietly create a SECOND usage.csv in there, and the
-# whole point of this document — one artifact, two languages — would evaporate.
+# process's working directory. That's safe for npm, which always runs its
+# scripts from the project root — but `uv run` makes no such promise, so
+# pyweather/usage.py can't get away with the same trick. It resolves the
+# ledger from `__file__` instead — two directories up from usage.py, which
+# lands here, at the repo root, no matter where `uv run` was invoked from.
+# Without that, the Python lessons could quietly create a SECOND usage.csv
+# wherever you happened to be standing, and the whole point of this document
+# — one artifact, two languages — would evaporate.
 #
 # Same directory, same file. `uv run agent` and `npm run agent` append to it.