4.5 KiB
Documentation sitemap
Bare OS splits documentation by audience so each tree can stay focused and CI can verify links and generated artifacts. Use this page when you are unsure which folder to open.
Fast path: Get started (clone → two terminals → shell) · Documentation home (full hub).
On this page
Doc universe at a glance
| I want to… | Start here | Canonical numbers / env |
|---|---|---|
| Run it today | Get started | User manual — ch.3 |
| Understand two drives | Concepts — Two drives | Booter reference |
| Understand boot order | Concepts — Boot | KERNEL_CONTRACT |
| Read the full story | Handbook | Handbook — ch.3 Protocol |
Use the shell and man |
User manual | Handbook — ch.9 POSIX / shell |
Use agent (QVAC / REST coding agent) or chat (swarm chat) |
User manual — ch.4 · man agent / man chat in the guest · Discord /agent: developer-guide ch.21 |
Handbook — ch.3–4 / ch.6; HTTP policy (REST + web_fetch) |
| Tab completion / REPL keys | Shell completion and REPL editor | Handbook — ch.9 §3 |
Extend /bin or scripts |
Developer guide | COREUTILS_COMMANDS, verify-man-coverage |
| Write a Discord bot | Developer guide — Discord bots | Environment appendix — DISCORD_*, man discord-bot |
| Bump contracts or releases | Documentation home — Contract bump checklist | Compatibility matrix, package CHANGELOGs |
| Every env variable | Environment and POSIX appendix | Do not duplicate in prose elsewhere |
| Security / vault posture | Vault threat model | Developer guide — Privacy / telemetry |
| CI and verifier scripts | scripts/README.md | Root package.json pretest |
Diagram — how the trees relate
flowchart LR
subgraph entry [Entry]
GS[get-started.md]
Hub[docs/README.md]
end
subgraph learn [Understand]
Concepts[docs/concepts]
HB[handbook]
end
subgraph do [Do]
UM[users-manual]
DG[developer-guide]
end
subgraph spec [Specify]
Ref[docs/reference]
Arch[docs/architecture]
ADR[docs/adr]
end
GS --> Hub
Hub --> Concepts
Hub --> UM
Hub --> HB
Hub --> DG
HB --> Ref
DG --> Ref
Ref --> Arch
Ref --> ADR
In prose: get-started and the documentation home route you into concepts (short evergreen), the user manual (run), the handbook (why), or the developer guide (how). Reference, architecture, and ADRs hold normative tables, env inventories, and decisions — narrative chapters should link there instead of copying version strings.
Where to go when you are stuck
- Operators: Troubleshooting router · FAQ · User manual — ch.7.
- Contributors: Contributing to docs · run
npm run pretestbefore pushing doc edits. - Maintainers: Release checklist ·
npm run release-checklist.
Repository canonical remote: https://git.ssh.surf/snxraven/bare-operating-system.git — Markdown is written for clarity on any forge; GFM-style alerts may render as plain blockquotes on some hosts (CONTRIBUTING-DOCS.md).