State and lock

File	What it holds	Commit it?
pegboard.yaml	Your desired state	Yes
pegboard.lock	Pinned skill versions and hashes	Yes
.pegboard/state.json	What Pegboard wrote in this project	No
~/.local/state/pegboard/state.json	What Pegboard wrote globally	No
~/.local/state/pegboard/backups/	Copies of files from before each write	No
~/.cache/pegboard/	Downloaded skills	No

State

State records the keys, files, and symlinks Pegboard created for each target, along with their hash. It’s how Pegboard knows what’s its own, and how it detects drift. Secret values are never stored in it.

Lock

pegboard.lock sits next to each pegboard.yaml:

{
  "version": 1,
  "skills": {
    "mattpocock/skills@tdd": {
      "commit": "3f2a…",
      "skills": { "tdd": "sha256:91c4…" }
    }
  }
}

apply adds new sources to the lock, like npm install, and forgets the ones you no longer declare. To move to newer versions, run pegboard update.

If content downloaded from a pinned commit doesn’t match its hash, apply fails. With a complete lock and cache, apply doesn’t need the network. Local skills aren’t added to the lock.

Backups

Before changing a file, Pegboard writes a copy to a timestamped folder under ~/.local/state/pegboard/backups/. The output of apply includes the path when it overwrites an edited file.