Skip to main content
A reference is a deck the workspace keeps to make other decks from. It is a deck like any other: it has versions, files, an owner and share links. What makes it a reference is one line in its AGENT.md. An agent that authors a new deck fetches the reference, reads it, and builds the new deck from what it read. There are two types today:
  • A brand holds how the company looks and sounds: fonts, colours, backgrounds, shapes, motion and voice. Its pages show the brand applied, and its files carry the logo and the fonts.
  • A template holds the structure of a recurring deck: what the deck is for, which pages it has and how to fill them. Its pages are the model to copy.
brand and template are names for the same thing underneath. The API calls it reference.

​
The type comes from the file

The reserved AGENT.md at the root of the bundle (see Deck self-description) may start with a frontmatter: a YAML block between two --- lines, at the very top of the file. A frontmatter whose type is Brand or Template makes the deck a reference of that type. The match ignores case, and the API returns the type in lowercase. Every reference carries the same first fields: Then come the fields of the type. A brand has fonts, colors, background, shape, motion and voice. A template has purpose, pages and fill. Slideless stores every field as you wrote it. It reads type and nothing else, so the shape inside each field is yours to choose. The text under the frontmatter is the prose an agent reads. The frontmatter says what can be said in values. The prose says the rest: the judgement calls, the things never to do, where each file is. The frontmatter must close within the first 16 KB of the file, and it must stay under 16 KB once parsed.

​
A brand

​
A template

​
A frontmatter that cannot be used

The classification never refuses a push. When the frontmatter is malformed, too large, or names a type Slideless does not know, the push succeeds and the deck stays an ordinary deck. The push answer carries one sentence that says what was unusable, in version.referenceWarning, and the CLI prints it. For example:
Fix the file and push again. The next version is classified afresh. An AGENT.md with no frontmatter, or with a frontmatter that has no type, is an ordinary briefing. It raises no warning.

​
Existing decks

A deck is classified when a version is pushed. A deck that already exists stays an ordinary deck until its next push, even when its AGENT.md already carries a usable frontmatter. Push it once and it becomes a reference.

​
What the API returns

A deck carries three fields for this, on every read:
  • reference: the frontmatter of the current version as an object, with type in lowercase. It is null on an ordinary deck.
  • audience: private or workspace.
  • defaultReference: true or false.
Each version carries its own reference and referenceWarning, so the history shows what each push declared.

​
The audience

The audience says who in the workspace reads a reference. It is a property of the deck. It is never a field of the frontmatter, so nobody changes it by editing a file.
  • private is the default. The reference follows the ordinary deck rule: its owner, the workspace’s admins and owners, and the collaborators invited on it (Workspaces).
  • workspace opens the reference to every member of the workspace. They read the deck, its versions and its files. Nobody gains the right to push to it or to change it. Every version opens, the ones pushed before the switch included. Look at the history before you publish a deck that started as something else.
Guests do not read a workspace reference through the audience. A guest is someone whose only access is a collaborator invitation on one deck, and that invitation stays the way to show an outsider a reference. Whoever administers the deck sets the audience: its owner, or a workspace admin or owner.
The answer is the updated deck. The refusals:

​
The default reference

A workspace has at most one default reference per type: one default brand, one default template. The default is the one an agent takes when nobody names another. A workspace admin or owner sets it:
The rules:
  • The reference must have the workspace audience. On a private reference the call answers 409 audience_private. A default that most members cannot read would be of no use to them.
  • Setting a default clears the previous default of that type. There is no moment with two.
  • { "defaultReference": false } clears it. The workspace then has no default of that type.
  • A default reference cannot return to private while it is the default (409 default_reference). Clear the default, then change the audience.
  • Deleting a default reference is allowed. The workspace then has no default of that type.
  • On an ordinary deck the call answers 422 not_a_reference.

​
A project’s brand

