Terminology¶
Overlay: a directory of agent configuration assets and, optionally, a manifest.
Overlay root: the overlay's top directory. Relative paths are resolved from it.
Identity: the name a consumer installs an overlay under, compared normalized.
Manifest: the optional metadata at the overlay root: the front matter of OVERLAY.md, or the
document overlay.cfg, never both.
Front matter: a block at the start of a Markdown document between a --- line and the next --- or
... line, split from the rest as Manifest says.
Body: the bytes of a document after its front matter.
Viewer, gate: a viewer shows a document to a person; a gate applies or validates it, and refuses what a viewer would still show.
Format line: a first line starting #! that names a document's format, or its front matter's.
Data model: the value a manifest reads as, the same whatever its format.
Default: what a file in a conventional place adds to a field without being declared, unless
the manifest's defaults turns it off; see Package.
Consumer: software that reads or exposes overlay assets. A consumer can be read-only.
Overlay manager: a consumer that locates, installs, updates, removes or composes overlays.
Harness: the agent program an overlay is given to.
Active overlays: the overlays a consumer applies to one session or process, after dependencies.
Composition order: the deterministic order in which active overlays contribute.
Env value: what env gives a variable: text, a path under the root, or a secret reference.
Placeholder: ${NAME} or one of its forms in an env value's text, substituted from the
environment being built when the variable is set; see Substitution.
Setup phase: what setup is told it is doing, install, sync or remove; see
Setup phases.
Sync: an operation of a consumer that brings an installed overlay up to date: fetching its
source again, changing its source, ref or pin, or running its setup again on request. Every sync
runs the sync phase.
State directory: a directory outside the overlay root, per identity and OS, where setup writes; kept across syncs and digests, deleted after removal.
Knowledge: the files of an overlay that its consumer serves to an agent by path through the knowledge tools; see Knowledge.
Format (of a knowledge file): what the first line of a markdown file, a shebang, names: aos (or agentic), the default, markdown,
md or raw (as written), envsubst, mustache (the real engines, with options) or a server's own; a file of one of the last three is a template, rendered when it is read; see Templates.
Hook: a script an overlay, or a scope's own configuration, runs at an event of a session; see Hooks.
Event: a named moment of a session at which hooks run, such as session-start or pre-tool.
Session: one run of a harness with an agent, from the moment it opens to the moment it ends.
Scope: a set of overlays a consumer installs and activates together, such as a user's or a project's. A consumer documents its scopes; AOS defines none.
Environment (of dependencies): a directory outside every overlay root where a runtime's packages are installed: shared in a scope, named, or isolated to one overlay; see Dependencies.
Secret reference: a provider and its fields, or a secret's name, that say where a value comes from; never the value.
Tree digest: the SHA-256 digest of an overlay's files, computed as Integrity defines.
Pin: a tree digest a consumer requires an overlay to have.
Non-default setting: a choice, declared by an overlay or made by a consumer, that is looser than the default and that a consumer reports.
Informational field: a field a store shows and nothing else reads: the about table and a
catalog's own fields; see Store metadata and catalogs.
Store: a consumer, or the part of one, that lists overlays for a person to find and install.
Catalog: a document listing overlays by name with their sources, for a store; a registry is a catalog in the minimal form.
Label: the name a consumer gives a catalog in its own configuration, which qualifies the names two catalogs share.
Reference implementation: dotagents, the implementation behaviour is compared against. AOS does not require it.
Conformance classes¶
An implementation states which of these it claims; see Conformance:
- Read-only consumer: lists and reads overlay files without changing them.
- Manifest reader: reads
OVERLAY.mdandoverlay.cfginto the data model and validates them. - Environment: builds an environment from
env,env_files,pathsand root variables. - Runtime and setup: probes runtimes and runs setup.
- Integrity: computes tree digests and enforces pins.
- Resolver: resolves sources and dependencies in a deterministic order.
- Manager: installs, updates, removes and composes overlays.
- Store: lists overlays from catalogs, with their informational fields and icons.
- Hooks: runs hooks at a session's events, allowed by digest, and applies what they output.
- Knowledge: serves the knowledge of the overlays active in a session to its agent over MCP.
A class includes another's obligations only when the implementation claims both.