Lifecycle

Every step is a CLI command you can observe, and each one fails closed. When a command will not run, hcpx availability gives the reason, so an agent reads it before planning and never meets the denial mid-run.

lint → install → activate → connect → availability → exec

Step	Command	What changes	Proves
Lint	`hcpx lint <dir>`	Nothing	Policy covers every command and trigger; Skill present and naming the same commands; wrap is named or pass-through
Install	`hcpx install <dir>`	Pack copied to `$HCP_HOME/packs/<id>/`	The three files are valid and stored
Activate	`hcpx activate <id>`	Pack on this session; Skill copied to `$HCP_HOME/skills/<id>/SKILL.md`	The session may use it
Connect	`hcpx connect <id>`	Binding minted through the hub	Credentials exist for this Principal. Skipped when mode is `public`
Availability	`hcpx availability <id>`	Nothing	Which commands this Principal may run right now, and why not
Exec	`hcpx exec <id> <verb>`	The world	Grant → confirm → mint → Adapter → sandbox → result

Availability#

Availability reports four flags per pack, with executable per command, and every false carries a reason.

Flag	Meaning	False when
installed	Present in the store	Never installed, or uninstalled
activated	On the harness session	Installed but not activated
connected	Binding minted	Non-public pack that has not run `connect`
executable	This command passes grants now	Any of the above, or `missing verb.exec.read` / `missing verb.exec.write`

Terminal

hcpx availability ledger --json

JSON

{
  "pack_id": "ledger",
  "status": ["installed", "activated"],
  "installed": true,
  "activated": true,
  "connected": false,
  "adapter_kind": "wrap",
  "skill_present": true,
  "verbs": [
    { "verb_key": "setup.status", "operation": "read",  "land": "local", "executable": true },
    { "verb_key": "transfer",     "operation": "write", "land": "local", "executable": false, "reason": "missing verb.exec.write" }
  ],
  "capabilities": [
    { "capability": "pack.install",    "granted": true },
    { "capability": "pack.connect",    "granted": true },
    { "capability": "verb.exec.read",  "granted": true },
    { "capability": "verb.exec.write", "granted": false },
    { "capability": "sense.enable",    "granted": false }
  ]
}

The store#

The first run of hcpx creates the store and installs the hcp-cli bootstrap pack, so a working pack is always there to exec against. Set HCP_HOME to move the store, for example in CI or to keep a project store apart from a personal one.

$HCP_HOME/                 default ~/.hcp
  packs/<id>/              installed packs — the three files
  skills/<id>/SKILL.md     Skill copies, written on activate
  state.json               activated · connected · grants

Activate and connect#

Install puts a pack in the store and activate puts it on a session, so a runtime can hold many packs and expose a few, and a host generates surfaces from exactly the activated set. Host wiring with hcpx adopt is a separate, optional step.

Connect applies to Binding modes user, local and mothership. It needs pack.connect, a capability apart from daily writes, and is the only step that mints a long-lived credential, while health commands report and never connect.

Deactivate and uninstall#

Terminal

hcpx deactivate ledger     # leaves the pack in the store, removes it from the session
hcpx uninstall ledger      # removes the directory

A runtime can also turn off a pack's triggers alone without touching the CLI wrap.

Availability#

The store#

Activate and connect#

Deactivate and uninstall#

Related#