---
title: "How-to guides"
description: "Task-oriented recipes: each guide solves one job you already have in mind, and every example in it is executed by the engine's test suite."
source: "https://aontu.dev/how-to/"
---

# How-to guides

Each guide solves one task and assumes you know the basics: the [tutorial](https://aontu.dev/docs/tutorial) teaches those. Every example is executed by the engine repository's test suite before it reaches this page.

## Run, embed, and integrate

Getting aontu into your process or pipeline, and its answers out.

-   [Run a file or start a REPL](https://aontu.dev/how-to/run-cli-and-repl)

    Evaluate a file, read from stdin, or question a document interactively with the \`aontu\` command.

-   [Call aontu from TypeScript](https://aontu.dev/how-to/call-from-typescript)

    Embed the engine in Node with the \`Aontu\` class: parse, unify and generate from your own code.

-   [Call aontu from Go](https://aontu.dev/how-to/call-from-go)

    Embed the engine with the Go port: the same three calls, with errors returned instead of thrown.

-   [See the canonical form](https://aontu.dev/how-to/see-canonical-form)

    Print what a document means (defaults, disjunctions and all) instead of what it resolves to.

-   [Inject values from the host program](https://aontu.dev/how-to/inject-host-values)

    Fill \`$name\` variables from the calling program to parameterise a model from code.

-   [Give an agent an entrypoint to a definition](https://aontu.dev/how-to/give-an-agent-an-entrypoint)

    Generate a ground-truth stanza with \`aontu agentsmd\` and serve the verbs over MCP with \`aontu mcp\`.

-   [Collect errors instead of throwing](https://aontu.dev/how-to/collect-errors)

    Gather every problem in one pass with \`collect: true\` (TypeScript) or \`Check\` (Go) instead of stopping at the first.

-   [Read a conflict error](https://aontu.dev/how-to/read-a-conflict-error)

    What a conflict message names, in what order, and how to tell a conflict from an unresolved path.

-   [Wire your editor](https://aontu.dev/how-to/wire-your-editor)

    Connect \`aontu lsp\` to VS Code, Neovim, or any LSP client for diagnostics as you type.

## Templates, defaults, and composition

Building one model out of reusable parts.

-   [Provide defaults that callers can override](https://aontu.dev/how-to/provide-defaults)

    Write a default in a disjunction with the type an override must satisfy, and layer defaults by rank.

-   [Apply a template to many keys](https://aontu.dev/how-to/apply-a-template-to-many-keys)

    Use a \`&:\` spread entry to unify one template into every key of a map or every element of a list.

-   [Seal generated children deeply](https://aontu.dev/how-to/seal-generated-children)

    Close both the set of \`pack\`-generated children and each child's shape, or seal from the side with a hidden guard.

-   [Reference and reshape other parts of the document](https://aontu.dev/how-to/reference-and-reshape)

    Pull other parts of the document in by reference, extend them, and relocate them with \`move\` and \`copy\`.

-   [Keep schema and helper fields out of the output](https://aontu.dev/how-to/keep-schema-out-of-output)

    Mark schema and helper fields with \`type()\` or \`hide()\` so they constrain and compute without being generated.

## Schemas and constraints

Saying what data must look like, from optional keys to recursive shapes.

-   [Constrain every element of a list](https://aontu.dev/how-to/constrain-list-elements)

    Type every element of a list with a \`&:\` spread, and know why a bare \`\[string\]\` does not.

-   [Forbid unexpected keys](https://aontu.dev/how-to/forbid-unexpected-keys)

    Seal a map with \`close\` so a typo'd or invented key is refused instead of absorbed.

-   [Make a field optional](https://aontu.dev/how-to/make-a-field-optional)

    Suffix a key with \`?\` so a field that never receives a value is dropped instead of erroring.

-   [Name a reusable constraint](https://aontu.dev/how-to/name-a-reusable-constraint)

    Build a \`uint8\`/\`port\` vocabulary as a \`type()\`-marked block of ordinary fields.

-   [Define a recursive schema](https://aontu.dev/how-to/define-a-recursive-schema)

    Reference a definition inside itself to get a schema that applies at every depth of the data.

-   [Carry exact money over JSON](https://aontu.dev/how-to/carry-exact-money-over-json)

    Keep money exact inside aontu and cross JSON as a fixed-scale decimal string with a conversion mark.

-   [Export JSON Schema](https://aontu.dev/how-to/export-json-schema)

    Export a model as JSON Schema 2020-12 with \`aontu jsonschema\`, and read the loss report it owes you.

-   [Generate code from a model](https://aontu.dev/how-to/generate-code)

    Generate target-language source from a model: a rule set over the records, a component tree of files and lines, and \`aontu render\` to write the bytes and hold them against their goldens.

## Query, explain, and change

The model get, model why, model set and trim loop over a live document.

-   [Query a path](https://aontu.dev/how-to/query-a-path)

    Print one node of the evaluated document by path, or a keys, types, or depth-limited view of it.

-   [Explain a value](https://aontu.dev/how-to/explain-a-value)

    List every contribution that met at a path (which file, which line, which layer) with aontu model why.

-   [Change a value with an overlay](https://aontu.dev/how-to/change-a-value-with-an-overlay)

    Append a change to an overlay file with aontu model set, so the original document keeps its bytes and a bad change is refused before it lands.

-   [Gate an agent's changes by role](https://aontu.dev/how-to/gate-changes-by-role)

    Ask aontu allow whether a role may change a subtree before aontu model set writes it, with the answer read from a role model that is itself an aontu document.

-   [Change a pinned value](https://aontu.dev/how-to/change-a-pinned-value)

    Rewrite a pinned literal where the author wrote it with aontu model set --in-place, and know the cases where the verb appends instead.

-   [Find dead entries](https://aontu.dev/how-to/find-dead-entries)

    Report map entries whose removal changes nothing, so layered files do not silt up with lines a template already implies.

-   [Draw a model](https://aontu.dev/how-to/draw-a-model)

    Draw a model as a dependency tree, matrix or architecture layers with aontu view, and gate the committed figures in CI.

## Validate and evolve

The gate verbs: vet, breaking, relations, reaches and hash.

-   [Validate data in CI](https://aontu.dev/how-to/validate-in-ci)

    Run aontu vet in a pipeline so a document that does not hold fails the build, with the reason attached.

-   [Gate schema changes](https://aontu.dev/how-to/gate-schema-changes)

    Gate schema edits with aontu breaking, so a change that would refuse previously valid documents fails the review.

-   [Check that components agree about their relations](https://aontu.dev/how-to/check-relations)

    Declare a relation once at the field with rel(), acyclic() and inverse(), and have the whole model's edge set checked.

-   [Query reachability between entities](https://aontu.dev/how-to/query-reachability)

    Ask whether one entity reaches another over the declared edges with aontu reaches, and get the path as the answer.

-   [Pin what a document means](https://aontu.dev/how-to/pin-a-document-hash)

    Pin a document's meaning to one string with aontu hash, and detect when the meaning moves.

-   [Format a document](https://aontu.dev/how-to/format-a-document)

    Put a document in the agreed form with \`aontu fmt\`, gate a repository on it in CI, read what the formatter will and will not change, and point \`--lint\` at the style it never touches.

## Modules and multi-file

Splitting a model across files and vendoring a dependency closure.

-   [Split a model across files](https://aontu.dev/how-to/split-a-model-across-files)

    Load other source files with @"path" so a base model and its overrides unify into one document.

-   [Vendor a dependency closure for an offline build](https://aontu.dev/how-to/vendor-a-dependency-closure)

    Lock a dependency closure with aontu sync and commit aontu\_meta/vendor/ so a build resolves every import with no network at all.

-   [Vendor a module by hand](https://aontu.dev/how-to/vendor-by-hand)

    Bootstrap a module dependency with no repository to fetch from by copying its source tree into aontu\_meta/vendor/ and letting aontu sync pin what it means.

-   [Publish a package](https://aontu.dev/how-to/publish-a-package)

    Publish a package with aontu publish, gated on compatibility with the version before it, into a local repository that aontu pkg serve serves and aontu sync reads.