Publish the brand as data at stable addresses, with llms.txt as the rules for agents

Context and Problem Statement

The sites and the people and agents who build them need the brand as data, not as pages to read: which units exist and in which order, what colour and type each uses, which files are published and where. Until now Kanon carried a hand-written design section the sites copied from, and each site kept its own token file. Brand already generates units.json, manifest.json, tokens.json, contrast.json and fonts.json; what is missing is the contract (what each holds, that addresses never move, how they are served) and the rules in a form an agent reads before it writes a line of a site.

Decision Drivers

Criteria 1 (every claim traceable), 2 (one family), 7 (three languages) and 9 (generated and tested) of ADR-0009; the plan’s standard that the page and the file cannot disagree (ADR-0006).

Considered Options

• The generated JSON files plus a generated llms.txt, all at stable root addresses with CORS
• A single bundle (one JSON with everything) and no plain-text rules
• Keep the design section of Kanon as the agents’ source and link the JSON from it

Decision Outcome

Proposed: the first option.

• The files. /units.json (the register: units, categories, orders, each unit’s signature and text colour, AKRIBIS One’s ring geometry and spectrum), /manifest.json (every published mark file with its size and kind), /tokens.json (the whole system in DTCG: colour, typography, shape), /tokens/contrast.json (every declared pairing with its WCAG 2 and APCA values), /fonts/fonts.json (every font file: coverage, axes, features, metrics, the fit test) and /llms.txt. The CSS files of ADR-0015, 0020 and 0021 sit beside them under /tokens/.
• Stable addresses. A file may gain fields; it loses or renames one only by a decision. Web fonts carry a content hash in their name and the Office package the font version, so /fonts/* is cached for a year as immutable.
• Version. Every file carries its generation date (version or generated). Numbered versions and a changelog come with topic 5.4.
• Served to everyone. Access-Control-Allow-Origin: * on /tokens/*, /fonts/*, /tokens.json, /units.json, /manifest.json and /llms.txt, so a site on another origin loads the fonts and a tool fetches the data.
• llms.txt, generated by brand/src/llms.ts on every build, in English (the language of the records): a summary; how a site or tool uses the tokens and the marks and what it must never do; the rules of every topic, by section and number, with its status and the records that decide it (the specification for proposed and ratified topics, the open questions for the others); the register with brand ids and colours; the file index; the decision log with links. It names only addresses the build published; naming one it did not fails the build. It replaces the design part of Kanon, which will point here.
• Proof. The site’s own components read these files, so the page and the data are one. brand/test/data.test.ts checks that every file exists and carries its date, that llms.txt holds every topic, every proposed or ratified rule verbatim, every record and every unit, and that the headers grant CORS to each address.

Consequences

• Good, because an agent building any AKRIBIS site can start from one URL and get the rules, the ids, the colours and the files, as they stand on the day of the build.
• Good, because the sites stop keeping copies: the data has one home and one date.
• Open: a JSON Schema for the data files (units.json already names one that is not yet published); the rules in Spanish and Portuguese as well; numbered versioning (5.4).