Docs+AutoPass patch

developer-guide/07-apps-beyond-the-shell.md

@@ -1,65 +1,111 @@
-# Chapter 7 — “Apps” beyond the shell (what is realistic today)
+# Chapter 7 — Apps beyond the shell
 
-Bare OS does not have an app store, sandboxed widgets, or a second GUI runtime inside the image. An **application** here is usually:
+Bare OS now ships a **P2P App Store** client (`/bin/appstore`) and **guest Pear tooling** (`/bin/pear`) so “applications” can be authored, published, installed, and launched **inside the shell** without a second GUI runtime.
 
-- a **workflow** built from the **shell**, **`/bin`** tools, and files on the **personal** drive; or
+This chapter orients you to what is **real today** versus what still requires a **host Pear** process.
-- a **custom kernel** + utilities; or
-- a **host Pear app** that changes boot behavior.
-
-This chapter orients you without over-promising.
 
 ---
 
-## The default “app”: shell + `/bin` + git
+## Three application models
 
-Most user goals are met by:
+| Model | When to use | Entry points |
+| --- | --- | --- |
+| **Shell + `/bin` + files** | Scripts, pipelines, git on the VFS | `$HOME`, `run(ctx, argv)` utilities |
+| **Pear app (guest)** | P2P apps with `pear://` distribution | `pear init` → `stage` → `release` → `appstore install` → `launch` |
+| **Host Pear app** | Custom booter/seeder images, native addons, desktop Pear | Repo root `pear run`, new Pear project (Chapter 1) |
+
+Most **end-user Pear apps** you build in Bare OS follow the **guest Pear + App Store** row. See **[Guest Pear and App Store workflow](../docs/guides/guest-pear-and-appstore-workflow.md)** for copy-paste commands.
+
+---
+
+## Guest Pear pipeline (`/bin/pear`)
+
+Implemented in `packages/bare-os-coreutils` (`pear.js`, `pear-stage.js`, `pear-release.js`).
+
+```bash
+pear init
+cd ~/pear-projects/my-pear-app
+pear stage
+login                    # unlock identity / HDMS
+pear release .
+pear seed .
+```
+
+- **`pear stage`** — Writes `<project>/.pear/stage/` (`sources/`, `package.json`, `app.bundle.js`, `stage.json`).
+- **`pear release`** — Mirrors the stage tree onto a writable HDMS mount (`/mnt/pear-<name>/`) and prints **`pear://`** links (uses HDMS registry keys; does not require host Pear CLI).
+- **`pear seed`** — Best-effort Hyperswarm flush so peers can replicate the release drive.
+
+Release metadata is stored in **`<project>/.pear/release.json`**.
+
+---
+
+## P2P App Store (`/bin/appstore`)
+
+Implemented in `packages/bare-os-coreutils` (`appstore.js`, `appstore-pear.js`, `p2p-suite.js` preamble).
+
+```bash
+appstore install my-app pear://0.<length>.<key> --yes
+appstore launch my-app
+```
+
+- **`install`** — Fetches the `pear://` release tree (local HDMS mount with matching key, or ephemeral readonly HDMS fetch) into `~/.appstore/packages/<name>/` (or `/mnt/appstore/packages/<name>/` when the store HDMS drive is mounted).
+- **`launch`** — Runs the materialized entry script (`sources/index.js` or `package.json` `main`) in the guest shell; output appears on **`ctx.console`**.
+- **`update`** — Re-fetches from the package’s stored `pearLink`.
+- **`setup`** — Prints how to create/mount the optional **`appstore`** HDMS label.
+
+Design and trust model: **[p2p-app-store.md](../docs/design/p2p-app-store.md)**.
+
+---
+
+## The default platform: shell + `/bin` + git
+
+Workflows that are not Pear-packaged still use:
 
 - Scripts in **`$HOME`** (`run(ctx, argv)`).
 - Pipelines and redirection (simulated stdin/stdout).
-- **`git`** for repositories on the VFS (see [Handbook ch.8](../handbook/08-git-on-bare-os.md)).
+- **`git`** on the VFS ([Handbook ch.8](../handbook/08-git-on-bare-os.md)).
-
-That is the **intended** application platform for end users.
 
 ---
 
-## initd and background flavor
+## initd, cron, and services
 
-The booter registers **initd**-style disposers via [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js). The stock system uses this lightly (e.g. kernel logger). **Extending** this usually means **host** booter changes: register a start function during `executeKernel`, not from arbitrary `/bin` scripts.
+**initd** — User units under `~/.config/bare-os/units/`. `appstore services` can generate initd unit stubs for packages that declare a service manifest (see `appstore.js`).
 
-Read [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js) before adding long-running tasks—teardown must be explicit (`stopBareInitd`).
+**Timers / cron** — See [Chapter 11](11-kernel-pear-cookbook.md) and handbook ch.4.
-
----
-
-## Cron and timers
-
-**`bare-cron`** reads **`/etc/bare-os/crontab`** on the system image (if present), then the user’s **`~/.crontab`** on the personal drive; invalid lines are logged and skipped. **`crontab`** installs/lists/removes the **user** file (requires login). Timer drop-ins under `**~/.config/bare-os/timers/*.timer`** (**`[Timer]`** `**OnCalendar=**` + `**ExecLine=`**) merge into the same minute scheduler. See [Handbook ch.4](../handbook/04-the-booter-runtime.md) and [Developer guide ch.11](11-kernel-pear-cookbook.md).
-
-**Socket-shaped activation:** initd unit drop-ins can set **`SocketActivationIpc=<fifo-name>`** so a service’s **`start()`** runs when something first **`readFile`**s that logical FIFO under **`/run/bare-os/ipc/`** (see **`bare-initd.js`**).
 
 ---
 
 ## HDMS and `/mnt`
 
-After identity unlock, optional **HDMS** mounts may appear under **`/mnt`**. Utilities use **`ctx.vfs`**; HDMS integration is advanced and covered narratively in the handbook (identity + HDMS chapter). User scripts should prefer **`vfs.readFile`** / **`writeFile`** over hard-coding drive objects.
+After **login**, HDMS mounts extra Hyperdrives under **`/mnt/<label>/`**. Pear releases use labels like **`pear-my-pear-app`**. The App Store prefers label **`appstore`** at **`/mnt/appstore`**.
+
+User scripts should use **`ctx.vfs`** rather than hard-coding drive handles.
 
 ---
 
 ## Replacing the kernel
 
-A heavier “app” might ship a **different `/boot/init.js**`—for example a menu-driven UI using **`readLine`** or a non-interactive worker when `**BARE_OS_SKIP_REPL=1`**. You still have the **single JavaScript realm** per session; there is no fork into a second Bare process from inside the image.
+Shipping a different **`/boot/init.js`** remains a **kernel image** change (non-interactive worker, custom menu, etc.). Pear **user apps** do not require replacing the stock kernel.
 
 ---
 
-## When you actually need a new Pear app
+## When you need a new host Pear app
 
-If you need **multiple OS images**, **custom networking**, or **native addons** not suitable for `AsyncFunction` utilities, create a **new Pear application** that embeds or forks the booter pattern—this is **host** development (Chapter 1), not `/bin` development.
+Use a **new Pear application** on the host when you need:
+
+- A different system image or booter embedding model
+- Native addons unsuitable for `AsyncFunction` `/bin` scripts
+- Desktop/mobile Pear runtime features
+
+Guest **`pear release`** still produces valid **`pear://`** links consumable by host **`pear run`**.
 
 ---
 
 ## See also
 
+- [Guest Pear and App Store workflow](../docs/guides/guest-pear-and-appstore-workflow.md)
+- [Chapter 12 — Bare modules and Pear](12-bare-modules-and-pear-ecosystem.md)
 - [Chapter 3 — Kernel](03-kernel-boot-init.md)
-- [Handbook — Booter runtime](../handbook/04-the-booter-runtime.md)
 - [Handbook — Identity, vault, HDMS](../handbook/05-identity-vault-and-hdms.md)
 
 ---

developer-guide/11-kernel-pear-cookbook.md

