---
title: "Aontu documentation"
description: "What Aontu is, how its documentation is organised, and a 30-second taste of unification."
source: "https://aontu.dev/docs/"
---

# Aontu documentation

Rendered from [`docs/index.md`](https://github.com/aontu-lang/aontu/blob/main/docs/index.md) in the engine repository — where a correction belongs, and where the test suite executes every example on this page.

Aontu is a JSON structure **unifier**: a small language (a purpose-specific dialect inspired by [CUE](https://cuelang.org/)) and an engine that merges partial structures into one consistent result, or reports exactly where they conflict. The same source can describe data, the schema that constrains it, and the defaults that fill it in — all in one notation, all combined by a single operation: _unification_.

This repository ships **two implementations kept in parity**:

-   **TypeScript** in [`ts/`](https://github.com/aontu-lang/aontu/blob/main/ts/) — the canonical implementation, published to npm as [`aontu`](https://npmjs.com/package/aontu).
-   **Go** in [`go/`](https://github.com/aontu-lang/aontu/blob/main/go/) — a port (`github.com/aontu-lang/aontu/go`) that mirrors the core semantics.

Both are checked against one language-agnostic test suite in [`test/spec/`](https://github.com/aontu-lang/aontu/blob/main/test/spec/).

## How this documentation is organised

The documentation is split by **what you are trying to do** when you open it. Reach for the part that matches your need:

| If you want to… | Read |
| --- | --- |
| **Learn** Aontu from zero by building something, step by step | [Tutorial](https://aontu.dev/docs/tutorial) |
| **Accomplish a specific task** you already have in mind | [How-to guides](https://aontu.dev/docs/how-to) |
| **Look up** exact syntax, semantics, options, or API surface | [Language reference](https://aontu.dev/docs/reference-language) · [API reference](https://aontu.dev/docs/reference-api) |
| **Understand** how and why the engine works the way it does | [Explanation](https://aontu.dev/docs/explanation) |

Tooling:

-   [The `aontu` command](https://aontu.dev/docs/reference-api#command-line-interface) — one binary and eleven verbs, in both implementations. `vet` validates data documents against a schema (and ships wrapped for CI as a [GitHub Action](https://github.com/aontu-lang/aontu/blob/main/vet-action/README.md)); `subsume` and `breaking` gate schema evolution; `get` and `why` ask an evaluated document what it says and what contributed to it; `set` changes one in an overlay, by appending or in place; `trim` reports redundant entries; `relations` runs the declared identity checks and `reaches` answers whether one entity reaches another at any remove; `jsonschema` exports the model as JSON Schema and names what the export cannot carry; `hash` pins what a document _means_; `mod` maintains a dependency closure; `agentsmd` writes the prose stanza for a definition. With no file, `aontu` starts a REPL.
-   [Language Server (LSP)](https://aontu.dev/docs/lsp) — the `aontu-lsp` diagnostics server (TypeScript and Go), how to wire it into an editor, and the reusable LSP library API.
-   [The MCP server](https://aontu.dev/docs/reference-api#the-mcp-server) — `aontu-mcp`, a Model Context Protocol server over stdio (TypeScript; the Go port offers the same calls as library API) answering with the identical reports the CLI prints.

For agents:

-   [The Aontu skill](https://github.com/aontu-lang/aontu/blob/main/docs/skill/SKILL.md) — an agent-facing teaching pack: the [grammar card](https://github.com/aontu-lang/aontu/blob/main/docs/skill/grammar-card.md), a [worked example ladder](https://github.com/aontu-lang/aontu/blob/main/docs/skill/examples.md) whose documents the test suite executes, and the [error-code index](https://github.com/aontu-lang/aontu/blob/main/docs/skill/error-codes.md). The `aontu agentsmd` verb generates the matching AGENTS.md stanza.
-   [The published grammar](https://aontu.dev/docs/reference-api#the-published-grammar) — [`grammar/aontu.gbnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.gbnf) and [`grammar/aontu.lark`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.lark), the emission surface for constrained decoding, held by a test to accept every canonical form the shared suite produces.

Contract:

-   [The trust contract](https://aontu.dev/docs/trust) — hermeticity, termination, determinism, and sandboxing: what a host may rely on when evaluating an Aontu document, exactly where each guarantee is conditional today, and the budget/cycle error taxonomy.

Two further documents support the project itself:

-   [Test coverage](https://github.com/aontu-lang/aontu/blob/main/docs/test-coverage.md) — how coverage is measured for both implementations, the current numbers, and where the gaps are.
-   [Shared test specification](https://github.com/aontu-lang/aontu/blob/main/docs/shared-spec.md) — the format of the cross-language `test/spec/*.tsv` suite.

Design notes (deeper analyses of specific behaviours and known defects) live in [`docs/design/`](https://github.com/aontu-lang/aontu/blob/main/docs/design/):

-   [Colon-chain nested `@"file"` import](https://github.com/aontu-lang/aontu/blob/main/docs/design/nested-import-colon-chain.md) — a since-resolved Go-port parity defect (fixed upstream in `@tabnas/multisource/go`) where a colon-chain imported value was dropped.
-   [The number model](https://github.com/aontu-lang/aontu/blob/main/docs/design/number-model.md) — how a numeric literal is classified and how kind travels through operators and canon: the pre-tower record, its rounding edges since reversed by the tower’s exactness rule.
-   [The number tower](https://github.com/aontu-lang/aontu/blob/main/docs/design/number-tower.md) — _implemented_: boru’s four-leaf number structure mirrored (`integer`, `float`, `biginteger`, `bigdecimal` under a pure-supertype `number`), the `0d` exact literals, the `lossy_integer_literal` exactness error, and where a unification lattice forces deviations from boru.

The design behind the verb surface lives in [`capability-review/`](https://github.com/aontu-lang/aontu/blob/main/docs/capability-review/index.md): the survey that asked what Aontu lacked in order to serve as a systems-definition ground truth for agents, with eight companion design documents (G1–G8) covering the constraint algebra, the validation verb, subsumption and schema evolution, identity and relations, the trust contract, distribution, the machine-facing access surface, and generation. Those documents argue and specify; what each verb actually does is in the [API reference](https://aontu.dev/docs/reference-api#command-line-interface), and what has been built phase by phase is recorded in the [progress register](https://github.com/aontu-lang/aontu/blob/main/docs/capability-review/progress.md).

The project site — [aontu.dev](https://aontu.dev), not yet live — is planned in [`site/`](https://github.com/aontu-lang/aontu/blob/main/docs/site/index.md): what it serves, and where each page’s content comes from (this documentation set is _rendered_ there, not rewritten). The steps that stand it up outside a session are in [`docs/site/manual-tasks.md`](https://github.com/aontu-lang/aontu/blob/main/docs/site/manual-tasks.md).

### Why the split?

The four kinds of document answer four different questions and are kept separate on purpose. A tutorial holds your hand and is allowed to omit detail; a how-to assumes you know the basics and just need the recipe; a reference is exhaustive and dry so you can trust it as the source of truth; an explanation is discursive and is the only place that argues about trade-offs. Mixing them — a reference that teaches, a tutorial that digresses into design rationale — serves none of those needs well, so each lives in its own file.

The rule applies to the toolkit as much as to the language, which is why a verb can appear in all four without any of them repeating another: met once, in passing, while the tutorial builds something; given as a recipe for one goal in the how-to guides; specified exhaustively — every flag, every exit code — in the API reference; and argued for, never merely listed, in the explanation.

## A 30-second taste

```plaintext
# A schema, a default, and data — unified into one result.
port:    *8080 | integer
host:    string
host:    "localhost"
```

Unifying the three lines above yields:

```json
{ "host": "localhost", "port": 8080 }
```

The `port` is constrained to be an `integer`, defaults to `8080`, and — because nothing overrode the default — `8080` is what comes out. `host` is constrained to a `string` and pinned to `"localhost"`. Conflicting facts (e.g. a second `port: "high"`, or a `port: 1.5`) would instead produce a precise unification error rather than a silent wrong answer: the preferred branch keeps the kind it names, which is [argued in the explanation](https://aontu.dev/docs/explanation#a-preference-is-gated-by-kind-not-by-family).

Try it without writing any code — both implementations ship an `aontu` command that evaluates a file or starts a REPL:

```sh
echo 'port: *8080 | integer' | node ts/bin/aontu.js   # or: go run ./cmd/aontu
```

Start with the [Tutorial](https://aontu.dev/docs/tutorial).