77d4782c86
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>
2.9 KiB
nestri
Open-source cloud gaming: a control plane and the guest components that run inside a box. This repository is public. That is the single most important fact about it and most of the rules below follow from it.
Layout
Split by what a thing is, not by what language it is written in.
apps/ what runs api, auth (TS) · nescope, neswire, nescapture (Rust)
crates/ shared Rust nesprotocol
packages/ shared TS core, auth
docs/ long-form alchemy.md
Both toolchains live at the root: package.json is the Bun workspace,
Cargo.toml the Cargo one.
bun install |
dependencies |
bun dev |
local Cloudflare dev via Alchemy |
cargo build --workspace · cargo test --workspace |
the Rust half |
bun run deploy:sandbox |
deploy a stage |
Two rules that are not style preferences
Nothing closed may enter this repo. Not source, not a dependency, not a directory that "looked convenient". Before adding a top-level directory, know which component it is and that the component is open. This has already been caught once, in a commit that was never pushed.
Versions are pinned once, centrally. A Cargo member writes
tokio.workspace = true and never a version; a TS package uses the root
catalog. Two packages in one tree must not disagree about a dependency.
Where the detail is
These load automatically when you work in the directory they describe — read them there rather than duplicating them here.
packages/core/CLAUDE.md— domain modules: the.sql.ts/index.tspair,fn(), the serialization boundary, ids, the actor model, the error type, auth flow.apps/api/CLAUDE.md— route modules, registration,.meta()vs.openapi(), error flow.docs/alchemy.md— infrastructure: stages, bindings, secrets, service bindings, the CLI.
Things worth knowing before you start
This tree is mid-rewrite. The Rust components arrived recently, one commit
each, imported as trees rather than as history — so git log on them starts at
the import and their own past is not here. Docs for that half are thin and
being written.
The TypeScript half predates the Rust half, so the guides above describe it in much more depth. That is a gap in the writing, not a statement about which half matters.
Rust components are guest-side: they run inside a virtual machine, not on
the control plane. nescope composites, nescapture captures and encodes
frames from inside the workload's own process, neswire handles audio, and
nesprotocol is the wire format all three share. None of them talk to the API.
Conventions
Conventional commits. Explain why in the body — the diff already shows what. Comments earn their place by saying something the code cannot; a comment restating the line below it is noise.