# 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`** (QVAC / REST coding agent) or **`chat`** (swarm chat) | [User manual — ch.4](../users-manual/04-shell-path-and-scripts.md) · **`man agent`** / **`man chat`** in the guest · Discord **`/agent`**: [developer-guide ch.21](../developer-guide/21-discord-bots.md) | [Handbook — ch.3–4 / ch.6](../handbook/03-protocol-and-disk.md); [HTTP policy](reference/http-curl-and-wget.md) (REST + **`web_fetch`**) |
| 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)).