Wanjohi 77d4782c86 docs: split CLAUDE.md by scope, and say what this repo is ...

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>

2026-08-26 18:23:42 +03:00

..

alchemy.md

docs: split CLAUDE.md by scope, and say what this repo is

2026-08-26 18:23:42 +03:00