This directory is a compact navigation map for people and agents working on ElastOS. It explains where responsibilities and code live. It does not create a second architecture, glossary, backlog, or readiness ledger.
Read these in order when a statement matters:
PRINCIPLES.mddefines stable product and authority constraints.ARCHITECTURE.mddefines responsibility and trust boundaries.- GitHub issues record verified behavior, known limitations and open work.
AGENTS.mddefines the operator and agent process.- The contract for the touched surface defines its exact interface.
If this map disagrees with one of those files, the source of truth wins and this map must be corrected.
Before editing a diagram or path map, fill in this short record:
Layer:
Capability:
Hidden detail:
Done-check:
Layer names the Home, Runtime, capsule, provider, Carrier, or host-adapter
boundary. Capability names the exact resource and operation. Hidden detail
states what the capsule or projection must not see, such as a host path, peer,
backend, credential, socket, or transport. Done-check is one command a new
contributor can run to prove the change.
For this map, the minimum check is node scripts/system-map-check.mjs from the
repository root. A code or contract change also needs the narrow test for its
own surface. If those four lines cannot be stated, the proposed edit is not
ready.
- Layered C4 model: system context, containers, components, supporting code ownership, trust, identity, dynamic, and deployment views. Each diagram is deliberately small enough to read or copy into Mermaid Live on its own.
- Interactive C4 viewer: a navigable projection of the same
model.
c4.mdremains canonical; runnode scripts/system-map-check.mjsfrom the repository root to verify that the viewer is bound to its exact source. - Code and product tree: stable paths for the major Runtime, capsule, provider, Home, collaboration, Browser, and AI surfaces.
- Human and agent architecture: principal parity, Profiles, Agent Host capsules, delegation, and model/effect flows.
- Private network contract: signed membership, named services, Carrier routes, and optional compatibility adapters.
- Model provider contract: explicit selection, streaming, cancellation, recovery, and terminal results.
- Consequence-aware effects: one Runtime effect path with operation-specific observation, actuation, settlement, and local-safety requirements.
Use the canonical Glossary for terminology. Use the documentation index to find detailed contracts and verification guides.