File-level reference
This directory holds the split file-by-file inventory that used to live in the root DOCUMENTATION.md stub. Use it when you need paths, package roles, and environment variables without a narrative walkthrough.
Documentation map (single index)
| Kind | Where to start |
|---|---|
| Project overview | README |
| First run (clone → shell) | Get started |
| Documentation hub | docs/README.md (includes topic index: canonical reference vs handbook / user manual / developer guide) |
| Doc sitemap | docs/sitemap.md |
| Glossary / FAQ / troubleshooting | glossary.md · faq.md · troubleshooting.md |
| Operator narrative | Handbook |
Contributor / ctx / Pear |
Developer guide |
| Day-to-day use | Users manual |
| File-level inventory | This directory (docs/reference/) |
| JSON Schemas | schemas/README.md |
| Kernel contract (boundaries) | docs/architecture/KERNEL_CONTRACT.md |
| Kernel subsystem map | docs/architecture/kernel-subsystems.md |
| POSIX conformance matrix | docs/reference/conformance-matrix.md · machine-readable posix-compliance-matrix.json (pretest) |
| Syscall + socket bridge contract | syscall-socket-contract.md · posix-syscall-facade-map.md · POSIX Issue 7 traceability |
| Hyperswarm / Protomux booter teardown | hyperswarm-protomux-teardown.md |
| ADRs | docs/adr/ |
| Audit baseline | docs/audit/PLACEHOLDER_BASELINE.md |
| OTA / bundles (operators) | docs/deployment/OTA_AND_BUNDLES.md |
| CI / verifiers | scripts/README.md |
On this page
Topics (former monolith map)
- Repository layout and root metadata (former §§1–8) — Repository layout and root metadata
- Kernel image sources (former §9) — Kernel image sources
- Package: bare-os-protocol (former §10) — Package: bare-os-protocol
- Package: bare-os-seeder (former §11) — Package: bare-os-seeder
- Package: bare-os-booter (former §§12.1–12.9) — Package: bare-os-booter
- Shell completion + Fish REPL editor — Shell completion and REPL editor
- bare-os-coreutils, tests, and seeder build hook (former §§12.10–12.12) — bare-os-coreutils, tests, and seeder build hook
- Architecture: end-to-end data flow (former §13) — Architecture: end-to-end data flow
- Kernel architecture contract (booter vs image, boot steps) — KERNEL_CONTRACT.md
- Placeholder / stub audit baseline — PLACEHOLDER_BASELINE.md
- OTA and Bare/Pear bundles — OTA_AND_BUNDLES.md
- Environment variables and POSIX appendix (former §14, §14a) — Environment variables and POSIX appendix
- POSIX syscall facade (
ctx.bareOsSyscall) — posix-syscall-facade-map.md - Hyperswarm / Protomux teardown (booter) — hyperswarm-protomux-teardown.md
- Kernel feature bits and handshake — Kernel extensions; source of truth for word masks —
packages/bare-os-protocol/lib/kernel-feature-bits.js - Bits, env,
/proc, andctxmap — Kernel capabilities index ctxAPI versioning — ctx-api-versioning.md- Version alignment — Compatibility matrix
- Node vs Bare test hosts — node-vs-bare-host-matrix.md
- Legacy ↔ canonical names — Naming alias matrix
- Kernel program status tables — Feature roadmap status
- VFS path classes (policy sketch) — vfs-path-classes.md
- Kernel security subsystems — kernel-security-subsystems.md
- Vault / encryption threat model — vault-threat-model.md
- Observability contracts — observability-contracts.md
- Kernel extensions (short index) — kernel-extensions-capability-specs.md
- Kernel extensions (generated TOC) — kernel-extensions-generated-toc.md
- OTA channel sketch — ota-channels.md
- POSIX conformance dashboard (sketch) — conformance-dashboard.md
- POSIX conformance matrix (subsystem table) — conformance-matrix.md
- Kernel subsystem boundaries — kernel-subsystems.md
- Machine-readable data stubs — ../data/README.md
- Kernel program (governed expansion) — developer-guide/kernel-program.md
- Out of scope and tooling (former §§15–16) — Out of scope and tooling
- curl and wget (delegation, fetch stack, policy) — curl and wget
- Published JSON Schemas — schemas/README.md
Narrative docs
- Handbook — why the system exists and how the architecture fits together.
- Developer guide — how to extend
run/start, usectx, and test under Pear. - User manual — operator-oriented guide to running and using the image.