# Agentic Documents — A Short Field Guide
# Why Noma exists  [#why-noma-exists]

Markdown is excellent at the lightest end of the document spectrum. HTML is excellent at the rendering end. The space between them — structured documents that humans still want to read in source — is where Noma lives.

[CALLOUT tone="note"]
This book is intentionally short. It is the smallest set of ideas you need to use Noma productively, written in Noma so you can see the format defending itself.

[/CALLOUT]

## The three layers  [#why-noma-exists/the-three-layers]

Every Noma document has three layers stacked on top of each other:

[GRID columns=3]
[CARD title="Source" variant="info"]
What humans and agents edit. Plain text, clean Git diffs, stable IDs.

[/CARD]

[CARD title="Artifact" variant="success"]
What humans consume. Standalone HTML, PDF, EPUB. One file you can share.

[/CARD]

[CARD title="Agent context"]
What AI systems use. Deterministic LLM export, less noisy than HTML, more structured than Markdown.

[/CARD]

[/GRID]

The same source feeds all three. You write once; Noma renders into the form your reader needs.

## What you trade away  [#why-noma-exists/what-you-trade-away]

Noma asks you to learn two new pieces of syntax — ::block{attrs} for typed blocks and block-id for cross-references — in exchange for native layout, semantic blocks, validation, and an agent patch protocol. If your document is six paragraphs and a code fence, Markdown is still the right answer. If it has claims, evidence, plots, decisions, and a quarterly review task attached, Noma starts paying for itself by the third edit.

# The block model  [#the-block-model]

Noma documents are trees of typed blocks. Each block knows what it is, what it contains, and how it should render across HTML, PDF, and LLM context.

## Anatomy of a block  [#the-block-model/anatomy-of-a-block]

```noma
::claim{id="claim-living-docs" confidence=0.9}
Documentation rots faster than the code it describes.
::
```

The opener carries the type (claim), an attribute list (id, confidence), and the body content. The closer is a bare :: on its own line. Children get one more colon than their parent — :::card inside ::grid, ::::tab inside :::tabs.

## Why typed blocks matter  [#the-block-model/why-typed-blocks-matter]

A claim is not a risk is not a decision. The validator can reason about them differently — claims should have backing evidence, risks should have an owner, decisions should have a status. Themes can render them with different visual emphasis. Agents can patch them by ID without touching unrelated text.

[CLAIM id="claim-typed-blocks" confidence=0.82]
Typed semantic blocks are the smallest change to plain text that unlocks every downstream advantage Noma offers.

[/CLAIM]

[EVIDENCE for="claim-typed-blocks" source="dogfooding-april-2026"]
Across the three demo artifacts in this repo, every cross-cutting feature — validation, agent patching, deterministic LLM export, theme variants — falls out of the typed block model with no per-feature schema work.

[/EVIDENCE]

## The minimal block set  [#the-block-model/the-minimal-block-set]

You can do most real work with about a dozen blocks: section, paragraph, code, list, quote, table, callout, grid, card, claim, evidence, risk, agent_task. The rest are convenience.

# Edits agents can trust  [#edits-agents-can-trust]

The single most important question this format answers is: can an AI agent edit my document without breaking it?

The answer in Markdown is "sort of, if you're lucky." The answer in HTML is "no." The answer Noma is built to give is yes, by construction.

## The patch protocol  [#edits-agents-can-trust/the-patch-protocol]

Agents propose operations, not full-file rewrites. Five ops cover most editing flows:

| Operation          | What it does                            |
| ------------------ | --------------------------------------- |
| `replace_block`    | Swap a single block by ID               |
| `add_block`        | Insert a new block under a parent       |
| `delete_block`     | Remove a block by ID                    |
| `update_attribute` | Change one attribute on one block       |
| `rename_id`        | Move an ID, retargeting every reference |

```bash
noma patch thesis.noma --op '{"op":"update_attribute","id":"asml-euv-moat","key":"confidence","value":0.9}' --inplace
```

The CLI parses, applies, re-serializes via the source printer, and writes back. The unrelated 95% of the file is byte-identical to where you left it.

The patch protocol is the third leg of the-three-layers introduced in chapter 1: source, artifact, agent context. Without it, the agent layer is read-only.

## Why this matters  [#edits-agents-can-trust/why-this-matters]

[CLAIM id="claim-block-trust" confidence=0.88]
Trust in agent edits scales with the blast radius of each edit. Block-level patches make that blast radius small enough that humans will let agents touch real documents.

[/CLAIM]

[EVIDENCE for="claim-block-trust" source="user-research-2026q2"]
Across nine research-team interviews, the consistent objection to LLM-assisted document editing was "I don't trust it not to silently rewrite something I care about." Block-scoped patches with diffable output addressed the objection in every case.

[/EVIDENCE]

## Where to go next  [#edits-agents-can-trust/where-to-go-next]

```bash
# patch a real demo
noma patch examples/thesis.noma --op '{"op":"update_attribute","id":"asml-euv-moat","key":"confidence","value":0.95}'

# render this book to a single HTML page
noma render examples/book/book.noma.yml --to html --out dist/book.html

# pipe the LLM context to your agent of choice
noma render examples/book/book.noma.yml --to llm
```

[AGENT_TASK id="book-quarterly-review"]
Re-read this book once a quarter. If a paragraph still describes the format and CLI accurately, leave it. If the CLI has new commands or block types, file a replace_block patch op and a follow-up commit. The book is meant to age in lockstep with the code.

[/AGENT_TASK]