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

name, version, description, tags, requires

name	version	description	tags	requires
bare-os-hdms	1.0.0	HDMS — extra Hyperdrives under /mnt, registry on the personal drive, Autopass invite/pair, and identity-gated ctx.runHdms.	hdms hyperdrive identity autopass mounts	read_man_page read_file vfs

bare-os-hdms Skill

When to use

Use when the user asks about HDMS (Hyperdrive Management): hdms** CLI, **/.bare/hdms/registry.json**, **/mnt/<label>** mounts, invite/pair sharing, **ctx.runHdms**, **ctx.bareOsSubscribeHdmsLifecycle**, or how HDMS relates to **login / guest mode.

Prerequisites

• HDMS activates after identity unlock. Guest sessions can list mounts that are already open; mutating commands (create**, **add**, registry edits, **invite**, **pair**, etc.) go through **assertLoggedIn**: require **ctx.identity.state === 'unlocked' and an active HDMS controller.
• Implementation: packages/bare-os-booter/lib/hdms-manager.js** (**runHdmsCli**, **HdmsController**), exposed as **ctx.runHdms(argv)** in **packages/bare-os-booter/index.js.

Registry and VFS

• Registry path (constant): /.bare/hdms/registry.json** on the personal drive (**HDMS_REGISTRY_PATH).
• Writable mounts: hdms create <label> — new Corestore namespace + Hyperdrive, replicate to swarm.
• Read-only by key: hdms add <label> <z32-key> — open an existing drive by key string.
• VFS: paths /mnt/<label>/…**; writable mounts allow **put on those routes.
• www label: A mount labeled www** at **/mnt/www** also routes **$HOME/.www** and **/home/<active>/.www** in the VFS—the same docroot the stock **bare-os-www** initd serves by default. See **handbook/05-identity-vault-and-hdms.md** and **handbook/04-the-booter-runtime.md § bare-os-www.

Invite and pair (Autopass / BlindPairing)

High-level behavior (details and caveats in handbook/05-identity-vault-and-hdms.md):

• Invite with a drive: hdms invite [--read-only] <label>** stores a pending share for the peer. **--rw** uses a separate Autopass key (**pending-share-rw**) with **signerKey** + **writerSecretHex** so peers do not silently mount read-only when read/write was intended. Anyone who can read the paired Autopass ledger can write the drive — treat **--rw as highly sensitive.
• hdms invite --read-only** on a writable label sets the peer’s Autopass writer row read-only; read-only Autobase writers are not append-capable, so **invite --read-only + pair often fails with “Not writable” / timeout — for normal HDMS pairing, omit --read-only unless you understand the limitation.
• Pair: hdms pair [--persist|--no-persist] <invite>** — bounded waits (**BARE_OS_HDMS_PAIR_WAIT_MS**, **BARE_OS_HDMS_PAIR_READY_MS**, **BARE_OS_HDMS_PAIR_SHARE_WAIT_MS**, **BARE_OS_HDMS_INVITE_CLEAR_MS** — see env appendix / booter). Default persists to registry; **--no-persist keeps the mount ephemeral. Inviter must stay online with matching Hyperswarm bootstrap or pairing stalls.
• Invite without a label: hdms invite** (optional **--read-only) only pairs Autopass; pending drive offers are cleared — no automatic /mnt mount for the peer.

Kernel hooks

• ctx.bareOsSubscribeHdmsLifecycle(fn)** — callback with **{ kind: 'afterActivate' | 'beforeDeactivate', labels?: string[] }** so **/boot/init.js can refresh mount-dependent state without forking HDMS.
• Stock booter also calls onAfterActivate** on the **hdms module export when present (see developer-guide/11-kernel-pear-cookbook.md).
• After applyUnlockedEnv**, the booter’s **onIdentityUnlocked** path (**packages/bare-os-booter/index.js**) activates Corestore, swarm, the personal drive, and HDMS with the mount map. Custom **/boot/init.js** may assign **ctx.onIdentityUnlocked** for extra post-login hooks (see **handbook/05-identity-vault-and-hdms.md).

Execution steps (for the agent)

1. If the user is guest, explain that mutations require login** / **login --new** first; **hdms list may still work for existing mounts.
2. For subcommands and flags, prefer read_man_page hdms** when available; otherwise cite **handbook/05-identity-vault-and-hdms.md** and **packages/bare-os-booter/lib/hdms-manager.js.
3. For pairing failures, check timeout env vars, bootstrap connectivity, and whether --read-only was used inappropriately on invites.

Constraints

• Read-only unless the user explicitly asks to run hdms mutating commands and policy allows.
• Do not promise cross-runtime behavior beyond what runHdmsCli and Autopass/Hyperdrive versions in this repo implement.
• Treat writer secrets and z32 invite tokens as secrets; do not echo them into logs or chat in full.