---
name: pear-dev
version: 0.2.0
description: Create, stage, build, release, and seed Pear applications entirely from inside a booted Bare OS using ctx.pear and /bin/pear.
tags: [pear, p2p, build, bundle, stage, release, seed, ctx.pear, development]
---

# pear-dev Skill

## When to Use This Skill

Use this skill whenever the user (or another agent) wants Pear development work inside Bare OS:
- Scaffold a new Pear app (`pear init`)
- Stage / bundle an app for deployment (`pear stage`)
- Publish to a real `pear://` link from the guest shell (`pear release`)
- Keep the release replicating (`pear seed`)
- Inspect what Pear tooling is available via `ctx.pear`
- Integrate Pear app creation with the P2P App Store

## Core Capabilities

- `ctx.pear` — Pear development surface (when `BARE_OS_BARE_MODULES` is enabled):
  - `ctx.pear.pearBuild`, `ctx.pear.pearBundle`, `ctx.pear.pearRef`
  - `ctx.pear.bareBundleCompile`, `ctx.pear.bareBundleEvaluate`
- `/bin/pear` command:
  - `pear help` | `pear info` | `pear list`
  - `pear init [dir]` — scaffold project skeleton
  - `pear stage [dir]` — write `<project>/.pear/stage/` (sources + bundle)
  - `pear release [dir]` — publish stage to HDMS Hyperdrive, print `pear://` links
  - `pear seed [dir]` — swarm flush / replication for the release drive
  - `pear build` / `pear bundle` — aliases for `pear stage`

## End-to-End Workflow (Guest Shell Only)

The full pipeline runs inside the Bare OS shell. No host-side `pear stage` / `pear release` is required.

```bash
pear init
cd ~/pear-projects/my-pear-app
pear stage
login                    # unlock identity vault if not already logged in
pear release
pear seed
```

**Requirements for release/seed:**
- Identity unlocked (`login`) so HDMS is active
- Prior successful `pear stage` (`.pear/stage/stage.json` must exist)

Release creates (or reuses) a writable HDMS mount `pear-<app-name>` at `/mnt/pear-<app-name>/`, mirrors the staged tree there, and writes `.pear/release.json` with `pearLink` and `versionedLink`.

## Recommended Agent Loop

1. `run_command "pear list"` — confirm ctx.pear tools loaded
2. `run_command "pear init"` or scaffold in project dir
3. `run_command "pear stage ."`
4. Ensure user is logged in (HDMS active); if guest, prompt `login`
5. `run_command "pear release ."`
6. `run_command "pear seed ."` for replication
7. Optional: `appstore install <name> <pear://link> --yes`

## Safety & Limits

- Release drives live on the user's personal HDMS namespace (same trust model as `hdms create`).
- Re-release overwrites files on the release mount by path; stale paths are not purged automatically.
- `pear seed` is best-effort swarm flush — not a guarantee of wide replication.
- Do not claim host Pear sidecar is needed for release; the guest `/bin/pear` path is authoritative.

## Files & References

- Plan: `docs/design/ctx-pear-surface-and-bare-audit-plan.md`
- Staging: `packages/bare-os-coreutils/lib/pear-stage.js`
- Release: `packages/bare-os-coreutils/lib/pear-release.js`
- Command: `packages/bare-os-coreutils/src/pear.js`