bare-operating-system/packages/bare-os-seeder/kernel/share/agent-workspace/skills/pear-dev/SKILL.md

name, version, description, tags

name	version	description	tags
pear-dev	0.2.0	Create, stage, build, release, and seed Pear applications entirely from inside a booted Bare OS using ctx.pear and /bin/pear.	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.

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/pear-stage.js
• Release: packages/bare-os-coreutils/lib/pear/pear-release.js
• Command: packages/bare-os-coreutils/src/pear.js