82 lines
4.4 KiB
Markdown
82 lines
4.4 KiB
Markdown
# 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](get-started.md) (clone → two terminals → shell) · [Documentation home](README.md) (full hub).
|
||
|
||
---
|
||
|
||
## On this page
|
||
|
||
- [Doc universe at a glance](#doc-universe-at-a-glance)
|
||
- [Diagram — how the trees relate](#diagram--how-the-trees-relate)
|
||
- [Where to go when you are stuck](#where-to-go-when-you-are-stuck)
|
||
|
||
---
|
||
|
||
## Doc universe at a glance
|
||
|
||
| I want to… | Start here | Canonical numbers / env |
|
||
| --- | --- | --- |
|
||
| Run it today | [Get started](get-started.md) | [User manual — ch.3](../users-manual/03-running-seeder-and-booter.md) |
|
||
| Understand two drives | [Concepts — Two drives](concepts/two-drive-model.md) | [Booter reference](reference/package-bare-os-booter.md) |
|
||
| Understand boot order | [Concepts — Boot](concepts/boot-and-init-timeline.md) | [KERNEL_CONTRACT](architecture/KERNEL_CONTRACT.md) |
|
||
| Read the full story | [Handbook](../handbook/README.md) | [Handbook — ch.3 Protocol](../handbook/03-protocol-and-disk.md) |
|
||
| Use the shell and `man` | [User manual](../users-manual/README.md) | [Handbook — ch.9 POSIX / shell](../handbook/09-posix-utilities-shell-and-vfs.md) |
|
||
| Use **`agent`** (HTTPS assistant) or **`chat`** (swarm chat) | [User manual — ch.4](../users-manual/04-shell-path-and-scripts.md) · **`man agent`** / **`man chat`** in the guest | [Handbook — ch.3–4 / ch.6](../handbook/03-protocol-and-disk.md); [HTTP policy](reference/http-curl-and-wget.md) (for **`agent`**) |
|
||
| Tab completion / REPL keys | [Shell completion and REPL editor](reference/shell-completion-and-repl-editor.md) | [Handbook — ch.9 §3](../handbook/09-posix-utilities-shell-and-vfs.md#3-shell-lists-pipelines-and-builtins-packagesbare-os-booterlibshelljs) |
|
||
| Extend `/bin` or scripts | [Developer guide](../developer-guide/README.md) | [`COREUTILS_COMMANDS`](../packages/bare-os-coreutils/lib/commands.mjs), `verify-man-coverage` |
|
||
| Write a Discord bot | [Developer guide — Discord bots](../developer-guide/21-discord-bots.md) | [Environment appendix — `DISCORD_*`](reference/environment-and-posix-appendix.md), **`man discord-bot`** |
|
||
| Bump contracts or releases | [Documentation home — Contract bump checklist](README.md#contract-bump-checklist) | [Compatibility matrix](reference/compatibility-matrix.md), package CHANGELOGs |
|
||
| Every env variable | [Environment and POSIX appendix](reference/environment-and-posix-appendix.md) | Do not duplicate in prose elsewhere |
|
||
| Security / vault posture | [Vault threat model](security/vault-threat-model.md) | [Developer guide — Privacy / telemetry](../developer-guide/13-privacy-telemetry-pii.md) |
|
||
| CI and verifier scripts | [scripts/README.md](../scripts/README.md) | Root `package.json` **`pretest`** |
|
||
|
||
---
|
||
|
||
## Diagram — how the trees relate
|
||
|
||
```mermaid
|
||
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](troubleshooting.md) · [FAQ](faq.md) · [User manual — ch.7](../users-manual/07-troubleshooting-and-operations.md).
|
||
- **Contributors:** [Contributing to docs](CONTRIBUTING-DOCS.md) · run **`npm run pretest`** before pushing doc edits.
|
||
- **Maintainers:** [Release checklist](release-checklist.md) · **`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](CONTRIBUTING-DOCS.md)).
|