Skip to content

Store metadata and catalogs

Optional Extension, Proposed. A store is a consumer, or the part of one, that lists overlays for a person to find and install, by name, summary, icon and tags, from one or more catalogs. This section defines what an overlay says about itself for a store (about), the catalog a store lists from, through which a consumer also resolves skill names, and what a store may believe of either.

All of it is informational, but for a catalog's skills, which a consumer that resolves skill names reads. A consumer that shows no store and resolves no names ignores this section and loses nothing: no field here changes what an overlay does.

Status: dotagents reads the minimal form of a catalog as its registry (see Sources and distribution). It reads no about table, shows no store and reads no icon.

Informational fields

about is a table of the manifest, in overlay.cfg as here or in OVERLAY.md's front matter:

name = "release-notes"
description = "Conventions for release notes and changelogs."

[about]
summary = "Release notes and changelogs, written the same way in every repository."
icon = "icon.webp"
homepage = "https://example.org/overlays/release-notes"
repository = "https://github.com/example/overlays"
license = "MIT OR Apache-2.0"
authors = ["Example Docs Team <docs@example.org>"]
tags = ["documentation", "release", "changelog"]
Field Type Meaning
summary line What the overlay is for, in one line, shown under its name in a listing
icon relative path A PNG or WebP image in the overlay; see Icons
homepage https URL A page about the overlay
repository https URL A page where its files can be browsed. It is not a source: nothing is fetched from it
license license expression The overlay's license
authors array of lines Who wrote it, as display text, conventionally Name <address>
tags array of tags Words a store filters and searches by
  • A line is a non-empty string with no control character (U+0000–U+001F, U+007F–U+009F), no U+2028 or U+2029, and no bidirectional embedding, override or isolate (U+202A–U+202E, U+2066–U+2069), which would let displayed text read differently from its characters.
  • An https URL starts https://, names a host, and holds no user information, white space or control character.
  • A license expression is an SPDX license expression: license identifiers (ASCII letters, digits, . and -, optionally followed by +) and LicenseRef- references, a WITH exception, joined by AND and OR with parentheses, AND binding tighter than OR. The operators are upper case. Parentheses nested past the depth bound make no expression. Whether an identifier is on the SPDX License List is not checked; a store MAY check it for display.
  • A tag is lowercase ASCII letters and digits in runs joined by single -, at most 32 characters; tags holds each tag once.

The Core fields stay where they are: a store shows name as the overlay's title and description as its long text, as plain text.

Informational only

  • Only a store and a validator read about; any other consumer MUST NOT. Reading the manifest still checks the data model everywhere, so a null inside about makes the manifest unreadable, as a null in an unknown key does.
  • Nothing in about changes composition, its order, activation, the environment, setup, dependencies, permissions, trust or the result of any other section. A consumer MUST NOT act on it, and MUST NOT give it to an agent as instructions.
  • A problem in about never stops an overlay from applying. A validator reports it, at a pointer under /about, like any other problem; a consumer that applies the overlay treats a manifest whose only problems are under /about as valid, and a store leaves out each invalid field.

about is a table this specification defines, so a key it does not define is an error to a validator, and a store leaves that key out.

Icons

