docs: one Claude file — cut agent context from 24227 to 2209 bytes, under the 4096-byte cap

[thedavidmeister]

Refs rainlanguage/rainix#298

rainix / static / static fails on main and on every open PR:

ERROR: this repo loads 24227 bytes of agent context at the start of every session
— 20131 over the 4096-byte cap. Cut 20131 bytes; do NOT raise the cap
(it is a floor-only ratchet).
    24227  CLAUDE.md

After this PR, from the same rainix-static binary the action runs:

agent-context-cap: clean — 2209 bytes loaded at session start (cap 4096)

The cap is not raised, the check is not skipped, and nothing is imported with
@path (which would be charged the same).

This repo gets ONE agent file

There is no .claude/rules/ directory, and adding one is not the way under the
cap. A rule scoped to src/**/*.sol + script/**/*.sol + test/**/*.sol is
every Solidity file in the repo: it does not load on demand, it loads on
essentially every turn that touches anything, which is the same permanent charge
as CLAUDE.md moved somewhere the gate does not count it. Relocating to a
path-scoped rule is only for content that has ALREADY passed the inclusion test
and merely happens to be path-scoped. Content that fails the test is deleted,
wherever it would otherwise land.

The repo is not big enough to justify a second file, so everything that survives
fits in CLAUDE.md alone — 2209 charged of 4096, with 1887 to spare.

The test, applied per LINE and not per file

Would a capable agent working here get this wrong, or merely take a moment
to find it?

CLAUDE.md is seven bullets. What each one stops an agent doing:

bullet	what an agent does without it
broadcasting is key custody; Manual sol artifacts is workflow_dispatch only	wires a merge, tag or schedule to the deploy, and spends real money from a real key
a sol-v* tag is the sole release trigger; [package].version is the LAST publish	bumps [package].version in an ordinary PR, treating it as a next-version slot
src/generated/<tag>/ is append-only	edits or tidies a frozen record that consumers already pin
ADDRESS_REGISTRY_ROOT == address(0) is INTENDED	"fixes" the rollout state, moving the deploy address, code hash and snapshot together
the deploy/verify abstracts in src/ are a SCOPED exception, not to be copied into a consumer repo	"fixes" the layout here, or exports the exception to a repo that has not earned it and breaks test/src/** mirroring src/**
slither.config.json filters those abstracts by exact filename, never by the src/abstract/ prefix	rewrites the filter as a prefix, silently exempting the next deployable file added there
a vm.createSelectFork failure is not a missing deployment	reads a rate-limited endpoint as a NotDeployedOnNetwork and chases a deploy that is fine

Each is a wrong ACTION, not a slow one. Everything else is discoverable and is
gone.

What the two .claude/rules/ files contributed, and what was cut from them

Both files are deleted. Line by line:

line	disposition
src/ holds the deploy machinery, and that is a scoped exception — incl. do-not-copy	kept (bullet 5)
slither.config.json matches filenames exactly, keep it that way when adding an abstract	kept (bullet 6)
vm.createSelectFork failure ≠ NotDeployedOnNetwork	kept (bullet 7)
.soldeerignore excludes test/, so an abstract there is unusable downstream	deleted — read .soldeerignore
why slither has nothing to say about those files (inherited, never deployed)	deleted — run slither
"fork tests need every RPC endpoint, not just the one under test"	deleted — the vm.createSelectFork error names the missing variable when it fires
the five <NETWORK>_RPC_URL values	moved to a committed .env.example

.env.example is a file, not context: an agent reads it on demand, it is where
anyone looks for it anyway, and the gate does not charge it. It is not restated
in prose.

What was deleted outright, and where each is recoverable from

Object to any specific one of these rather than to the diff as a whole.

deleted section	recoverable from
Project Overview	README.md opening + "Approach"
Build & Development, the command block, "CI runs three matrix tasks"	README.md § Develop, which lists what each of the three reusable workflows runs
the src/lib/LibRainDeploy.sol function-by-function tour	the NatSpec on each function
IAddressRegistryV1 / AddressRegistry (mutable bindings, resolve-once)	README.md § Address registry, at greater length
IMigrationRegistryV1 / MigrationRegistry — timestamp-not-flag, non-zero genesis, head vs per-migration refusal, msg.sender namespace	README.md § Migration registry, which states every one of them
generated snapshots: one list / three readers, the freeze coupling, DEPENDENCIES frozen with the release	script/Build.sol's own contract NatSpec, which says all of it
GeneratedSnapshotShapeTest shape spec, "values deliberately not asserted"	the test contract's NatSpec, verbatim
ast = true, the pinned solc settings, the [package].version comment	foundry.toml, which comments all three
the four verification groups and the candidate/released exemptions	README.md § Deploy verification, including the table
RainDeploySuitesBase / RainDeployBroadcast / Deploy.sol / RainDeployVerify* descriptions	README.md § One declaration + the contracts' NatSpec
Key Design Patterns, and Deploy → verify → tag	README.md § Deploying, and then releasing
License / SPDX headers / REUSE	README.md § License, REUSE.toml, and rainix-sol-legal enforcing it

Edits outside CLAUDE.md

• .env.example is new and committed. Five <NETWORK>_RPC_URL public
  endpoints plus a comment on why all five have to resolve —
  RainDeployVerifyChain forks every network in supportedNetworks(), not only
  the one under test. Added to .soldeerignore (local test setup is not part of
  the published package) and to REUSE.toml (a .env file carries no SPDX
  header).
• src/abstract/RegistryDeploySuites.sol NatSpec is unchanged from main.
  It says "see the scoped exception recorded in CLAUDE.md", and that is again
  where the exception is. No pointer to a file that does not exist.
• REUSE.toml no longer annotates .claude/**/ — an annotation for a path
  the repo does not contain is a licence claim about nothing. .soldeerignore
  keeps its .claude line: an ignore has a live subject either way, since a
  local .claude/settings.local.json can appear in a working tree at publish
  time.

