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
abouttable, 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+) andLicenseRef-references, aWITHexception, joined byANDandORwith parentheses,ANDbinding tighter thanOR. 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;tagsholds 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 insideaboutmakes the manifest unreadable, as a null in an unknown key does. - Nothing in
aboutchanges 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
aboutnever 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/aboutas 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 0Afor PNG;RIFF, a size andWEBPfor WebP, whose first chunk isVP8,VP8LorVP8X. - No SVG. SVG is not an icon format, and a
.svgpath 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'sVP8frame header,VP8Lheader orVP8Xcanvas 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,.yamland.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 asoverlay.cfgis: a format line, else TOML. A catalog is never a front matter document:catalog.mdis not read asOVERLAY.mdis.
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
#pathnames the catalog file), to the same repository at the same ref, whose#pathis 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.
- for a catalog on this machine, against the catalog file's directory, with
- 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
httporhttpsURL (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. refbelongs to a Git source that has no ref of its own. Arefbeside 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
pinin 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 reportedunpinned. - 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/andlib/additions, theenvfile, and theenv.<ext>andsetup.<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.mdorCONTEXT.md, and aCONTEXT.mdthat is ignored; itsroutinglines 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_failureand the variables itsets, 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,
unpinnedincluded.
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.