The open standard: three artifact specs

The leverage in a documentation platform is not its API. It is being the format other tools emit and consume. So what is offered as an open standard here is the artifacts — three of them, smallest first — and not the product.

This document is the outline of that standard as the specification decides it (D99, revision 24, with the program in Q3). The schemas themselves live in their own repositories, generated from the product's own type sources; this is the map of what they cover, what conformance means, and what an implementation that is not cuppy has to do.

A correction a reader coming from an older brief needs. The three specs are cuppy-document, cuppy-signal and cuppy-known-issues. They are not the hub layout, the document contract and the MCP surface: the command registry and the settings registry are the product and are versioned with it, and the hub skeleton beyond _boot/ and the folder card is a convention others may match rather than a standard. The reason is given below, because it is the most common thing to get wrong about this program.

1. The three specs

spec	the core object	extensions	producers	consumers
cuppy-document	the front matter: role, shape, short id, summary, covers, facets, depends_on, freshness, source	the six shape blocks, and x-<vendor> namespaced blocks	any docs-as-code repository, a control plane pushing release documents, a system pushing entity dossiers	any agent, any hub, and search engines through the raw document URL
cuppy-signal	a learning event: a retrieval, an outcome, an attempt, a note or a gap, with its kind, its points, its half-life and its context	custom kinds in a namespace	an agent client, a continuous-integration job, a hub	a hub, a reranker, an analytics store
cuppy-known-issues	the feed: a signature, what it means, the fixes, what it was fixed in, and whether the message misleads	vendor blocks	a hub, a vendor's continuous integration	an agent's error envelope, a dashboard

Why those three and in that order. cuppy-document is the one artifact two parties already want to exchange: a repository that writes front matter and a hub that serves it. cuppy-signal is the one artifact that makes a hub improve rather than merely store, and it is worth standardising precisely because the events come from clients nobody controls. cuppy-known-issues is the smallest useful public feed a vendor can publish, and the one with an obvious consumer that is not a hub at all.

2. What is normative, and what is informative

Normative — an implementation that does not do these is not conforming:

• The field set and types of each core object, as the published schema states them.
• The closed vocabularies: the five roles, the seven shapes, the four freshness

tiers (probed, sourced, crawled, asserted) and the status values.

• The freshness floor: an authored write stores asserted; only an executed

attempt or a vendor artifact may raise a tier, and a verifier field is written by the platform and never by an author.

• The extension rule: an extension block is namespaced x-<vendor> and carries its

own schema URL. An implementation validates a namespaced block it knows, ignores one it does not, and refuses an unknown block that is not namespaced.

• The pointer rule: a stored reference between documents is an id, never a path.
• The deprecation rule: a field is deprecated for one minor version before it is

removed.

Informative — described so an implementation can interoperate, not required:

• The folder spine beyond _boot/ and the folder card. Others may match it; it is

a convention, and reference/standard/hub-standard.md is where it is written down.

• The three depth rungs and their names. The rungs are how cuppy serves a document;

a conforming producer does not have to have depths at all.

• The retrieval design: the four stages, the fusion constant, the learned re-rank.

All product.

• The boot document's sections and budgets. A hub that has no boot document can

still emit conforming documents.

Explicitly not standardised, and this is the half that keeps the standard small: the command registry, which is cuppy's API; the settings registry; and the hub skeleton beyond the two names above. Standardising the product would be standardising one implementation's shape, which is the failure mode the program is designed to avoid.

3. How the standard versions itself

Three rules, and the specs are useless without them.

1. Every schema carries a $id URL with a semantic version, and the schema is

generated from the product's own type sources rather than written twice. A drift between the generated schema and the schema committed in the spec repository is a build failure, not a discovery made later by a reader.

1. An extension is namespaced and versioned on its own. A vendor adds a block

without colliding with anyone and without forking the core.

1. A field is deprecated for one minor version before removal, so a producer has a

release in which both spellings validate.

Added to those, two program rules from Q3: the specification changes only through its repository with a versioned changelog, and the platform never ships a format change the specification does not already describe. The second one is the expensive one to keep and the only one that makes the standard credible.

4. How a product other than cuppy implements it

A conforming producer has to do four things.

1. Emit front matter that validates against cuppy-document: the common fields, the

right shape block when the body is not plain markdown, no path in a pointer field, and asserted freshness on anything it authored itself.

1. Keep its own identifiers out of the id field. A short id is minted by the hub

that stores the document. A producer that has its own identifier carries it in a namespaced extension block, not in short_id.

1. Declare its extensions under x-<vendor> with a schema URL, so a consumer that

does not know the vendor still round-trips the document unchanged.

1. Emit signals for what it observes, not for what it believes. A retrieval, an

outcome and an attempt are events; a claim that a document is good is not one.

A conforming consumer has to do three.

1. Validate what it knows and ignore what it does not. An unknown namespaced block

is data to be preserved, not an error.

1. Round-trip unchanged. A document read and written back carries every block it

arrived with, including the ones the consumer could not interpret.

1. Respect the freshness floor. A consumer that re-serves a document may not

promote its tier.

Conformance is meant to be mechanical: a fixture set per shape, plus a validator command line (cuppy validate) that accepts every fixture and refuses a document carrying an unknown non-namespaced block. Neither exists in this tree yet — the software development kit and its validator are Phase 4 and 5 work, and nothing under apps/ or packages/ implements either, read by searching the tree at the base commit in this document's front matter. Treat the conformance kit as a proposal with a specified shape, not as something you can run today.

5. The honest position, and the bar for governance

The bar the program sets itself is a second producer, and it is not met. Stated plainly, against the case study in tracking/roadmap/research/2026-10-12-open-standard-positioning.md:

what a standard needs	where this one is
a core schema, versioned, outside the product	the core schema exists, is unversioned, and lives inside the product
an extension mechanism	present, and hub-only
more than one producer and consumer	one of each
a conformance kit	tests inside the product, not a kit
governance beyond one party	one owner

Two moves are cheap and are the next ones: the schema repository with versioned ids, which is one generation script over type sources that already exist; and the conformance kit, which is packaging fixtures that already exist. Everything after that waits on a producer nobody here controls. The two candidates available inside this build are a control plane publishing its release documents through a publisher credential, and a go-to-market system emitting entity dossiers the same way.

Donation to a foundation is considered only after two outside producers exist. That is a deliberate order: a standard donated before it has users is a document with a governance process attached, and the case study is the reason the order is written down rather than left to judgement.

6. What a reader should take from this document

If you are writing documents: write to cuppy-document, which in practice means writing to the front-matter contract in reference/standard/hub-standard.md. That is the whole of conformance for an author.

If you are building a tool that reads or writes hubs: the four producer rules and the three consumer rules above are the contract, and the extension rule is the one that decides whether your tool and someone else's can hold the same document without destroying each other's fields.

If you are deciding whether to depend on this standard: read section 5 first. One producer, one consumer and one owner is where it stands, and it is stated here rather than discovered later.

Next reads

• reference/standard/hub-standard.md — the spine and the front-matter contract the

document spec is drawn from.

• guides/sdk-and-transport.md — the client libraries and the two protocol eras, and

what is built versus specified.

• guides/skill-packs.md — what a hub compiles out of its documents, and the manifest

that makes a silent run auditable.

• reference/cuppy/tool-naming-standard.md — the naming rules on the product side of

the line this document draws.