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. Implementation plans stay out of the public 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 Eelgrass 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.