Snapshots

copybook snapshot renders every definition with its example values and writes one Markdown file per definition:

---
id: console.create-project.agent
kind: prompt
title: "Set up Acme with your coding agent"
source: src/create-project.ts#setUpWithAgent
placements:
  - console/create-project/done
params:
  orgId: org-summer-dust-12345678
  projectId: round-bar-12345678
embeds:
  - acme.cli.install
  - acme.cli.init
hash: sha256:a7bcdda7487fd64a
---

Set up this app on Acme.

1. npm i -g acme@latest. If that fails, use `npx acme@latest` in place of `acme`. …

Snapshots with variants get a ## <variant key> section per variant.

Why snapshotsCopy Anchor Link

Snapshots track output, not source:

• Changes show up where they land. Change acme.cli.deploy and the diff shows every prompt and snippet that embeds it, not just the one line you edited.
• Reviewers see what users see. DevRel and docs reviewers can review a prompt change without reading TypeScript.
• "When did this change?" is git log. Every snapshot file has its own history, including authors and pull requests. Studio shows it per definition.
• Ownership is a CODEOWNERS rule. For example: copybook/snapshots/console.* @devrel.

Check in CICopy Anchor Link

copybook check

check fails when a snapshot is missing, out of date (it prints the diff), or orphaned. It also validates the definitions:

• every required param has an example or a default;
• templates render the same output twice, so they're pure;
• placements are listed in the config, if you list them;
• aliases don't collide with ids.

Pass --base origin/main to also warn when an id disappears without being kept as an alias.

Only what changedCopy Anchor Link

copybook list --changed --base origin/main

This lists the definitions whose rendered output differs from the base ref, including ones that aren't snapshotted yet. Tests and evals use the same list, so a pull request only runs what it changed.