Updates

docs/audit/ctx-bare-audit-notes.md

@@ -581,3 +581,7 @@ After pulling these changes:
 3. `ctx.pear` should now contain `pearBuild`, `pearBundle`, and `pearRef` (plus the bare bundle helpers).
 
 The packages are optionalDependencies so the system still boots cleanly even if they are temporarily unavailable.
+
+**Robustness improvements (this session)**
+- `ctx.pear` is now **always** present on the guest ctx (as `{}` if empty) when bare modules are enabled. Previously it was omitted entirely if no packages loaded.
+- `pear info` and `pear list` now provide clear, actionable diagnostics explaining *why* `ctx.pear` is empty and the exact steps to fix it on production (npm install in booter/seeder + rebuild).

docs/design/ctx-pear-surface-and-bare-audit-plan.md

@@ -2,7 +2,12 @@
 
 **Status:** Final completion wave executed. All remaining plan items (19-21) driven to completion.
 
-**Production note (May 2026):** Added `pear-build`, `pear-bundle`, and `pear-ref` as `optionalDependencies` in both `bare-os-booter` and `bare-os-seeder` package.json files so that `ctx.pear` actually populates on production servers (where the local Holepunch mirror does not exist). See audit notes for install/rebuild instructions.
+**Production note (May 2026):** 
+- Added `pear-build`, `pear-bundle`, and `pear-ref` as `optionalDependencies` in both booter and seeder.
+- Made `ctx.pear` always present on the guest context (even if empty).
+- Greatly improved diagnostics in `pear info` / `pear list` so users on production servers get exact fix instructions when the packages aren't loaded.
+
+See audit notes for details.
 
 **Key final actions:**
 - Dedicated pear verifier created + integrated + run in broad harness (all green).

kernel/bin/pear

@@ -130,17 +130,43 @@ autonomous "build Pear app → publish to my store" workflows.
     ctx.console.log('pear — Pear development tools (ctx.pear surface)')
     ctx.console.log('Bare OS version of selected Pear runtime packages.')
     ctx.console.log('')
+
+    const bareModulesEnabled = !ctx.env || (ctx.env.BARE_OS_BARE_MODULES !== '0' && ctx.env.BARE_OS_BARE_MODULES !== 'false')
+
     if (ctx.pear && typeof ctx.pear === 'object') {
       const keys = Object.keys(ctx.pear).sort()
-      ctx.console.log(`Exposed on ctx.pear (${keys.length} packages):`)
+      if (keys.length > 0) {
-      for (const k of keys) {
+        ctx.console.log(`Exposed on ctx.pear (${keys.length} packages):`)
-        const val = ctx.pear[k]
+        for (const k of keys) {
-        const type = typeof val
+          const val = ctx.pear[k]
-        ctx.console.log(`  ${k.padEnd(20)} ${type}`)
+          const type = typeof val
+          ctx.console.log(`  ${k.padEnd(20)} ${type}`)
+        }
+      } else {
+        ctx.console.log('ctx.pear exists but is empty.')
+        ctx.console.log('')
+        if (!bareModulesEnabled) {
+          ctx.console.log('Reason: BARE_OS_BARE_MODULES is disabled.')
+        } else {
+          ctx.console.log('Reason: No Pear packages were successfully imported during boot.')
+          ctx.console.log('        This usually means the packages (pear-build, pear-bundle, pear-ref)')
+          ctx.console.log('        are not installed in the booter\'s node_modules.')
+          ctx.console.log('')
+          ctx.console.log('Fix: On the machine running the booter/seeder, run:')
+          ctx.console.log('        npm install')
+          ctx.console.log('      Then rebuild and restage the image.')
+          ctx.console.log('')
+          ctx.console.log('Note: On developer machines the local mirror may provide them.')
+          ctx.console.log('      On production servers they must come from npm (see optionalDependencies).')
+        }
       }
     } else {
-      ctx.console.log('ctx.pear is not currently populated (BARE_OS_BARE_MODULES may be disabled).')
+      ctx.console.log('ctx.pear property is missing from the guest context.')
+      if (!bareModulesEnabled) {
+        ctx.console.log('BARE_OS_BARE_MODULES is disabled.')
+      }
     }
+
     ctx.console.log('')
     ctx.console.log('Run "pear list" for the same view.')
   }
