01 — Overview

Atto documents combine three layers into a single plain-text format. Markdown carries prose, LaTeX carries notation, and Atto directives carry structure. The parser walks them in order and produces a single deterministic Abstract Syntax Tree (AST).

Every .atto file is human-readable, git-diffable, and stable under round-trip serialization. Equal ASTs produce equal byte streams.

02 — Frontmatter

Frontmatter.

Every document begins with a YAML frontmatter block delimited by ---. Frontmatter declares document-level metadata: title, type, effective date, and any custom fields the document model accepts. Keys are serialized alphabetically on output.

Core fields

Example

---
title: Services Agreement
document_type: services_agreement
authoring_mode: hybrid
effective_date: 2026-04-23
jurisdiction: delaware
version: 1
---

03 — Sections

Sections.

Sections use standard Markdown headings, ## through ######. The parser tracks heading depth to build the section tree; heading text becomes the canonical section label. Top-level document title comes from frontmatter; body sections start at ##.

## Payment Terms

Client shall pay within 15 days of invoice.

### Late Fees

Overdue amounts accrue at 1.5% per day.

### Currency

All amounts are in USD unless otherwise stated.

04 — Inline Formatting

Inline formatting.

Standard Markdown inline syntax: **bold**, *italic*, `code`, and [text](url). Raw HTML is rejected — the parser does not pass through tags. If Markdown cannot express what you need, use a directive.

Example

Client shall pay within **15 days** of invoice.
See the [master agreement](https://example.com) for definitions, including *reasonable notice*.

Amounts invoiced under clause `3.1.a` are non-refundable once ~~delivered~~ accepted in writing.

05 — Inline LaTeX

Inline LaTeX.

Wrap an expression in single dollar signs: $…$. Renders in-line with surrounding prose at body text size. Dollar signs inside the expression must be escaped as \$.

Variables and operators

The late fee is $L = B \times 0.015$ per day.
Present value equals $PV = FV / (1 + r)^n$.

Greek letters and fractions

Interest accrues at rate $\alpha = \frac{r}{n}$ where $n$ is the number of compounding periods and $\beta \approx 0.05$ is the service margin.

Subscripts and aggregates

Total liability is bounded by $L_{max} = \sum C_i$ across all invoices $i \in \{1, \ldots, n\}$.

06 — Display LaTeX

Display LaTeX.

Wrap an expression in double dollar signs: $$…$$ on their own lines. Renders as a centered display block, isolated from surrounding prose.

Compound interest

The value after $t$ years of compounding:

$$
A = P\left(1 + \frac{r}{n}\right)^{nt}
$$

Summation

Post-money valuation aggregates pre-money plus all investment tranches:

$$
V_{post} = V_{pre} + \sum_{i=1}^{n} I_i
$$

Aligned equations

The late-fee calculation, written out:

$$
\begin{aligned}
L &= B \times r \\
  &= B \times 0.015 \\
  &= 0.015 B \quad \text{(per day)}
\end{aligned}
$$

07 — Directives

Directives.

Directives are typed semantic blocks. They open with ::name on a line by itself, close with a bare ::, and accept YAML-shaped content between. The parser validates directive names against a closed registry — unknown names are rejected at parse time.

::parties

Declares the parties to the document. Each party is a list entry keyed first by role, then name. Optional entity and jurisdiction attributes describe the legal form.

::parties
- role: Provider
  name: Baldwinson Corp.
  entity: delaware_corp
  jurisdiction: delaware
- role: Client
  name: Example Client LLC
  entity: llc
- role: Guarantor
  name: Atto Ventures
::

::signature-block

Declares one or more signatures. Each entry binds a party to a named signer with a sign_order. The Baldwinson Protocol layer enforces the order — signer 2 cannot countersign until signer 1 has.

::signature-block
- party: Baldwinson Corp.
  signer: Curtis Baldwinson
  title: CEO
  email: curtis@baldwinson.co
  sign_order: 1
- party: Example Client LLC
  signer: Jane Hart
  title: Managing Partner
  email: jane@example.com
  sign_order: 2
::

::attachment

References an external file by content hash. The document treats the attachment as part of its canonical content; the freeze event verifies every hash before emitting doc.freeze.

::attachment
label: Schedule A
uri: atto://attach/schedule-a.pdf
sha256: 4c1f...a7
media_type: application/pdf
bytes: 131072
::

::callout

A typed admonition. The tone attribute selects the visual and semantic treatment; an optional title gives the callout a one-line header. The body is parsed as Markdown.

All tones

::callout
tone: note
title: Definitions
Capitalized terms take the meanings given in §1.
::

::callout
tone: info
title: Reference
See the master agreement for fallback provisions.
::

::callout
tone: warning
title: Review Required
This clause applies only on quarterly distributions.
::

::callout
tone: danger
title: Irrevocable
Once executed, this waiver cannot be revoked without both parties’ written consent.
::

::review-anchor

Anchors a review thread to a specific AST node. Comments attach to the anchor by id, not to line numbers — edits around the anchor do not orphan the thread. The body is the content under review.

::review-anchor
id: late-fee-review
status: pending
assignee: counsel@example.com
tags: [legal, pricing]
The late fee calculation in §3.2 is pending counsel approval.
Current formula: $L = B \times 0.015$ per day.
::

08 — Serialization

Serialization rules.

Serialization is deterministic. Two ASTs that are structurally equal serialize to byte-identical output. The implications:

• Trailing whitespace is stripped on every line.
• Every block is separated by exactly one blank line.
• YAML keys in frontmatter and directives are sorted alphabetically.
• Line endings are LF, encoding is UTF-8.
• The final byte is a single newline.

This makes git diff reflect semantic change, not formatting drift.

09 — Abstract Syntax Tree

Abstract Syntax Tree mapping.

Each surface construct maps to a node type. The set is closed: the parser rejects unknown directives rather than silently passing them through.

document     → Document { frontmatter, children[] }
##...######   → Section { depth, title, children[] }
paragraph    → Paragraph { inlines[] }
**x**        → Strong { children[] }
*x*          → Emphasis { children[] }
`x`          → Code { value }
[text](url)  → Link { url, children[] }
$x$          → MathInline { tex }
$$x$$        → MathDisplay { tex }
::name       → Directive { name, attrs, body }

10 — MVP Scope

MVP scope.

The v0 parser implements the full set described above. The MVP runtime implements: frontmatter, sections, inline formatting, inline and display LaTeX, and the five core directives. Anything outside that set is a post-v0 extension.

The signing pipeline targets ::signature-block only. Other directives have no lifecycle effect in v0 — they render and serialize, but do not emit protocol events.