Wire a project with petbox-wire

1. Wire one project

Run the full wire once per project directory. You need an API key for that project first — mint it on the project's Connect agent page in the UI; petbox-wire never mints keys.

Pass the key as an environment variable, not --key <KEY> — npm writes the full command line
of every invocation to ~/.npm/_logs/*.log in plain text with no rotation, so an argument-passed
key sits there readable indefinitely; an env-var assignment is never part of that logged argv.
petbox-wire already reads the key straight from process.env[VAR] when --key is omitted, so
no extra flag is needed:

# bash / zsh
PETBOX_<PROJECT>_API_KEY=<API_KEY> npx petbox-wire <dir> <projectKey>

# PowerShell
$env:PETBOX_<PROJECT>_API_KEY='<API_KEY>'; npx petbox-wire <dir> <projectKey>

It validates the key against the server before persisting anything, so a bad key never lands in your stores. Re-running is idempotent and self-heals a half-wired machine.

What the full wire writes into <dir>: .mcp.json (Claude Code), .opencode/opencode.json (opencode), .factory/mcp.json (Factory Droid — merged, not overwritten, so team servers survive), and the kit's eight skills — petbox, petbox-agent-factory, petbox-methodology, petbox-write-economy, petbox-node-authoring, petbox-analysis-workspace, petbox-factory-run, petbox-second-reading — each as a SKILL.md written into both skill surfaces, .claude/skills/<name>/ (Claude Code natively, and opencode through its Claude-compatible discovery path) and .factory/skills/<name>/ (Factory Droid's native root). All three MCP configs reference the key as ${VAR} / {env:VAR} — the key itself is never written into a project file.

Three frontmatter keys ride along on every skill the kit writes, and they are three independent axes — doc/agent-wiring.md §2f in the repo carries the full contract:

• petbox: managed — provenance. This is the only thing the write guard trusts to recognise a file as the kit's own before it overwrites or deletes it. Put petbox: manual in a file at one of those paths and the kit hands the path back to you: never rewritten, never removed, and — unlike a stranger's file — logged as yours rather than as a refusal, so it can never reach the run's exit code. Any other content there (no marker at all) is refused loudly and left byte-for-byte alone.
• petbox-digest: auto | manual — whether the skill enters the salience index the kit's opencode plugin injects into opencode's system prompt. auto for petbox, petbox-methodology, petbox-write-economy and petbox-node-authoring; manual for the other four. It changes nothing on Claude Code or Droid.
• disable-model-invocation: true — the key Claude Code and Droid honour to refuse a model-initiated call, so the skill only runs when a human asks for it by name. Carried by petbox-agent-factory, petbox-analysis-workspace and petbox-factory-run. petbox-second-reading deliberately does not carry it: it stays out of the digest yet remains callable by an agent that decides it applies.

Note: on a fresh machine the environment variable only exists in new terminals (Windows user-scope env; POSIX ~/.petbox/env.sh sourced from your login profiles). The kit's own hooks read ~/.petbox/keys.json directly, but that file does not always hold a copy of the key: when the wire obtained the key from a live environment variable, it writes a ${VAR} reference there instead — never a copy of the secret (see §9 below). A hook whose own process inherits that variable resolves the reference and works immediately; one that doesn't fails loudly at session start, naming the missing variable, rather than silently starting without a key.

2. The env-var name

The key is always held in an environment variable named PETBOX_<PROJECT>_API_KEY. The project key is upper-cased, every run of non-alphanumeric characters collapses to a single _, leading and trailing _ are trimmed, and PETBOX_ is prefixed. So kpvotes → PETBOX_KPVOTES_API_KEY and $system → PETBOX_SYSTEM_API_KEY. This is the same name the UI Connect agent page and the onboarding runbook show you, so the two paths agree.

--env VAR overrides the derived name, and a re-run reuses the name already recorded in the registry for that directory — an existing project never gets renamed under you. If your machine was wired before this scheme landed it may still carry an older name (e.g. _SYSTEM_API_KEY); when a config's ${VAR} doesn't resolve, check ~/.petbox/keys.json for the name you actually have.

3. Commands

update, apply, status, doctor, roles, profile and model take no <dir> <projectKey>; they resolve the project themselves (or don't need one).

4. Where a roster comes from

An agent roster is assembled from three independent sources, each with its own owner:

1. The portable agent definition — file-authoritative. Roles, tiers, required capabilities, spawn/escalation rules. Built by laying ordered layers over each other, lowest first: base (the kit's own default-agents.json, shipped in the package, always present) < user (~/.petbox/agents/) < project (<project root>/.petbox/agents/). Nothing is fetched: the kit does not ask a server what the roles are. It is portable: it carries no model ids — a definition containing role.model is rejected.
2. The local role→model binding — machine-authoritative. ~/.petbox/roles.json: activeProfile + profiles.<name>.agents.<harness>.roles.<role>.model. Never uploaded, never invented; if a role is unbound, no model: line is emitted (a Factory droid gets model: inherit). Edit it with petbox-wire model set / model unset (see the commands table above) — not by hand; both print next: petbox-wire apply because neither compiles artifacts itself. petbox-wire status (also above) shows exactly where a role's current model came from (roster/seed/none).
3. The harness capability matrix — kit data. Ships with the npm package and states, per harness, which capabilities exist (mcp_subagent, hooks, spawn_subagents, …). Known harnesses: claude-code, opencode, droid.

The gate between them is truthfulness: a role may only require capabilities the target harness actually declares. A role that fails is skipped and reported — never silently written with the offending line dropped. Clean roles in the same run are still written.

5. apply — compiled agent files

npx petbox-wire apply            # definition from base < user < project, always
npx petbox-wire apply --offline  # also skip the workspace probe behind the skill refresh
npx petbox-wire layers           # which layers exist, and which one gave which field

apply finds the artifact target directory by git rev-parse --show-toplevel from cwd — the git worktree apply is actually running in — falling back to cwd itself only when cwd is not inside a git working tree at all. It deliberately does not consult the registry (~/.petbox/projects.json) for this: the registry answers project identity (which project/key/base-URL), not where artifacts land. Running apply from inside a worktree therefore writes into that worktree, never into the primary tree it was branched from — an earlier version resolved the target the same way it resolved project identity (registry longest-prefix) and could silently rewrite the primary tree's agent files from a worktree checked out on a different branch; that bug is fixed. apply always prints which root it resolved and how (git/cwd).

It then builds the definition from the file cascade base < user < project — no network on that leg, so --offline does not change it — and writes, under that root:

Emitted file (and frontmatter name:) are namespaced petbox-<role> — role.slug and ~/.petbox/roles.json themselves stay unprefixed; only the render is. model: frontmatter is written only when the role is bound (an unbound droid gets model: inherit) — it never invents a concrete model id.

Warning: every generated file carries a petbox: managed origin marker, and apply overwrites files that carry it. It does the opposite for a file that doesn't — a real, non-PetBox file sitting at that exact path — where it refuses (loud, non-zero exit) to touch it at all, rather than clobbering it. Do not hand-edit a petbox: managed file; changes belong in a definition layer (~/.petbox/agents or <root>/.petbox/agents) or in roles.json (models), then re-apply. A pre-namespacing leftover (e.g. .claude/agents/worker.md) that PetBox itself owns is removed once its petbox-<role>.md replacement is written; a same-named file without the marker is left alone either way.

6. Offline, and what a broken layer does

The definition needs no network and has no cache: its layers are local files already. A layer directory that does not exist is a layer with no opinion — the ordinary case on a fresh machine, and never a warning.

A layer that IS there and cannot be read, parsed or validated fails loudly, and the shape of that depends on what the command is doing:

• apply and doctor BUILD artifacts, so they refuse: exit 1, the absolute path and the parser's own message on stderr, and nothing written or changed.
• The SessionStart hooks RENDER a banner, so they degrade: the process still exits 0 (a hook that crashes a session is worse than one that degrades), but the banner opens with a marker line naming the broken file, the protocol under it comes from the kit base, and ~/.petbox/wire.log gets a trace.

In neither case is a previously-successful result substituted for the unreadable one. That substitution is exactly what turns a broken source into a silent one — it is why there is no last-known-good copy of a definition anywhere.

--offline therefore has nothing to do with the definition. It skips the network calls the kit still makes: the /api/auth/validate workspace probe behind the skill refresh (apply, doctor, status), the memory-canon fetch, and doctor's banner-budget check. roles, roles export, profile use, model set and model unset are offline by construction — no network path exists for them at all.

The SessionStart memory canon still lives on the server and still has a cache: ~/.petbox/cache/<project>.canon.md.

7. Exit codes

Note: the full-wire path is not limited to 2/1. Its own visible steps (self-smoke, then the apply pass that seeds bindings and compiles artifacts) can each fail without aborting the run, and the reported exit code is the strongest of them by priority 1 > 3 > 4 > 0 — so a full wire whose final apply step hits a truthfulness block or an incomplete skill refresh surfaces 3 or 4, not just 1. Usage errors (2) still end the run immediately during argument parsing, before any step can compete.

Exit 3 is a policy outcome, not a crash: the definition asked for something a harness does not offer. Fix the definition (or accept the skip); don't retry. Exit 4 similarly is not a crash — re-run petbox-wire apply to retry just the step that was skipped.

8. Scopes and endpoints

The CLI does not read definitions from the server at all any more, so no agents:* scope is needed to wire or apply.

9. What lives under ~/.petbox/

These are not secrets you should commit anywhere, and nothing here is regenerated by update except the kit itself.