icon names a file of the overlay by a relative path ending in .png or .webp, in any ASCII case. The file is a member of the tree digest like any other, and a validator that knows the overlay's files checks that it is there. No file is an icon by its name; only about.icon names one.

  • Formats. PNG (PNG, third edition) and WebP (RFC 9649). The content MUST be the format its extension names, told by its signature: 89 50 4E 47 0D 0A 1A 0A for PNG; RIFF, a size and WEBP for WebP, whose first chunk is VP8, VP8L or VP8X.
  • No SVG. SVG is not an icon format, and a .svg path is invalid. An SVG file is an XML document that can hold scripts, links, external references, fonts, styles and entity declarations; showing one safely means an XML parser that refuses entities and an allow-list of elements and attributes that every store would have to implement alike, for an icon that a 256-pixel raster already serves.
  • Limits. A store bounds an icon by settings with defaults: a size in bytes (512 KiB is RECOMMENDED) and a width and a height in pixels (1024 each are RECOMMENDED); there is no floor. It reads the dimensions from the header (PNG's IHDR; WebP's VP8 frame header, VP8L header or VP8X canvas size) and refuses an icon past a limit before decoding it.
  • Still and bare. A store shows an icon as a still image, the first frame of an animated one. It shows and follows nothing an image carries besides its pixels (text chunks, Exif, XMP), and MAY ignore an embedded colour profile.
  • Shape. Authors ship a square icon, 256 by 256 pixels or larger within the default limits; transparency is allowed. A store scales an icon to fit the space it gives it, keeping its aspect ratio, and never crops it.

A store refuses an icon, checking in this order:

Check Class
The path's extension is neither .png nor .webp icon-format
The file is larger than the size limit icon-too-large
The content has neither signature icon-format
The content is the other format icon-mismatch
The header cannot be read, or gives a width or height of zero icon-unreadable
The width or the height is past its limit icon-dimensions
The image fails to decode icon-unreadable

Missing or refused. When icon is absent or invalid, names no file of the overlay, or the file is refused, a store shows a placeholder of its own: an image it ships, or one it draws from the overlay's name. It never shows an image fetched from elsewhere or another overlay's icon in its place. It reports a refused icon where it reports other display problems, never as a problem of the overlay, which installs and activates as if it had no icon.

Catalogs

Optional Extension. A catalog is a document listing overlays and skills by name with the source of each, so a store can list and search them, and a consumer resolve a name, without fetching any. It is the registry that dotagents reads, extended: a registry is a catalog in the minimal form. A catalog can be a file in any directory or repository, or at a URL, and a consumer can be given several.

Reading a catalog

A catalog's file name (for a URL, the last segment of its path) selects its format, since existing registries are named by format:

  • .toml, .json, .yaml and .yml, in any ASCII case, name TOML, JSON and YAML. One leading byte-order mark is dropped and the rest is parsed whole: a first line #!... is not a format line (TOML reads it as a comment, JSON as an error).
  • Any other name (catalog.cfg, or none) is read as overlay.cfg is: a format line, else TOML. A catalog is never a front matter document: catalog.md is not read as OVERLAY.md is.

Everything else of reading holds: UTF-8, the data model, static reading, and limits on size and depth, as settings with defaults (4 MiB and 64 are RECOMMENDED, since a catalog lists many overlays).

A directory as a catalog

When a catalog's location names a directory (a directory of the machine, or a #path that is a directory of a Git repository or archive) instead of a file, the directory is a catalog in the minimal form: each immediate subdirectory is an overlay entry, named by the subdirectory, whose source is that subdirectory at the same location, and for a Git repository at the same ref. A manifest is optional for an overlay, so none is required. Files, and subdirectories a consumer does not read as overlays, are ignored. A subdirectory whose name is not a valid overlay name (.git, __pycache__) is skipped and reported (invalid-name), and two names that compare equal refuse both (duplicate-name), as in a file. A directory with no entry lists nothing, and a store says that the directory holds no overlays, not that no catalog was found. Such a catalog has no name, description, skills or full entry.

Entries and forms

name = "Example overlays"
description = "The overlays a team installs."
homepage = "https://example.org/overlays"

[overlays]
engineering = "../engineering"

[overlays.release-notes]
source = "https://github.com/example/overlays.git#release-notes"
ref = "4b825dc642cb6eb9a060e54bf8d69288fbee4904"
pin = "sha256:8280aaf5de7c4f61342f648586d534e481ae095cef223dded70f5b1db5bd84a1"
description = "Conventions for release notes and changelogs."

[overlays.release-notes.about]
summary = "Release notes and changelogs, written the same way in every repository."
icon = "icons/release-notes.png"
tags = ["documentation", "release", "changelog"]