@@ -54,6 +54,7 @@ Storage write limits use existing hooks (**`BARE_OS_VFS_QUOTA_*`**, **`BARE_OS_H
 
 ## Pear / Git / HTTP
 
+- **Guest Pear apps** — Author, release, install, and launch Pear apps entirely in the shell: see **[Guest Pear and App Store workflow](../docs/guides/guest-pear-and-appstore-workflow.md)** (`/bin/pear`, `/bin/appstore`). Host **`pear run pear://…`** remains for full Pear desktop/runtime on a Pear-capable machine.
 - **Mirror-drive hints** — `ctx.bareOsEmitMirrorDriveHint({ label?, key? })` emits `bare-os:mirror-drive-hint` on Node-style hosts for mirror-drive–style workflows (labels/keys only; trust boundaries unchanged).
 - **Release metadata** — Host can set `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, and `BARE_OS_IMAGE_DIGEST`; they appear in `/run/bare-os/boot.json`.
 - **`ctx.bareOsRequestPearReload()`** — Returns hints and env strings; the host `**pear-runtime` / `pear-runtime-updater**` must perform any real reload. A successful host reload can swap the Pear **booter** bundle so a new **`bare-module-manifest.data.mjs`** (from **`npm run sync:bare-manifest`** at staging time) takes effect; **`ctx.bareOsRequestPearReload`** does not rewrite **`ctx.bare`** in-process—expect a new guest boot for an updated host import list. Drive-only edits to **`/lib/bare/bare-module-manifest.json`** still merge bundles from the image without re-staging Pear.

developer-guide/12-bare-modules-and-pear-ecosystem.md

@@ -76,16 +76,25 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru
 
 ---
 
-## New: `ctx.pear` surface (2026)
+## New: `ctx.pear` surface and `/bin/pear` (2026)
 
-In addition to `ctx.bare`, a parallel `ctx.pear` surface now exists for Pear-level development tooling.
+A parallel **`ctx.pear`** surface exposes Pear-level development tooling to in-image scripts.
 
-- Populated from the new `pearEntries` tier in the module manifest.
+- Populated from **`pearEntries`** in `bare-module-manifest.json` (`pear-build`, `pear-bundle`, `pear-ref`, `bare-bundle-compile`, …).
-- Initial packages include `pear-build`, `pear-bundle`, `pear-ref`, plus re-exposed bare bundle helpers.
+- Static host imports under `pear://` via `bare-os-ctx-pear-host.js` (see HDMS manager pattern — no dynamic `import("pkg")` from guest bundles).
-- Exposed via the real `/bin/pear` command (`pear info`, `pear list`, etc.).
+- **`/bin/pear`**: `help`, `info`, `list`, `init`, `stage`, `release`, `seed` (`build`/`bundle` alias `stage`).
-- Full design, audit findings, and remaining implementation plan live in `docs/design/ctx-pear-surface-and-bare-audit-plan.md` and the audit notes.
 
-This enables creating, staging, and (with host delegates) releasing real Pear apps entirely from inside a booted Bare OS instance, with natural integration into the P2P App Store.
+**Guest workflow (no host Pear CLI required for release):**
+
+```bash
+pear init && pear stage && pear release . && pear seed .
+appstore install my-app pear://0.<length>.<key> --yes
+appstore launch my-app
+```
+
+Full operator guide: **[docs/guides/guest-pear-and-appstore-workflow.md](../docs/guides/guest-pear-and-appstore-workflow.md)**.
+
+Design and audit: `docs/design/ctx-pear-surface-and-bare-audit-plan.md`, `docs/audit/ctx-bare-audit-notes.md`.
 
 ---
 

developer-guide/README.md

@@ -64,7 +64,7 @@ Full script index: [scripts/README.md](../scripts/README.md). Gate everything wi
 - **[04 — User scripts and PATH resolution](04-user-scripts-and-path.md)** — `run(ctx, argv)`, shebangs, `*.js` in cwd, `./` paths, `/bin`.
 - **[05 — Modules and `import`](05-modules-and-imports.md)** — Why ESM does not apply to in-image scripts; bundling and alternatives.
 - **[06 — Extending `/bin` (coreutils)](06-extending-bin-coreutils.md)** — `commands.mjs`, `build.mjs`, preamble, man pages.
-- **[07 — Apps beyond the shell](07-apps-beyond-the-shell.md)** — What an “app” means here; initd, cron, git, custom kernels (overview).
+- **[07 — Apps beyond the shell](07-apps-beyond-the-shell.md)** — P2P App Store (`/bin/appstore`), guest Pear (`/bin/pear`), HDMS mounts; initd, cron, git.
 - **[08 — Testing and debugging](08-testing-and-debugging.md)** — `npm test`, Brittle, Pear dev, common failure modes.
 - **[09 — Security and trust](09-security-and-trust.md)** — System vs personal drive; eval boundaries.
 - **[10 — Glossary and FAQ](10-glossary-and-faq.md)** — Quick definitions; frequent questions.

docs/PEAR-RUN.md

@@ -110,4 +110,14 @@ Hoisted deps live at the repo root. For `pear stage` to include runtime modules,
 
 ## `pear run` vs `pear release`
 
-After `pear stage`, run `pear release <channel>` so `pear run pear://<key>` resolves to the new length.
+**Host (booter/seeder packages):** After `pear stage`, run `pear release <channel>` on the **host** so `pear run pear://<key>` resolves to the new length. See the versioned links in the sections above.
+
+**Guest (booted Bare OS shell):** Use **`/bin/pear`** instead — no host Pear CLI required:
+
+```bash
+pear stage
+pear release .
+pear seed .
+```
+
+Then distribute with **`appstore install <name> pear://0.<length>.<key> --yes`** and **`appstore launch <name>`**. Full steps: **[guides/guest-pear-and-appstore-workflow.md](guides/guest-pear-and-appstore-workflow.md)**.

docs/README.md

@@ -333,6 +333,7 @@ When you change **`BARE_OS_CTX_API_VERSION`**, **`/proc`** JSON schemas, **`BARE
 - First run: [Get started](./get-started.md) · Doc map: [Sitemap](./sitemap.md).
 - Legacy monolith map: [DOCUMENTATION.md](../DOCUMENTATION.md) (points here and to reference).
 - Pear channels and host env: [PEAR-RUN.md](./PEAR-RUN.md).
+- Guest Pear + App Store (in-shell author, release, install, launch): [guides/guest-pear-and-appstore-workflow.md](./guides/guest-pear-and-appstore-workflow.md).
 - Repository quick start: [README.md](../README.md).
 
 ---

docs/audit/bundle-health.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-05-26T23:43:00.347Z",
+  "generatedAt": "2026-05-26T23:57:44.193Z",
   "normativeManifest": "packages/bare-os-booter/lib/bare-module-manifest.json",
   "buildTool": "packages/bare-os-bare-libs/build.mjs",
   "bundles": [

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

@@ -568,6 +568,22 @@ All changes are being made with the same verifier-first, clone-aware, Bare-guest
 
 Added the Pear packages required for `ctx.pear` to actually appear in guests:
 
+---
+
+## May 2026 — Guest Pear release + App Store materialization (shipped)
+
+**Code:**
+
+- `packages/bare-os-coreutils/lib/pear-stage.js` — guest `pear stage`
+- `packages/bare-os-coreutils/lib/pear-release.js` — guest `pear release` / `pear seed` (HDMS + pear://)
+- `packages/bare-os-coreutils/lib/appstore-pear.js` — pear:// fetch, mirror, in-guest launch
+- `packages/bare-os-coreutils/src/appstore.js` — install/launch/update wired to appstore-pear
+- `packages/bare-os-coreutils/test/pear-stage.test.mjs`, `pear-release.test.mjs`, `appstore-pear.test.mjs`
+
+**Documentation:** `docs/guides/guest-pear-and-appstore-workflow.md` (canonical operator guide).
+
+**Behavior:** `appstore install` copies release trees from matching HDMS mounts or ephemeral readonly fetch; `appstore launch` runs `sources/index.js` on `ctx.console`. No peerctl-only launch stub. `pear release` does not require host Pear CLI or `ctx.bare.hypercoreIdEncoding` (uses HDMS registry z32 keys + inline encoder fallback).
+
 - Moved `pear-build`, `pear-bundle`, and `pear-ref` into the **main `dependencies`** (not optional) in both:
   - `packages/bare-os-booter/package.json`
   - `packages/bare-os-seeder/package.json`

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

@@ -160,8 +160,8 @@ This document defines a complete, gated, 50-round implementation plan.
 | 32 | Create new manifest tier + entries for Pear packages | Start with core build/bundling packages | **In Progress** | First cut landed: added "pearEntries" array + 5 initial packages (pear-build, pear-bundle, pear-ref, bare-bundle-compile, bare-bundle-evaluate) to bare-module-manifest.json. Generator + all safety verifiers green. See audit notes Implementation Log. Loader + ctx exposure in progress (next rows). |
 | 33 | Implement core `ctx.pear` object construction | Parallel to `buildBareCtxObjectFromHost` | **Done** | buildPearCtxObjectFromHost + loadPearModuleManifest added + wired into boot + ctx attachment in index.js + .d.ts. First 5 packages now reachable as ctx.pear.pearBuild etc. Verifiers green. See audit notes. |
 | 34 | Implement drive bundle support for new Pear bundles | If `bundle: true` entries are added | Pending | |
-| 35 | Create initial `/bin/pear` command skeleton | Basic subcommands: `init`, `info`, `stage` | **Done** | Real command created (help, info, list, stage stub). Registered + man page + full coreutils rebuild. 183 commands now. Binaries in kernel + seeder. `pear list` already shows live ctx.pear content. See audit notes. |
+| 35 | Create initial `/bin/pear` command | `init`, `info`, `list`, `stage`, `release`, `seed` | **Done** | See `lib/pear-stage.js`, `lib/pear-release.js`, `docs/guides/guest-pear-and-appstore-workflow.md` |
-| 36 | Wire basic staging using exposed `pear-build` / `bare-build` | End-to-end `pear stage` equivalent in guest | Pending | |
+| 36 | Wire basic staging using exposed `pear-build` / `bare-build` | End-to-end `pear stage` in guest | **Done** | `pear-stage.js` |
 | 37 | Add release/seeding primitives | Use existing swarm + Hyperdrive primitives | Pending | |
 | 38 | Implement gated kernel extension path for Pear tools | If needed | Pending | |
 | 39 | Full service + initd integration for Pear apps | Allow installed Pear apps to run as services | Pending | |
@@ -208,7 +208,9 @@ Any change that touches `ctx` API surface, boot policy, or protocol must:
 
 ---
 
-## Phase 2 Design Draft: ctx.pear Surface (in progress)
+## Phase 2 Design Draft: ctx.pear Surface
+
+**May 2026 implementation status:** Guest **`pear stage`**, **`pear release`**, **`pear seed`**, and App Store **`install`** / **`launch`** with real **`pear://`** materialization are **shipped**. Canonical operator guide: **`docs/guides/guest-pear-and-appstore-workflow.md`**. Host Pear CLI remains optional for booter/seeder channel releases and full **`pear run`** desktop runtime.
 
 **Status:** First-cut design synthesized from Phase 1 audit (Rounds 1–11 / plan-04–plan-11). Draws directly on:
 - The two-path ctx.bare architecture (host import + drive IIFEs)
@@ -261,20 +263,23 @@ Host delegate pattern (already proven):
 
 ### 4. Integration with Existing OS Surfaces
 
-- **P2P App Store**: Natural consumer. `appstore install pear://...` already materializes Pear apps. `ctx.pear` + `/bin/pear` give the *authoring* side so users can create the packages that then go into the store.
+- **P2P App Store:** **`appstore install`** fetches pear:// release trees via **`lib/appstore-pear.js`**; **`appstore launch`** runs materialized **`sources/<main>`** in the guest shell. See **`docs/guides/guest-pear-and-appstore-workflow.md`**.
-- **HDMS + two-drive model**: Recommend a `pear-dev` label convention (`/mnt/pear-dev`) for projects, staging areas, and release artifacts (keeps system drive clean).
+- **HDMS:** Pear releases use writable mounts **`pear-<app-name>`**; optional App Store label **`appstore`** at **`/mnt/appstore`**.
-- **Agent skill**: New `pear-dev` skill (modeled exactly on the production `appstore` skill after its 50-round polish). Autonomous workflows: "create new Pear app → stage it → test launch → release to my HDMS appstore drive".
+- **Agent skills:** **`pear-dev`** + **`appstore`** (cross-referenced).
-- **/bin/pear** (new coreutil, Tier-1): Subcommands `init`, `stage`, `bundle`, `release`, `seed`, `info`, `launch` (many will be thin wrappers + host delegates for the heavy parts).
+- **`/bin/pear`:** **`init`**, **`stage`**, **`release`**, **`seed`**, **`info`**, **`list`** — guest-pure for the release path (no host Pear CLI required).
-- **Existing peerctl / appctl / pkg-swarm-index**: Extend rather than duplicate for the "release & seed" verbs.
+- **`appctl`:** Registry helper; launch may still delegate via peerctl for host Pear apps.
 
 ### 5. Host Delegate Strategy (the practical reality)
 
-From the clone + booter Pear files we already have (`bare-os-pear-ipc-registry.js`, multiple `bare-os-proc-pear-*-hrpc.js`, `bare-os-pear-updater-bridge.js`):
+**Shipped (May 2026):** **`pear release`** and **`pear seed`** run in the guest via HDMS (writable release drive + Hyperswarm flush). **`pear release`** uses HDMS registry z32 keys and an inline encoder fallback — not the host Pear CLI.
 
-- Short-term (this Batch D work): `ctx.pear` exposes the build/bundle/init surface directly (guest-pure where possible). `release`/`seed`/`live IPC` verbs are explicit delegates that shell out to or HRPC the host Pear sidecar (user must have Pear running on the host or the OS spawns a controlled one).
+**Still host-delegated or optional:**
-- Longer-term: Full in-guest Pear sidecar is out of scope (heavy native + rocksdb + updater).
 
-This is the same pragmatic split the App Store already uses successfully for launch + services.
+- Full **`pear run`** Pear desktop/mobile runtime on a Pear-capable host
+- Heavy signing / sidecar IPC not yet exposed as guest-pure verbs
+- **`appctl launch`** may use peerctl for host-managed Pear apps
+
+This matches the App Store split: guest authoring + install/launch for simple apps; host Pear for full runtime when needed.
 
 ### 6. Open Design Questions (to resolve before impl)
 

docs/design/p2p-app-store.md

@@ -1,6 +1,6 @@
 # P2P App Store (design)
 
-**Status:** Feature Complete — 50-round autonomous production polish sprint successfully delivered. No remaining TODOs or scaffolding.  
+**Status:** Core user-app paths shipped (May 2026): real `pear://` materialization and in-guest launch. Kernel-ext verification and multi-index discovery remain incremental.  
 **Owner:** Raven (with community input)  
 **Related:** HDMS, `appctl`, `pkg-swarm-index`, kernel extensions, agent skills, two-drive model
 
@@ -109,15 +109,23 @@ This drive is **personal** by default but can be shared via Autopass/HDMS if the
 - Agent skill skeleton + basic discovery using existing `pkg-swarm-index`
 - Documentation + `man appstore`
 
-### Phase 2 — User Apps & Services (10-round autonomous sprint completed)
+### Phase 2 — User Apps & Services (shipped core paths)
-- Rich manifest + launcher stub materialization
-- `launch`, `update`, `setup`, and `services` scaffolding
-- Gated kernel-ext path with strong warnings
-- Significantly expanded agent skill with multi-step autonomous workflows
-- Much stronger HDMS preference and UX
-- Comprehensive error handling and documentation updates
 
-The App Store command is now a solid, usable foundation with clear paths for the remaining high-value items (real P2P content fetch, auto-initd services, full kernel-ext gating).
+- **`appstore install`** — Real `pear://` materialization via **`lib/appstore-pear.js`** (local HDMS mount or ephemeral readonly fetch + VFS mirror into `packages/<name>/`).
+- **`appstore launch`** — In-guest execution of `sources/<main>` (or `package.json` `main`); output on `ctx.console` (no peerctl-only stub).
+- **`appstore update`** — Re-fetch from stored `pearLink`.
+- Manifest + `appstore-meta.json` with `materializationVersion: 3` and fetch metadata.
+- `setup`, `services` scaffolding, gated kernel-ext warnings, HDMS preference, agent skill.
+
+Remaining Phase 2 items: automatic initd wiring for all service types, full kernel-ext verification pipeline.
+
+### Phase 2b — Guest Pear authoring (May 2026)
+
+- **`/bin/pear`**: `init`, `stage`, `release`, `seed` (aliases `build`/`bundle` for stage).
+- **`pear release`** publishes `.pear/stage/` to a writable HDMS drive and emits versioned **`pear://`** links without host Pear CLI.
+- Natural handoff to App Store: `appstore install <name> <pearLink> --yes` then `appstore launch <name>`.
+
+Operator guide: **[docs/guides/guest-pear-and-appstore-workflow.md](../guides/guest-pear-and-appstore-workflow.md)**.
 
 ### Phase 3 — Kernel Extensions (High Care)
 - Signed extension manifest format for the store
@@ -162,30 +170,37 @@ These can be mixed into the broader Batch D plan. Suggested priority order for t
 | D-APP-02 | `/bin/appstore` skeleton (list, info, search via pkg-swarm-index) | 1 | D-APP-01 | New binary |
 | D-APP-03 | Agent skill `appstore` (discovery + safe install guidance) | 1 | D-APP-02 | |
 | D-APP-04 | HDMS auto-mount of appstore drive on session start | 1 | D-APP-01 | |
-| D-APP-05 | Full user-app install flow (manifest → materialization) | 2 | D-APP-02 | |
+| D-APP-05 | Full user-app install flow (manifest → materialization) | 2 | D-APP-02 | **done** — `appstore-pear.js` fetch + mirror |
-| D-APP-06 | Service manifest + initd unit generation from installed packages | 2 | D-APP-05 | |
+| D-APP-06 | Service manifest + initd unit generation from installed packages | 2 | D-APP-05 | partial — `appstore services` scaffolding |
-| D-APP-07 | `appstore launch` + integration with existing Pear launch paths | 2 | D-APP-05 | |
+| D-APP-07 | `appstore launch` + integration with existing Pear launch paths | 2 | D-APP-05 | **done** — in-guest script launch; `appctl` still uses peerctl |
 | D-APP-08 | Signed manifest format + verification for kernel extensions | 3 | D-APP-05 | Security critical |
 | D-APP-09 | Gated `install --kernel-ext` + boot policy integration | 3 | D-APP-08 | |
 
 ---
 
-## Pear Development Integration (Added 2026)
+## Pear Development Integration (May 2026)
 
-The completion of the `ctx.pear` surface and `/bin/pear` command (see `docs/design/ctx-pear-surface-and-bare-audit-plan.md`) creates a powerful closed loop with the App Store:
+The **`ctx.pear`** surface and **`/bin/pear`** command (see `docs/design/ctx-pear-surface-and-bare-audit-plan.md`) close the loop with the App Store:
 
-- Users (and agents using the new `pear-dev` skill) can now **create and stage real Pear applications entirely inside Bare OS**.
+| Step | Command | Result |
-- Those staged Pear apps are natural `app` packages for the App Store.
+| --- | --- | --- |
-- `appstore install` (or direct pear:// materialization) + `appstore launch` becomes the distribution and execution path for apps the user just built with Pear tooling.
+| Author | `pear init` / edit sources | Project under `~/pear-projects/` |
+| Stage | `pear stage` | `.pear/stage/` |
+| Publish | `pear release` | HDMS mount + `pear://0.<length>.<key>` |
+| Replicate | `pear seed` | Swarm flush (best-effort) |
+| Distribute | `appstore install NAME pear://… --yes` | `~/.appstore/packages/NAME/` |
+| Run | `appstore launch NAME` | Guest shell runs `sources/index.js` |
 
-**Recommended combined agent workflow**:
+**Implementation files:**
-1. `pear-dev` skill → help user/author create + stage a Pear app using `ctx.pear` + `/bin/pear`.
-2. `appstore` skill → publish the result into the user's personal HDMS App Store drive.
-3. Other booted users discover/install/run it normally.
 
-This was one of the original long-term visions for both features. The two skills (`pear-dev` + `appstore`) are now explicitly cross-referenced.
+- `packages/bare-os-coreutils/lib/pear-stage.js`, `lib/pear-release.js`
+- `packages/bare-os-coreutils/lib/appstore-pear.js`
+- `packages/bare-os-coreutils/src/appstore.js`
+
+**Agent skills:** `pear-dev` + `appstore` (cross-referenced).
+
+**Not yet in guest:** `pear run` subcommand (full Pear runtime); compiled-only `app.bundle.js` launch without `sources/` entry.
 
-Future work (plan-17 continuation): richer `pear://` materialization helpers inside the App Store code, and possibly a `pear release` subcommand that can target an App Store drive directly.
 | D-APP-10 | Appstore-sourced extensions loaded with distinct source tag + audit | 3 | D-APP-09 | |
 | D-APP-11 | `/proc/bare_os/appstore.json` + virtual files | 2 | D-APP-04 | Observability |
 | D-APP-12 | `ctx.bareOsAppstore*` methods (install, list, drive ref) | 2 | D-APP-05 | ctx API bump |
@@ -208,7 +223,9 @@ This feature has the potential to become one of the most visible and useful part
 ---
 
 **Related existing files to keep in sync:**
-- `kernel/etc/bare-os/apps.registry.example.json`
+- `packages/bare-os-coreutils/lib/appstore-pear.js`
+- `packages/bare-os-coreutils/lib/pear-stage.js`, `lib/pear-release.js`
+- `docs/guides/guest-pear-and-appstore-workflow.md`
 - `packages/bare-os-booter/lib/hdms-manager.js`
 - `packages/bare-os-coreutils/src/appctl.js` and `pkg-swarm-index.js`
 - `developer-guide/kernel-program.md`

docs/glossary.md

@@ -34,6 +34,12 @@ Short definitions for terms used across the user manual, handbook, developer gui
 
 **`ctx.bare`** — Frozen map of curated modules exposed to in-image code per manifest and optional **`/lib/bare`** bundles. See [developer-guide/12-bare-modules-and-pear-ecosystem.md](../developer-guide/12-bare-modules-and-pear-ecosystem.md).
 
+**`ctx.pear`** — Frozen map of Pear development packages (`pear-build`, `pear-bundle`, `bare-bundle-compile`, …) exposed when **`BARE_OS_BARE_MODULES`** is enabled. Used by **`/bin/pear`**.
+
+**App Store (`/bin/appstore`)** — Guest command to install packages from **`pear://`** links into **`~/.appstore/`** (or **`/mnt/appstore`**) and **launch** entry scripts in the shell. See [guides/guest-pear-and-appstore-workflow.md](guides/guest-pear-and-appstore-workflow.md).
+
+**`/bin/pear`** — Guest Pear dev CLI: **`init`**, **`stage`**, **`release`**, **`seed`**. Publishes apps to HDMS and **`pear://`** links without host Pear CLI. Same guide as App Store.
+
 **Guest** — Pre-login session identity; typically **`BARE_OS_IDENTITY=guest`**. Contrast with logged-in user and vault flows in [handbook/05-identity-vault-and-hdms.md](../handbook/05-identity-vault-and-hdms.md).
 
 **HDMS** — Hyperdrive mount subsystem: optional extra drives under **`/mnt`**. Handbook: [Chapter 5](../handbook/05-identity-vault-and-hdms.md).
@@ -50,7 +56,7 @@ Short definitions for terms used across the user manual, handbook, developer gui
 
 **MBR (Bare OS)** — 512-byte bootstrap block on the system image with magic **`BIOS`** and Hyperdrive discovery key material (not a PC BIOS partition table). Seeder is canonical; eligible booted peers may mirror the same block `0` for availability. Layout: [handbook/03-protocol-and-disk.md](../handbook/03-protocol-and-disk.md).
 
-**Pear** — Packaging and distribution layer for Bare apps; seeder and booter ship as Pear projects. Host notes: [PEAR-RUN.md](./PEAR-RUN.md).
+**Pear** — Packaging and distribution layer for Bare apps; seeder and booter ship as Pear projects. Host: [PEAR-RUN.md](./PEAR-RUN.md). Guest authoring/install: [guides/guest-pear-and-appstore-workflow.md](guides/guest-pear-and-appstore-workflow.md).
 
 **Personal drive** — Writable Hyperdrive for **`$HOME`**, **`/.bare/`**, vault snapshots, logs, and user files. Routed by the VFS alongside the read-only system tree.
 

docs/guides/guest-pear-and-appstore-workflow.md

@@ -0,0 +1,113 @@
+# Guest Pear development and P2P App Store workflow
+
+**Status:** Shipped in-tree (May 2026)  
+**Implementation:** `packages/bare-os-coreutils/src/pear.js`, `lib/pear-stage.js`, `lib/pear-release.js`, `src/appstore.js`, `lib/appstore-pear.js`
+
+This guide describes the **end-to-end workflow inside a booted Bare OS shell**. You do **not** need host-side `pear release` or a Pear sidecar to author, publish, install, or run simple Pear apps from the guest.
+
+---
+
+## Prerequisites
+
+- Booted Bare OS session with **`/bin/pear`** and **`/bin/appstore`** on the system image (rebuild with `npm run build -w bare-os-coreutils` and re-seed if missing).
+- **`login`** (identity unlocked) for **`pear release`**, **`pear seed`**, and App Store fetch from remote `pear://` keys (HDMS must be active).
+- Optional: **`BARE_OS_BARE_MODULES`** enabled for `pear stage` pack/compile tools on `ctx.pear` / `ctx.bare` (release no longer requires `hypercore-id-encoding` on `ctx.bare` — HDMS registry keys are used).
+
+---
+
+## Author → release (guest `/bin/pear`)
+
+```bash
+pear init
+cd ~/pear-projects/my-pear-app
+
+# edit sources (default index.js logs "Hello from my Pear app!")
+
+pear stage          # writes .pear/stage/ (sources, bundle, stage.json)
+pear release .      # HDMS mount pear-<name>, prints pear:// links
+pear seed .         # best-effort Hyperswarm flush for the release drive
+```
+
+**Outputs:**
+
+| Artifact | Location |
+| --- | --- |
+| Staged tree | `<project>/.pear/stage/` |
+| Release metadata | `<project>/.pear/release.json` |
+| Live release mount | `/mnt/pear-<app-name>/` (HDMS writable drive) |
+| Shareable link | `pear://0.<length>.<z32-key>` (use the **versioned** line after each release) |
+
+**Host Pear** (`pear run pear://…` on a Pear-capable machine) remains valid for full desktop Pear runtimes; the guest workflow is authoritative for building and publishing the link.
+
+---
+
+## Install → run (guest `/bin/appstore`)
+
+```bash
+appstore install my-pear-app \
+  pear://0.<length>.<z32-key> \
+  --yes
+
+appstore list
+appstore info my-pear-app
+
+appstore launch my-pear-app    # runs sources/index.js in the guest shell
+```
+
+**Install** (`appstore-pear.js`):
+
+1. Resolves the `pear://` key (including `pear://0.<length>.<key>` form).
+2. Copies the release tree from a **local HDMS mount** with the same key when present (e.g. your `pear-my-pear-app` mount), otherwise opens an **ephemeral readonly** HDMS mount and waits for content.
+3. Materializes files under `~/.appstore/packages/<name>/` (or `/mnt/appstore/packages/<name>/` when the App Store HDMS drive is mounted).
+
+**Launch** executes the package entry script (`package.json` `main`, typically `sources/index.js`) via the guest `ctx.console` — you should see application output (e.g. `Hello from my Pear app!`) in the shell.
+
+**Refresh** after a new `pear release`:
+
+```bash
+appstore update my-pear-app
+```
+
+---
+
+## App Store HDMS drive (optional)
+
+Personal fallback (`~/.appstore/`) works without extra setup. For a dedicated store drive:
+
+```bash
+appstore setup          # instructions
+hdms create appstore    # label appstore → /mnt/appstore
+appstore install … --yes
+```
+
+Registry then prefers `/mnt/appstore/registry.json`.
+
+---
+
+## Agent skills
+
+| Skill | Path |
+| --- | --- |
+| Pear authoring | `kernel/share/agent-workspace/skills/pear-dev/SKILL.md` |
+| Install / launch | `kernel/share/agent-workspace/skills/appstore/SKILL.md` |
+
+---
+
+## Related documentation
+
+- [PEAR-RUN.md](../PEAR-RUN.md) — host `pear stage` / `pear release` for **booter** and **seeder** channels
+- [p2p-app-store.md](../design/p2p-app-store.md) — architecture and trust model
+- [ctx-pear-surface-and-bare-audit-plan.md](../design/ctx-pear-surface-and-bare-audit-plan.md) — `ctx.pear` surface
+- [developer-guide/07-apps-beyond-the-shell.md](../../developer-guide/07-apps-beyond-the-shell.md)
+- [developer-guide/12-bare-modules-and-pear-ecosystem.md](../../developer-guide/12-bare-modules-and-pear-ecosystem.md)
+
+---
+
+## Limitations (honest)
+
+| Area | Current behavior |
+| --- | --- |
+| `pear run` in guest | Not a `/bin/pear` subcommand; use `appstore launch` or host `pear run` for full Pear runtime |
+| `app.bundle.js` launch | Launch prefers `sources/<main>`; compiled bundles need a future guest evaluator |
+| Remote fetch | Requires HDMS + swarm; may time out if the release was never seeded |
+| Kernel extensions via store | Gated / partial; see design doc |

docs/reference/feature-roadmap.md

@@ -855,13 +855,13 @@ See the full design at [docs/design/p2p-app-store.md](../../docs/design/p2p-app-
 
 | # | Item | Status |
 | ---: | --- | --- |
-| 1 | App Store drive convention + HDMS label `appstore` + basic registry schema v1 | planned |
+| 1 | App Store drive convention + HDMS label `appstore` + basic registry schema v1 | done |
-| 2 | `/bin/appstore` skeleton (list, info, search via pkg-swarm-index) | planned |
+| 2 | `/bin/appstore` (list, info, search, install, launch, update, setup) | done |
-| 3 | New agent skill `skills/appstore/SKILL.md` (discovery + safe install guidance) | planned |
+| 3 | Agent skill `skills/appstore/SKILL.md` | done |
-| 4 | HDMS auto-mount of appstore drive on session/login | planned |
+| 4 | HDMS auto-mount of appstore drive on session/login | partial — manual `hdms create appstore` |
-| 5 | Full user-app install flow (manifest resolution + materialization into store drive) | planned |
+| 5 | Full user-app install flow (manifest + pear:// materialization) | done — `appstore-pear.js` |
-| 6 | Service manifest + automatic initd unit generation from installed packages | planned |
+| 6 | Service manifest + automatic initd unit generation | partial — `appstore services` |
-| 7 | `appstore launch` + integration with existing Pear/appctl/peerctl paths | planned |
+| 7 | `appstore launch` (in-guest script execution) | done |
 | 8 | Signed extension manifest format + verification for store-sourced kernel extensions | planned |
 | 9 | Gated `appstore install --kernel-ext` + boot policy fields (pins, review status) | planned |
 | 10 | Appstore-sourced extensions loaded with distinct source tag + audit trail | planned |
@@ -880,13 +880,13 @@ This thread delivers the ability to create, stage, release, and seed real Pear a
 | ---: | --- | --- |
 | 1 | Add `pearEntries` tier to manifest + parallel loading in booter (`loadPearModuleManifest`) | done |
 | 2 | `buildPearCtxObjectFromHost` + `ctx.pear` exposure on guest context | done |
-| 3 | `/bin/pear` skeleton command (info, list, basic stage stub) + man page | done |
+| 3 | `/bin/pear` command (info, list, init, stage, release, seed) + man page | done |
-| 4 | `pear-dev` agent skill (autonomous Pear dev workflows) + seed list update | done |
+| 4 | `pear-dev` agent skill + seed list | done |
-| 5 | Cross-skill integration: `pear-dev` + `appstore` skills recognize each other | done |
+| 5 | Cross-skill integration: `pear-dev` + `appstore` | done |
-| 6 | Richer `/bin/pear` subcommands (`init`, `stage` awareness, basic bundle hooks) | done |
+| 6 | Guest `pear stage` (VFS `.pear/stage/`, bare-pack + compile) | done |
-| 7 | Host delegate strategy for heavy Pear operations (sidecar IPC, signing, seeding) | planned |
+| 7 | Host delegate for heavy Pear ops (optional; guest release is primary) | partial |
-| 8 | HDMS convention for `pear-dev` drive (parallel to `appstore` label) | planned |
+| 8 | HDMS convention for `pear-dev` drive (parallel to `appstore` label) | partial — `pear-<name>` on release |
-| 9 | `pear release` / `pear seed` that can target App Store drives or direct swarms | planned |
+| 9 | Guest `pear release` / `pear seed` (HDMS + pear:// links) | done |
 | 10 | Full verification, Batch D roadmap items, zero-TODO polish, agent-assisted review | planned |
 
 ### Other Themes (to be expanded)

handbook/07-operations-and-development.md

@@ -183,9 +183,11 @@ These run **`scripts/ensure-pear-node-modules.mjs`** first so Pear’s module re
 
 ## Pear channels, staging, and `pear://` links
 
-After **`pear stage`** / **`pear release`**, Pear prints a `**pear://…`** link per app. Consumers normally run **those** keys—not arbitrary git checkouts—unless they use dev mode **`pear run --dev .`**.
+**Host (booter/seeder):** After **`pear stage`** / **`pear release`** on the host, Pear prints a **`pear://…`** link per app. Consumers run those keys with host **`pear run`**, or use dev mode **`pear run --dev .`**.
 
-**Concrete keys and re-staging steps** (seeder/booter channels, versioned links, host env for OTA): **[PEAR-RUN.md](../docs/PEAR-RUN.md)**. That file also documents **`BARE_OS_PEAR_*`**, HTTP allow/deny lists, TLS pin env vars, and **`ctx.bare`** toggles mirrored from the host.
+**Guest (booted shell):** Use **`/bin/pear`** to stage and release user apps, then **`/bin/appstore`** to install and launch — no host Pear CLI required. See **[guides/guest-pear-and-appstore-workflow.md](../docs/guides/guest-pear-and-appstore-workflow.md)**.
+
+**Concrete keys and re-staging steps** (seeder/booter channels, versioned links, host env for OTA): **[PEAR-RUN.md](../docs/PEAR-RUN.md)**.
 
 **OTA-shaped flow (doc contract):** Pear’s channel / release metadata on the host pairs with **`BARE_OS_PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`**, and optional **`ctx.bareOsPearUpdaterDelegate()`** (async) when **`BARE_OS_PEAR_UPDATER_MODULE`** or **`BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON`** is set—see [developer-guide ch.11 — Pear workflows](../developer-guide/11-kernel-pear-cookbook.md). **`ctx.bareOsSystemRevision`** exposes **`id`**, **`pending`**, and **`slot`** for guest policy; **`/etc/bare-os/boot.policy.json`** rollback fields and boot markers (**`BARE_OS_BOOT_ROLLBACK_APPLY`**, **`BARE_OS_SYSTEM_REVISION_PENDING`**) gate whether a newer system key is adopted after the next boot.
 

kernel/etc/bare-os/posix_utilities.json

@@ -1,7 +1,7 @@
 {
   "schema": 2,
   "profileId": "bare-os-posix-like",
-  "generatedAt": "2026-05-26T23:42:58.195Z",
+  "generatedAt": "2026-05-26T23:57:42.108Z",
   "note": "Sparse POSIX Issue 7 coverage hints; commandIndex is generated each coreutils build.",
   "commandIndex": [
     {

kernel/lib/bare/manifest.json

@@ -1,18 +1,18 @@
 {
   "version": 1,
   "bundles": [
-    {
-      "path": "/lib/bare/bundles/safetyCatch.js",
-      "keys": [
-        "safetyCatch"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/b4a.js",
       "keys": [
         "b4a"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/safetyCatch.js",
+      "keys": [
+        "safetyCatch"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/hypercoreIdEncoding.js",
       "keys": [
@@ -37,12 +37,6 @@
         "bareEncoding"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/barePath.js",
-      "keys": [
-        "barePath"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareEvents.js",
       "keys": [
@@ -55,6 +49,12 @@
         "protomux"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/barePath.js",
+      "keys": [
+        "barePath"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareAbort.js",
       "keys": [
@@ -85,12 +85,6 @@
         "bareAppKit"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareReadline.js",
-      "keys": [
-        "bareReadline"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareCrypto.js",
       "keys": [
@@ -98,27 +92,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareAsyncHooks.js",
+      "path": "/lib/bare/bundles/bareReadline.js",
       "keys": [
-        "bareAsyncHooks"
+        "bareReadline"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/fetch.js",
-      "keys": [
-        "fetch"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/bareBmp.js",
-      "keys": [
-        "bareBmp"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/bareAtomics.js",
-      "keys": [
-        "bareAtomics"
       ]
     },
     {
@@ -128,9 +104,27 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareBundleCompile.js",
+      "path": "/lib/bare/bundles/fetch.js",
       "keys": [
-        "bareBundleCompile"
+        "fetch"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/bareAsyncHooks.js",
+      "keys": [
+        "bareAsyncHooks"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/bareAtomics.js",
+      "keys": [
+        "bareAtomics"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/bareBmp.js",
+      "keys": [
+        "bareBmp"
       ]
     },
     {
@@ -139,6 +133,12 @@
         "bareBundle"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareBundleCompile.js",
+      "keys": [
+        "bareBundleCompile"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareBuffer.js",
       "keys": [
@@ -175,24 +175,30 @@
         "bareBoot"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareBundleEvaluate.js",
-      "keys": [
-        "bareBundleEvaluate"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareDebugLog.js",
       "keys": [
         "bareDebugLog"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareBundleEvaluate.js",
+      "keys": [
+        "bareBundleEvaluate"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareDelta.js",
       "keys": [
         "bareDelta"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareCov.js",
+      "keys": [
+        "bareCov"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareDiagnosticsChannel.js",
       "keys": [
@@ -200,9 +206,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareCov.js",
+      "path": "/lib/bare/bundles/bareBundleId.js",
       "keys": [
-        "bareCov"
+        "bareBundleId"
       ]
     },
     {
@@ -217,24 +223,12 @@
         "bareEnv"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareBundleId.js",
-      "keys": [
-        "bareBundleId"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareExif.js",
       "keys": [
         "bareExif"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareDaemon.js",
-      "keys": [
-        "bareDaemon"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareFfmpeg.js",
       "keys": [
@@ -253,6 +247,12 @@
         "bareDgram"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareDaemon.js",
+      "keys": [
+        "bareDaemon"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareGif.js",
       "keys": [
@@ -265,30 +265,30 @@
         "bareFormat"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareFormData.js",
-      "keys": [
-        "bareFormData"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareHeif.js",
       "keys": [
         "bareHeif"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareHrtime.js",
-      "keys": [
-        "bareHrtime"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareGtk.js",
       "keys": [
         "bareGtk"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareFormData.js",
+      "keys": [
+        "bareFormData"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/bareHrtime.js",
+      "keys": [
+        "bareHrtime"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareFileLogger.js",
       "keys": [
@@ -301,18 +301,18 @@
         "bareHttpParser"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareIco.js",
-      "keys": [
-        "bareIco"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareFs.js",
       "keys": [
         "bareFs"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareIco.js",
+      "keys": [
+        "bareIco"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareImageResample.js",
       "keys": [
@@ -331,18 +331,18 @@
         "bareInspect"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareHttps.js",
-      "keys": [
-        "bareHttps"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareJpeg.js",
       "keys": [
         "bareJpeg"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareHttps.js",
+      "keys": [
+        "bareHttps"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareIntl.js",
       "keys": [
@@ -385,6 +385,12 @@
         "bareLink"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareMake.js",
+      "keys": [
+        "bareMake"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareModuleResolve.js",
       "keys": [
@@ -392,9 +398,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareMake.js",
+      "path": "/lib/bare/bundles/bareNdk.js",
       "keys": [
-        "bareMake"
+        "bareNdk"
       ]
     },
     {
@@ -409,12 +415,6 @@
         "bareMedia"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareNdk.js",
-      "keys": [
-        "bareNdk"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareNodeFetch.js",
       "keys": [
@@ -422,9 +422,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareModuleLexer.js",
+      "path": "/lib/bare/bundles/bareModule.js",
       "keys": [
-        "bareModuleLexer"
+        "bareModule"
       ]
     },
     {
@@ -434,9 +434,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareModule.js",
+      "path": "/lib/bare/bundles/bareModuleLexer.js",
       "keys": [
-        "bareModule"
+        "bareModuleLexer"
       ]
     },
     {
@@ -481,42 +481,42 @@
         "bareNodeRuntime"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/barePack.js",
-      "keys": [
-        "barePack"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/barePunycode.js",
       "keys": [
         "barePunycode"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareProcess.js",
-      "keys": [
-        "bareProcess"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/barePackDrive.js",
-      "keys": [
-        "barePackDrive"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareQuerystring.js",
       "keys": [
         "bareQuerystring"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareProcess.js",
+      "keys": [
+        "bareProcess"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/barePack.js",
+      "keys": [
+        "barePack"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/barePrebuild.js",
       "keys": [
         "barePrebuild"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/barePackDrive.js",
+      "keys": [
+        "barePackDrive"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareQueueMicrotask.js",
       "keys": [
@@ -541,6 +541,12 @@
         "bareSdl"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/barePromClient.js",
+      "keys": [
+        "barePromClient"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareSemver.js",
       "keys": [
@@ -559,12 +565,6 @@
         "bareSignals"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/barePromClient.js",
-      "keys": [
-        "barePromClient"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareRepl.js",
       "keys": [
@@ -607,12 +607,6 @@
         "bareSvg"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareSystemLogger.js",
-      "keys": [
-        "bareSystemLogger"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareStorage.js",
       "keys": [
@@ -626,9 +620,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareStructuredClone.js",
+      "path": "/lib/bare/bundles/bareSystemLogger.js",
       "keys": [
-        "bareStructuredClone"
+        "bareSystemLogger"
       ]
     },
     {
@@ -638,9 +632,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareSubprocess.js",
+      "path": "/lib/bare/bundles/bareStructuredClone.js",
       "keys": [
-        "bareSubprocess"
+        "bareStructuredClone"
       ]
     },
     {
@@ -649,6 +643,12 @@
         "bareTimers"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareSubprocess.js",
+      "keys": [
+        "bareSubprocess"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareTpl.js",
       "keys": [
@@ -679,24 +679,30 @@
         "bareTls"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareTty.js",
-      "keys": [
-        "bareTty"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareUnpack.js",
       "keys": [
         "bareUnpack"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareTty.js",
+      "keys": [
+        "bareTty"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareV8.js",
       "keys": [
         "bareV8"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareThread.js",
+      "keys": [
+        "bareThread"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareVm.js",
       "keys": [
@@ -710,9 +716,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareThread.js",
+      "path": "/lib/bare/bundles/bareWebp.js",
       "keys": [
-        "bareThread"
+        "bareWebp"
       ]
     },
     {
@@ -721,18 +727,6 @@
         "bareWebKit"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareUnionBundle.js",
-      "keys": [
-        "bareUnionBundle"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/bareWebp.js",
-      "keys": [
-        "bareWebp"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareWebKitGtk.js",
       "keys": [
@@ -746,9 +740,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareV8ToIstanbul.js",
+      "path": "/lib/bare/bundles/bareUnionBundle.js",
       "keys": [
-        "bareV8ToIstanbul"
+        "bareUnionBundle"
       ]
     },
     {
@@ -757,6 +751,12 @@
         "bareWinUi"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareV8ToIstanbul.js",
+      "keys": [
+        "bareV8ToIstanbul"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareXdiff.js",
       "keys": [
@@ -764,9 +764,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareZlib.js",
+      "path": "/lib/bare/bundles/bareWhich.js",
       "keys": [
-        "bareZlib"
+        "bareWhich"
       ]
     },
     {
@@ -776,15 +776,15 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareZmq.js",
+      "path": "/lib/bare/bundles/bareZlib.js",
       "keys": [
-        "bareZmq"
+        "bareZlib"
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareWhich.js",
+      "path": "/lib/bare/bundles/bareZmq.js",
       "keys": [
-        "bareWhich"
+        "bareZmq"
       ]
     },
     {
@@ -1740,8 +1740,8 @@
   ],
   "bundleProvenance": {
     "schemaVersion": 1,
-    "generatedAt": "2026-05-26T23:43:00.338Z",
+    "generatedAt": "2026-05-26T23:57:44.184Z",
-    "gitCommit": "ab3f0916711cbabb5268e8dd8be1c58041138886",
+    "gitCommit": "21580f21bc3817ae8d39640fe07f948af2c32308",
     "nodeVersion": "v20.19.4",
     "bundleTier": "all",
     "normativeManifest": "packages/bare-os-booter/lib/bare-module-manifest.json",

kernel/lib/bare/shell-completion.json

@@ -1,6 +1,6 @@
 {
   "schema": 1,
-  "atMs": 1779838978194,
+  "atMs": 1779839862107,
   "commands": [
     "agent",
     "appctl",

kernel/share/agent-workspace/skills/appstore/SKILL.md

@@ -1,135 +1,76 @@
 ---
 name: appstore
-version: 0.1.0
+version: 0.2.0
-description: Discover, review, and install packages from the P2P App Store into the user's appstore HDMS drive. Supports user apps, services, and (gated) kernel extensions.
+description: Discover, install, launch, and update P2P packages from pear:// links. Real HDMS/VFS materialization and in-guest launch.
-tags: [appstore, p2p, hdms, packages, extensions]
+tags: [appstore, p2p, hdms, packages, extensions, pear]
 requires: [read_skill, read_proc_file, run_command, vfs]
 ---
 
 # appstore Skill
 
 ## When to use
-Use when the user wants to explore or install applications, services, or kernel extensions from the P2P App Store.
 
-The feature is production-complete after a 50-round autonomous polish sprint. All core flows are fully supported.
+Use when the user wants to install, launch, update, or manage packages from the P2P App Store — especially Pear apps published with `pear release`.
 
 ## Core concepts
-- **App Store Drive**: A dedicated HDMS-mounted Hyperdrive (default label: `appstore`, mounted at `/mnt/appstore`).
-- **Registry**: `~/.appstore/registry.json` (or the drive's registry) tracks installed packages.
-- **Package Types**:
-  - `app` — Normal user applications
-  - `service` — Long-running services (may create initd units)
-  - `kernel-ext` — High-trust kernel extensions (requires explicit approval + policy)
 
-## Recommended workflow
+- **App Store drive** — Optional HDMS label `appstore` at `/mnt/appstore`; falls back to `~/.appstore/`.
-1. Use `run_command` with `appstore list` or `appstore info <name>` to inspect the local store.
+- **Registry** — `registry.json` lists installed packages and `pearLink` values.
-2. For discovery, the future `appstore search` will use the P2P index (`pkg-swarm-index`).
+- **Materialization** — `lib/appstore-pear.js` copies the release tree into `packages/<name>/` (from local HDMS mount or ephemeral readonly fetch).
-3. When suggesting installation:
+- **Launch** — Runs `sources/<main>` in the guest shell (output on `ctx.console`).
-   - Clearly distinguish between `app`/`service` vs `kernel-ext`.
-   - For kernel extensions, **strongly warn** the user and reference the trust model in the design doc.
-4. After any conceptual install, remind the user to run `appstore list` to verify.
 
-## Safety rules
+## End-to-end flow (with pear-dev)
-- Never suggest installing a `kernel-ext` without explicit user confirmation and review of the manifest.
-- Kernel extensions from the store must be signed and are subject to boot policy.
-- Prefer reading live state via `read_proc_file /proc/bare_os/appstore.json` (when it exists) over static docs.
 
-## Current State (Production-Ready)
+```bash
-The App Store feature is complete and production-ready after a 50-round autonomous polish sprint.
+pear init && pear stage && pear release . && pear seed .
-- Full install/uninstall/launch/update flows with rich materialization.
+appstore install my-app pear://0.<length>.<key> --yes
-- Strong HDMS preference with excellent fallback UX.
+appstore launch my-app
-- Gated but fully supported kernel extension path.
+```
-- Service unit generation.
-- Deep agent autonomy with multi-step workflows.
-- No remaining limitations in day-to-day usage.
 
-## Practical agent usage examples
+Requires **login** for HDMS when fetching remote keys.
+
+## Practical commands
 
-**Check what's installed:**
 ```
 run_command "appstore list"
+run_command "appstore info my-pear-app"
+run_command "appstore install my-pear-app pear://0.10.<key> --yes"
+run_command "appstore launch my-pear-app"
+run_command "appstore update my-pear-app"
+run_command "appstore setup"
 ```
 
-**Inspect a specific package:**
+## Safety rules
-```
-run_command "appstore info simple-file-share"
-```
 
-**Install a package (with confirmation):**
+- Never install `kernel-ext` without explicit user approval and design-doc review.
-```
+- Always pass **`--yes`** on install when the user confirmed.
-run_command "appstore install my-p2p-app --yes"
+- After install, suggest **`appstore launch`** to verify behavior.
-```
+- If install fails on fetch, ensure user ran **`pear seed`** and is **logged in**.
 
-**Install from explicit P2P link (copies release tree from HDMS / swarm):**
+## Current behavior (May 2026)
-```
-run_command "appstore install my-p2p-app pear://0.<length>.<key> --yes"
-```
 
-**Launch (runs sources/index.js in the guest shell — prints app output):**
+| Command | Behavior |
-```
+| --- | --- |
-run_command "appstore launch my-p2p-app"
+| `install` | Fetches pear:// tree into package dir; reports file count + method |
-```
+| `launch` | Executes materialized `sources/index.js` (or `main`) in guest |
+| `update` | Re-runs materialization from stored `pearLink` |
+| `search` | Delegates to `pkg-swarm-index` (best-effort) |
 
-**Refresh after a new pear release:**
+**Limitations:** No guest `pear run` for full Pear desktop runtime; launch uses source entry, not `app.bundle.js` alone.
-```
-run_command "appstore update my-p2p-app"
-```
 
-**When user asks to install something:**
+## HDMS notes
-1. Use `run_command "appstore info <name>"` if it exists locally.
-2. Warn clearly if it's a `kernel-ext` type (high trust, requires review and policy).
-3. For kernel-ext, strongly recommend reading the design doc and getting user explicit approval.
-4. After install, run `appstore list` to confirm.
-5. Suggest `appstore launch <name>` to run it.
-6. For full HDMS experience, suggest using `hdms` or `appstore setup`.
 
-**HDMS integration notes:**
+- Prefer `/mnt/appstore` when label `appstore` is mounted (`appstore setup` for instructions).
-- The App Store strongly prefers a drive mounted at `/mnt/appstore` (label `appstore` via HDMS).
+- Pear release drives (`pear-<app-name>`) are reused automatically when the `pear://` key matches.
-- Tell users to run `appstore setup` — it prints clear instructions and the exact HDMS commands they need.
-- Current behavior gracefully falls back to personal `~/.appstore/` when no HDMS drive is mounted.
-- Once the user mounts the drive with the correct label, `appstore` commands will prefer it automatically.
-
-**10-Round Autonomous Sprint Completed:**
-Major progress delivered across the sprint:
-- HDMS detection and strong preference (Round 1)
-- Rich materialization with launcher stubs (Round 2)
-- Service unit scaffolding (Round 3)
-- Gated kernel-ext installation path with warnings (Round 4)
-- This skill now supports multi-step autonomous workflows (Round 5)
-- Improved launch + basic update/refresh (Round 6)
-- Better error handling and UX messaging (Round 7)
-- Documentation and design updates (Round 8)
-- Deeper P2P index awareness (Round 9)
-- Full verification and sprint closure (Round 10)
-
-**Multi-step autonomous workflows the agent can now execute:**
-1. Run `appstore setup` and guide the user on HDMS drive creation/mount.
-2. Use `appstore search` + `info` to evaluate packages.
-3. For normal apps: recommend + perform safe install with --yes after user confirmation.
-4. For services: install + remind about potential initd generation.
-5. For kernel-ext: **never proceed without explicit user approval** + require reading the trust model.
-6. After install, offer `appstore launch` or `list`.
-7. Use `appstore update` for refresh when appropriate.
-8. Always surface whether the real HDMS drive or personal fallback is being used.
-
-The agent treats the App Store as a first-class, governed extension mechanism for the OS.
 
 ## Related skills
-- `hdms` — for manual drive mounting if needed
-- `kernel-program-extension` — if the package touches kernel extensions or boot policy
-- `bareos-code-change` — when modifying appstore-related code
-- `pear-dev` — **new** (2026): Author real Pear applications using `ctx.pear` + `/bin/pear`, then publish them into the App Store (pear:// materialization + launch). Use together for full "create Pear app → stage → install to my App Store" autonomous flows.
 
-## Pear App Synergy (New Capability)
+- **`pear-dev`** — Author and release Pear apps (`/bin/pear`)
+- **`hdms`** — Drive mounts
+- **`kernel-program-extension`** — Kernel extensions from store
 
-Pear apps are now a natural fit for the App Store:
+## References
-- Use the `pear-dev` skill to create and stage real Pear applications inside Bare OS (via the new `ctx.pear` surface and `/bin/pear`).
-- Once staged, treat them as normal `app` type packages for `appstore install` (they can be launched via Pear primitives or the App Store launch mechanism).
-- The combination of `pear-dev` + `appstore` skills gives the agent the ability to help users build and distribute their own P2P Pear software entirely from within the OS.
 
-When a user says "I want to make a new P2P notes app", the correct combined workflow is:
+- `docs/guides/guest-pear-and-appstore-workflow.md`
-1. Use `pear-dev` skill to guide creation + staging.
+- `docs/design/p2p-app-store.md`
-2. Use `appstore` skill to publish the result into the user's personal HDMS App Store.
+- `packages/bare-os-coreutils/lib/appstore-pear.js`
-3. Later users can discover/install it via normal App Store flows.
-
-This is one of the major end goals of the ctx.pear work.

packages/bare-os-booter/lib/hdms-manager.js

@@ -860,6 +860,15 @@ export class HdmsController {
     })
     await this.autopass.ready()
     attachAutopassReplicateOnce(this.swarm, () => this.autopass?.base)
+    try {
+      this.autopass.on('error', (err) => {
+        bareOsHostBooterWarn(
+          'hdms_autopass',
+          'Autopass error',
+          err?.message || String(err)
+        )
+      })
+    } catch (_) {}
   }
 }
 

packages/bare-os-booter/lib/hdms-share-offer.js

@@ -36,11 +36,15 @@ export function writerSecretBytesFromHex(hex) {
   return b4a.from(normalizeWriterSecretHex(hex), 'hex')
 }
 
-/** @param {{ remove: (k: string) => Promise<unknown> }} ap */
+/** @param {{ remove: (k: string) => Promise<unknown>, member?: { flushed: () => Promise<void> }, base?: { update?: () => Promise<void> } }} ap */
 export async function removeBothHdmsShareKeys(ap) {
   for (const k of [HDMS_AUTOPASS_SHARE_KEY, HDMS_AUTOPASS_SHARE_RW_KEY]) {
     try {
       await ap.remove(k)
+      if (ap.member) await ap.member.flushed()
+      try {
+        await ap.base?.update?.()
+      } catch (_) {}
     } catch {
       /* no prior offer */
     }

packages/bare-os-booter/test.js

@@ -3466,6 +3466,21 @@ test('hdms-share-offer decodeRwShareOffer and normalizeWriterSecretHex', async (
   t.is(decodeRwShareOffer({ value: '{"label":"x","key":"y","writerSecretHex":"' + hex + '"}' }), null)
 })
 
+test('autopass hyperdb legacy value header (type byte omitted)', async (t) => {
+  const db = require('autopass/spec/db')
+  const records = db.collections[0]
+  const keyBuf = records.encodeKey({ key: 'bare-os-hdms/pending-share' })
+  const valueBuf = records.encodeValue(1, 1, {
+    key: 'bare-os-hdms/pending-share',
+    value: '{"label":"x","key":"y"}',
+    file: null
+  })
+  t.ok(records.reconstruct(1, keyBuf, valueBuf))
+  const legacyHeader = Buffer.from(valueBuf)
+  legacyHeader[0] = 1
+  t.ok(records.reconstruct(1, keyBuf, legacyHeader))
+})
+
 test('parseHdmsPairArgv flags and invite token', async (t) => {
   t.alike(parseHdmsPairArgv(['--no-persist', 'invitez32']), {
     ok: true,

packages/bare-os-coreutils/README.md

@@ -7,7 +7,7 @@
 
 **When to use:** run **`npm run build -w bare-os-coreutils`** whenever you change **`src/*.js`**, **`lib/commands.mjs`**, or **`man/pages/*`** so **`kernel/bin/*`** and **`man.json`** stay in sync before **`pretest`** or **`pear run`**.
 
-**Documentation:** [Concepts — POSIX](../../docs/concepts/posix-stance.md) · [Developer guide — extending `/bin`](../../developer-guide/06-extending-bin-coreutils.md) · [Coreutils reference](../../docs/reference/package-bare-os-coreutils-and-ci.md) · [Handbook ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md).
+**Documentation:** [Concepts — POSIX](../../docs/concepts/posix-stance.md) · [Developer guide — extending `/bin`](../../developer-guide/06-extending-bin-coreutils.md) · [Coreutils reference](../../docs/reference/package-bare-os-coreutils-and-ci.md) · [Handbook ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) · [Guest Pear + App Store](../../docs/guides/guest-pear-and-appstore-workflow.md) (`pear`, `appstore` preambles: `pear-stage.js`, `pear-release.js`, `appstore-pear.js`).
 
 ## Command contract
 

packages/bare-os-coreutils/man/pages/appstore.json

@@ -3,13 +3,18 @@
   "section": 1,
   "title": "appstore",
   "synopsis": [
-    "appstore [OPTION]... [OPERAND]..."
+    "appstore list | info NAME | install NAME pear://LINK --yes",
+    "appstore launch NAME | update NAME | uninstall NAME",
+    "appstore setup | search [query] | services [NAME]"
   ],
-  "description": "Bare OS implementation of appstore. Full behavior is defined in packages/bare-os-coreutils/src/appstore.js.",
+  "description": "P2P App Store client for Bare OS. Installs packages from pear:// links by copying the release Hyperdrive tree into ~/.appstore/packages/ (or /mnt/appstore when the appstore HDMS drive is mounted). install uses lib/appstore-pear.js: prefers a local HDMS mount with the same key, otherwise opens an ephemeral readonly HDMS mount and mirrors files over VFS. launch runs the materialized entry script (package.json main, usually sources/index.js) in the guest shell via ctx.console. Requires login for remote pear:// fetch. See docs/guides/guest-pear-and-appstore-workflow.md.",
   "options": [],
   "keywords": [
     "appstore",
     "bare-os",
-    "coreutils"
+    "coreutils",
+    "pear",
+    "p2p",
+    "hdms"
   ]
 }

packages/bare-os-coreutils/man/pages/pear.json

@@ -3,15 +3,20 @@
   "section": 1,
   "title": "pear",
   "synopsis": [
-    "pear [OPTION]... [SUBCOMMAND]..."
+    "pear help | info | list | init [dir]",
+    "pear stage [dir] | build [dir] | bundle [dir]",
+    "pear release [dir] [--label HDMS-LABEL]",
+    "pear seed [dir] [--wait-ms N]"
   ],
-  "description": "Pear development tools inside Bare OS (ctx.pear surface). Full behavior is defined in packages/bare-os-coreutils/src/pear.js.",
+  "description": "Pear development tools inside Bare OS (ctx.pear surface). init scaffolds a project; stage writes .pear/stage/ (sources, bundles, stage.json) using ctx.pear/ctx.bare pack tools when enabled; release publishes the stage tree to a writable HDMS mount and prints pear:// links (no host Pear CLI required); seed flushes Hyperswarm for the release drive. Requires identity unlock (login) for release/seed. Implementation: packages/bare-os-coreutils/src/pear.js, lib/pear-stage.js, lib/pear-release.js. See docs/guides/guest-pear-and-appstore-workflow.md.",
   "options": [],
   "keywords": [
     "pear",
     "bare-os",
     "coreutils",
     "p2p",
-    "build"
+    "build",
+    "release",
+    "hdms"
   ]
 }

packages/bare-os-coreutils/share/agent-workspace/skills/appstore/SKILL.md

@@ -1,135 +1,76 @@
 ---
 name: appstore
-version: 0.1.0
+version: 0.2.0
-description: Discover, review, and install packages from the P2P App Store into the user's appstore HDMS drive. Supports user apps, services, and (gated) kernel extensions.
+description: Discover, install, launch, and update P2P packages from pear:// links. Real HDMS/VFS materialization and in-guest launch.
-tags: [appstore, p2p, hdms, packages, extensions]
+tags: [appstore, p2p, hdms, packages, extensions, pear]
 requires: [read_skill, read_proc_file, run_command, vfs]
 ---
 
 # appstore Skill
 
 ## When to use
-Use when the user wants to explore or install applications, services, or kernel extensions from the P2P App Store.
 
-The feature is production-complete after a 50-round autonomous polish sprint. All core flows are fully supported.
+Use when the user wants to install, launch, update, or manage packages from the P2P App Store — especially Pear apps published with `pear release`.
 
 ## Core concepts
-- **App Store Drive**: A dedicated HDMS-mounted Hyperdrive (default label: `appstore`, mounted at `/mnt/appstore`).
-- **Registry**: `~/.appstore/registry.json` (or the drive's registry) tracks installed packages.
-- **Package Types**:
-  - `app` — Normal user applications
-  - `service` — Long-running services (may create initd units)
-  - `kernel-ext` — High-trust kernel extensions (requires explicit approval + policy)
 
-## Recommended workflow
+- **App Store drive** — Optional HDMS label `appstore` at `/mnt/appstore`; falls back to `~/.appstore/`.
-1. Use `run_command` with `appstore list` or `appstore info <name>` to inspect the local store.
+- **Registry** — `registry.json` lists installed packages and `pearLink` values.
-2. For discovery, the future `appstore search` will use the P2P index (`pkg-swarm-index`).
+- **Materialization** — `lib/appstore-pear.js` copies the release tree into `packages/<name>/` (from local HDMS mount or ephemeral readonly fetch).
-3. When suggesting installation:
+- **Launch** — Runs `sources/<main>` in the guest shell (output on `ctx.console`).
-   - Clearly distinguish between `app`/`service` vs `kernel-ext`.
-   - For kernel extensions, **strongly warn** the user and reference the trust model in the design doc.
-4. After any conceptual install, remind the user to run `appstore list` to verify.
 
-## Safety rules
+## End-to-end flow (with pear-dev)
-- Never suggest installing a `kernel-ext` without explicit user confirmation and review of the manifest.
-- Kernel extensions from the store must be signed and are subject to boot policy.
-- Prefer reading live state via `read_proc_file /proc/bare_os/appstore.json` (when it exists) over static docs.
 
-## Current State (Production-Ready)
+```bash
-The App Store feature is complete and production-ready after a 50-round autonomous polish sprint.
+pear init && pear stage && pear release . && pear seed .
-- Full install/uninstall/launch/update flows with rich materialization.
+appstore install my-app pear://0.<length>.<key> --yes
-- Strong HDMS preference with excellent fallback UX.
+appstore launch my-app
-- Gated but fully supported kernel extension path.
+```
-- Service unit generation.
-- Deep agent autonomy with multi-step workflows.
-- No remaining limitations in day-to-day usage.
 
-## Practical agent usage examples
+Requires **login** for HDMS when fetching remote keys.
+
+## Practical commands
 
-**Check what's installed:**
 ```
 run_command "appstore list"
+run_command "appstore info my-pear-app"
+run_command "appstore install my-pear-app pear://0.10.<key> --yes"
+run_command "appstore launch my-pear-app"
+run_command "appstore update my-pear-app"
+run_command "appstore setup"
 ```
 
-**Inspect a specific package:**
+## Safety rules
-```
-run_command "appstore info simple-file-share"
-```
 
-**Install a package (with confirmation):**
+- Never install `kernel-ext` without explicit user approval and design-doc review.
-```
+- Always pass **`--yes`** on install when the user confirmed.
-run_command "appstore install my-p2p-app --yes"
+- After install, suggest **`appstore launch`** to verify behavior.
-```
+- If install fails on fetch, ensure user ran **`pear seed`** and is **logged in**.
 
-**Install from explicit P2P link (copies release tree from HDMS / swarm):**
+## Current behavior (May 2026)
-```
-run_command "appstore install my-p2p-app pear://0.<length>.<key> --yes"
-```
 
-**Launch (runs sources/index.js in the guest shell — prints app output):**
+| Command | Behavior |
-```
+| --- | --- |
-run_command "appstore launch my-p2p-app"
+| `install` | Fetches pear:// tree into package dir; reports file count + method |
-```
+| `launch` | Executes materialized `sources/index.js` (or `main`) in guest |
+| `update` | Re-runs materialization from stored `pearLink` |
+| `search` | Delegates to `pkg-swarm-index` (best-effort) |
 
-**Refresh after a new pear release:**
+**Limitations:** No guest `pear run` for full Pear desktop runtime; launch uses source entry, not `app.bundle.js` alone.
-```
-run_command "appstore update my-p2p-app"
-```
 
-**When user asks to install something:**
+## HDMS notes
-1. Use `run_command "appstore info <name>"` if it exists locally.
-2. Warn clearly if it's a `kernel-ext` type (high trust, requires review and policy).
-3. For kernel-ext, strongly recommend reading the design doc and getting user explicit approval.
-4. After install, run `appstore list` to confirm.
-5. Suggest `appstore launch <name>` to run it.
-6. For full HDMS experience, suggest using `hdms` or `appstore setup`.
 
-**HDMS integration notes:**
+- Prefer `/mnt/appstore` when label `appstore` is mounted (`appstore setup` for instructions).
-- The App Store strongly prefers a drive mounted at `/mnt/appstore` (label `appstore` via HDMS).
+- Pear release drives (`pear-<app-name>`) are reused automatically when the `pear://` key matches.
-- Tell users to run `appstore setup` — it prints clear instructions and the exact HDMS commands they need.
-- Current behavior gracefully falls back to personal `~/.appstore/` when no HDMS drive is mounted.
-- Once the user mounts the drive with the correct label, `appstore` commands will prefer it automatically.
-
-**10-Round Autonomous Sprint Completed:**
-Major progress delivered across the sprint:
-- HDMS detection and strong preference (Round 1)
-- Rich materialization with launcher stubs (Round 2)
-- Service unit scaffolding (Round 3)
-- Gated kernel-ext installation path with warnings (Round 4)
-- This skill now supports multi-step autonomous workflows (Round 5)
-- Improved launch + basic update/refresh (Round 6)
-- Better error handling and UX messaging (Round 7)
-- Documentation and design updates (Round 8)
-- Deeper P2P index awareness (Round 9)
-- Full verification and sprint closure (Round 10)
-
-**Multi-step autonomous workflows the agent can now execute:**
-1. Run `appstore setup` and guide the user on HDMS drive creation/mount.
-2. Use `appstore search` + `info` to evaluate packages.
-3. For normal apps: recommend + perform safe install with --yes after user confirmation.
-4. For services: install + remind about potential initd generation.
-5. For kernel-ext: **never proceed without explicit user approval** + require reading the trust model.
-6. After install, offer `appstore launch` or `list`.
-7. Use `appstore update` for refresh when appropriate.
-8. Always surface whether the real HDMS drive or personal fallback is being used.
-
-The agent treats the App Store as a first-class, governed extension mechanism for the OS.
 
 ## Related skills
-- `hdms` — for manual drive mounting if needed
-- `kernel-program-extension` — if the package touches kernel extensions or boot policy
-- `bareos-code-change` — when modifying appstore-related code
-- `pear-dev` — **new** (2026): Author real Pear applications using `ctx.pear` + `/bin/pear`, then publish them into the App Store (pear:// materialization + launch). Use together for full "create Pear app → stage → install to my App Store" autonomous flows.
 
-## Pear App Synergy (New Capability)
+- **`pear-dev`** — Author and release Pear apps (`/bin/pear`)
+- **`hdms`** — Drive mounts
+- **`kernel-program-extension`** — Kernel extensions from store
 
-Pear apps are now a natural fit for the App Store:
+## References
-- Use the `pear-dev` skill to create and stage real Pear applications inside Bare OS (via the new `ctx.pear` surface and `/bin/pear`).
-- Once staged, treat them as normal `app` type packages for `appstore install` (they can be launched via Pear primitives or the App Store launch mechanism).
-- The combination of `pear-dev` + `appstore` skills gives the agent the ability to help users build and distribute their own P2P Pear software entirely from within the OS.
 
-When a user says "I want to make a new P2P notes app", the correct combined workflow is:
+- `docs/guides/guest-pear-and-appstore-workflow.md`
-1. Use `pear-dev` skill to guide creation + staging.
+- `docs/design/p2p-app-store.md`
-2. Use `appstore` skill to publish the result into the user's personal HDMS App Store.
+- `packages/bare-os-coreutils/lib/appstore-pear.js`
-3. Later users can discover/install it via normal App Store flows.
-
-This is one of the major end goals of the ctx.pear work.

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-26T23:42:58.195Z",
+  "generatedAt": "2026-05-26T23:57:42.108Z",
   "note": "Sparse POSIX Issue 7 coverage hints; commandIndex is generated each coreutils build.",
   "commandIndex": [
     {

packages/bare-os-seeder/kernel/lib/bare/manifest.json

@@ -1,18 +1,18 @@
 {
   "version": 1,
   "bundles": [
-    {
-      "path": "/lib/bare/bundles/safetyCatch.js",
-      "keys": [
-        "safetyCatch"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/b4a.js",
       "keys": [
         "b4a"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/safetyCatch.js",
+      "keys": [
+        "safetyCatch"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/hypercoreIdEncoding.js",
       "keys": [
@@ -37,12 +37,6 @@
         "bareEncoding"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/barePath.js",
-      "keys": [
-        "barePath"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareEvents.js",
       "keys": [
@@ -55,6 +49,12 @@
         "protomux"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/barePath.js",
+      "keys": [
+        "barePath"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareAbort.js",
       "keys": [
@@ -85,12 +85,6 @@
         "bareAppKit"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareReadline.js",
-      "keys": [
-        "bareReadline"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareCrypto.js",
       "keys": [
@@ -98,27 +92,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareAsyncHooks.js",
+      "path": "/lib/bare/bundles/bareReadline.js",
       "keys": [
-        "bareAsyncHooks"
+        "bareReadline"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/fetch.js",
-      "keys": [
-        "fetch"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/bareBmp.js",
-      "keys": [
-        "bareBmp"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/bareAtomics.js",
-      "keys": [
-        "bareAtomics"
       ]
     },
     {
@@ -128,9 +104,27 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareBundleCompile.js",
+      "path": "/lib/bare/bundles/fetch.js",
       "keys": [
-        "bareBundleCompile"
+        "fetch"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/bareAsyncHooks.js",
+      "keys": [
+        "bareAsyncHooks"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/bareAtomics.js",
+      "keys": [
+        "bareAtomics"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/bareBmp.js",
+      "keys": [
+        "bareBmp"
       ]
     },
     {
@@ -139,6 +133,12 @@
         "bareBundle"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareBundleCompile.js",
+      "keys": [
+        "bareBundleCompile"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareBuffer.js",
       "keys": [
@@ -175,24 +175,30 @@
         "bareBoot"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareBundleEvaluate.js",
-      "keys": [
-        "bareBundleEvaluate"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareDebugLog.js",
       "keys": [
         "bareDebugLog"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareBundleEvaluate.js",
+      "keys": [
+        "bareBundleEvaluate"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareDelta.js",
       "keys": [
         "bareDelta"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareCov.js",
+      "keys": [
+        "bareCov"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareDiagnosticsChannel.js",
       "keys": [
@@ -200,9 +206,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareCov.js",
+      "path": "/lib/bare/bundles/bareBundleId.js",
       "keys": [
-        "bareCov"
+        "bareBundleId"
       ]
     },
     {
@@ -217,24 +223,12 @@
         "bareEnv"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareBundleId.js",
-      "keys": [
-        "bareBundleId"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareExif.js",
       "keys": [
         "bareExif"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareDaemon.js",
-      "keys": [
-        "bareDaemon"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareFfmpeg.js",
       "keys": [
@@ -253,6 +247,12 @@
         "bareDgram"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareDaemon.js",
+      "keys": [
+        "bareDaemon"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareGif.js",
       "keys": [
@@ -265,30 +265,30 @@
         "bareFormat"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareFormData.js",
-      "keys": [
-        "bareFormData"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareHeif.js",
       "keys": [
         "bareHeif"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareHrtime.js",
-      "keys": [
-        "bareHrtime"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareGtk.js",
       "keys": [
         "bareGtk"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareFormData.js",
+      "keys": [
+        "bareFormData"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/bareHrtime.js",
+      "keys": [
+        "bareHrtime"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareFileLogger.js",
       "keys": [
@@ -301,18 +301,18 @@
         "bareHttpParser"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareIco.js",
-      "keys": [
-        "bareIco"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareFs.js",
       "keys": [
         "bareFs"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareIco.js",
+      "keys": [
+        "bareIco"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareImageResample.js",
       "keys": [
@@ -331,18 +331,18 @@
         "bareInspect"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareHttps.js",
-      "keys": [
-        "bareHttps"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareJpeg.js",
       "keys": [
         "bareJpeg"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareHttps.js",
+      "keys": [
+        "bareHttps"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareIntl.js",
       "keys": [
@@ -385,6 +385,12 @@
         "bareLink"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareMake.js",
+      "keys": [
+        "bareMake"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareModuleResolve.js",
       "keys": [
@@ -392,9 +398,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareMake.js",
+      "path": "/lib/bare/bundles/bareNdk.js",
       "keys": [
-        "bareMake"
+        "bareNdk"
       ]
     },
     {
@@ -409,12 +415,6 @@
         "bareMedia"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareNdk.js",
-      "keys": [
-        "bareNdk"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareNodeFetch.js",
       "keys": [
@@ -422,9 +422,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareModuleLexer.js",
+      "path": "/lib/bare/bundles/bareModule.js",
       "keys": [
-        "bareModuleLexer"
+        "bareModule"
       ]
     },
     {
@@ -434,9 +434,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareModule.js",
+      "path": "/lib/bare/bundles/bareModuleLexer.js",
       "keys": [
-        "bareModule"
+        "bareModuleLexer"
       ]
     },
     {
@@ -481,42 +481,42 @@
         "bareNodeRuntime"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/barePack.js",
-      "keys": [
-        "barePack"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/barePunycode.js",
       "keys": [
         "barePunycode"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareProcess.js",
-      "keys": [
-        "bareProcess"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/barePackDrive.js",
-      "keys": [
-        "barePackDrive"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareQuerystring.js",
       "keys": [
         "bareQuerystring"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareProcess.js",
+      "keys": [
+        "bareProcess"
+      ]
+    },
+    {
+      "path": "/lib/bare/bundles/barePack.js",
+      "keys": [
+        "barePack"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/barePrebuild.js",
       "keys": [
         "barePrebuild"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/barePackDrive.js",
+      "keys": [
+        "barePackDrive"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareQueueMicrotask.js",
       "keys": [
@@ -541,6 +541,12 @@
         "bareSdl"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/barePromClient.js",
+      "keys": [
+        "barePromClient"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareSemver.js",
       "keys": [
@@ -559,12 +565,6 @@
         "bareSignals"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/barePromClient.js",
-      "keys": [
-        "barePromClient"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareRepl.js",
       "keys": [
@@ -607,12 +607,6 @@
         "bareSvg"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareSystemLogger.js",
-      "keys": [
-        "bareSystemLogger"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareStorage.js",
       "keys": [
@@ -626,9 +620,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareStructuredClone.js",
+      "path": "/lib/bare/bundles/bareSystemLogger.js",
       "keys": [
-        "bareStructuredClone"
+        "bareSystemLogger"
       ]
     },
     {
@@ -638,9 +632,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareSubprocess.js",
+      "path": "/lib/bare/bundles/bareStructuredClone.js",
       "keys": [
-        "bareSubprocess"
+        "bareStructuredClone"
       ]
     },
     {
@@ -649,6 +643,12 @@
         "bareTimers"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareSubprocess.js",
+      "keys": [
+        "bareSubprocess"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareTpl.js",
       "keys": [
@@ -679,24 +679,30 @@
         "bareTls"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareTty.js",
-      "keys": [
-        "bareTty"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareUnpack.js",
       "keys": [
         "bareUnpack"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareTty.js",
+      "keys": [
+        "bareTty"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareV8.js",
       "keys": [
         "bareV8"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareThread.js",
+      "keys": [
+        "bareThread"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareVm.js",
       "keys": [
@@ -710,9 +716,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareThread.js",
+      "path": "/lib/bare/bundles/bareWebp.js",
       "keys": [
-        "bareThread"
+        "bareWebp"
       ]
     },
     {
@@ -721,18 +727,6 @@
         "bareWebKit"
       ]
     },
-    {
-      "path": "/lib/bare/bundles/bareUnionBundle.js",
-      "keys": [
-        "bareUnionBundle"
-      ]
-    },
-    {
-      "path": "/lib/bare/bundles/bareWebp.js",
-      "keys": [
-        "bareWebp"
-      ]
-    },
     {
       "path": "/lib/bare/bundles/bareWebKitGtk.js",
       "keys": [
@@ -746,9 +740,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareV8ToIstanbul.js",
+      "path": "/lib/bare/bundles/bareUnionBundle.js",
       "keys": [
-        "bareV8ToIstanbul"
+        "bareUnionBundle"
       ]
     },
     {
@@ -757,6 +751,12 @@
         "bareWinUi"
       ]
     },
+    {
+      "path": "/lib/bare/bundles/bareV8ToIstanbul.js",
+      "keys": [
+        "bareV8ToIstanbul"
+      ]
+    },
     {
       "path": "/lib/bare/bundles/bareXdiff.js",
       "keys": [
@@ -764,9 +764,9 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareZlib.js",
+      "path": "/lib/bare/bundles/bareWhich.js",
       "keys": [
-        "bareZlib"
+        "bareWhich"
       ]
     },
     {
@@ -776,15 +776,15 @@
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareZmq.js",
+      "path": "/lib/bare/bundles/bareZlib.js",
       "keys": [
-        "bareZmq"
+        "bareZlib"
       ]
     },
     {
-      "path": "/lib/bare/bundles/bareWhich.js",
+      "path": "/lib/bare/bundles/bareZmq.js",
       "keys": [
-        "bareWhich"
+        "bareZmq"
       ]
     },
     {
@@ -1740,8 +1740,8 @@
   ],
   "bundleProvenance": {
     "schemaVersion": 1,
-    "generatedAt": "2026-05-26T23:43:00.338Z",
+    "generatedAt": "2026-05-26T23:57:44.184Z",
-    "gitCommit": "ab3f0916711cbabb5268e8dd8be1c58041138886",
+    "gitCommit": "21580f21bc3817ae8d39640fe07f948af2c32308",
     "nodeVersion": "v20.19.4",
     "bundleTier": "all",
     "normativeManifest": "packages/bare-os-booter/lib/bare-module-manifest.json",

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

@@ -1,6 +1,6 @@
 {
   "schema": 1,
-  "atMs": 1779838978194,
+  "atMs": 1779839862107,
   "commands": [
     "agent",
     "appctl",

packages/bare-os-seeder/kernel/share/agent-workspace/skills/appstore/SKILL.md

@@ -1,135 +1,76 @@
 ---
 name: appstore
-version: 0.1.0
+version: 0.2.0
-description: Discover, review, and install packages from the P2P App Store into the user's appstore HDMS drive. Supports user apps, services, and (gated) kernel extensions.
+description: Discover, install, launch, and update P2P packages from pear:// links. Real HDMS/VFS materialization and in-guest launch.
-tags: [appstore, p2p, hdms, packages, extensions]
+tags: [appstore, p2p, hdms, packages, extensions, pear]
 requires: [read_skill, read_proc_file, run_command, vfs]
 ---
 
 # appstore Skill
 
 ## When to use
-Use when the user wants to explore or install applications, services, or kernel extensions from the P2P App Store.
 
-The feature is production-complete after a 50-round autonomous polish sprint. All core flows are fully supported.
+Use when the user wants to install, launch, update, or manage packages from the P2P App Store — especially Pear apps published with `pear release`.
 
 ## Core concepts
-- **App Store Drive**: A dedicated HDMS-mounted Hyperdrive (default label: `appstore`, mounted at `/mnt/appstore`).
-- **Registry**: `~/.appstore/registry.json` (or the drive's registry) tracks installed packages.
-- **Package Types**:
-  - `app` — Normal user applications
-  - `service` — Long-running services (may create initd units)
-  - `kernel-ext` — High-trust kernel extensions (requires explicit approval + policy)
 
-## Recommended workflow
+- **App Store drive** — Optional HDMS label `appstore` at `/mnt/appstore`; falls back to `~/.appstore/`.
-1. Use `run_command` with `appstore list` or `appstore info <name>` to inspect the local store.
+- **Registry** — `registry.json` lists installed packages and `pearLink` values.
-2. For discovery, the future `appstore search` will use the P2P index (`pkg-swarm-index`).
+- **Materialization** — `lib/appstore-pear.js` copies the release tree into `packages/<name>/` (from local HDMS mount or ephemeral readonly fetch).
-3. When suggesting installation:
+- **Launch** — Runs `sources/<main>` in the guest shell (output on `ctx.console`).
-   - Clearly distinguish between `app`/`service` vs `kernel-ext`.
-   - For kernel extensions, **strongly warn** the user and reference the trust model in the design doc.
-4. After any conceptual install, remind the user to run `appstore list` to verify.
 
-## Safety rules
+## End-to-end flow (with pear-dev)
-- Never suggest installing a `kernel-ext` without explicit user confirmation and review of the manifest.
-- Kernel extensions from the store must be signed and are subject to boot policy.
-- Prefer reading live state via `read_proc_file /proc/bare_os/appstore.json` (when it exists) over static docs.
 
-## Current State (Production-Ready)
+```bash
-The App Store feature is complete and production-ready after a 50-round autonomous polish sprint.
+pear init && pear stage && pear release . && pear seed .
-- Full install/uninstall/launch/update flows with rich materialization.
+appstore install my-app pear://0.<length>.<key> --yes
-- Strong HDMS preference with excellent fallback UX.
+appstore launch my-app
-- Gated but fully supported kernel extension path.
+```
-- Service unit generation.
-- Deep agent autonomy with multi-step workflows.
-- No remaining limitations in day-to-day usage.
 
-## Practical agent usage examples
+Requires **login** for HDMS when fetching remote keys.
+
+## Practical commands
 
-**Check what's installed:**
 ```
 run_command "appstore list"
+run_command "appstore info my-pear-app"
+run_command "appstore install my-pear-app pear://0.10.<key> --yes"
+run_command "appstore launch my-pear-app"
+run_command "appstore update my-pear-app"
+run_command "appstore setup"
 ```
 
-**Inspect a specific package:**
+## Safety rules
-```
-run_command "appstore info simple-file-share"
-```
 
-**Install a package (with confirmation):**
+- Never install `kernel-ext` without explicit user approval and design-doc review.
-```
+- Always pass **`--yes`** on install when the user confirmed.
-run_command "appstore install my-p2p-app --yes"
+- After install, suggest **`appstore launch`** to verify behavior.
-```
+- If install fails on fetch, ensure user ran **`pear seed`** and is **logged in**.
 
-**Install from explicit P2P link (copies release tree from HDMS / swarm):**
+## Current behavior (May 2026)
-```
-run_command "appstore install my-p2p-app pear://0.<length>.<key> --yes"
-```
 
-**Launch (runs sources/index.js in the guest shell — prints app output):**
+| Command | Behavior |
-```
+| --- | --- |
-run_command "appstore launch my-p2p-app"
+| `install` | Fetches pear:// tree into package dir; reports file count + method |
-```
+| `launch` | Executes materialized `sources/index.js` (or `main`) in guest |
+| `update` | Re-runs materialization from stored `pearLink` |
+| `search` | Delegates to `pkg-swarm-index` (best-effort) |
 
-**Refresh after a new pear release:**
+**Limitations:** No guest `pear run` for full Pear desktop runtime; launch uses source entry, not `app.bundle.js` alone.
-```
-run_command "appstore update my-p2p-app"
-```
 
-**When user asks to install something:**
+## HDMS notes
-1. Use `run_command "appstore info <name>"` if it exists locally.
-2. Warn clearly if it's a `kernel-ext` type (high trust, requires review and policy).
-3. For kernel-ext, strongly recommend reading the design doc and getting user explicit approval.
-4. After install, run `appstore list` to confirm.
-5. Suggest `appstore launch <name>` to run it.
-6. For full HDMS experience, suggest using `hdms` or `appstore setup`.
 
-**HDMS integration notes:**
+- Prefer `/mnt/appstore` when label `appstore` is mounted (`appstore setup` for instructions).
-- The App Store strongly prefers a drive mounted at `/mnt/appstore` (label `appstore` via HDMS).
+- Pear release drives (`pear-<app-name>`) are reused automatically when the `pear://` key matches.
-- Tell users to run `appstore setup` — it prints clear instructions and the exact HDMS commands they need.
-- Current behavior gracefully falls back to personal `~/.appstore/` when no HDMS drive is mounted.
-- Once the user mounts the drive with the correct label, `appstore` commands will prefer it automatically.
-
-**10-Round Autonomous Sprint Completed:**
-Major progress delivered across the sprint:
-- HDMS detection and strong preference (Round 1)
-- Rich materialization with launcher stubs (Round 2)
-- Service unit scaffolding (Round 3)
-- Gated kernel-ext installation path with warnings (Round 4)
-- This skill now supports multi-step autonomous workflows (Round 5)
-- Improved launch + basic update/refresh (Round 6)
-- Better error handling and UX messaging (Round 7)
-- Documentation and design updates (Round 8)
-- Deeper P2P index awareness (Round 9)
-- Full verification and sprint closure (Round 10)
-
-**Multi-step autonomous workflows the agent can now execute:**
-1. Run `appstore setup` and guide the user on HDMS drive creation/mount.
-2. Use `appstore search` + `info` to evaluate packages.
-3. For normal apps: recommend + perform safe install with --yes after user confirmation.
-4. For services: install + remind about potential initd generation.
-5. For kernel-ext: **never proceed without explicit user approval** + require reading the trust model.
-6. After install, offer `appstore launch` or `list`.
-7. Use `appstore update` for refresh when appropriate.
-8. Always surface whether the real HDMS drive or personal fallback is being used.
-
-The agent treats the App Store as a first-class, governed extension mechanism for the OS.
 
 ## Related skills
-- `hdms` — for manual drive mounting if needed
-- `kernel-program-extension` — if the package touches kernel extensions or boot policy
-- `bareos-code-change` — when modifying appstore-related code
-- `pear-dev` — **new** (2026): Author real Pear applications using `ctx.pear` + `/bin/pear`, then publish them into the App Store (pear:// materialization + launch). Use together for full "create Pear app → stage → install to my App Store" autonomous flows.
 
-## Pear App Synergy (New Capability)
+- **`pear-dev`** — Author and release Pear apps (`/bin/pear`)
+- **`hdms`** — Drive mounts
+- **`kernel-program-extension`** — Kernel extensions from store
 
-Pear apps are now a natural fit for the App Store:
+## References
-- Use the `pear-dev` skill to create and stage real Pear applications inside Bare OS (via the new `ctx.pear` surface and `/bin/pear`).
-- Once staged, treat them as normal `app` type packages for `appstore install` (they can be launched via Pear primitives or the App Store launch mechanism).
-- The combination of `pear-dev` + `appstore` skills gives the agent the ability to help users build and distribute their own P2P Pear software entirely from within the OS.
 
-When a user says "I want to make a new P2P notes app", the correct combined workflow is:
+- `docs/guides/guest-pear-and-appstore-workflow.md`
-1. Use `pear-dev` skill to guide creation + staging.
+- `docs/design/p2p-app-store.md`
-2. Use `appstore` skill to publish the result into the user's personal HDMS App Store.
+- `packages/bare-os-coreutils/lib/appstore-pear.js`
-3. Later users can discover/install it via normal App Store flows.
-
-This is one of the major end goals of the ctx.pear work.

patches/autopass+3.4.0.patch

@@ -1,5 +1,5 @@
 diff --git a/node_modules/autopass/index.js b/node_modules/autopass/index.js
-index 1d1e684..cc1652e 100644
+index 1d1e684..34a93db 100644
 --- a/node_modules/autopass/index.js
 +++ b/node_modules/autopass/index.js
 @@ -98,7 +98,12 @@ class AutopassPairer extends ReadyResource {
@@ -16,3 +16,116 @@ index 1d1e684..cc1652e 100644
      const check = () => {
        if (this.pass.base.writable) {
          this.pass.base.off('update', check)
+@@ -218,7 +223,12 @@ class Autopass extends ReadyResource {
+ 
+   async _apply(nodes, view, base) {
+     for (const node of nodes) {
+-      await this.router.dispatch(node.value, { view, base })
++      try {
++        await this.router.dispatch(node.value, { view, base })
++      } catch (err) {
++        this.emit('error', err)
++        throw err
++      }
+     }
+     await view.flush()
+   }
+diff --git a/node_modules/autopass/spec/db/index.js b/node_modules/autopass/spec/db/index.js
+index f8bcd6e..573789d 100644
+--- a/node_modules/autopass/spec/db/index.js
++++ b/node_modules/autopass/spec/db/index.js
+@@ -6,6 +6,17 @@ const { version, getEncoding, setVersion } = require('./messages.js')
+ 
+ const versions = { schema: version, db: 1 }
+ 
++/** HyperDB v4.22+ prefixes values with type=0; older rows store version as first uint. */
++function _decodeCollectionValueHeader(state, collection) {
++  const type = c.uint.decode(state)
++  if (type !== 0) {
++    state.start = 0
++    collection.decodedVersion = type
++    return
++  }
++  collection.decodedVersion = c.uint.decode(state)
++}
++
+ // '@autopass/records' collection key
+ const collection0_key = new IndexEncoder([IndexEncoder.STRING], { prefix: 0 })
+ 
+@@ -22,9 +33,7 @@ function collection0_reconstruct(schemaVersion, keyBuf, valueBuf) {
+   const key = collection0_key.decode(keyBuf)
+   setVersion(schemaVersion)
+   const state = { start: 0, end: valueBuf.byteLength, buffer: valueBuf }
+-  const type = c.uint.decode(state)
+-  if (type !== 0) throw new Error('Unknown collection type: ' + type)
+-  collection0.decodedVersion = c.uint.decode(state)
++  _decodeCollectionValueHeader(state, collection0)
+   const record = collection0_enc.decode(state)
+   record.key = key[0]
+   return record
+@@ -87,9 +96,7 @@ function collection1_reconstruct(schemaVersion, keyBuf, valueBuf) {
+   const key = collection1_key.decode(keyBuf)
+   setVersion(schemaVersion)
+   const state = { start: 0, end: valueBuf.byteLength, buffer: valueBuf }
+-  const type = c.uint.decode(state)
+-  if (type !== 0) throw new Error('Unknown collection type: ' + type)
+-  collection1.decodedVersion = c.uint.decode(state)
++  _decodeCollectionValueHeader(state, collection1)
+   const record = collection1_enc.decode(state)
+   record.id = key[0]
+   return record
+@@ -152,9 +159,7 @@ function collection2_reconstruct(schemaVersion, keyBuf, valueBuf) {
+   const key = collection2_key.decode(keyBuf)
+   setVersion(schemaVersion)
+   const state = { start: 0, end: valueBuf.byteLength, buffer: valueBuf }
+-  const type = c.uint.decode(state)
+-  if (type !== 0) throw new Error('Unknown collection type: ' + type)
+-  collection2.decodedVersion = c.uint.decode(state)
++  _decodeCollectionValueHeader(state, collection2)
+   const record = collection2_enc.decode(state)
+   record.key = key[0]
+   return record
+@@ -217,9 +222,7 @@ function collection3_reconstruct(schemaVersion, keyBuf, valueBuf) {
+   const key = collection3_key.decode(keyBuf)
+   setVersion(schemaVersion)
+   const state = { start: 0, end: valueBuf.byteLength, buffer: valueBuf }
+-  const type = c.uint.decode(state)
+-  if (type !== 0) throw new Error('Unknown collection type: ' + type)
+-  collection3.decodedVersion = c.uint.decode(state)
++  _decodeCollectionValueHeader(state, collection3)
+   const record = collection3_enc.decode(state)
+   record.key = key[0]
+   return record
+@@ -282,9 +285,7 @@ function collection4_reconstruct(schemaVersion, keyBuf, valueBuf) {
+   const key = collection4_key.decode(keyBuf)
+   setVersion(schemaVersion)
+   const state = { start: 0, end: valueBuf.byteLength, buffer: valueBuf }
+-  const type = c.uint.decode(state)
+-  if (type !== 0) throw new Error('Unknown collection type: ' + type)
+-  collection4.decodedVersion = c.uint.decode(state)
++  _decodeCollectionValueHeader(state, collection4)
+   const record = collection4_enc.decode(state)
+   record.key = key[0]
+   return record
+@@ -347,9 +348,7 @@ function collection5_reconstruct(schemaVersion, keyBuf, valueBuf) {
+   const key = collection5_key.decode(keyBuf)
+   setVersion(schemaVersion)
+   const state = { start: 0, end: valueBuf.byteLength, buffer: valueBuf }
+-  const type = c.uint.decode(state)
+-  if (type !== 0) throw new Error('Unknown collection type: ' + type)
+-  collection5.decodedVersion = c.uint.decode(state)
++  _decodeCollectionValueHeader(state, collection5)
+   const record = collection5_enc.decode(state)
+   record.id = key[0]
+   return record
+@@ -412,9 +411,7 @@ function collection6_reconstruct(schemaVersion, keyBuf, valueBuf) {
+   const key = collection6_key.decode(keyBuf)
+   setVersion(schemaVersion)
+   const state = { start: 0, end: valueBuf.byteLength, buffer: valueBuf }
+-  const type = c.uint.decode(state)
+-  if (type !== 0) throw new Error('Unknown collection type: ' + type)
+-  collection6.decodedVersion = c.uint.decode(state)
++  _decodeCollectionValueHeader(state, collection6)
+   const record = collection6_enc.decode(state)
+   record.key = key[0]
+   return record