This directory is the repository-native map for Loong's public architecture references.
The Mintlify site under site/ is the public builder-facing reading path. This
index exists for contributors and source readers who need the repository
markdown behind that shorter public architecture summary.
- you need the repository-native architecture references rather than the shorter Mintlify summary
- you are changing runtime boundaries, layering, or engineering rules
- you want the source documents that back the public builder contract
| If you are trying to... | Start here | Why |
|---|---|---|
| read the public builder-facing overview first | ../../site/build-on-loong/overview.mdx |
site/ is the public builder hub |
| edit repository-native architecture references | this index | this directory is the source-facing architecture map |
| understand the overall repository docs layering | ../README.md |
it explains how repo-native docs differ from Mintlify pages |
This directory keeps the architecture references that remain part of the OSS surface. Deeper implementation packages, comparative studies, and internal-only design backlog artifacts are intentionally out of the public docs flow.
| Document | Read it when... |
|---|---|
| Core Beliefs | you need the engineering principles that should survive refactors |
| Layered Kernel Design | you need the crate and layer boundary model before changing runtime shape |
| Runtime Entrypoint and Bootstrap Map | you need the shortest source-facing map of how CLI, channel, gateway, control-plane, and daemon task turns enter the shared runtime |
| Single-Entry Runtime Convergence | you are working on session-vs-memory ownership or converging host turn seams without breaking the current crate contract |
| Harness Engineering | you are working on the agent-driven development environment itself |
| Execution Discipline And Long-Running Ownership | you are changing proactive agent behavior, long-running task ownership, or completion semantics beyond one turn |
| Tool Surface Exposure | you are changing provider-visible tool exposure, discovery, or hidden-tool progressive disclosure |
- keep this index focused on architecture references that remain part of the OSS source surface
- do not turn
design-docs/back into a catch-all archive for backlog design bundles, internal comparisons, or implementation packages - put new reader-facing explainers in
site/when they are really public docs pages rather than source references
- Start with Core Beliefs if you need the repository's architectural taste and invariants.
- Continue to Layered Kernel Design if the change touches boundaries, ownership, or layering.
- Read Runtime Entrypoint and Bootstrap Map when the problem is “which runtime/bootstrap surface actually owns this turn?”
- Read Execution Discipline And Long-Running Ownership when the work is really about proactive execution, long-running task state, or completion semantics.
- Read Tool Surface Exposure when the work touches provider-visible tools, discovery, or hidden-tool progressive disclosure.
- Read Harness Engineering only when the work is really about the development environment or agent workflow itself.