@@ -148,11 +174,13 @@ autonomous "build Pear app → publish to my store" workflows.
   async function cmdList() {
     if (!ctx.pear || typeof ctx.pear !== 'object') {
       ctx.console.log('ctx.pear is not available in this environment.')
+      ctx.console.log('Run "pear info" for diagnostics.')
       return
     }
     const keys = Object.keys(ctx.pear).sort()
     if (keys.length === 0) {
-      ctx.console.log('No packages currently exposed on ctx.pear.')
+      ctx.console.log('ctx.pear exists but no packages loaded.')
+      ctx.console.log('Run "pear info" for detailed reasons and fix instructions.')
       return
     }
     ctx.console.log(`ctx.pear — ${keys.length} package(s) available:\n`)
@@ -213,9 +241,8 @@ autonomous "build Pear app → publish to my store" workflows.
           k.toLowerCase().includes('build') || k.toLowerCase().includes('bundle')
         ))
       } else {
-        ctx.console.log('pear stage / build: ctx.pear.pearBuild not yet available in this environment.')
+        ctx.console.log('pear stage / build: ctx.pear.pearBuild not available.')
-        ctx.console.log('Current exposed packages on ctx.pear:')
+        ctx.console.log('Run "pear info" for status and instructions on making Pear build tooling available.')
-        await cmdList()
       }
       break
     case 'init':

kernel/etc/bare-os/posix_utilities.json

