# Repository layout and root metadata Former monolith **DOCUMENTATION.md** §§1–8. [Reference index →](README.md) ## 1. Repository tree (source only) ``` bare-operating-system/ ├── package.json # Root workspace manifest ├── package-lock.json # Locked dependency tree (npm, all workspaces) ├── README.md # User-facing overview and doc map ├── DOCUMENTATION.md # Stub → docs/reference (former monolith) ├── docs/ │ ├── README.md # Docs hub (reference + themes + catalog) │ ├── bare-holepunch-catalog.json │ ├── reference/ # File-level reference; index: docs/reference/README.md │ └── themes/ ├── handbook/ # Narrative handbook (chapters + diagrams) │ ├── README.md # Index + links to chapters │ ├── 00-preface.md, 01-introduction.md … 10-manpages-and-online-help.md ├── developer-guide/ # How-to: in-image JS, ctx, coreutils, testing │ ├── README.md # Index + reading order │ ├── 01-two-runtimes-host-vs-image.md … 12-bare-modules-and-pear-ecosystem.md ├── LICENSE # Apache-2.0 notice (HoneyPeer, LLC) ├── patches/ # patch-package deltas (applied post-install; see § patches below) ├── .gitignore # Ignore rules ├── .prettierrc # Prettier formatting defaults ├── .github/ │ └── workflows/ │ └── ci.yml # GitHub Actions CI ├── kernel/ # Files staged into the system Hyperdrive │ ├── init.js │ ├── bin/ # Tier-1 utilities (built from bare-os-coreutils) │ ├── lib/bare/ # Optional ctx.bare drive bundles + manifest (bare-os-bare-libs) │ └── etc/ │ └── os-release └── packages/ ├── bare-os-protocol/ # Shared protocol + MBR + seed channel │ ├── package.json │ ├── index.js │ ├── constants.js │ ├── test.js │ └── lib/ │ ├── messages.js │ ├── channel.js │ └── kernel-feature-bits.js ├── bare-os-bare-libs/ # esbuild → kernel/lib/bare/bundles + manifest.json (seeder mirror) │ ├── package.json │ └── build.mjs ├── bare-os-coreutils/ # Sources + build → kernel/bin/* and seeder copy │ ├── package.json │ ├── build.mjs │ ├── lib/runtime.js │ ├── lib/sed-engine.js, lib/awk-engine.js ← prepended for sed/awk (see build preamble) │ └── src/*.js ├── bare-os-seeder/ # Publishes OS drive + MBR │ ├── package.json │ ├── index.js │ ├── kernel/ # Vendored for Pear (sync from repo kernel/) │ └── lib/ │ └── paths.js └── bare-os-booter/ # Boots from swarm peers only (TTY splash + timeout) ├── package.json ├── CHANGELOG.md # ctx API version history ├── index.js ├── test.js └── lib/ ├── paths.js ├── swarm-disk.js ├── kernel-runner.js ├── bare-os-abort.js ├── bare-os-http-policy.js ├── bare-os-ctx-api.js ├── bare-os-ctx-bare.js # ctx.bare host import + drive bundle merge ├── bare-module-manifest.json ├── bare-os-ctx.d.ts ├── git-cli.js # isomorphic-git; booter delegates `git` ├── curl-cli.js # Fetch HTTP client; booter delegates `curl` ├── wget-cli.js # Fetch downloads; booter delegates `wget` ├── identity-account.js # Ed25519 account blob (bare-crypto PBKDF2 + ChaCha20-Poly1305) ├── identity-session.js # Guest vs unlocked env, vault save, ctx hooks ├── vfs.js # Two-drive path routing ($HOME → personal drive) ├── shell.js # POSIX-ish line parser + builtins (incl. login/logout) ├── fish-readline.js # TTY editor; per-USER REPL history; tab menu + ghost ├── completion-engine.js # Async completion: man/PATH/VFS/proc, ranking, registry ├── repl-session.js └── … ``` --- ## 2. Root: [package.json](../../package.json) - `name` — `bare-operating-system` - `private` — `true` — not published as a single npm package - `type` — `module` — ESM - `workspaces` — `["packages/*"]` — npm workspaces (protocol, coreutils, seeder, booter, …) - `scripts.pretest` — Runs `bare-os-coreutils` + `bare-os-bare-libs` builds, kernel/seeder parity, [`smoke:bare-manifest`](../../scripts/smoke-bare-manifest-imports.mjs) - `scripts.gen:bare-catalog` — Refresh [`docs/bare-holepunch-catalog.json`](../bare-holepunch-catalog.json) from GitHub + npm (see [Chapter 12](../../developer-guide/12-bare-modules-and-pear-ecosystem.md)) - `scripts.sync:bare-manifest` — Apply catalog → [`bare-module-manifest.json`](../../packages/bare-os-booter/lib/bare-module-manifest.json) `entries` (preserves curated `pearEntries`) + booter `optionalDependencies` - `scripts.test` — Runs `npm run test --workspaces --if-present` - `scripts.format` — `prettier --write .` - `scripts.lint` — `prettier --check .` - `engines.node` — `>=20` - `devDependencies` — `prettier@^3.4.2` No runtime dependencies at the root; all stack deps live in workspace packages. --- ## 3. Root: [package-lock.json](../../package-lock.json) - **Format**: npm lockfile v3 (`lockfileVersion: 3`). - **Role**: Pins exact versions of the full install graph (root + `packages/bare-os-protocol`, `bare-os-seeder`, `bare-os-booter` and all transitive dependencies: `hyperdrive`, `corestore`, `hyperswarm`, `protomux`, `brittle`, Bare-related packages, native addons such as `rocksdb-native`, etc.). - **Workspaces**: Lists workspace package paths and links workspace packages to `"node_modules/bare-os-protocol"` etc. - **Not reproduced here line-by-line** — it is thousands of lines; use `npm ls` or open the file for the exact tree. --- ## 4. Root: [README.md](../../README.md) User-oriented documentation: project goal, layout table, prerequisites (Node 20+, Pear/Bare), `npm ci`, `npm test`, how to run seeder and booter with `node index.js`, environment variables, Corestore path semantics (`~/.bare-os` defaults), placeholder `pear://` table, protocol summary (`bare-os-v1`, MBR layout), license pointer. Runtime drift guard: - Run [`npm run verify:bare-runtime`](../../package.json) before bare-only workflows. - Minimum supported host runtime for this repo is **bare v1.28.0**. - If `bare --version` is lower, upgrade host tools with: - `npm i -g bare-runtime pear` - Quick rollback (if needed) to prior known versions on your machine: - `npm i -g bare-runtime@ pear@` - then re-run `npm run verify:bare-runtime` and `npm run test:bare`. Narrative handbook (architecture diagrams, chapter walkthrough): [handbook/README.md](../../handbook/README.md). Per-workspace overviews: [packages/bare-os-protocol/README.md](../../packages/bare-os-protocol/README.md), [packages/bare-os-coreutils/README.md](../../packages/bare-os-coreutils/README.md), [packages/bare-os-seeder/README.md](../../packages/bare-os-seeder/README.md), [packages/bare-os-booter/README.md](../../packages/bare-os-booter/README.md), [kernel/README.md](../../kernel/README.md), [scripts/README.md](../../scripts/README.md). --- ## 5. Root: [LICENSE](../../LICENSE) Apache License, Version 2.0 header: copyright year 2026, HoneyPeer, LLC ownership statement, standard AS-IS disclaimer, link to , and pointer to third-party vendor licenses. --- ## 6. Root: [.gitignore](../../.gitignore) Ignores: - `node_modules/` - `data/` (legacy; optional local Corestore if you still keep trees here — defaults now use `~/.bare-os`) - `coverage/` - `.DS_Store` - `*.log` - `.pear/` - `packages/*/.test-data/` (brittle test Corestore dirs) --- ## 7. Root: [.prettierrc](../../.prettierrc) JSON: `semi: false`, `singleQuote: true`, `trailingComma: "none"`. --- ## 8. CI: [.github/workflows/ci.yml](../../.github/workflows/ci.yml) - **Triggers**: `push` and `pull_request` to `main`. - **Job `test`**: `ubuntu-latest`, checkout, `actions/setup-node@v4` with Node 20 and npm cache on `package-lock.json`, then `npm ci`, install a modern Bare runtime (`bare-runtime`) for `brittle-bare` / bare smoke tests, and run `npm test`. --- ## 9. Root: `patches/` ([patch-package](https://github.com/ds300/patch-package)) The repo may ship **`patches/*.patch`** files in **patch-package** format (for example [`patches/autopass+3.4.0.patch`](../../patches/autopass+3.4.0.patch)) so maintainers can apply small **upstream dependency fixes** during development. They are **not** staged into the guest Hyperdrive. **`patch-package`** is a root devDependency; wire a **`postinstall`** script if you want patches applied automatically after **`npm ci`**. Document **why** each patch exists in the commit message and keep diffs minimal.