QA

• Discriminating tests: n/a — the acceptance test is the gate itself, run
  locally. nix run path:<rainix>#rainix-static -- agent-context-cap ., the
  exact binary .github/actions/agent-context-cap/action.yml invokes, from
  rainix main. Before: the 24227-byte failure above, exit 1. After:
  clean — 2209 bytes loaded at session start (cap 4096), exit 0. The diff
  contains no Solidity at all, so there is no behaviour to test.
• The gate does NOT enforce the one-file rule, and I proved that rather than
  assuming it. P1 — restore both deleted rules files verbatim, paths:
  frontmatter intact: charged total stays at 2209, and the gate reports
  clean. So nothing in CI would catch a future agent moving text back into
  .claude/rules/ behind an all-Solidity glob; the line in CLAUDE.md saying
  there is no .claude/rules/ is the only thing that does, which is why it is
  worth its bytes. P2 — same two files with the frontmatter stripped: 5114,
  1018 OVER the cap, exit 1, both files named. P2 is what makes P1 a real null
  rather than a harness that measured nothing: the tool does see those files and
  does charge them, and paths: is precisely the thing that makes them free.
  Tree restored to 2209 and git status clean after each.
• Oracle: the gate's own output, from rainix's source rather than my
  arithmetic. rainix-static's agent_context_cap charges CLAUDE.md plus
  transitive @path imports plus every .claude/rules/**.md without paths:,
  and strips block-level HTML comments — which is why 2344 bytes on disk are
  2209 charged (the two SPDX comment lines). Every number here is a line of the
  tool's output.
• Category check: the ask is one thing — get the repo under the cap without
  raising it or skipping the check — and the category is every file the gate
  charges. Covered: CLAUDE.md is the only charged file that exists,
  .claude/ does not exist at all, no @path import is introduced. The cap
  constant is untouched and lives in rainix, not here. Adjacent and deliberately
  not done: Unname every return under src/, and stop the generator emitting named ones #129 (named
  returns) is a live ruling, but the old CLAUDE.md documented no return-naming
  convention, so there was nothing to relocate and nothing was invented.

Local verification

• nix develop -c forge fmt --check — exit 0.
• nix develop -c reuse lint — compliant, 77/77 files with copyright and
  licence information, exit 0 (78/78 previously: two rules files out, one
  .env.example in).
• pre-commit denofmt and taplo — passed on commit.
• forge test is not run against this branch because it cannot differ from
  main: git diff main --name-status is exactly .env.example,
  .soldeerignore, CLAUDE.md, REUSE.toml. No .sol, no foundry.toml, no
  remappings.txt, no soldeer.lock, no slither.config.json — nothing the
  compiler or the test runner reads. CI runs it anyway and is the verdict that
  counts.

[coderabbitai]

Warning

Review limit reached

@thedavidmeister, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 14 minutes

Limit details: You’ve used all 1 included review currently available under your plan.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9ee7fc6b-e539-4359-b43c-c2cb798be30d

📥 Commits

Reviewing files that changed from the base of the PR and between c243088 and 7061fba.

📒 Files selected for processing (4)

• .env.example
• .soldeerignore
• CLAUDE.md
• REUSE.toml

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[thedavidmeister]

Reviewed 7061fba: ready — Closes the repo-wide rainix / static failure.

Read off the CI log on this head rather than a local run: agent-context-cap: clean — 2209 bytes loaded at session start (cap 4096). All three jobs green — static, test, legal.

One agent file, seven bullets, no .claude/rules/. Each bullet states a wrong ACTION an agent would take without it, not a fact it would take a moment to find: broadcasting is key custody so nothing automatic may reach it; [package].version is the last publish so an ordinary PR does not bump it; a cut tag can never be un-cut so a frozen record is never edited; the zero root is the rollout state and must not be "fixed"; the src/ abstracts are a scoped exception that must not be carried into a consumer repo; the slither filter stays exact-filename or a deployable file added later is silently exempted; and a createSelectFork failure is an unreachable endpoint rather than a missing deployment.

The five RPC URLs went to .env.example — a file read on demand rather than prose charged on every turn. Everything else was deleted, not relocated: what .soldeerignore excludes, why slither has nothing to say about those files, and the whole architecture tour, all recoverable by reading the repo.

The merge with main takes this branch's file entire. #89 added a description of the source-anchor group after this branch was cut; run() calls the anchor on its first line and RainDeploySuitesBase defines it once, so a reader who opens either file has the answer — and #89's own mutation matrix pins the property twice over, which makes it enforced rather than remembered.

RegistryDeploySuites.sol is restored byte-identical to main, so its NatSpec pointing at CLAUDE.md is true again. REUSE.toml drops .claude/**/ and gains .env.example; reuse lint compliant.

The finding worth carrying forward: the gate does NOT enforce the one-file rule. Restoring both deleted rules files verbatim with their paths: frontmatter leaves the charge at exactly 2209 and the gate still reports clean; stripping the frontmatter gives 5114 and fails, which proves the tool sees them and the first result is a real null rather than a dead probe. Nothing in CI catches text moved back behind an all-Solidity glob — only the line in CLAUDE.md saying this is the repo's one agent file.

Merging this restores slither to CI across the repo: agent-context-cap gates the step ahead of slither, so slither has not run on any rain.deploy head, including main, while the cap was breached.

CodeRabbit reports Review rate limited — green check, no review behind it, so the zero-thread count is vacuous.