docs: describe save_file's real sequence in the Python README

[dmccoystephenson]

Summary

Stage A documentation-accuracy sweep. The numbered "What a save actually does" list in python/README.md was checked against GitHubDocsClient.save_file and two claims did not hold:

• Step 1 said the default branch's tip SHA is always looked up. save_file reads it only when the per-file branch does not exist yet (get_ref_sha(default_branch) sits inside the if branch_sha is None: block). The tip lookup is moved into step 2, where it actually happens.
• Step 3 omitted the get_file(path, ref=branch) read that supplies the SHA for the PUT. It is now stated, together with its consequence: a save edits a file that already exists. For a path with no file on the branch, the read 404s and save_file raises GitHubDocsError with .status 404 before any commit — leaving behind any per-file branch that step 2 just created. This was confirmed by running save_file("new.md", …) against a patched urlopen: the request sequence stopped at GET …/contents/new.md?ref=docs-edit/new.md, and the resulting error carried status 404.

The module docstring in python/src/github_docs/client.py carried the same step list and is corrected in the same way. That is a docstring-only change: _redact, the Authorization header and error construction are untouched.

The sweep also found that the README's Errors section ("Everything that stopped an edit from landing raises GitHubDocsError") does not hold for a read timeout or a non-JSON 2xx body. Because that is a code bug (the README describes the intended contract), it is filed as #11 and not changed here.

Half: python/ only.

No tracking issue: this is drift found during the Stage A sweep.

Skipped issues

• 0.1.0 is unpublished on npm and PyPI, so 505 lines of forked GitHub-content code stay duplicated across two orgs #5 and PyPI trusted publishing is unconfigured, and this is the one release workflow with no dry_run to rehearse it #6 were deferred because both are operator/release decisions (publishing 0.1.0 and configuring PyPI trusted publishing) that no change to this repository can settle. Each already has a comment recording the deferral.
• A read timeout or a non-JSON 2xx body escapes save_file as something other than GitHubDocsError #11 was deferred because it was filed during this cycle. It is a code fix and belongs in a separate implementation cycle.

Test plan

• Behaviour claims checked against save_file and confirmed with a patched-urlopen probe
• CI python (3.9–3.13) green on the PR head. The only code change is a docstring, but local verification was UNVERIFIED: the sandbox interpreter is Python 3.8, below the 3.9 floor, so the CI matrix is the anchor
• CI js legs green (not touched)

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric (head fc52aeb):

• Scope: PASS — two files. python/README.md changes only the save-sequence list and adds one paragraph, and client.py changes only the matching module-docstring lines.
• Tests-new: PASS (n/a) — no new public symbol.
• Tests-fix: PASS (n/a) — no production behaviour changed; the code bug found alongside is filed as A read timeout or a non-JSON 2xx body escapes save_file as something other than GitHubDocsError #11 and not fixed here.
• Sibling structure: PASS — no new files.
• Sibling renames: PASS (n/a) — nothing renamed.
• Docs: PASS — the README list and the module docstring now agree with each other and with save_file. The tip-SHA read is only inside if branch_sha is None:, and get_file(path, ref=branch) precedes the PUT.
• Issue resolution: PASS (n/a) — no Closes. This is sweep drift with no tracking issue.
• CI: PASS — all eight legs green on fc52aeb (js 18/20/22, python 3.9–3.13). Local Python verification was UNVERIFIED (the sandbox interpreter is 3.8, below the floor), so CI on the head SHA is the anchor.
• No-leak (python): PASS — no GitHubDocsError message is added or changed.
• Stdlib-only / No runtime dependency / Support-matrix parity / Sentinel intact: PASS — neither manifest nor tests/ is touched.
• Do-not-auto-merge paths: none matched. client.py changes only in the module docstring; _redact, the Authorization header and error construction are not in the diff.

Judgment call flagged for a human reader:

• python/README.md:74-77 — the new paragraph documents that a save of a non-existent path leaves the per-file branch behind. That is accurate today (create_ref runs before get_file), but documenting it could read as endorsing it. It is stated as current behaviour and not as a guarantee. If the owner considers it a bug, it belongs with A read timeout or a non-JSON 2xx body escapes save_file as something other than GitHubDocsError #11's error-surface work and not in this docs PR.

Out-of-diff observation: the README's Errors section still overstates the contract ("Everything that stopped an edit from landing raises GitHubDocsError"). Two paths contradict it, a body-read timeout and a non-JSON 2xx body. The code is what is wrong, so the text was left alone and the fix is tracked in #11.

This review comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson