Skip to content

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:

  1. Read-only consumer: lists and reads overlay files without changing them.
  2. Manifest reader: reads OVERLAY.md and overlay.cfg into the data model and validates them.
  3. Environment: builds an environment from env, env_files, paths and root variables.
  4. Runtime and setup: probes runtimes and runs setup.
  5. Integrity: computes tree digests and enforces pins.
  6. Resolver: resolves sources and dependencies in a deterministic order.
  7. Manager: installs, updates, removes and composes overlays.
  8. Store: lists overlays from catalogs, with their informational fields and icons.
  9. Hooks: runs hooks at a session's events, allowed by digest, and applies what they output.
  10. 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.