Internals
This VitePress site (docs/) is public documentation — consumer guides and maintainer process docs grounded in what the code does today.
Internal design docs, ADRs, agent workstreams, living plans, and review guides live in the repo at:
They are not published by the docs build. Link out to GitHub (or read them in a checkout) when you need them.
Map
| Path | Contents | Public? |
|---|---|---|
internals/decisions.md | Doctrine + ADR-style decisions | Private — promote distilled product claims only |
internals/shift-left-audit.md | Full inventory of concerns moved out of the business layer | Private detail — public distillations under /business/ + consumer shift-left |
internals/engine-plan.md | Engine phase narrative (may lag Status) | Private — Status wins on disagreement |
internals/plans/ | Living implementation plans | Private — not a product roadmap |
internals/language-spec.md | Full language draft | Private — promote carefully into consumer language pages |
internals/review-guides/ | PR teaching guides | Private (maintainer process summarized here) |
internals/rust-notes/ | Rust chapters from real Eelden code | Private |
internals/notes/ | Scratch / platform notes | Private |
internals/migrations.md, explorer*.md | Workstream notes | Private |
What stays private vs what gets promoted
Stay in internals/: phase checklists, unfinished plan tasks, agent workstream chatter, raw ADR debate, stress/DST scenario design, spike lineage essays, anything that would imply a Not-yet feature ships.
Promote to public docs (usually under /consumers/, process under /maintainers/, value under /business/):
- Capability inventory → Status
- Shift-left value + diligence tables → Business (from
internals/shift-left-audit.md) - Stable language/CLI/HTTP/client behavior once it matches Status
- Maintainer process distilled from
AGENTS.md(this section) - Deploy mechanics for docs + playground (Deploy)
When doctrine or capabilities change in internals/, update the matching public pages in the same PR so the site stays honest — Status first.
Agents
Cursor / coding agents: follow root AGENTS.md (Rust policy, teaching mandate, tripwire tests). The internals/ tree is the agent source of truth for design; crates/ is the engine of record.
Public readers who are not contributing deeply should stay on this site.