[skills]
pdf = "https://github.com/example/skills.git#skills/pdf"

A catalog is a mapping with an overlays mapping, a skills mapping, or both:

Key Type Meaning
overlays mapping of name to entry The overlays the catalog lists
skills mapping of skill name to entry The skills the catalog lists, resolving a name an overlay gives without a source
name line The catalog's title, informational
description string What the catalog holds, informational
homepage https URL A page about the catalog, informational

Other top-level keys are allowed, kept and not acted on, as in a manifest. A document with neither mapping, including one that is itself a mapping of names to sources, is not a catalog (not-a-catalog). Where one is a mapping and the other is present and is not, the other is reported at its pointer and the catalog is read.

Each key of overlays is an overlay name, valid and compared normalized as identities are; each key of skills is a skill name, compared without regard to ASCII case. The two are listed apart, so one name can be both. A value, the entry, is either:

  • a string, the overlay's source: a minimal entry; or
  • a table, a full entry:
Key Type Meaning
source string Required. The overlay's source
ref string The Git ref, for a Git source written without @ref: a branch, tag or commit with no /, :, \, @, #, white space or control character, not starting with -
pin digest A tree digest the catalog's author reviewed
description string Informational, as the manifest's
about table The informational fields; its icon is a file beside the catalog

For a skill, the source is the skill's own directory, as a table in a manifest names it, and pin is its tree digest.

A full entry has no other key: an unknown key refuses the entry, since a misspelt pin must not install an overlay unpinned.

The forms are told apart statically, by the type of each entry in the data model, never by content, file name or another key: a string entry is minimal, a table full, and one catalog may mix them. A catalog whose entries are all strings is in the minimal form, which is what readers of today's registries read; one with any table entry is in the full form. The top-level name, description and homepage do not change the form.

Sources in a catalog

