CLAUDE.md said "Rust components are guest-side: they run inside a virtual
machine". That was true of every one of them until yesterday and is now false,
which makes it worse than a gap -- it is instruction that would send someone
looking for nesdoctor in the wrong half of the system.
Records the two things about it that hold nowhere else in this tree. Its
dependency list is part of its interface, because it is handed to strangers and
asked to be trusted. And it cannot be verified on the development machine
alone: both bugs it has shipped were Windows-only, found by users, in code
paths Linux never executes -- so prefer a property test that runs everywhere
over a platform check that runs nowhere, and read what the Windows and macOS
runners print.
The payload-independence rule is the one thing about this repo that is
easy to violate by being helpful. Stating it where it will be read before
the first edit is cheaper than catching it in review.
CLAUDE.md was 1,324 lines and all of it was about the TypeScript half, written
before there was another half. Every line of it loaded on every turn regardless
of what was being worked on, which is a real cost paid constantly for context
that is usually irrelevant.
Split by where it applies, so each guide loads when you are in the directory it
describes:
packages/core/CLAUDE.md 694 domain modules, fn(), actor, errors, auth
apps/api/CLAUDE.md 284 routes, registration, error flow
docs/alchemy.md 345 stages, bindings, secrets, the CLI
CLAUDE.md 72 the repo, both toolchains, two hard rules
Nothing was rewritten or dropped — the three files are the original text,
verified identical after the split. What the root file now carries is only what
is true repo-wide: the layout, the commands, where the detail lives, and the two
rules that are not style preferences. One of those is that nothing closed may
enter this repo, which is here because it has already been caught once.
The README described a streaming platform in four bullets and did not mention
that half the repository is Rust that runs inside a virtual machine. It now says
what each component does, why a micro-VM rather than a container, what is
deliberately absent, and what decides whether a thing is open — data is, capacity
is not.
It also says plainly that this is mid-rewrite and the docs are behind. Someone
arriving at a repo whose documentation does not match its tree should be told
that by the README rather than discover it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
