docs: bring CLAUDE.md back under its own budget - #141
Merged
Conversation
21142 chars against the 20k the file sets for itself, measured with wc -c rather than estimated. It was already over before the long-range forecast work, which added the tripwire that pushed it further. The SQLite connection PRAGMAs, the busy_timeout arithmetic, the promotion explanation and the production numbers behind it move to beacon-storage, whose description already names Transaction/ReadOnlyTransaction as a load trigger and which did not carry the depth. What stays in CLAUDE.md is the part that fails silently: a read on the write path serialises against every other read and never says so. Compressed rather than cut: the deployment paragraph, whose detail is in deploy/README.md; the BEACON_PROXY_URL bullet, which restated the egress rule given three sections above; and the measure-never-estimate paragraph, whose procedure belongs to the compress-claude-md skill. Cut outright: the embedded-assets bullet, both halves of which are visible in cmd/web/main.go. Nothing was dropped. All 227 backticked spans and all 16 figures in the old text still appear in CLAUDE.md or in a skill. Refs: #135 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U6jNuzK5PZrhDWBxB3t2gY
This was referenced Aug 23, 2026
prorochestvo
added a commit
that referenced
this pull request
Aug 23, 2026
#140 was opened this morning against 16ae37c and slims CLAUDE.md by moving depth into the three project skills. It conflicts now, and much of what it moved has since arrived by other routes — the outlook work carried its own skill sections, and #141 relocated the SQLite PRAGMA and write-lock depth. What did not arrive is canon written nowhere else, so it is taken here verbatim rather than paraphrased. beacon-collection gains the source kind and options JSON column, the cmd/doctor operator umbrella, and the reason the Telegram bot bypasses the proxy in code rather than by configuration: it is the channel that reports collection failures, so it must not share a failure mode with what it reports on. beacon-http-api gains the HMAC key/message order, which is the way round that is easy to invert; the --api-dsn rationale; and the PublicError contract with the three assertions a controller error test owes. beacon-storage gains the repository pattern, the source-deletion cascade and deploy-time schema reconciliation. All four descriptions are replaced by #140's, whose load triggers are strictly wider — a skill that does not load is knowledge that is lost. CLAUDE.md is thinned only where that depth moved, and every tripwire stays: the inner-mux bypass, the batching, the cascade warning and the three-assertion rule keep their sentence. 19330 to 17823. #140's own restructuring of CLAUDE.md into Architecture / Tripwires / Configuration is not taken. It is a larger editorial change than this, the file is already under budget, and it should be its own decision rather than a side effect of salvage. Nothing was dropped: all 210 backticked spans and 15 figures in the previous CLAUDE.md still appear in it or in a skill. Refs: #140 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U6jNuzK5PZrhDWBxB3t2gY
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
CLAUDE.mdwas at 21142 chars against the 20k it sets for itself. Measured withwc -c,not estimated — it was already at 20526 before the long-range forecast work, which added the
607-char tripwire that pushed it further.
Now 19330, with 670 to spare.
What moved
Relocated to
beacon-storage(~1400). The three connection PRAGMAs, thebusy_timeoutarithmetic, the deferred-promotion explanation and the production numbers behind it. That
skill's description already names
Transaction/ReadOnlyTransactionas a load trigger and itdid not carry the depth, so this is a move rather than a delete.
What stays in
CLAUDE.mdis the half that fails silently — a read on the write pathserialises against every other read and never says so, which is exactly the class the file's
own routing rule reserves space for.
SQLITE_BUSY, by contrast, announces itself.What was compressed
root-owned migration, the health gate with rollback and the sudoers reasoning all stay;
the rest is in
deploy/README.md, which the paragraph already pointed at.BEACON_PROXY_URLbullet — it restated the egress rule given three sectionsabove. The hardcoded
Proxy: nilfor Telegram and "nothing here readsHTTPS_PROXY" stay,both being silent if got wrong.
compress-claude-mdskill;the guard it exists for does not, and stays.
What was cut
The embedded-assets bullet.
//go:embed staticand "static lives undercmd/web/static/" are both visible incmd/web/main.go, andbeacon-http-apialready namesthat path in its load triggers. Nothing about it is silent.
Nothing was dropped
Per the rule the file states for itself: every backticked span and figure was extracted from
the old text and checked against the new set.
No security contract was touched — the auth boundary, the 404-not-403 rule and the
collection-egress default are byte-for-byte unchanged.
Refs #135