Context Nest Specification
The Context Nest Specification is the canonical reference for the protocol. It defines the complete format, rules, and behavior that implementations must follow. This page is a high-level pointer — the authoritative text lives in the spec repository.
Current version
The specification is maintained in the context-nest-spec repository.
Sections
The spec is organized roughly as follows. Section numbering may have shifted as the spec evolved — treat the numbers as indicative and consult the spec repository for the authoritative ordering.
| Section | Description |
|---|---|
| Vault Structure | Layout modes, CONTEXT.md, config.yaml |
| Selector Grammar | Composable query syntax (tag atoms written as #X) |
| Source Nodes | Live data instructions, transports, dependencies; writable/repairable source nodes |
| Addressing | contextnest:// URI scheme, resolution, federation |
| Context Index | context.yaml manifest format |
| Per-Document Versioning | Keyframe + per-version change-log storage, history.yaml, graft-proof numbering |
| Nest Checkpoints | Vault-level atomic snapshots, single-seal bulk import |
| Integrity Verification | SHA-256 hash chains, cross-chain binding, hardened tamper detection |
| Context Injection & Tracing | Query flow, audit tracing |
| Context Packs | Pack format, agent instructions |
| Configuration | Per-vault config + central ~/.contextnest/config.yaml registry |
| Inline Syntax | Context links, tags (including namespaced tags), mentions |
| Validation Rules | Document, source, and cross-reference validation |
| Obsidian Compatibility | Flat layout, properties panel |
| Git Compatibility | Diff-friendly design, merge behavior |
| Extension Points | Custom fields, transports, edge types |
Status lifecycle
Nodes move through a five-state governed lifecycle: draft → pending_review → approved → published, with rejected as a terminal off-ramp from review. See Status Lifecycle and Frontmatter.
Node types
The protocol defines these node type values: document, snippet, glossary, persona, prompt, source, tool, reference, agent, artifact, table, and skill. See Node Types.
Canonical operation catalog
The protocol defines a single canonical set of context_* operations. The same operations are exposed consistently behind the engine (library API), the CLI (ctx), and the MCP server — the surface differs but the operation set is one catalog.
| Operation | Purpose (indicative) |
|---|---|
context_init |
Initialize a vault |
context_create |
Create a node |
context_get |
Fetch a node |
context_update |
Update a node |
context_move |
Move / rename a node |
context_delete |
Delete a node |
context_list |
List nodes |
context_search |
Full-text / metadata search |
context_query |
Selector-based query |
context_table_query |
Query a table node |
context_overview |
Vault overview |
context_md |
Read/emit CONTEXT.md |
context_versions |
List a node's versions |
context_export |
Export nodes |
context_submit_review |
Submit a draft for review (→ pending_review) |
context_review_queue |
List nodes awaiting review |
context_approve |
Approve a reviewed node (→ approved) |
context_reject |
Reject a reviewed node (→ rejected) |
context_publish |
Publish an approved node (→ published) |
context_my_drafts |
List the caller's drafts |
context_comments |
Read/write review comments |
context_resolve |
Resolve a comment/thread |
context_assign_steward |
Assign a steward |
context_stewards |
List stewards |
context_grant |
Grant access |
context_share_nest |
Share a nest |
context_request_deletion |
Request deletion (governed) |
context_deletion_queue |
List pending deletions |
context_resolve_deletion |
Resolve a deletion request |
context_sync_folder |
Sync a folder into the vault |
context_unsynced_list |
List unsynced items |
Selectors
Selectors filter by tag using a bare tag atom, #X — for example #engineering — which composes with the rest of the selector grammar. See Selectors.
Error codes
Operations surface structured error codes. Notable ones:
| Code / error | Raised when |
|---|---|
VALIDATION_FAILED |
A node fails validation (frontmatter, schema, or cross-reference rules). Confirmed: engine ValidationError uses code VALIDATION_FAILED. |
RejectedDocumentError |
An operation targets or would publish a node in the rejected state. Confirmed: engine class, thrown on the publish path. |
INTEGRITY_ERROR |
An integrity check fails (IntegrityError) — see Integrity Verification. |
Implementations
| Package | Description |
|---|---|
@promptowl/contextnest-engine |
Core engine (TypeScript) |
@promptowl/contextnest-cli |
CLI tool (ctx) |
@promptowl/contextnest-mcp-server |
MCP server |
License
The specification is licensed under Apache-2.0.
Contributing
Contributions to the specification are welcome. See the spec repository for guidelines.
Related pages
- FrontmatterEvery Context Nest document begins with a YAML frontmatter block delimited by ---. The frontmatter contains structured metadata that the resolver…
- Integrity VerificationContext Nest uses SHA-256 hash chains to make version history tamper-evident. Each version's chain hash depends on all previous versions. Changing any…
- Node TypesEvery document in a Context Nest vault has a type field in its frontmatter. The type tells agents how to interpret the content.
- Selectors OverviewSelectors are the composable query grammar for Context Nest. They let you precisely describe which documents you want — by tag, type, status, pack, node…
- Status LifecycleEvery document in a nest carries a status that governs where it is in its life and whether retrieval can see it. ContextNest uses a five-state lifecycle —…