# 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](https://github.com/PromptOwl/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](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/status-lifecycle) and [Frontmatter](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/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](https://nest.promptowl.ai/d/promptowl-documents/protocol/concepts/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](https://nest.promptowl.ai/d/promptowl-documents/protocol/selectors/overview).

## 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](https://nest.promptowl.ai/d/promptowl-documents/protocol/versioning/integrity-verification). |

## Implementations

| Package | Description |
|---------|-------------|
| [`@promptowl/contextnest-engine`](https://www.npmjs.com/package/@promptowl/contextnest-engine) | Core engine (TypeScript) |
| [`@promptowl/contextnest-cli`](https://www.npmjs.com/package/@promptowl/contextnest-cli) | CLI tool (`ctx`) |
| [`@promptowl/contextnest-mcp-server`](https://www.npmjs.com/package/@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](https://github.com/PromptOwl/context-nest-spec) for guidelines.