# Chapter 7 — Troubleshooting and operations

**Prerequisites:** earlier chapters of this manual. **Time to read:** about eight minutes.

---

## On this page

- [Boot and swarm issues](#boot-and-swarm-issues)
- [Missing binaries or stale image](#missing-binaries-or-stale-image)
- [Environment variables](#environment-variables)
- [Themes and terminals](#themes-and-terminals)
- [CI and contributing](#ci-and-contributing)
- [Pretest and verifier failures](#pretest-and-verifier-failures)
- [Pear and module resolution](#pear-and-module-resolution)
- [Documentation link checks](#documentation-link-checks)

---

## Boot and swarm issues

**Symptom: booter exits on timeout.** The booter could not replicate the system drive in time. Typical causes:

- the **seeder** is not running or not reachable on the network;
- bootstrap nodes are wrong or blocked—review **`HYPERSWARM_BOOTSTRAP`** and firewall rules;
- you are using **offline LKG** mode without a valid local system drive (advanced; see reference docs).

Start the seeder first, wait until it is advertising, then start the booter. For protocol-level failure modes, read [Handbook — Chapter 3](../handbook/03-protocol-and-disk.md).

**Symptom: “no peers” or empty replication.** Confirm both processes use compatible **bootstrap** configuration (**`HYPERSWARM_BOOTSTRAP`**, corporate VPNs, and local firewalls frequently block DHT traffic). Try a clean Corestore path only after you are sure networking is not the root cause, or you may chase ghosts while the real issue was connectivity.

**Symptom: boot reaches shell but `/proc` looks empty or wrong.** Some **`/proc`** nodes require a minimum **ctx API** or capability words. Compare **`/proc/bare_os_features`** (when present) with the [compatibility matrix](../docs/reference/compatibility-matrix.md) and the versions printed by **`bare_os.capabilities`** during seeding.

---

## Missing binaries or stale image

**Symptom: a `/bin` tool is missing or obviously old under Pear.** The **`bare-os-coreutils`** workspace must be **built** before staging or seeding. From the repo root:

```bash
npm run build -w bare-os-coreutils
```

If you changed **`kernel/`** but the seeder still ships an old tree, CI’s **`verify-kernel-seeder-parity`** error means **`packages/bare-os-seeder/kernel/`** is out of sync with **`kernel/`**—copy or sync per maintainer workflow before release.

---

## Environment variables

There are **many** **`BARE_OS_*`** toggles. Host-side variables are often copied into the guest session so kernels and scripts see a consistent environment.

For a **complete list** and POSIX-related notes, use [Environment variables and POSIX appendix](../docs/reference/environment-and-posix-appendix.md). For a shorter **operator cheat sheet** grouped by component, see [Handbook — Chapter 7](../handbook/07-operations-and-development.md#environment-variables-cheat-sheet).

When debugging, ask whether the variable was set on the **host** before launching the booter, because the guest only sees what the booter forwards into **`shellEnv`**.

---

## Themes and terminals

**Symptom: colors or `ls --color` look wrong.** Themes interact with **`LS_COLORS`**, **`~/.barerc`**, and the **truecolor** versus **256-color** capability of your terminal emulator. Read the themes documentation and handbook notes rather than chasing random color codes:

- [docs/themes/README.md](../docs/themes/README.md)
- [Handbook — Chapter 7: Themes, LS_COLORS, and real terminals](../handbook/07-operations-and-development.md#themes-ls_colors-and-real-terminals)

---

## CI and contributing

Root **`npm test`** runs workspace tests after **`pretest`**, which builds artifacts and runs repository verifiers (kernel or seeder parity, ctx API alignment, capability contracts, documentation links, man coverage, compatibility matrix strings, kernel program governance + proc schema + roadmap table checks, Pear import rules, bare manifest smoke).

If **`gen:bare-catalog:check`** fails, regenerate the catalog with **`npm run gen:bare-catalog`** and commit the JSON. If **`verify-doc-links`** fails, fix broken relative **`.md`** links in the walked trees.

For a full maintainer-oriented walkthrough, [Handbook — Chapter 7](../handbook/07-operations-and-development.md) remains the authoritative operations chapter.

---

## Pretest and verifier failures

**`verify-kernel-seeder-parity`** — **`kernel/`** and **`packages/bare-os-seeder/kernel/`** must match **byte-for-byte**. Copy the canonical tree into the package (maintainer scripts or **`cp -R`**) after editing **`kernel/`**, then re-run **`pretest`**.

**`verify-kernel-capabilities-word-*`** — The [feature roadmap](../docs/reference/feature-roadmap.md) keeps **`## Capability word 6`…`11`** checklists as pipe tables with fixed row counts. Do not shrink those tables without updating the matching script under **`scripts/`**.

**`verify-ctx-api-feature-bits` / `verify-ctx-dts`** — The **`ctx` API** semver and **kernel capability** documentation must agree with **`packages/bare-os-protocol`** and **`packages/bare-os-booter`**. Start from the compatibility matrix when bumping versions.

**`verify-man-coverage`** — Every **`kernel/bin/*`** file must include the **`BARE_OS_BIN_API`** pragma and have a **`man`** page. Regenerate coreutils outputs after adding a command.

**`verify-compat-matrix`** — Strings in [compatibility-matrix.md](../docs/reference/compatibility-matrix.md) must mention current versions; the script is substring-based, not structural.

**`verify-pear-no-static-node-import`** — Pear bundles must not embed forbidden static **`node:`** imports; follow patterns in the booter’s Pear entry code.

---

## Pear and module resolution

If **`pear run`** fails with missing modules but **`npm ci` at the repo root succeeded**, run the **`npm run os:seeder`** / **`os:booter`** scripts from the **root** so **`scripts/ensure-pear-node-modules.mjs`** mirrors hoisted dependencies into the package **`node_modules`** Pear expects. Running **`pear run`** manually from a clean package directory without that step is a common source of **`Cannot find package`** errors.

---

## Documentation link checks

**`verify-doc-links`** walks **`docs/`**, **`handbook/`**, **`developer-guide/`**, **`scripts/`**, **`users-manual/`**, **`packages/`**, **`kernel/`**, and root **`README.md`**, **`DOCUMENTATION.md`**, **`PEAR-RUN.md`**. It skips **`packages/bare-os-seeder/kernel/**`** because that tree is identical to **`kernel/**`**; fix links in **`kernel/**`** only. Use **relative** `something.md` targets in links so CI can resolve them from each file’s directory.

---

_Previous: [Chapter 6](06-help-man-and-documentation-map.md)_ · _Next: [Chapter 8 — Further reading](08-further-reading.md)_