Checkpoints
A nest checkpoint is an atomic, immutable snapshot of the entire vault — the Context Nest equivalent of a git commit.
Why checkpoints?
Per-document versioning alone cannot guarantee cross-link consistency. When Document B is re-published, any document linking to it immediately resolves to the new version. Checkpoints pin the entire graph at a point in time.
Structure
Checkpoints are stored in .versions/context_history.yaml:
checkpoints:
- checkpoint: 1
at: "2026-01-15T10:00:00Z"
triggered_by: "nodes/architecture"
document_versions:
nodes/architecture: 1
nodes/api-reference: 1
document_chain_hashes:
nodes/architecture: "sha256:a1b2c3..."
nodes/api-reference: "sha256:d4e5f6..."
checkpoint_hash: "sha256:x7y8z9..."Automatic creation
A new checkpoint is created every time a document is published. The checkpoint records the current version of every published document.
Pinned resolution
Use @N in URIs to resolve documents at a specific checkpoint:
contextnest://nodes/architecture@5This returns the version of architecture that was current at checkpoint 5.
Rebuild
If checkpoint history is corrupted or missing, rebuild it from per-document histories:
ctx checkpoint rebuild