A consumer resolves an entry's source against the catalog's own location, the source it read the catalog file from.

  • A relative source is a directory location that does not start with /, \ or a drive letter and :. Nothing in it is expanded (~ is a name). It resolves:
    • for a catalog on this machine, against the catalog file's directory, with . and .. removed;
    • for a catalog in a Git repository (a Git source whose #path names the catalog file), to the same repository at the same ref, whose #path is the catalog file's directory joined with the relative location and its own #path, with . and .. removed. A path that leaves the repository refuses the entry (leaves-repository);
    • for a catalog at a URL, to that location resolved as a URL reference against the catalog's URL, keeping its own #path.
  • Any other source stays as written. A Git location written as a relative path (../other.git) is not defined by this edition: a catalog writes Git locations in full.
  • A catalog from elsewhere names nothing on this machine. In a catalog read from a Git repository or a URL, an absolute directory, a Git location that is a local path, or any file: URL, refuses the entry (local-source): a catalog chooses its own sources, and one naming a local path would install whatever the consumer's machine holds there. A host that is this machine, as a manifest's source defines it, is local too, and so is any location with a scheme before a path (file:/etc/x, javascript:x), which is never relative.
  • A catalog from elsewhere names a location that is neither Git nor an http or https URL (invalid-source), and holds no credential: a query, a password, or a user over the web refuses the entry (source-credentials). A catalog on the consumer's own machine is the user's, and may.
  • ref belongs to a Git source that has no ref of its own. A ref beside an @ref, on a relative source (whose ref is the catalog's), or on a source that is not Git refuses the entry (ref-not-allowed).

An entry's icon is a relative path resolved the same way, beside the catalog file; being a relative path, it cannot leave the catalog's directory.

What a store lists

A store refuses an entry, alone, and reports it, in overlays and in skills alike:

The entry Class
Its name is not a valid overlay name, or skill name invalid-name
Its name compares equal to another's in the same mapping of the catalog: both are refused duplicate-name
It is neither a string nor a table; a table has no string source, an unknown key, or a ref of the wrong form invalid-entry
Its source is not one (source form) invalid-source
Its pin is not a digest invalid-pin
Its ref is not allowed ref-not-allowed
Its relative source leaves the catalog's repository leaves-repository
A catalog from elsewhere names a local source local-source
A catalog from elsewhere names a source holding a credential source-credentials

An informational field that is invalid or unknown (the catalog's name, description or homepage; an entry's description; each field of an entry's about, or an about that is not a table) is left out and reported, and its entry is still listed. The whole catalog is refused only when it cannot be read or has no overlays mapping.

Several catalogs

A consumer may be given several catalogs. It gives each a label from its own configuration: a valid overlay name, unique among its catalogs when normalized, never taken from the catalog, since two catalogs can share a name.

  • An identity that more than one catalog offers is listed once per catalog, each shown qualified by its label as <label>/<name>. An identity that one catalog alone offers is shown by its name. A refused entry offers nothing.
  • Entries are never merged: not their sources, refs, pins or informational fields, even where they agree.
  • A user names an entry <label>/<name>, or by a name that one catalog alone offers. A name that more than one catalog offers is ambiguous: a consumer MUST NOT pick one by itself. It asks the user, or follows an order of catalogs the user configured for this, and reports which catalog it took.

Trust

A catalog is advertising. Its author writes its informational fields, and nothing makes them true: an entry can take another overlay's name, summary or icon, and a pin says only what that author reviewed.

  • A store MUST show each entry's source, without user information or query (as distribution says), beside its name and its catalog's label: the source, not the name, says where an overlay comes from.
  • Before fetching, a store MAY show the catalog's informational fields, as the catalog's. After fetching, the overlay's own manifest and tree are authoritative: what a store shows of a fetched overlay (name, description, informational fields, icon) comes from the overlay, and where the catalog said otherwise the catalog is wrong.
  • A pin in an entry is a pin. A consumer installing from that entry computes the tree digest of what it fetched before it installs, sets up or exposes anything of it, and refuses the overlay on a mismatch; when the user's configuration pins it too, both MUST match. The consumer records the pin it checked in its own configuration. An entry without one installs unpinned unless the user pins it, and is reported unpinned.
  • A catalog makes no overlay trusted. Fetching from a catalog is not installing; installing is the user's trust decision, as for any source.

Before installing

Before a consumer installs an overlay a store offers, it MUST show the user what the overlay would do, computed from the fetched overlay's manifest and list of files, after fetching and before activating, never from catalog claims:

  • the defaults present and on: bin/ and lib/ additions, the env file, and the env.<ext> and setup.<ext> that would run;
  • its env scripts, which run only once the user allows its digest; its setup, the variant that would run on this OS and its network need; its dependency files, their environments and whether each is pinned;
  • the overlays it requires, each shown and accepted the same way;
  • its context: the body of OVERLAY.md or CONTEXT.md, and a CONTEXT.md that is ignored; its routing lines and its rules files, which reach an agent too;
  • every skill it names from elsewhere, each with its source, the catalog that offered it, and whether it is pinned, every name that is missing or ambiguous, and every collision a skill would join, all accepted together with the overlay. These are shown before any of them is fetched; after fetching, each one's front matter keys and files are shown before it is delivered;
  • the variables it sets or adds to, the secrets and host variables it asks for, its MCP servers and its commands;
  • its hooks: each event, the script that would run, its match, timeout, on_failure and the variables it sets, what the event's payload tells it (the text of each prompt, a tool's input), each event the consumer cannot fire, or fires only in part, on the harnesses it serves, that a hook runs with the user's access and can read what the harness stores, and that they stay off until allowed at this digest;
  • every non-default setting activating it would report, unpinned included.

Nothing of the overlay runs to compute this: reading is static. A catalog field that seems to say any of it (a tag offline, a summary saying it runs nothing) is not evidence of it, and a store MUST NOT present it as such.