Manifest¶
Core. An overlay MAY carry a manifest at its root, in one of two files:
OVERLAY.md, the standard form: the manifest is its front matter, and its body is the overlay's context;overlay.cfg, the same fields as a document of their own, for overlays written by tools.
A consumer MUST accept an overlay with neither; it reads as the empty mapping. An overlay with both
is refused, never merged (two-manifests), whatever either holds: two places to write a field is
the duplication this rule exists to prevent. Telling which is present needs the overlay's list of
files and neither file's content.
Status: dotagents 0.9.0, the reference implementation, reads
overlay.cfg.OVERLAY.mdis Proposed until an implementation reads it; see Compatibility.
A consumer that does not read OVERLAY.md yet MUST say so of an overlay that holds one, or refuse it:
applying it as an overlay with no manifest would silently drop everything its front matter declares.
Reading overlay.cfg¶
A reader turns the file's bytes into a value of the data model in these steps. The same steps apply to every other file AOS reads as a document, such as an env file.
- Byte-order mark. One leading UTF-8 byte-order mark (
EF BB BF) is dropped. Only one. -
Format line. If the remaining bytes start with
#!, the first line names the format:- the line runs to the first line feed (
0x0A), which is not part of it; - it is split on runs of space, tab, form feed and carriage return (so a carriage return before the line feed is whitespace), and the last word is taken;
- of that word, the part after the last
/or\is taken, leading.characters are dropped, and ASCII letters are lowercased; - the result is the format name:
#!json,#!/usr/bin/env yamland#!.TOMLnamejson,yamlandtoml.
The line, with its line feed, is removed before the rest is parsed; a parse error's line number still counts it. A line that yields no name (
#!alone, or only whitespace) is an error. 3. Default. Otherwise the format istoml, and the bytes are parsed whole. 4. No guessing. Nothing else selects a format: not the content ({,---,%YAML), not another marker, not the file's extension, not a retry with another parser. A document starting{without a format line is TOML, and fails as TOML. 5. Parse with the selected format's rules below, then check the result against the data model. - the line runs to the first line feed (
The text is UTF-8. Invalid UTF-8 is an error in every format. A byte-order mark where the parser's text starts (a second one, or one after the format line) is an error, since parsers disagree on it. A document whose remaining text is empty or only spaces, tabs and line breaks reads as the empty mapping, in every format.
Formats¶
| Name | Aliases | Class | Syntax |
|---|---|---|---|
toml |
Core: every reader MUST read it | TOML 1.0. A construct a later TOML adds (a newline or trailing comma in an inline table, the \e and \xHH escapes) is not portable: a reader either refuses it or gives it the meaning that TOML defines, and authors do not use it |
|
yaml |
yml |
Core: every reader MUST read it | Restricted YAML: YAML 1.2, one document, core schema |
json |
Optional Extension | RFC 8259 |
Both TOML and YAML are required. Front matter defaults to YAML, so nobody can read OVERLAY.md
without it; overlay.cfg keeps its own default of TOML, and an aos env file and a catalog named
by no extension follow it, so nobody can read those without TOML. Requiring YAML changes what a reader
can read, never what an unmarked document is: an overlay.cfg holding YAML still needs its #!yaml.
A reader MAY support further formats under names of its own. A reader that meets a format name it
does not support MUST refuse the document with an error that names the format; it MUST NOT fall back
to another format. An error names the format only when the name is ASCII letters, digits, -, _
and .; otherwise it says that the line names no supported format.
Static reading¶
Reading a manifest MUST NOT execute anything, read any other file, or consult the environment. Whatever library a reader is built on, it reads the manifest this way:
- No includes or imports. No directive pulls in another file or URL (
include,import,$ref,extends,!include). Such keys are ordinary data. - No interpolation or templating.
$NAME,${NAME},%(name)s,{{ name }}and<NAME>in a string are those characters. A field that gives a string meaning (a path relative to the root, a routing line, an env value's substitution) says so itself, and acts only when the declaration is applied. - YAML: only the restricted subset.
- JSON: a reader MUST refuse a duplicate key in one object, and the non-standard
NaN,Infinityand comments. - Libraries that offer includes, relative imports, variable expansion or templating (some general configuration readers do) MUST have those features off for AOS documents.
Restricted YAML¶
Wherever AOS reads YAML (front matter, a #!yaml document, a .yaml catalog) it reads this subset of
YAML 1.2, which a reader can build from a parser's events with nothing applied. Block and flow styles,
quoted and block scalars and comments are ordinary YAML, and stay.
| A reader MUST refuse | Class |
|---|---|
An anchor (&a) or an alias (*a), defined or not |
yaml-anchor |
A tag: !include, !!python/..., !!binary, !!str, a verbatim !<...>, the bare !, on a scalar or a collection |
yaml-tag |
A mapping key <<, in any scalar style and however it is written ("\x3c<") |
yaml-merge-key |
A directive: %YAML, %TAG |
yaml-directive |
More than one document, including content after a line ... |
parse-error |
U+0085, U+2028 or U+2029 anywhere in the text, which YAML 1.1 and 1.2 parsers split differently, and U+FEFF, which some keep in a key and others drop. As an escape in a double-quoted string ("\u2028") it is a character of the string |
parse-error |
A key that is not a string: a plain scalar resolving to another type (1:, true:), or a collection |
non-string-key |
Two keys equal once read, in whichever styles (a and "a") |
duplicate-key |
Nothing is expanded before it is refused. The size of a document with aliases is not the size of its text, so a reader refuses an anchor or an alias where it stands. A library that applies aliases, tags or merge keys and hands back the result cannot be checked afterwards, by which time it has done so: a reader builds on that library's parser events, or on another parser.
Typing is strict. A quoted or block scalar is a string. A plain scalar resolves by the YAML 1.2 core schema, and by nothing else:
| A plain scalar | Is |
|---|---|
empty, ~, null, Null, NULL |
a null, refused (null-value) |
true, True, TRUE, false, False, FALSE |
a boolean |
[-+]?[0-9]+, 0o[0-7]+, 0x[0-9a-fA-F]+ |
an integer, in decimal when it has a leading zero; outside signed 64 bits, refused (integer-range) without converting it, however many digits it has |
[-+]?(\.[0-9]+\|[0-9]+(\.[0-9]*)?)([eE][-+]?[0-9]+)? |
a float |
.inf, +.inf, -.inf and .nan, in the core schema's spellings (.Inf, .NAN, ...) |
refused (non-finite-float); +.nan is no core-schema float, and is a string |
anything else, yes, on, 2026-11-04, 1_000, 0b11 and 1:20 included |
a string |
The schema's types then hold as in every format: priority: "5" and priority: 5.0 are not integers.
Data model¶
The result of reading is a mapping whose keys are strings. Values are:
| Type | TOML | JSON | YAML |
|---|---|---|---|
| string | string | string | string scalar |
| integer, signed 64-bit | integer | number with no fraction and no exponent | core-schema int |
| float, finite | float | number with a fraction or an exponent | core-schema float |
| boolean | boolean | true / false |
core-schema bool |
| array | array | array | sequence |
| mapping, string keys | table | object | mapping |
A reader MUST refuse:
- a null (
null,~), anywhere, including in keys it does not recognise; - a TOML date, time or date-time value;
- a non-finite float (
nan,inf); - an integer outside the signed 64-bit range;
- a mapping key that is not a string, and two keys equal in one mapping;
- a string that is not valid Unicode (a lone surrogate escape in JSON).
Two documents in different formats are the same manifest when their data model values are equal.
A number's type follows how it is written, never its size: a JSON integer outside the signed 64-bit
range is refused, not read as a float. Where a field takes an integer, a float of equal value is not
accepted (30.0 is not 30).
Mapping order carries no meaning anywhere in AOS.
A reader MUST bound what it reads: a size in bytes and a nesting depth. Both are settings with
defaults (1 MiB and 64 are RECOMMENDED); there is no floor. The depth counts arrays and mappings: the
top-level mapping is at depth 1, and an array or mapping inside one at depth n is at depth n + 1.
The depth bound holds while parsing, in every format: text nested past it is refused (too-deep), and
a parser that recurses on its input MUST NOT reach the end of its stack first. A document of a few
hundred kilobytes of [ is within the size bound. Reading takes time and memory linear in the length
of the text, nesting included, so a refusal costs no more than reading: a parser that is slower than
that on deep nesting is preceded by a scan of its own that refuses nesting past the bound. An integer is
refused past 64 bits before it is converted.
OVERLAY.md¶
Core, Proposed. OVERLAY.md at the overlay root is the manifest and the context in one file, as
SKILL.md is for a skill. The name matches exactly: overlay.md and kb/OVERLAY.md are files like
any other.
---
name: release-notes
description: Conventions for release notes and changelogs.
requires: [engineering]
priority: 450
about:
summary: Release notes and changelogs, written the same way everywhere.
license: MIT
---
# Release notes
Write a release note for the reader who is deciding whether to upgrade.
- The same fields. The front matter holds the fields of
overlay.cfg,aboutincluded, as a value of the data model. The schema, validation and static reading apply as they do there. -
YAML unless it says otherwise. A first line inside the opening fence that starts
#!is a format line, with its rules; without one the metadata is restricted YAML. To YAML the line is a comment, so tools that know front matter still see front matter; a#!before the fence would be a line of text, and there would be no front matter at all.--- #!toml name = "release-notes" --- -
No front matter. A file with no opening fence has an empty manifest, and all of it is the body.
- A body is the context. A body holding anything but white space (space, tab, carriage return and
line feed, and nothing else) is the overlay's
contextdefault, instead ofCONTEXT.md. While it is context,CONTEXT.mdis ignored and reported (context-ignored) wherever it is named, incontextor a harness'scontext. A body of white space is no body, andCONTEXT.mdstays.[defaults] context = falseturns the body off as it wouldCONTEXT.md: nothing of the file is context,CONTEXT.mdmeans only whatcontextsays of it, and a body that is not context is not read. NamingOVERLAY.mdincontextnames its body and puts it there, as namingCONTEXT.mddoes. A body that is context is UTF-8 text, or the overlay is refused (invalid-utf8). - Digests do not change.
OVERLAY.mdis a member of the tree digest like any file, by its bytes. Its front matter and body are not hashed apart, and nothing in them is normalized first, so a file differing in line ends or a byte-order mark has another digest, though it reads alike.
The split¶
Splitting a document into metadata and body is one step, on bytes, before any parser and without
decoding. Reading the metadata is a second: a reader that wants only the body never parses. The same
split serves OVERLAY.md, a context file and a SKILL.md.
- Byte-order mark. One leading byte-order mark (
EF BB BF) belongs to the file, and is in neither the metadata nor the body. A second one is text. - Lines. Only a line feed (
0A) ends a line, and a carriage return directly before it is part of that line end. A carriage return elsewhere, a form feed, U+0085, U+2028 and U+2029 end no line, andLFandCRLFmay mix within one file. - Fences. A fence is a line holding
---or...from its first byte, followed only by spaces and tabs up to its line end.--- # note,---,----and---with a form feed are not fences, and a carriage return at the very end of a file, with no line feed, is not a line end. - Opening. The first line is the opening fence, and it is
---....closes and never opens. - Closing. The closing fence is the next line that is
---or..., whichever comes first. It may be the file's last line, with no line end. The split knows no format: a line---in a TOML multi-line string closes the block there. - Metadata and body. The metadata is every byte from after the opening fence's line end up to the closing fence. The body is every byte after the closing fence's line end. Neither is changed: no line end is normalized, no blank line and no later byte-order mark is dropped, and the body is not checked as UTF-8 until it is used as context. Normalizing is the caller's choice, after the split.
A reader tells these cases apart. A viewer shows a document to a person; a gate applies or validates it.
| Case | When | Manifest | A viewer | A gate |
|---|---|---|---|---|
none |
The first line is no opening fence, and the document does not look like one | empty | Shows the body | Accepts it |
malformed |
The first line is no opening fence, but after white space and byte-order marks the text starts with --- or ..., or a format line comes right before a fence |
Shows the text, all of it | Refuses: malformed-fence |
|
unterminated |
There is an opening fence and no closing fence, so no block | Shows the text, all of it | Refuses: unterminated-front-matter |
|
too-large |
The bound ended before the split did | Shows no metadata | Refuses: too-large |
|
empty |
The metadata is only white space, or a format line and white space | empty | Shows the body | Accepts it |
unknown-format |
A format line names a format the reader does not read, or none | Shows the metadata as unreadable text | Refuses, by name: unsupported-format, no-format-named |
|
does-not-parse |
The parser refuses it, or reading does | Shows the metadata as unreadable text | Refuses, by the reading class | |
not-a-mapping |
It parses to a sequence or a scalar | Shows the metadata as text | Refuses: not-a-mapping |
|
mapping |
It reads as a mapping | the mapping | Shows its fields | Applies the data model and the schema to it |
A malformed document is refused rather than read as one with no manifest, because the difference
is invisible (a space, a no-break space, a second byte-order mark) and the cost is silent: every field,
[defaults] turning off a script included, would be dropped, and the metadata sent to an agent as text,
while a laxer reader saw a block. A context file is only context, so for it the
case is none. A viewer splits by this rule, never by its Markdown renderer's own, so what it shows as
the body is what a gate takes as one.
Positions. Offsets count bytes from the first byte of the file, a byte-order mark included. Lines
count from 1 at the file's first line, whose opening fence is line 1, so the metadata starts on line 2
and a format line counts as one. A refusal names the file and the line, as OVERLAY.md:3, and the
column where the parser gives one (OVERLAY.md:3:5; columns are not compared across parsers, which
count them in different units). With nothing finer, it names the metadata's first line.
Bounds¶
The head is every byte from after any byte-order mark through the closing fence's line end. A
reader bounds it by a setting, 1 MiB by default, with no floor; a head past the bound is too-large,
and a refusal names the setting. A split reads nothing past its bound, not even to see whether a
closing fence follows, so an unclosed block past the bound is too-large rather than unterminated,
and a first line still possibly an opening fence when the bound ends is too-large too. The body does
not count, however long it is: it is bounded where it is used, as context. The
depth is a setting as it is for any document.
Why a block closes by --- or ...¶
Both, in one rule for every document, because YAML itself ends a document with ... and starts a new
one with ---, because a context file closed by ... must not start showing an
agent its metadata, and because a narrower reader and a wider one would otherwise disagree about where
the same file's metadata ends. The vectors hold every reader to the same line.
Validation¶
The JSON Schema at schemas/overlay.schema.json describes the
data model a manifest must have, in any format. JSON Schema cannot express every rule (an integer
field refusing a float, cross references, files that must exist); a validator checks those
semantically, as each section states.
The schema is the strict authoring profile. dotagents is more tolerant of ordinary fields: it replaces a value of the wrong type with the default, with a warning. A strict failure does not mean dotagents would refuse the overlay.
Unknown keys. Unknown top-level keys are allowed and MUST be preserved by a parser that exposes the document. A consumer MUST NOT act on an unknown key. Inside a table this specification defines, unknown keys are errors unless the table says otherwise.
A problem under about is reported like any other, and never makes a manifest invalid for applying:
about is informational only.
There is no manifest version field. The edition is a property of the specification, not of a manifest.
Fields¶
| Field | Type | Class | Default | Section |
|---|---|---|---|---|
name |
string | Core | the directory name | Package |
description |
string | Core | "" |
|
requires |
array of overlay names | Core | [] |
Dependencies |
routing |
array of strings | Core | [] |
Composition |
rules |
array of relative paths | Core | [], after the defaults |
Composition |
priority |
integer | Core | 500 |
Composition |
defaults |
mapping of default to boolean | Core, Proposed | every default on | Package |
context |
array of relative paths | Optional Extension, Proposed | [], after the defaults |
Context and harnesses |
skills |
array of skill names and tables | Optional Extension, Proposed | [], after the defaults |
Skills |
options |
mapping of option name to option | Optional Extension, Proposed | {} |
Context and harnesses |
env |
mapping of variable to env value | Optional Extension, Proposed | {} |
Environment |
env_files |
array of env files | Optional Extension, Proposed | [], after the defaults |
Environment |
paths |
array of path additions | Optional Extension, Proposed | [], after the defaults |
Environment |
env_scripts |
array of scripts | Optional Extension, Proposed | [], after the defaults |
Environment |
runtime |
mapping | Optional Extension, Proposed | {} |
Runtime and setup |
setup |
array of setup variants | Optional Extension, Proposed | [], after the defaults |
Runtime and setup |
scripts |
mapping of command name to script | Optional Extension | {} |
Commands |
mcp |
mapping | Optional Extension | absent | MCP |
hooks |
mapping of event to hook | Optional Extension, Proposed | {}, after the defaults |
Hooks |
harness |
mapping of harness id to hints | Optional Extension, Proposed | {} |
Context and harnesses |
knowledge |
mapping | Optional Extension, Proposed | absent | Knowledge through MCP |
about |
mapping of informational fields | Optional Extension, Proposed, informational | absent | Store metadata |
Eight fields have defaults that come from the overlay's files. They apply
first, the field's declared entries follow, and a declared entry naming the same file or directory
as a default entry replaces it (in hooks, one naming the same event); defaults turns one off.
Every field reads the same in OVERLAY.md's front matter as in overlay.cfg, hooks included. A field's class is the class of its
declaration; the class of each default is in that section.
A relative path is /-separated and relative to the overlay root, and every component of it:
- is not empty and does not end in
.or a space (so.and..are excluded, and so are names Windows silently shortens); - holds none of
\ : * ? " < > |, no control character (U+0000–U+001F, U+007F–U+009F), and no character that some filesystems ignore or that reorders text (U+200C–U+200F, U+202A–U+202E, U+2066–U+206F, U+FEFF); - is not, in any ASCII case, an excluded name or a Windows device name (
con,prn,aux,nul,conin$,conout$,comorlptfollowed by a digit or¹²³) with or without an extension, and does not end in.pycin any case; - holds no
~followed by a digit, the shape of a Windows short name.
No field names a manifest (manifest-file): overlay.cfg is named by none, and OVERLAY.md only
by context and a harness's context, where it stands for its body. Named as a rules file, an env file or
a script, a manifest's fields would be read, or reach an agent, as something else.
The schema's relPath expresses exactly this. A consumer resolves a relative path under the root
and opens it so that it cannot leave the root through a symbolic link, a junction or .. (for
example openat2 with RESOLVE_BENEATH, or a check of the opened handle's final path).
Core fields in dotagents¶
| Field | dotagents 0.8.3 |
|---|---|
name |
The directory name when absent, empty, or not a string. A sort and display tiebreaker; the installed identity is the directory name. |
description |
"" when absent or not a string. |
requires |
Non-strings and invalid names dropped with a warning; normalized and deduplicated in order. Used by add and remove. |
routing |
Non-strings and blanks dropped; surrounding newlines trimmed. Appended to the managed routing section. |
rules |
Each path's leading run of - ** bullets, up to the next ## heading, appended to the always-on rules. No default: an absent rules contributes nothing. |
priority |
500; a boolean is not an integer. Sorted ascending by (priority, name, directory). |
Examples¶
As OVERLAY.md, the form above. As overlay.cfg, TOML, its default:
name = "python-quality"
description = "Python review conventions and reusable checks."
requires = ["engineering"]
routing = ["- Python changes → `$PYTHON_QUALITY_OVERLAY_ROOT/kb/PYTHON.md`"]
rules = ["kb/always-on.md"]
priority = 420
[[paths]]
variable = "PYTHONPATH"
path = "lib/python"
position = "append"
The same manifest in JSON. The format line is required, since TOML is the default:
#!json
{
"name": "python-quality",
"description": "Python review conventions and reusable checks.",
"requires": ["engineering"],
"routing": ["- Python changes → `$PYTHON_QUALITY_OVERLAY_ROOT/kb/PYTHON.md`"],
"rules": ["kb/always-on.md"],
"priority": 420,
"paths": [{ "variable": "PYTHONPATH", "path": "lib/python", "position": "append" }]
}
And in YAML:
#!yaml
name: python-quality
description: Python review conventions and reusable checks.
requires: [engineering]
routing: ["- Python changes → `$PYTHON_QUALITY_OVERLAY_ROOT/kb/PYTHON.md`"]
rules: [kb/always-on.md]
priority: 420
paths:
- variable: PYTHONPATH
path: lib/python
position: append