updates

DOCUMENTATION.md

@@ -36,12 +36,16 @@ bare-operating-system/
     │       └── channel.js
     ├── bare-os-seeder/         # Publishes OS drive + MBR
     │   ├── package.json
-    │   └── index.js
+    │   ├── index.js
+    │   ├── kernel/              # Vendored for Pear (sync from repo kernel/)
+    │   └── lib/
+    │       └── paths.js
     └── bare-os-booter/         # Boots from peers or local seed
         ├── package.json
         ├── index.js
         ├── test.js
         └── lib/
+            ├── paths.js
             ├── swarm-disk.js
             └── kernel-runner.js
 ```
@@ -238,15 +242,19 @@ Brittle tests:
 | `engines.bare`          | `>=2.0.0`                                                                                                                          |
 | `pear.name`             | `bare-os-seeder`                                                                                                                   |
 | `pear.stage.ignore`     | `.git`, `test`, `coverage`, `.DS_Store`, `node_modules/.bin`, `node_modules/.package-lock.json`                                    |
-| `imports`               | `fs`, `fs/promises`, `path`, `url` — Bare vs `node:` shims                                                                         |
+| `imports`               | `fs`, `fs/promises`, `path`, `url`, `node:url` — Bare vs `node:` shims                                                             |
 
-### 11.2 [packages/bare-os-seeder/index.js](packages/bare-os-seeder/index.js)
+### 11.2 [packages/bare-os-seeder/lib/paths.js](packages/bare-os-seeder/lib/paths.js)
 
-**Paths**
+Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/holepunchto/pear-rti) `MOUNT` / `swapDir`):
 
-- `repoRoot` = two levels up from this file → monorepo root.
-- `corestorePath()` = `BARE_OS_SEED_STORE` or `repoRoot/data/corestore-seeder`.
-- `kernelRoot` = `BARE_OS_KERNEL_ROOT` (resolved) or `repoRoot/kernel`.
+- **`packageRootDir(metaUrl)`** — If `import.meta.url` is `file:`, `path.dirname(fileURLToPath(...))` via **`node:url`** (so `file:` is only passed to `fileURLToPath`). If `pear:` / other, `global.Pear.constructor.RTI.mount`, else `Pear.config.swapDir`, else `process.cwd()`.
+- **`defaultKernelRoot(pkgRoot, metaUrl)`** — `BARE_OS_KERNEL_ROOT` or `path.join(pkgRoot, 'kernel')` (vendored copy under the seeder package for Pear bundles).
+- **`defaultSeedCorestorePath(pkgRoot, metaUrl)`** — `BARE_OS_SEED_STORE` or `../../data` from `pkgRoot` when `file:`, else `pkgRoot/data` for Pear checkout.
+
+### 11.3 [packages/bare-os-seeder/index.js](packages/bare-os-seeder/index.js)
+
+**Paths** — Uses `./lib/paths.js` for `_pkg`, `corestorePath()`, and `kernelRoot` (no `fileURLToPath(import.meta.url)` on the hot path for `pear:`).
 
 **`stageKernelTree(drive, kernelRoot)`**
 
@@ -276,20 +284,26 @@ Brittle tests:
 
 ### 12.1 [packages/bare-os-booter/package.json](packages/bare-os-booter/package.json)
 
-| Item                    | Detail                                         |
-| ----------------------- | ---------------------------------------------- |
-| `main`                  | `./index.js`                                   |
-| `scripts.start` / `dev` | `bare index.js`                                |
-| `scripts.test`          | `brittle-node test.js`                         |
-| `dependencies`          | Same hyperstack as seeder + `bare-os-protocol` |
-| `devDependencies`       | `brittle`                                      |
-| `imports`               | `path`, `url` Bare/Node conditional            |
+| Item                    | Detail                                                   |
+| ----------------------- | -------------------------------------------------------- |
+| `main`                  | `./index.js`                                             |
+| `scripts.start` / `dev` | `bare index.js`                                          |
+| `scripts.test`          | `brittle-node test.js`                                   |
+| `dependencies`          | Same hyperstack as seeder + `bare-os-protocol`           |
+| `devDependencies`       | `brittle`                                                |
+| `imports`               | `path`, `url`, `node:url` Bare/Node conditional          |
+| `pear.stage.ignore`     | Includes `test.js`, `.test-data` so tests are not staged |
 
-### 12.2 [packages/bare-os-booter/index.js](packages/bare-os-booter/index.js)
+### 12.2 [packages/bare-os-booter/lib/paths.js](packages/bare-os-booter/lib/paths.js)
 
-**Note:** Imports are ordered as: external modules, `repoRoot` from `__dirname`, then `./lib/...` (SwarmDisk, kernel-runner).
+- **`packageRootDir(metaUrl)`** — Same as seeder (Pear RTI / `swapDir` / `cwd`).
+- **`defaultBootCorestorePath`** / **`defaultLocalSeedCorestorePath`** — `../../data` when `file:`, else `pkgRoot/data`.
 
-**`bootStorePath()`** — `BARE_OS_BOOT_STORE` or `repoRoot/data/corestore-booter`.
+### 12.3 [packages/bare-os-booter/index.js](packages/bare-os-booter/index.js)
+
+**Imports** — `path`, protocol, `./lib/swarm-disk.js`, `./lib/kernel-runner.js`, `./lib/paths.js`.
+
+**`bootStorePath()`** — `defaultBootCorestorePath(_pkg, import.meta.url)`.
 
 **`createReadLine()`**
 
@@ -311,7 +325,7 @@ Brittle tests:
 
 **`bootLocal(disk, store, swarm)`**
 
-- `Corestore(BARE_OS_LOCAL_SEED || repoRoot/data/corestore-seeder)`, `Hyperdrive(seedStore)` (same store as seeder’s default layout).
+- `Corestore(defaultLocalSeedCorestorePath(...))`, `Hyperdrive(seedStore)` (same store as seeder’s default layout).
 - Poll for `/boot/init.js`, then `initPersonalDrive`, `executeKernel`.
 
 **`main()`**
@@ -323,7 +337,7 @@ Brittle tests:
 
 **Entry**: `main().catch(safetyCatch)`.
 
-### 12.3 [packages/bare-os-booter/lib/swarm-disk.js](packages/bare-os-booter/lib/swarm-disk.js)
+### 12.4 [packages/bare-os-booter/lib/swarm-disk.js](packages/bare-os-booter/lib/swarm-disk.js)
 
 **`SwarmDisk` class**
 
@@ -348,7 +362,7 @@ Brittle tests:
 
 - Fan-out message 3 to all peers with shared id (actually each peer gets same id from counter — **one id per `search()` call**, registered in `pendingSearches`; concurrent searches could collide in id space; documented as current behavior).
 
-### 12.4 [packages/bare-os-booter/lib/kernel-runner.js](packages/bare-os-booter/lib/kernel-runner.js)
+### 12.5 [packages/bare-os-booter/lib/kernel-runner.js](packages/bare-os-booter/lib/kernel-runner.js)
 
 - **`AsyncFunction`** = `Object.getPrototypeOf(async function () {}).constructor`.
 
@@ -361,7 +375,7 @@ Brittle tests:
 - Loads `/bin/<argv[0]>`, builds `AsyncFunction('ctx','argv', ...)` requiring `run` function, invokes `run(ctx, argv)`.
 - Unknown command: `ctx.console.log('unknown command: ...')`.
 
-### 12.5 [packages/bare-os-booter/test.js](packages/bare-os-booter/test.js)
+### 12.6 [packages/bare-os-booter/test.js](packages/bare-os-booter/test.js)
 
 - **`testCorestoreDir(name)`** — unique directory under `__dirname/.test-data/` (must exist parent via `mkdirSync`).