A project can name one brand of its own, chosen among the references linked to it. An agent authoring a deck for that project reads the project’s brand instead of the workspace’s default. A manager of the project sets it, and the reference has to be linked to the project first. When a push takes the type: Brand line out of that reference’s AGENT.md, it stops being a brand, so it stops being the project’s brand at the same moment.

​
When a reference stops being one

Each push classifies the deck again, from the new version’s AGENT.md.
  • The new version has no usable frontmatter. The deck becomes an ordinary deck in that same push. Its audience returns to private and it stops being the default. A later push that brings the frontmatter back makes it a reference again, but a private one: someone has to choose the workspace audience again. A deck never reopens to the workspace through a file alone.
  • The new version changes the type, from brand to template or the other way. The deck keeps its audience and stops being the default, since it was the default of a type it no longer has.
The push answer says so. When a push takes the audience back to private or drops the default, the version’s referenceWarning carries a sentence that names what the deck lost, after the sentence on the frontmatter when there is one. The CLI prints it, so the person who pushed knows at once.

​
Duplicating a reference

A duplicate copies one version of a deck. When that version is a reference, the duplicate is a reference of the same type. It is private and it is never the default, whatever the original was.

​
Listing references

References leave the ordinary list. GET /api/v1/presentations with no type returns ordinary decks only. The type parameter lists references instead:
brand and template list the references of that type, and reference lists every reference. The list holds what you can read: your own references, the ones you collaborate on, and every reference with the workspace audience. Admins and owners see them all. Add default=true to keep only the default references:
The first call answers “which deck is the house brand” in one request. It returns one deck, or none when the workspace has no default brand. The second returns the default of every type: default=true with no type means type=reference. Agents connected over MCP have two tools:
  • slideless_list_references takes a type and lists the references of that type.
  • slideless_get_default_reference takes a type and returns the workspace’s default of that type.

​
From the command line

The CLI carries the same operations, in one real family and two shortcuts: slideless reference <verb> takes --type brand|template where the type matters, and slideless brand and slideless template are the same verbs with the type already chosen. Eight verbs: list, pull, new, push, publish, unpublish, default, start (References: brand, template). The everyday sequence:
  • An admin scaffolds a folder with slideless brand new, fills its AGENT.md and its pages, and pushes it with slideless brand push. That push is what classifies the deck as a brand, and it names the new deck after the frontmatter’s title: line.
  • The same admin opens it with slideless brand publish, so every member of the workspace reads it, and makes it the house brand with slideless brand default.
  • A member authoring a deck runs slideless brand pull with no name, which fetches the workspace’s default into .slideless/brand/ beside the deck, and reads .slideless/brand/AGENT.md before writing a page.
  • A deck that follows a template starts as a copy of it: slideless template start <ref> ./new-deck writes a fresh folder with the type: line removed, so the deck is an ordinary deck.
  • The push records what the deck was made from: slideless push --brand <ref> and --template <ref> write the references entries above, and a push with neither flag records whatever .slideless/brand/ and .slideless/template/ were pulled from.

​
Reusing a reference’s files

A reference’s files follow the reference’s rule: whoever reads the reference reads its files. So a member who reads a workspace brand can put its logo in their own deck without uploading it again. The push asks the instance which files it is missing, and the instance answers that the logo is already present. The bytes are stored once in the workspace (Versions). This holds for as long as you read the reference. A file of a reference you cannot read counts as missing, and the push uploads it.

​
Provenance

A deck made from references records them in its metadata, under references:
Each entry names the type, the reference’s deck id and the version that was read. The version matters: a reference keeps changing, and the entry says which state of it the deck came from. metadata is replaced whole on a PATCH, so keep references when you change another key (Deck self-description).

​
Nothing is applied automatically

Slideless never changes a deck because a reference exists. A default brand does not restyle the workspace’s decks, and a new version of a template does not touch the decks made from it. A reference is content that an agent fetches and reads. The deck that comes out is whatever that agent wrote, and it stays as pushed.