A document, as a structure everything can read.
CND (Context Native Document) is an open standard. It represents a compiled document as a tree of typed, cross-referenced pieces. Retrieval and context engineering use it directly, and it converts to other formats, adding metadata a plain export never carries.
- heading 1 Summary refs @budget-q3
- paragraph Q3 revenue grew 23% over Q2, see Table 1. Ads scale with reach (Lee, 2026). refs @budget-q3 cites @lee2026
- heading 2 Revenue refs @growth
- paragraph Growth is measured as in Equation 1. refs @growth
- math (1) growth = Q3 / Q2 − 1 label=growth
- figure Figure 1 Revenue by month. label=rev-chart
- image Bar chart of monthly revenue
- heading 3 Budget
- heading 3.1 By line
- figure Table 1 Budget by line, Q2 vs Q3. label=budget-q3
- table 4 rows × 3 columns
- code python · forecast(q4)
- terms CAC · LTV
- bibliography@lee2026
Why a structure, and not just text.
Retrieval pipelines recover a document’s structure after the fact, from the finished page. A CND never has to: the structure is written down when the document compiles.
Known, not inferred
Sections, figures and headings come straight from the source.
Whole pieces
A section with its heading path, an equation with its number, a listing with its language.
Readable at a glance
An agent reads the CND and sees the outline, the type of every piece and every reference.
Every kind of content keeps its type.
Ten node types carry the body of a document, in reading order. Two pools beside the tree hold what the text points out to.
- heading
A level, its number, and the path of headings above it.
- paragraph
Running text, with the references and citations it carries.
- table
Rows and cells, kept as a table, never flattened to prose.
- quote
Quoted material, apart from the voice of the document.
- code
A listing, with its language.
- math
An equation, with its number and its source.
- figure
The captioned, numbered float around a table, an image or a listing.
- image
An image, with its alternative text.
- list
Ordered or not, with nested items.
- terms
A definition list: each term, and what it means.
graphSoonNodes and edges, kept as a graph rather than a picture of one.
canvasSoonA free-form board of shapes, text and links, kept as structure.
bibliographyThe works the document cites.
footnotesThe notes its markers point to.
Links that survive a rewrite.
A piece can point at three kinds of target, and every link names its target by label. The label lives in the source, so it outlasts every rebuild; a link that names nothing, or the wrong kind of thing, is invalid.
- References From a piece to another piece: “see Section 2”, “as in equation (1)”.
- Citations From a piece to a bibliography entry, with its form and page.
- Footnotes From a piece to the note its marker opens.
Cosmyc goes further: a reference can point into another document of the workspace, as in #xref(<growth>). Typst on its own only references within one document; Cosmyc resolves the label across the workspace, keeps the link through rewrites, and every document shows what it cites and what cites it.
{ "type": "paragraph", "text": "Growth is measured as in Equation 1.", "refs": [ { "label": "growth", "text_span": [25, 35] } ]}- unchanged heading Summary
- added paragraph Ads now lead the budget.
- moved paragraph Growth is measured as in Equation 1.
- changed math growth matched by label
Reconciliation
The same piece, from one version to the next.
Every compile builds a fresh CND. Reconciliation pairs it with the previous build, so a piece keeps its identity across edits and moves, and you see exactly what was added, removed, changed or moved.
- By label: exact, even after an edit or a move
- By content and place: unchanged, where it was
- By content: unchanged, moved elsewhere
- By place and type: edited in place
Cosmyc reconciles every new version before indexing it: unchanged pieces keep their identity and are not indexed again.
How Cosmyc uses it
RAG, on a structure that was there from the start.
The CND is the standard; this part is Cosmyc. Every document in a workspace is indexed from its CND, so retrieval runs on material that was clean before it was ever cut, and agents receive context that keeps its shape.
How do we measure growth?
- Growth is measured as in Equation 1.
- Followed from the reference (1) growth = Q3 / Q2 − 1
-
Chunks cut on the document’s own lines
A chunk is a section under its heading. A figure stays whole, with its image, listing or table.
-
Chunks that know where they sit
Each chunk is indexed with the path of headings above it, and carries its labels and the references and citations it makes.
-
Meaning and exact words, together
A question is matched by what it means and by its exact terms at once, then the candidates are reranked so the passage that answers comes first.
-
Agents follow the references
When an agent retrieves a passage that points at equation (1), the equation comes back with it, placed right after the passage that cites it.
-
Documents linked to each other
A reference can point into another document by its label: every document shows what it cites and what cites it.
-
Only what you may read
Permissions filter every request before results are ranked, and are checked again before anything is returned.
Read in order, without guessing.
Reading order is the tree
Walk the tree depth first and you read the document exactly as it was written. No position field to trust or to drift.
Every heading knows its path
A section carries the chain of headings above it, so a result always says where it sits in the document.
Pages, when there are pages
Each piece records the page it starts on, the one layout fact the tree cannot tell you on its own.
One structure, every format.
A CND is not only for retrieval and context engineering. Because every piece is typed and labelled, it converts to other formats without guessing, and the conversion can add what a plain export never carries. The SDK ships Markdown and HTML converters; any tool can write another.
- Front matter Title, authors, date, keywords and language, read from the document itself.
- Content in its own form Tables stay tables, terms keep their definitions, code keeps its language.
- Notes and sources Footnotes and the bibliography written out, each marker pointing at its entry.
- References Every reference keeps the label of what it points at.
Cosmyc works this way: its agents read every document as enriched Markdown converted from the CND, and the Markdown export is the same conversion. See it in the overview
---title: "Q3 report"authors: - "Acme finance"date: 2026-10-01keywords: - "budget"description: "Revenue and budget, July to September"lang: "en"cnd_version: "0.4.0"built_at: "2026-10-01T09:00:00+00:00"---# 1 Summary[budget-q3]Q3 revenue grew 23% over Q2, see Table 1. Ads scale with reach (Lee, 2026).[budget-q3] [@lee2026]# 2 Revenue[growth]Growth is measured as in Equation 1.[growth]growth = Q3 / Q2 − 1*Figure 1: Revenue by month.*# 3 Budget## 3.1 By line| Line | Q2 | Q3 || --- | --- | --- || Ads | 12.4k | 18.9k || Events | 8.0k | 7.2k || Content | 4.1k | 6.6k |*Table 1: Budget by line, Q2 vs Q3.*```pythonforecast(q4)```**CAC**: Cost to acquire a customer.**LTV**: Revenue over a customer's lifetime.## Bibliography- **lee2026** — Lee, M. (2026). Reach and returns in paid acquisition.Open, and yours to take.
The specification, the JSON Schema, a corpus of reference fixtures and a command-line tool are public, under Apache-2.0. The format does not depend on Cosmyc: any tool can produce it, any tool can read it.
cnd validatecnd hashcnd diffcnd buildcnd inspect