@@ -1,7 +1,7 @@
 {
   "schema": 2,
   "profileId": "bare-os-posix-like",
-  "generatedAt": "2026-05-26T22:02:23.960Z",
+  "generatedAt": "2026-05-26T22:37:49.833Z",
   "note": "Sparse POSIX Issue 7 coverage hints for /bin utilities. Omitted command names are not yet profiled here.",
   "commandIndex": [
     {

kernel/lib/bare/shell-completion.json

@@ -1,6 +1,6 @@
 {
   "schema": 1,
-  "atMs": 1779832943959,
+  "atMs": 1779835069832,
   "commands": [
     "agent",
     "appctl",

packages/bare-os-booter/index.js

@@ -4623,7 +4623,7 @@ async function executeKernel(disk, store, swarm, initSource) {
     ...(bareOsBareModulesEnabled(shellEnv)
       ? { bare: Object.freeze(bareLibrary) }
       : {}),
-    ...(bareOsBareModulesEnabled(shellEnv) && Object.keys(pearLibrary).length > 0
+    ...(bareOsBareModulesEnabled(shellEnv)
       ? { pear: Object.freeze(pearLibrary) }
       : {}),
     topic: topicKey(),

packages/bare-os-coreutils/src/pear.js

@@ -41,17 +41,43 @@ autonomous "build Pear app → publish to my store" workflows.
     ctx.console.log('pear — Pear development tools (ctx.pear surface)')
     ctx.console.log('Bare OS version of selected Pear runtime packages.')
     ctx.console.log('')
+
+    const bareModulesEnabled = !ctx.env || (ctx.env.BARE_OS_BARE_MODULES !== '0' && ctx.env.BARE_OS_BARE_MODULES !== 'false')
+
     if (ctx.pear && typeof ctx.pear === 'object') {
       const keys = Object.keys(ctx.pear).sort()
-      ctx.console.log(`Exposed on ctx.pear (${keys.length} packages):`)
+      if (keys.length > 0) {
-      for (const k of keys) {
+        ctx.console.log(`Exposed on ctx.pear (${keys.length} packages):`)
-        const val = ctx.pear[k]
+        for (const k of keys) {
-        const type = typeof val
+          const val = ctx.pear[k]
-        ctx.console.log(`  ${k.padEnd(20)} ${type}`)
+          const type = typeof val
+          ctx.console.log(`  ${k.padEnd(20)} ${type}`)
+        }
+      } else {
+        ctx.console.log('ctx.pear exists but is empty.')
+        ctx.console.log('')
+        if (!bareModulesEnabled) {
+          ctx.console.log('Reason: BARE_OS_BARE_MODULES is disabled.')
+        } else {
+          ctx.console.log('Reason: No Pear packages were successfully imported during boot.')
+          ctx.console.log('        This usually means the packages (pear-build, pear-bundle, pear-ref)')
+          ctx.console.log('        are not installed in the booter\'s node_modules.')
+          ctx.console.log('')
+          ctx.console.log('Fix: On the machine running the booter/seeder, run:')
+          ctx.console.log('        npm install')
+          ctx.console.log('      Then rebuild and restage the image.')
+          ctx.console.log('')
+          ctx.console.log('Note: On developer machines the local mirror may provide them.')
+          ctx.console.log('      On production servers they must come from npm (see optionalDependencies).')
+        }
       }
     } else {
-      ctx.console.log('ctx.pear is not currently populated (BARE_OS_BARE_MODULES may be disabled).')
+      ctx.console.log('ctx.pear property is missing from the guest context.')
+      if (!bareModulesEnabled) {
+        ctx.console.log('BARE_OS_BARE_MODULES is disabled.')
+      }
     }
+
     ctx.console.log('')
     ctx.console.log('Run "pear list" for the same view.')
   }
@@ -59,11 +85,13 @@ autonomous "build Pear app → publish to my store" workflows.
   async function cmdList() {
     if (!ctx.pear || typeof ctx.pear !== 'object') {
       ctx.console.log('ctx.pear is not available in this environment.')
+      ctx.console.log('Run "pear info" for diagnostics.')
       return
     }
     const keys = Object.keys(ctx.pear).sort()
     if (keys.length === 0) {
-      ctx.console.log('No packages currently exposed on ctx.pear.')
+      ctx.console.log('ctx.pear exists but no packages loaded.')
+      ctx.console.log('Run "pear info" for detailed reasons and fix instructions.')
       return
     }
     ctx.console.log(`ctx.pear — ${keys.length} package(s) available:\n`)
@@ -124,9 +152,8 @@ autonomous "build Pear app → publish to my store" workflows.
           k.toLowerCase().includes('build') || k.toLowerCase().includes('bundle')
         ))
       } else {
-        ctx.console.log('pear stage / build: ctx.pear.pearBuild not yet available in this environment.')
+        ctx.console.log('pear stage / build: ctx.pear.pearBuild not available.')
-        ctx.console.log('Current exposed packages on ctx.pear:')
+        ctx.console.log('Run "pear info" for status and instructions on making Pear build tooling available.')
-        await cmdList()
       }
       break
     case 'init':

packages/bare-os-seeder/kernel/bin/pear

@@ -130,17 +130,43 @@ autonomous "build Pear app → publish to my store" workflows.
     ctx.console.log('pear — Pear development tools (ctx.pear surface)')
     ctx.console.log('Bare OS version of selected Pear runtime packages.')
     ctx.console.log('')
+
+    const bareModulesEnabled = !ctx.env || (ctx.env.BARE_OS_BARE_MODULES !== '0' && ctx.env.BARE_OS_BARE_MODULES !== 'false')
+
     if (ctx.pear && typeof ctx.pear === 'object') {
       const keys = Object.keys(ctx.pear).sort()
-      ctx.console.log(`Exposed on ctx.pear (${keys.length} packages):`)
+      if (keys.length > 0) {
-      for (const k of keys) {
+        ctx.console.log(`Exposed on ctx.pear (${keys.length} packages):`)
-        const val = ctx.pear[k]
+        for (const k of keys) {
-        const type = typeof val
+          const val = ctx.pear[k]
-        ctx.console.log(`  ${k.padEnd(20)} ${type}`)
+          const type = typeof val
+          ctx.console.log(`  ${k.padEnd(20)} ${type}`)
+        }
+      } else {
+        ctx.console.log('ctx.pear exists but is empty.')
+        ctx.console.log('')
+        if (!bareModulesEnabled) {
+          ctx.console.log('Reason: BARE_OS_BARE_MODULES is disabled.')
+        } else {
+          ctx.console.log('Reason: No Pear packages were successfully imported during boot.')
+          ctx.console.log('        This usually means the packages (pear-build, pear-bundle, pear-ref)')
+          ctx.console.log('        are not installed in the booter\'s node_modules.')
+          ctx.console.log('')
+          ctx.console.log('Fix: On the machine running the booter/seeder, run:')
+          ctx.console.log('        npm install')
+          ctx.console.log('      Then rebuild and restage the image.')
+          ctx.console.log('')
+          ctx.console.log('Note: On developer machines the local mirror may provide them.')
+          ctx.console.log('      On production servers they must come from npm (see optionalDependencies).')
+        }
       }
     } else {
-      ctx.console.log('ctx.pear is not currently populated (BARE_OS_BARE_MODULES may be disabled).')
+      ctx.console.log('ctx.pear property is missing from the guest context.')
+      if (!bareModulesEnabled) {
+        ctx.console.log('BARE_OS_BARE_MODULES is disabled.')
+      }
     }
+
     ctx.console.log('')
     ctx.console.log('Run "pear list" for the same view.')
   }
@@ -148,11 +174,13 @@ autonomous "build Pear app → publish to my store" workflows.
   async function cmdList() {
     if (!ctx.pear || typeof ctx.pear !== 'object') {
       ctx.console.log('ctx.pear is not available in this environment.')
+      ctx.console.log('Run "pear info" for diagnostics.')
       return
     }
     const keys = Object.keys(ctx.pear).sort()
     if (keys.length === 0) {
-      ctx.console.log('No packages currently exposed on ctx.pear.')
+      ctx.console.log('ctx.pear exists but no packages loaded.')
+      ctx.console.log('Run "pear info" for detailed reasons and fix instructions.')
       return
     }
     ctx.console.log(`ctx.pear — ${keys.length} package(s) available:\n`)
@@ -213,9 +241,8 @@ autonomous "build Pear app → publish to my store" workflows.
           k.toLowerCase().includes('build') || k.toLowerCase().includes('bundle')
         ))
       } else {
-        ctx.console.log('pear stage / build: ctx.pear.pearBuild not yet available in this environment.')
+        ctx.console.log('pear stage / build: ctx.pear.pearBuild not available.')
-        ctx.console.log('Current exposed packages on ctx.pear:')
+        ctx.console.log('Run "pear info" for status and instructions on making Pear build tooling available.')
-        await cmdList()
       }
       break
     case 'init':

packages/bare-os-seeder/kernel/etc/bare-os/posix_utilities.json

@@ -1,7 +1,7 @@
 {
   "schema": 2,
   "profileId": "bare-os-posix-like",
-  "generatedAt": "2026-05-26T22:02:23.960Z",
+  "generatedAt": "2026-05-26T22:37:49.833Z",
   "note": "Sparse POSIX Issue 7 coverage hints for /bin utilities. Omitted command names are not yet profiled here.",
   "commandIndex": [
     {

packages/bare-os-seeder/kernel/lib/bare/shell-completion.json

@@ -1,6 +1,6 @@
 {
   "schema": 1,
-  "atMs": 1779832943959,
+  "atMs": 1779835069832,
   "commands": [
     "agent",
     "appctl",