3.9 KiB
Chapter 6 — Help, man, and the documentation map
Prerequisites: Home, identity, and vault. Time to read: about five minutes.
On this page
maninside the imagehelpand discoverability- Four documentation trees
- Where JSON and schemas live
- Regenerating
man.json - Searching topics (
man -k)
man inside the image
The stock image ships man(1) backed by a merged JSON database built from coreutils pages and handbook-derived material. After npm run build -w bare-os-coreutils and a fresh seed, you can run man ls, man sh, and many other topics the same way you would on a traditional Unix-like system, with the understanding that coverage follows what Bare OS packages—not every host man page exists here.
For how pages are ingested and how help differs from man, read Handbook — Chapter 10: Manual pages and online help.
Handbook as a man page: the merged database includes long-form narrative topics. Try man handbook (section 7) for the full handbook text inside the guest when your image build includes it.
help and discoverability
Some commands expose a help subcommand or usage text aimed at interactive discovery. Use help when you want a short reminder; use man when you want structured sections and cross-references that match the JSON database.
Four documentation trees
These four areas are intentional; each serves a different job:
- User manual (users-manual/README.md) — run and use Bare OS without reading the whole architecture first.
- Handbook (handbook/README.md) — narrative explanation of design, protocol, runtime, identity, POSIX surface, operations, and research context.
- Developer guide (developer-guide/README.md) — practical instructions for scripts,
ctx, kernelstart(ctx), coreutils development, testing, Pear integration, telemetry scrubbing. - Reference (docs/reference/README.md) — inventory of packages and files, environment variable appendix, architecture data-flow notes, compatibility matrix, capability index.
If you are lost, start at the documentation hub on the docs/ tree, which links outward to the handbook and developer guide.
Where JSON and schemas live
Telemetry, boot policy, and related artifacts are documented next to JSON Schemas under docs/schemas/. You usually touch these when integrating observability or strict boot checks, not for everyday shell use. Pointers appear in the root README and in Kernel extensions.
Regenerating man.json
The on-disk manual lives at kernel/share/man/man.json after npm run build -w bare-os-coreutils. If man <topic> is missing or stale, rebuild coreutils on the host, re-run the seeder so the system drive picks up the new JSON, then boot again. CI’s verify-man-coverage ensures every /bin command has a matching page—local edits to packages/bare-os-coreutils should keep that invariant.
Searching topics (man -k)
man -k <word> (same as --apropos) searches keywords compiled into man.json. It is the fastest way to discover which utilities document a feature (for example man -k color). Results depend on the keyword index produced during the coreutils build; if nothing matches, fall back to ls /bin and man <cmd> directly.
Previous: Chapter 5 · Next: Chapter 7 — Troubleshooting and operations