bare-operating-system/kernel/share/agent-workspace/skills/appstore/SKILL.md

name, version, description, tags, requires

name	version	description	tags	requires
appstore	0.2.0	Discover, install, launch, and update P2P packages from pear:// links. Real HDMS/VFS materialization and in-guest launch.	appstore p2p hdms packages extensions pear	read_skill read_proc_file run_command vfs

appstore Skill

When to use

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 — Optional HDMS label appstore at /mnt/appstore; falls back to ~/.appstore/.
• Registry — registry.json lists installed packages and pearLink values.
• Materialization — lib/appstore-pear.js copies the release tree into packages/<name>/ (from local HDMS mount or ephemeral readonly fetch).
• Launch — Runs sources/<main> in the guest shell (output on ctx.console).

End-to-end flow (with pear-dev)

pear init && pear stage && pear release . && pear seed .
appstore install my-app pear://0.<length>.<key> --yes
appstore launch my-app

Requires login for HDMS when fetching remote keys.

Practical commands

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"

Safety rules

• Never install kernel-ext without explicit user approval and design-doc review.
• Always pass --yes on install when the user confirmed.
• After install, suggest appstore launch to verify behavior.
• If install fails on fetch, ensure user ran pear seed and is logged in.

Current behavior (May 2026)

Command	Behavior
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)

Limitations: No guest pear run for full Pear desktop runtime; launch uses source entry, not app.bundle.js alone.

HDMS notes

• Prefer /mnt/appstore when label appstore is mounted (appstore setup for instructions).
• Pear release drives (pear-<app-name>) are reused automatically when the pear:// key matches.

Related skills

• pear-dev — Author and release Pear apps (/bin/pear)
• hdms — Drive mounts
• kernel-program-extension — Kernel extensions from store

References

• docs/guides/guest-pear-and-appstore-workflow.md
• docs/design/p2p-app-store.md
• packages/bare-os-coreutils/lib/appstore-pear.js