Docs: record the CI/release contract; fix stale README claims

CLAUDE.md gains a "CI and releasing" section (required checks,
the per-push-CI-stays-fast rule, the guarded test-ci entry point,
branch rules and the bypass notice, the release procedure pointer).
README's development section still said black; it now says ruff and
describes CI.  The quickstart claimed a 22-layer decoder at hidden
size 256 — stale since binary_increment's default width moved to
512; witnessed today: 20 layers at hidden 512, compile 1.5s.

Test Suite Status: Unknown
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: physicsrob

CLAUDE.md

@@ -181,6 +181,32 @@ tolerance-boundary flake (see *FP nondeterminism at tolerance boundaries*
 under *Debugging compiled graphs*). Investigate the ops on the failing
 codepath, not the test.
 
+# CI and releasing
+
+GitHub Actions (`.github/workflows/`) runs two required checks on every
+push and PR: `lint` (make lint) and `smoke` (`scripts/ci_smoke.py` —
+compile binary_increment on CPU, generate through a transformers
+pipeline, assert the output).  **Per-push CI stays fast; never add the
+full suite or any slow job to it** (decided 2026-07-23 — the full suite
+takes ~an hour on a 2-core runner).  The full CPU suite runs weekly via
+`full-tests.yml` and on demand via workflow_dispatch; its entry point,
+`make test-ci`, is guarded to refuse local runs — use `make test`
+(Modal) or `make test-local FILE=...` instead.
+
+Branch rules on `main`: force-pushes and deletion are blocked for
+everyone; the two checks are required with a repo-admin bypass, so a
+direct push prints `remote: Bypassed rule violations` — that notice is
+the ruleset working, not an error.
+
+Releases: `docs/releasing.md` is the procedure.  The version in
+`pyproject.toml` is the single source of truth; bumping it requires
+`make modal-lock` (the standalone lock records torchwright's version)
+plus `uv lock` at the umbrella.  Pushing a `v*` tag publishes to PyPI
+via Trusted Publishing; the workflow refuses a tag that doesn't match
+the pyproject version.  Keep `RELEASE_NOTES.md`'s `# Unreleased`
+section current as user-facing changes land — release time only
+retitles it.
+
 # Numerical noise
 
 Every approximate op in `torchwright/ops/` is measured against its exact-math

README.md

@@ -35,7 +35,7 @@ print(generate("1011\n", return_full_text=False)[0]["generated_text"])
 # 1100
 ```
 
-The compiler scheduled this graph into a 22-layer decoder at hidden size 256 (the
+The compiler scheduled this graph into a 20-layer decoder at hidden size 512 (the
 `d=D_MODEL` argument). Every weight was computed from the source graph; nothing
 was trained. Compiling this example took under ten seconds on a laptop CPU.
 
@@ -168,12 +168,17 @@ Examples that define `create_network_parts()` compile to a bundle with
 ## Development
 
 `torchwright/` holds the package (`graph`, `ops`, `compiler`, `debug`);
-`examples/`, `tests/`, and `docs/` are what they say. `make lint` (black + mypy)
+`examples/`, `tests/`, and `docs/` are what they say. `make lint` (ruff + mypy)
 and `make test-local FILE=tests/...` (single-file pytest) run anywhere. The full
 suite, `make test`, shards across GPU containers on Modal and needs a Modal
 account. `make measure-noise` regenerates the committed per-op noise data; two
 tests pin it to the code.
 
+CI runs on every push and pull request: `make lint`, plus a smoke that compiles
+an example on CPU and checks its generated output. The full suite additionally
+runs on CPU weekly. Releases are tagged (`v*`) and published to PyPI from CI;
+`docs/releasing.md` has the procedure.
+
 ## License
 
 Apache-2.0.