# Declarative source contract
This document defines the current author-facing input to `agentic-report`. Agents write content and
semantic intent; they do not write JSX, templates with executable helpers, page layout, or browser code in
the page itself. What one design needs beyond the built-in vocabulary comes through the page
[extensions](#extensions) it declares.
The implementation behind this source contract is described in [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
Only the syntax below and the generated schemas are accepted.
## Source directory
The input is a Markdown file or a directory containing `report.md` or `index.md`. A source directory may
also contain one YAML/JSON manifest, confined English/Russian alternate Markdown entries, Markdown partials,
images, downloadable resources, and fonts. References are relative to the primary entry's canonical
directory. The compiler resolves symbolic links before reading contents and rejects a canonical target
outside that directory.
## Metadata
Metadata can be frontmatter or `agentic-report.yaml`, `agentic-report.yml`, or `agentic-report.json`.
Frontmatter takes precedence. Supported fields are:
- `contractVersion`: authored source-contract major; omission is interpreted as legacy major `1`;
- `title`: non-empty document title; when omitted, the first level-one heading or filename is used;
- `description`: plain-text metadata description;
- `language`: tag used on ``; the current accepted subset is a 2–8 ASCII-letter primary tag
followed by optional 2–8 character ASCII alphanumeric subtags; default `und` means undetermined. `ru`
and its subtags select complete Russian package-owned reader chrome; `en`, `und`, and every unsupported
language select complete English chrome on a single-language page. The package does not translate
authored Markdown or CLI diagnostics. Visible and accessible package-generated chart numbers use the
same selected locale;
- `localizations`: optional fixed object whose `en` and `ru` values are confined relative `.md` entry
paths. The primary entry must itself resolve to `en` or `ru`, may not repeat its own locale, and remains
the fallback. Every alternate must declare the matching `language`, use the same `contractVersion`, be a
distinct ordinary file, and may contain only `contractVersion`, `title`, `description`, and `language`
metadata. Presentation, output, `url`, and `image` settings come from the primary entry. An empty object, unsupported
locale, recursive localization declaration, canonical alias, or lexical/symlink escape fails before
publication;
- `url`: optional absolute `http`/`https` address the page is served from, without user name, password
or `#fragment`; it is normalized to its canonical URL form and never requested. With a URL the page head
carries ``, `og:type`, `og:url`, `og:title`, `og:description`, `og:locale` with one
`og:locale:alternate` per other embedded language, and a Twitter card, all taken from the primary entry.
A language tag with a two-letter region maps to `ll_TT` (`pt-BR` → `pt_BR`); `en` and `ru` without a
region map to `en_US` and `ru_RU`; other tags without a two-letter region and `und` get no `og:locale`.
Give a page served as a directory index its address with the trailing `/` (`https://example.com/guide/`),
because the social image address is resolved against it. A page with more than one language variant
also carries `` for each language and `hreflang="x-default"`, all pointing
at the same address, because the variants share it and the page picks one from the reader's languages.
Without a URL the head carries none of these tags;
- `image`: optional confined relative path to a PNG, JPEG, WebP, GIF, or AVIF social preview image. A
`directory` build with a URL writes it under `assets/` with a content-hash name and publishes the absolute
address as `og:image` and `twitter:image` with a `summary_large_image` card. A `single-file` build, or a
build without a URL, omits the image and reports `SOCIAL_IMAGE_NOT_PUBLISHED`. Another file type, or a
path that is not a regular file, fails with `INVALID_SOCIAL_IMAGE` at the `image` field, and a path that
leaves the source directory is refused like any other local reference;
- `data`: optional list of up to 16 confined relative paths to JSON files the page reads when it builds;
see «Page data» below. It belongs to the primary entry, and every language variant reads the same files;
- `theme`: a built-in theme name (`neutral` by default; the built-in themes with their intent and palette
are listed in the generated [authoring catalog](../../skills/agentic-report/references/catalog.md#page-metadata)
and by `describe` under `page.themes`), a confined relative path to a `.yaml`, `.yml` or `.json` theme
file, or a theme object in the frontmatter; see «Themes» below;
- `scheme`: `system`, `light`, or `dark`;
- `layout`: one of the page layouts listed in the
[authoring catalog](../../skills/agentic-report/references/catalog.md#page-metadata) (`document` by
default); `slides` turns the page into a presentation and `screens` into a page that moves one screen per
gesture, both described under «Page navigation and motion»;
- `motion`: `none`, `restrained` or `expressive` (default); how much the page moves, decided by the brief.
The build refuses a technique above the level with `MOTION_LEVEL_EXCEEDED` at the place it is written
(a recipe value is named with its recipe): `none` allows no entrance, scene, pointer effect, count,
cascade, `count-up`, `:swap`, `:typing`, `:mark`, `spotlight` or `seam="fade"`; `restrained` allows one
chapter entrance (`transition="log"` included), one pointer effect, and those counts and small in-place
movements, but no `scene="progress|steps|scrub"`, `draw="scroll"`, `pulse`, `zoom`, `demo` with `play`,
`transition="staged"`. The
level is written on the root as `data-motion-level`; `none` stills the page for the runtime like reduced
motion, and below `expressive` extension effects draw their still state (`reason: "motion-level"`);
- `schemeToggle`: boolean; default `true`; shows the reader's package-owned light/dark button;
- `themeSwitcher`: boolean; default `false`; adds a reader theme selector that swaps between the built-in
themes and the page's own theme live without changing the color scheme;
- `topbar`: boolean; default `true`; renders the package top bar (title, contents button, page controls).
`false` builds a page to be filmed as a scene: no `.topbar`, the root carries `data-topbar="none"`,
nothing is reserved above the content in any layout, theme, scheme, width, or print, and anchors, the
contents sidebar, and sticky or pinned elements measure from the top edge (`--topbar-clearance` is
15 px). The scheme toggle, language selector, and changes list go with the bar; `review` (or a prior
review sidecar) and `themeSwitcher` with `topbar: false` fail with `INVALID_MANIFEST`;
- `review`: boolean; default `false`; ships Review Workspace. A build given a prior review sidecar enables it
automatically;
- `extensions`: optional list of 1–32 unique relative paths to extension manifests (`.yaml`, `.yml`,
`.json`), confined to the source root; primary entry only. See [Extensions](#extensions);
- `progress`: `none` (default), `page`, `chapters`, or `nodes`; `page` is a decorative normal-motion reading
line, `chapters` a segment per chapter along the top bar that fills while the chapter is read and jumps to
it, `nodes` the same chapters as a row of nodes on one line — passed chapters filled, the current one
ringed;
- `opening`: `center` (default) or `start`; alignment of a landing page's title, introduction, and actions;
- `attribution`: boolean; default `true`; shows the package-owned footer link **Made with Agentic Report**
to `https://agentic-report.witqq.dev/`. Set `false` to omit only that footer; authored links and prose are
unchanged;
- `output.format`: `single-file` or `directory`;
- `output.maxInlineBytes`: positive size budget for resources embedded in one file; a single-file build above
it fails with `INLINE_SIZE_BUDGET_EXCEEDED`.
Run `agentic-report schema` for the exact accepted manifest-input schema and defaults. Defaulted fields
remain optional in the emitted JSON Schema because the compiler accepts their omission. Use
`schema --scope directives` for directive grammar and constraints, or `schema --scope source` for the
complete source-object schema. The ESM API exposes defensive project-owned projections through
`getAuthoringSchema(scope)`, `getSourceContract()`, and `listExamples()`; concrete Zod schemas remain an
internal implementation detail. The complete checked JSON form is
[`../generated/source-contract.json`](../generated/source-contract.json),
and [`../../examples/manifest.json`](../../examples/manifest.json) binds packaged example identities to
their source-file SHA-256 hashes.
A multilingual build compiles the primary and every declared alternate, including each variant's partials
and local assets, into one artifact. The browser chooses the first available `en`/`ru` primary language in
ordered `navigator.languages`, or the primary entry when none matches. A native language selector appears
only when the artifact contains multiple variants. Manual switching atomically changes ``, title,
description, article, navigation, package controls, visualization text/number formatting, review targets,
and response forms. Review threads, response drafts, and component state are restored only within their
locale during the current tab session. No locale choice uses storage, changes generated bytes, or triggers a
network request or browser-side compilation.
Primary `report.md`:
```yaml
---
title: Architecture decision
language: en
localizations:
ru: report.ru.md
layout: document
---
```
Alternate `report.ru.md`:
```yaml
---
title: Архитектурное решение
language: ru
---
```
The ESM `initProject({ destination, starter? })` operation initializes a registry-owned packaged starter
into an absent directory whose immediate parent is an existing directory. A symbolic-link parent is
resolved, and `projectPath` reports the resolved destination. It rejects
unknown starters, unsafe runtime option shapes, symlinks and special files, then fully reads the complete
local tree and verifies the registry entry before publication. The destination is claimed exclusively and
ordinary files use no-overwrite creation. Existing destinations are rejected unchanged. A later write
failure is structured and may leave the new destination incomplete; the operation never deletes or rolls
back its contents. CLI `init [--starter ] [--json]` adapts the same operation. Starter
eligibility and the single-default flag are registry metadata shared by discovery and init. There is one
starter per page category, named after it: `landing`, `document` (the default), `dashboard`, `answer`, and
`presentation`;
each tree holds `report.md`, its Russian alternate, and a `brief.md` whose table lists the category's
brief dimensions. A starter is also a buildable example; there is no separate generator contract.
`page.categories` in `describe` lists the five categories with their purpose, recommended layout,
subvariants, and brief dimensions, and every example in `examples` names its `category` and `subvariant`.
A category is a recommendation: the compiler never checks or restricts which directives, modes, or
effects a page of a given category uses.
The normal first-use path is `init`, edit the generated Markdown and local assets, run one `build`, and open
the resulting artifact through `file://`. Build runs the complete source and render preparation before it
publishes output, so neither `validate` nor `inspect` is a prerequisite. Use those read-only operations only
when their separate diagnostic or discovery result is useful.
The ESM `validateReport({ input, format?, review?, url? })` and `inspectReport({ input, format?, review?, url? })` operations use the
production source and render preparation without output publication. CLI `validate [input] [--format
] [--url ] [--json]` and `inspect [input] [--format ] [--url ] [--json]` are adapters of the same
functions. Validation reports resolved project/entry identity, output format, derived runtime placement,
and warnings. Inspection also reports sorted relative source files, the page `structure` (layout, motion level, media
shown before the first section, per section its resolved recipe, place, surface, motion attributes,
and media counts, and per card group its card, form, plain-card and linked-card counts, with no author text), observed directives and local-resource occurrence counts, and the
registry-derived command/format/starter/capability catalog.
`snapshot [input] --out [--widths ] [--schemes ] [--motion ] [--measure] [--json]` builds
the source into `/page.html` and photographs it through a Playwright installed beside the
package, then writes a contact sheet; with `--measure` it writes no pictures and reports one `measure`
record per width, scheme and motion instead (overflow, small text, contrast with opacity, covered text,
empty bands, clipped headings, first screen, stops, page errors, wide and sparse tables, the reading
column, code broken inside a word, diagram labels, off-scheme blocks). It never overwrites a non-empty destination. Both commands read
and validate all resources required by the selected format but do not create or replace an output artifact.
### Build from ESM
`buildReport({ input, output?, format?, review?, share?, url?, since?, manifestDefaults? })` is the publishing operation.
`BuildReportOptions.manifestDefaults` accepts the exported `BuildManifestDefaults` type with four optional
readonly fields: `topbar`, `schemeToggle`, `themeSwitcher` and `review`. Each accepts a boolean or
`undefined`; omission or `undefined` supplies no default for that field.
Resolution applies package defaults, then these caller defaults, then the project manifest, then primary
frontmatter. Explicit authored values, including `false`, win. Alternate language entries inherit the
resolved primary settings.
```ts
import { buildReport, type BuildManifestDefaults } from 'agentic-report';
const manifestDefaults: BuildManifestDefaults = {
topbar: false,
schemeToggle: false,
themeSwitcher: false,
review: false,
};
await buildReport({
input: './my-page/report.md',
output: './my-page.html',
manifestDefaults,
});
```
Use these defaults when a Node host has a page-control policy and authors must remain able to override
it. The compiler reads the original entry, partials and localized files without copying or rewriting
source, so source identity, diagnostics and review targets retain their authored paths. The option is
specific to `buildReport`; it is not a CLI flag or an authored metadata field. Unknown fields,
non-object values and non-boolean field values fail before source I/O with `INVALID_MANIFEST_DEFAULTS`,
without returning submitted values or keys. The resolved settings still undergo normal manifest checks:
for example, `topbar: false` cannot combine with enabled Review Workspace or `themeSwitcher: true`.
`url` and CLI `--url ` on `build`, `validate` and `inspect` override the manifest `url` with the same validation
and fails with `PUBLIC_URL_INVALID` otherwise. A page with a public URL whose HTML exceeds 2,097,152 bytes,
the part of an HTML file Googlebot reads, reports `PUBLIC_PAGE_OVER_CRAWLER_LIMIT` with the measured size;
directory output keeps images, fonts, styles, and the runtime out of the HTML and removes that risk. `share: true`, or
CLI `build --share`, neutralizes compiler-owned workstation source links before serialization in either
output format. `BuildReportResult.share` identifies the selected profile and
`neutralizedSourceLinks` is the exact transformed-node count; human output prints the count for a share
build. The option does not rewrite source and is intentionally absent from validation and inspection.
## Review protocol and source binding
A build with Review Workspace enabled (`review: true` or a prior review sidecar) embeds an inert version-2
review manifest in a `template` element; a build without it carries no manifest. Container directives
that produce a final DOM owner and ordinary Markdown blocks receive deterministic review-target identities;
structural chart `series` data is reviewed through its owning chart rather than a removed intermediate node. Each target records its kind,
SHA-256 fingerprint, source-root-relative entry or partial path, and authored range. A section with an
explicit `id` also receives a stable review key. The manifest never contains source bodies or absolute
workstation paths.
The manifest `reportRevision` is a SHA-256 identity over the complete confined local input graph used by the
report—entry, metadata, expanded partials, theme and data files, every file of the declared extensions
(manifests, templates, styles, effect modules, island entries and assets), and referenced local resources—plus the target-manifest version,
source-contract version, target-algorithm version, and canonical target inventory. It is independent of output destination
and `single-file` versus `directory`; `BuildReportResult.contentHash` remains the hash of the serialized
output HTML and is a separate contract.
A single-language review artifact is strict version-3 JSON with a bound report revision. A multilingual
artifact is strict version 4 and additionally requires `report.locale` to be one of the report's declared
`en`/`ru` variants. Both forms allow at most 500 threads and at most 500 messages. Each thread owns ordered
revision segments; every segment binds one report revision and target to its messages and resolved boolean.
A selected-text segment additionally stores `selection.start` and
`selection.end` boundaries, each with a complete deterministic target reference and a non-negative Unicode
code-point offset, plus the bounded NFC `selection.quote`. The segment target must equal the start target.
This represents an exact range inside one target or across multiple targets without copying whole source
blocks. A whole-block thread omits `selection`. Valid closed version-2 whole-block artifacts are accepted and
normalize losslessly to version 3; version 2 never accepts selection fields. Legacy v2/v3 input against a
multilingual report routes to a unique exact revision when possible and otherwise to the primary locale.
Version 4 routes by locale before target binding, preserves fully missing stale targets in that locale, and
rejects an undeclared locale instead of substituting another source.
Changed continuation appends a current segment while historical segments remain immutable. Selection
endpoint targets bind independently; if either endpoint changes, disappears, or becomes ambiguous, the
aggregate thread reports that state and preserves the old quote as historical evidence instead of guessing
new offsets. Serialization sorts thread identities while preserving segment and conversational message order
and adds no clock or random field. Messages are trimmed and normalized to Unicode NFC before length
validation, while selected quotes preserve their meaningful whitespace after NFC normalization. Review text
is local potentially sensitive data and must be handled like report source.
Use the read-only ESM operation or CLI adapter:
```sh
agentic-report review ./review.json ./my-report --json
```
```ts
const result = await inspectReview({ input: './my-report', review: 'review.json' });
```
The review path is resolved relative to the prepared source root and cannot be absolute, traverse outside,
escape through a symlink, or alias an entry, manifest, included partial, referenced local resource, or
output identity by canonical path or hard link. An exact bound revision requires the exact target identity and fingerprint. For
a stale revision, an explicit stable key resolves first. Otherwise a unique target at the same authored
source origin (file, line, and column) resolves there; a changed fingerprint returns `changed` even when an
equal block exists elsewhere. Fingerprint relocation is considered only after the original origin is absent.
A unique cross-file match is considered a move only when the previous source file no longer contributes any
current review target. Zero matches return `missing` and multiple matches return `ambiguous`. The operation
does not rewrite Markdown or publish output.
Structured thread and message fields are bounded and credential-sanitized before CLI/ESM transport; surrounding source and
complete input files are never returned.
## Editions and changes
Every page carries, in each language version, an inert `` with the edition
record: contract version 1, `locale`, `edition` (1 without `--since`), `reportRevision`, the sections
(`id`, `authoredId`, `title`, `order`) and every block in reading order — its section, kind, optional
`stableKey`, and its visible text normalized to NFC with any run of spaces as one space: `text` for prose,
`rows` for a table, `items` for a list, `lines` for code, `nodes`/`edges` for a diagram (its caption in
`text`), `points` for a chart, `media` (`digest` of the image bytes and `alt`). The record holds no paths
and no time, so the same source still gives the same bytes; it is limited to 2,000,000 bytes and 5,000
blocks and counts against `output.maxInlineBytes`. A page built with `--url` carries no record.
`build`, `validate`, `inspect` and `snapshot` accept `--since ` (`since` in the ESM options): the
previous page (`.html`, or a directory with `index.html`, read up to 64 MB) or its source (`.md` or a
source directory, built in memory by the installed package). The path is a command-line argument like
`--output`, not confined to the source root; it may equal `--output` because it is read before
publication, and it may not be a file of the current source (by path or hard link). Sections pair by
authored `id`, then by shared blocks (Jaccard 0.5) and title; blocks inside a pair by explicit `id`, then by
identical content, then by word similarity (Dice 0.5); a unique removed and added pair with equal content
is a move. Prose differs word by word (`Intl.Segmenter`, Myers), code by lines, tables by rows (first cell,
then position), lists by items, diagrams by node `id` and edge ends, charts by series and label. A block
with more than 60 % of its words changed is shown replaced. Only what the reader sees counts: kinds of
spaces, presentation attributes and source file layout do not. The comparison is mechanical and judges
nothing.
With `--since` the page carries the change layer: an edition strip after the title and intro (on the title
slide or first screen of `slides` and `screens`) with the «Show changes» switch (on when opened,
remembered only for the session), previous and next, and the list; a «Changes N» topbar button with the
list grouped by section (a panel on wide screens, a bottom sheet on phones; links go to `#/n` in slides);
a dot at changed sections in the contents; a label and margin bar on changed blocks; `ins` and `del` inside
prose, cells and items; changed code lines; removed blocks as collapsed ghosts with the old text; moved
blocks with a link at their old place. Every node the layer adds is marked `data-edition-removed`: the
switch hides it with `display: none`, the Review Workspace offsets and quotes skip it, and the code copy
button copies only the new code. Colours come only from `--status-done`, `--status-review` and
`--status-returned`, always doubled by underline, strike-through or a word; forced colours use system
colours, reduced motion drops the jump highlight, and print follows the switch with ghosts open.
`build` and `inspect` results with `since` carry `changes`: `locale`, `since` (`edition`,
`reportRevision`), `edition`, `unchanged`, `totals` (`unchanged`, `changed`, `added`, `removed`, `moved`)
and `sections` with `id`, `title`, `status`, `renamedFrom`, `moved` and `blocks` (`kind`, `status`,
`source` of a new block or `previousOrder` of a removed one, `words` for prose, `movedFrom`). No block text
enters any result. Diagnostics: `EDITION_SINCE_UNREADABLE`, `EDITION_SINCE_COLLIDES`,
`EDITION_RECORD_MISSING`, `EDITION_RECORD_INVALID` (with `details.issues`), `EDITION_VERSION_UNSUPPORTED`
are errors; `EDITION_UNCHANGED`, `EDITION_LOCALE_ADDED`, `EDITION_REMOVED_TEXT_SHARED` (with `--share`) and
`EDITION_RECORD_OMITTED` (a record over its limit) are warnings.
### Review Workspace reader interface
Review Workspace ships only when `review` is `true` or a prior review sidecar is supplied; otherwise the page
carries no review manifest, topbar action, or annotation layer. When an enabled report contains review targets,
annotation is always available and its topbar includes `Review`; there
is no activation mode, target outline, block button, or exit action. Selecting eligible rendered text exposes
one localized **Create note** action beside the native selection. Activation snapshots the range and opens a
compact anchored popover containing the exact quote, message history, compose/edit actions, and resolve or
reopen. The range may stay inside one review target, cross nested inline markup, or end in a later target.
Both endpoints must belong to the same report article. Empty, whitespace-only, oversized, outside-report,
reversed, package-control, or unreconstructable ranges expose no action or fail import without replacing
current state. Releasing `Shift` after a keyboard selection focuses the action; pointer and touch selection
use the same captured state.
On desktop, the popover prefers the right or left of its anchor, then centers above or below when neither
side fits; every placement shifts/clamps within the visual viewport and its height is bounded so the thread
remains scrollable without moving the report. On mobile it becomes a bounded bottom surface inside the
visual viewport. Selection actions, saved-range markers, and the thread popover
recalculate from both window and `visualViewport` scroll/resize signals, so browser chrome and the on-screen
keyboard cannot strand them off screen. The contextual action and focus markers measure their complete
surface, clamp against a visible rectangle from the live range, and hide when the range is wholly offscreen.
A saved-range marker prefers a fully separated position above the range, then below it, before edge clamping;
this keeps direct marker activation distinct from tapping the highlighted text. Navigation, Review, language,
theme, and scheme controls use distinct package-owned topbar icons — 20 pixels for Review, language, theme
and scheme, 16 for navigation — with localized accessible names and title tooltips. The
native language selector remains the locale input and receives visible focus after switching. At constrained
widths visible labels and secondary page identity are omitted without imposing a document minimum width, and
coarse pointers receive larger targets. Visible contextual/action controls retain localized labels and use
16-pixel icons; Create note shows a pencil and View thread shows a comment.
The inert manifest contains at most 5,000 targets and at most 750,000 serialized bytes. These are independent
bounds, so verbose relative source locations can make the byte ceiling bind before the target count. Target
validation receives the count bound from the Node-side compiler; the shared browser-safe review contract
contains no environment-variable lookup.
The interface supports one thread per subject: one whole-block subject plus multiple distinct selected ranges
may coexist on the same target. Threads retain ordered user and agent messages, message editing, and
resolved/reopened state. Each exact current selection stays highlighted, with distinct open and resolved
treatment. Hover or tap on a highlight exposes **View thread**; its focusable overlay marker supplies the
keyboard route. Selecting the exact saved range also exposes **View thread** rather than a second create path.
Overlapping highlights choose one deterministic most-specific thread, and the full lifecycle continues in the
same anchored popover.
The topbar `Review` action opens only an overlay list of every current thread and prior evidence plus import
and one all-thread export. Choosing a current or bindable prior entry closes the list, brings its target into
view, and opens the same popover. Desktop uses a non-modal right overlay; mobile uses a native modal bottom
sheet. Neither changes report width, margin, scroll ownership, or authored DOM flow, and closing returns
focus to the visible Review action after list-origin navigation. Existing valid version-2/version-3
whole-block discussions remain list-accessible, but new threads are created only from text selection.
Canonical `review.json` download exports all whole-block and selected-text threads for the active locale
together: version 3 for a single-language page or version 4 with `report.locale` for a multilingual page.
Exact-revision import validates every current target, offset, range order, and quote against the rendered DOM
before swapping state and immediately restores valid selection highlights. It rejects oversized, malformed,
version-1, stale, foreign, non-current, or mismatched selected-text data without replacing active state;
valid version-2 whole-block import remains supported. On a multilingual page, import and current state are
isolated by locale; switching away and back restores only that locale's threads. Review state is session-only
and never written to browser storage, URL, network, or report source. Message authorship is descriptive
rather than authenticated.
The root metadata value and `output` must be objects; scalar and array shapes fail instead of being
silently replaced by defaults. Validation diagnostics point to the actual manifest or frontmatter field
range that supplied the failing value.
Defaults are `layout: document`, `theme: neutral`, `scheme: system`, `schemeToggle: true`,
`topbar: true`, `themeSwitcher: false`, `review: false`, `progress: none`, `opening: center`, and `attribution: true`.
### Themes
A theme is typed data from which the package generates the page stylesheet; the static package stylesheet
reads only the variables and root attributes the theme produces and never selects a theme by its name. A
theme file and a theme object share one schema (`agentic-report schema --scope theme`, `docs/generated/theme.schema.json`).
The same schema lists the public token vocabulary under `x-agentic-report-tokens`: every CSS variable a theme
declares, by group, with the field it comes from. Package styles, runtime effects and extensions read only
these tokens; `tests/unit/theme-tokens.test.ts` fails when a theme declares a variable outside the vocabulary,
when a token is read by nothing, or when a stylesheet or renderer names a colour of its own. The fields:
- `name`: theme identity for the theme selector; a file defaults to its file name, an inline theme to
`custom`; a built-in name is refused (`THEME_NAME_TAKEN`);
- `extends`: a built-in theme name or a confined relative path to another theme file; defaults to the
default theme. A chain that returns to a file it has passed fails with `THEME_EXTENDS_CYCLE`;
- `description`, `palette`: what the theme is for and why its colours are what they are;
- `scheme`: `both` or `dark` — a dark-only theme draws its dark palette in either reader scheme and has no
scheme button; every built-in theme draws both;
- `accent`: the restrained `graphite`, `cobalt`, `rust`, `moss`, `ochre`, `ink`, or the brighter `indigo`,
`teal`, `coral` — a named accent family with a checked light and dark pair;
- `fonts.pair`: the display, text, label and code faces of a built-in theme — `midnight` (Geologica, IBM
Plex Sans, JetBrains Mono, JetBrains Mono), `calm-paper` (Playfair, Literata, JetBrains Mono, JetBrains
Mono), `synthwave` (Unbounded, Exo 2, JetBrains Mono, JetBrains Mono), `noir` (Cormorant Garamond, Jost,
PT Mono, JetBrains Mono), `aurora` (Raleway, Commissioner, Victor Mono, Geist Mono), `daylight` (Onest,
Golos Text, Geist Mono, Geist Mono), `ember` (Oswald, Rubik, JetBrains Mono, JetBrains Mono), `blueprint`
(Tektur, Fira Sans, Martian Mono, JetBrains Mono), `terminal` (Martian Mono, JetBrains Mono, JetBrains
Mono, JetBrains Mono), `neutral` (Literata, Onest, Martian Mono, JetBrains Mono), `frost` (Onest, IBM Plex
Sans, Geist Mono, Geist Mono) — or `system` (the reader's system faces);
- `fonts.code`: the face of code blocks and inline code, emitted as `--font-code` — one of the text-grade
programming monos `jetbrains-mono`, `geist-mono` or `system-mono` (compact, a distinct 0/O and 1/l/I, full
Cyrillic); code is set with ligatures off. `fonts.mono` is the face of meta lines, chapter numbers and
other monospaced interface text (`--font-mono`; labels such as field labels and column headers use the
body face), where a wide or stylised mono may carry the theme's character;
- `fonts.heading`, `fonts.body`, `fonts.mono` name one of the 23 embedded
families (`onest`, `golos-text`, `ibm-plex-sans`, `exo-2`, `jost`, `commissioner`, `rubik`, `fira-sans`,
`geologica`, `manrope`, `raleway`, `unbounded`, `oswald`, `tektur`, `geist`, `literata`, `playfair`,
`cormorant-garamond`, `jetbrains-mono`, `martian-mono`, `geist-mono`, `victor-mono`, `pt-mono`) or
`system-sans`, `system-serif`, `system-mono` for a role and refine the pair. The package embeds the Latin and Cyrillic subsets of every family a
theme uses, so every reader sees the same type; `literata` and `playfair` are embedded with their
optical-size axis (`opsz`) and the page sets `font-optical-sizing: auto`, so their drawing follows the size;
- `typography.headingWeight`, `typography.displayWeight`, `typography.headingTracking`,
`typography.bodyLeading`, `typography.bodyTracking`: bounded numbers; `typography.displayCase`: `none` or
`uppercase` for display headings; `typography.displayScale` (0.6–1.2, default 1): the size of display
headings against the package scale; `typography.headingMeasure` (8–40, in `ch`, optional): the longest
line of the page title and of display and editorial section titles, emitted as `--heading-measure` — left
out, each of those headings keeps the package measure: the reading measure for a report title, 10–17ch
for landing, first-screen and display titles. Independently, the package caps a heading's size by the measured
letter width of its face so its longest word fits the column, and never breaks or hyphenates a word in a
heading. Russian headings never
take a tracking tighter than -0.025em, whatever the theme sets for Latin; `typography.captions`
(`plain` by default, or `italic`): figure captions and `source-line` text in the text face, or in the
heading face in italics — the serif italic caption of an editorial page when the heading face is a serif
(the embedded faces carry no italic drawing, so the browser slants the upright);
- `spacing.density` (`compact`, `comfortable`, `spacious`), `spacing.rhythm`, `spacing.cardMinimum`,
`spacing.gap` (`regular`, `tight`);
- `width` (`narrow`, `standard`, `wide`), `radius` (`sharp`, `soft`, `round`), `radii.control`,
`radii.card`, `radii.media` (`none`, `small`, `medium`, `large`; defaults `small`, `medium`, `medium`: the
step of the radius scale each role takes), `controls` (`regular`:
36 px buttons and fields with 32 px small ones, `compact`: 32 and 28 px; under a finger every control is
44 px), `backdrop` (`none`, `dots`, `grid`, `tint`, `grain`: a faint noise in the text colour over the page,
not printed),
`elevation` (`lifted`, `close`, `flat`);
- `colors.light.`, `colors.dark.`: `#rgb`, `#rrggbb`, `#rrggbbaa`, or `transparent` for the roles
`background`, `surface`, `raised`, `muted`, `heading`, `text`, `textMuted`, `border`, `borderStrong`,
`accent`, `accentStrong`, `accentSoft`, `accent2`, `focus`, `chart1`–`chart6`, the status roles
`statusDone`, `statusReview`, `statusReturned` (each follows `chart2`, `chart4`, `chart3` unless set, and
must reach 3:1 against `background` and `surface`), `marker`, `shadow`,
`mediaBacking` (the paper behind transparent image pixels; built-in themes keep it `transparent`, and a
dark scheme should not set a light paper — a dark-ink image ships a dark variant instead), and the code colours `codeBackground`, `codeText`, `codeKeyword`,
`codeString`, `codeNumber`, `codeFunction`, `codeType`, `codeComment`, `codePunctuation` that colour
highlighted code through Shiki's CSS-variables theme (every code colour, `codeComment` included because
it also draws diff line numbers, must reach 4.5:1 on `codeBackground`, on the tinted lines of a diff or
an edition — added lines under `statusDone` at 16 %, removed lines and an edition's ghost of a removed
line under `statusReturned` at 14 %, and hunk lines under `accent` at 9 % over `codeBackground` — and on `accentSoft`, which lights the code line of a scene step);
- `chrome.topbar` (`glass`, `ledger`), `chrome.navigation` (`plain`, `numbered`), `chrome.sectionTitle`
(`plain`, `rule`, `bar`), `chrome.cards` (`raised`, `ruled`), `chrome.components` (`soft`, `flat`,
`edged`), `chrome.landing` (`centered`, `ledger`), `chrome.edges` (`none`, `mono`: the page title and the
current chapter in small monospace captions along the screen edges on a wide screen);
- `ornaments.headingPrefix` (up to three characters), `ornaments.titleCursor` (boolean),
`ornaments.heroEmphasis` (`none`, `rule`, `shadow`), `ornaments.mediaTreatment` (`plain`, `vivid`),
`ornaments.linkedCard` (`raised`, `edge`), `ornaments.console` (`none`, `on`: bracketed labels, dashed
rules and a prompt mark), `ornaments.scanlines` and `ornaments.glow` (`none`, `on`; off in every built-in
theme, because a texture over the text and a phosphor glow read as a generated-site cliché).
Resolution applies the default theme, then the `extends` chain, then the theme's named accent, then its
explicit fields. The resolved theme must keep `heading` on `background`, `text` and `textMuted`
on `background` and `surface`, `accentStrong` on `background` and `surface`, `accent2` on `background`,
`background` on `heading` (the primary action label) and every code colour on `codeBackground` at 4.5:1 or
more, and `accent` and `focus` on `background` at 3:1 or more, in every scheme it draws; otherwise the build fails with `THEME_CONTRAST`.
Field errors fail with `THEME_INVALID`, an unknown name with `THEME_UNKNOWN`, a file outside the source root
with `THEME_OUTSIDE_SOURCE`, and an unreadable or malformed file with `THEME_READ_FAILED`; each diagnostic
points to the field's line in the theme file or frontmatter. Theme files are part of the source graph: they
are protected from output collision like any source file. These values select package-owned styles only;
CSS values, class names, JSX, templates, URLs, and callbacks are not accepted.
`agentic-report describe --json` and the ESM `getSourceContract()` return the built-in themes with their
intent and palette under `page.themes`, and the theme fields, accents, font families and contrast pairs
under `page.theme`.
The public landing uses `midnight`, Executive brief `daylight`, vendor decision `calm-paper`, launch
readiness and incident review extend `ember`, Terminal portfolio uses `terminal`, Cinematic story `noir`,
Motion showcase and research `aurora`, the landing starter `neutral`, and architecture and the dashboard
`blueprint`. These sources compose the same public components without page-specific CSS.
The five category starters combine these layouts with the public content, interaction, visualization,
partial, and local-asset contracts; they introduce no additional syntax.
## Partials and Markdown
`{{include: partials/context.md}}` inserts a Markdown partial. Only `.md` files are accepted. Includes are
limited to ten nested levels; cycles, missing files, malformed URI paths, and escaping lexical or symlink
paths fail with structured input diagnostics.
CommonMark plus GitHub Flavored Markdown tables, strikethrough, task-list syntax, and autolink literals is
converted through a typed unified AST. Raw HTML is not enabled. Sanitization occurs before package-trusted
syntax highlighting and semantic enhancement.
A colon in ordinary prose remains ordinary text under either of two lexical conditions: the name it opens
begins with a decimal digit, which no registered directive name does, or the colon is written against the
preceding letter, digit, combining mark or connector, whereas an authored directive always starts a fresh
token. So `21:01`, `21:01 — 00:12`, `1:30:05`, `3:1`, `1:10:100`, `localhost:9000`, `arXiv:2508.05775` and
`ключ:значение` require no backslash in Markdown or frontmatter. The first condition is independent of the
second, so `Пункт :2 списка.` is text as well. The rule restores only a leaf text directive without
attributes or children; an alphabetic name standing on its own after a space, any attributed or
child-bearing form, and every block-level form such as `::2` stay on the directive path, where an
unregistered name produces the normal directive diagnostic naming `\:` as the escape for ordinary prose
and a registered one is interpreted by its own rules, so a bare `:term` without its required attribute
reports the missing attribute instead of becoming text.
## Page data
`data` lists JSON files; each is addressed by its file name without `.json` (`data/run-96.json` is
`run-96`), which must be lowercase letters, digits and hyphens starting with a letter and unique on the
page. Files are confined to the source root like partials, at most 1 MB each, and join the source graph:
their bytes are part of the report revision. A missing file, a file outside the source root, a name that
cannot be addressed and invalid JSON fail with `DATA_READ_FAILED`, `DATA_OUTSIDE_SOURCE`,
`DATA_FILE_INVALID` and `DATA_JSON_INVALID` (the last one at the place of the syntax error in the file).
On a page that declares `data`, the build settles the data before any directive is read:
- `{{name.key.0.field}}` — a name, then object keys and list positions separated by dots — becomes the
value at that path in text, inline and block code, link and image targets, image alternative text and
directive attribute values (write the attribute quoted: `title="Run {{run.id}}"`). A string is placed
as written, a number as JSON writes it, `true`/`false` as words. The value goes into the parsed page as
text and is never read as Markdown, so data cannot add a directive, a link, emphasis or HTML. An unknown
name fails with `DATA_PATH_UNKNOWN`, a missing key or position with `DATA_PATH_MISSING`, and a list,
object or `null` with `DATA_VALUE_NOT_TEXT`; in code, a placeholder whose name is not data stays as
written, so code can show the template syntax of other tools.
- `:::each{in="run.stages" as="stage"}` repeats its body once per item of the list at `in`, with
`{{stage}}` or `{{stage.field}}` reading the item. A body that is one list repeats its items inside one
list; a body that is one table keeps its header row and repeats the rows below it inside one table. An
`each` may stand wherever its body could, for example between `cards` and its `card` directives or
between a `series` and its `point` leaves. A path that is not a list fails with `DATA_NOT_A_LIST`, an
item name already in use with `DATA_NAME_SHADOWED`; an empty list writes nothing.
- `::expect{data="run.stages" count="5"}` is a control value and renders nothing: `count` is the exact
number of items of a list, `min` and `max` bound the number of items or a number's value (`min="1"`: not
empty), `equals` compares a text, number or `true`/`false` value as written. The build fails with
`DATA_EXPECTATION_FAILED` at the `expect` line when the data diverge.
There is no expression language: a derived value — a streak, «k of N», a sum — is written into the JSON
before the build, or produced by a provider extension. `each` and `expect` on a page without `data` fail
with `DATA_NOT_DECLARED`.
## Extensions
A page extends the vocabulary for its own design through extension manifests listed in `extensions`.
Every manifest has these fields; anything else is refused with `EXTENSION_INVALID` and the line of the
field:
| Field | Meaning |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `kind` | `block`, `provider`, `effect` or `island` |
| `name` | `^[a-z][a-z0-9-]{1,40}$`; not a built-in directive, not `island`, not another extension |
| `description` | one sentence |
| `staticEquivalent` | what the reader gets without motion, without scripts and in print |
| `examples` | optional relative page sources that use the extension; two unlike ones are needed to check it |
| `licenses` | optional relative licence files of bundled third-party code |
Paths in a manifest are relative to the manifest and stay inside its directory (`EXTENSION_PATH_OUTSIDE`,
`EXTENSION_FILE_MISSING`). Fewer than two examples do not stop the build; it warns
`EXTENSION_EXAMPLES_MISSING`. `block` and `provider` declare `forms` (`leaf`, `container`) and
`attributes`, a map from a lowercase name to `{ type: string | number | boolean | enum, values,
required, default, description, maxLength, minimum, maximum }`; the author's directive is read against
them exactly as a built-in directive is against its attributes.
**`kind: block`** adds `template`, a `.md` file built from existing directives. `{{attribute}}` stands in
Markdown text or inside a quoted directive attribute value (`title="{{title}}"`); `{{content}}` stands
alone on a line of a container block and receives the author's body. The value is escaped for its place,
so no value can open a directive, close an attribute or add HTML. The expansion is checked, sanitized and
rendered like authored Markdown; a diagnostic inside it points at the author's directive and names
`details.template` and `details.templateLine`.
A block may add `styles`, a `.css` file of a few rules that give it a look the built-in blocks do not
have, such as a figure in large type. The rules are nested inside the block's own element — the top-level
elements of its expansion carry `data-extension-block=""` — so `&` is that element and a nested
selector reaches only inside it. The styles take their look from the theme only, by the same rules as the
package stylesheet: no colour literal (hex, `rgb()`, named colours), no typeface name, `font-size` from the
`--text-*` scale or a `clamp()` in `rem` and `vw`, `font-weight` from `--weight-*`, `--heading-weight` or
`--display-weight`, radii from `--radius-*`, and no `font` shorthand. On top of that a block's styles read
only public theme tokens (`agentic-report schema --scope theme`) and the `--text-*`, `--weight-*` and
`--heading-fit` scales, declare no variables, keep their braces balanced (braces inside strings and comments
do not count; an unclosed string or comment is refused), select no sibling of the block (`~` or `+` after
`&`, or at the start of a nested rule, where `&` is implied), name no document root (`:root`, `html`,
`body`), use no at-rule but `@media` and `@container`, load nothing (`url()`, `image-set()`, `@import`) and
contain neither `\` nor `<`. A
violation is refused with `EXTENSION_STYLES_INVALID` and the line of the styles file; styles above 8 192
bytes with `EXTENSION_STYLES_OVER_BUDGET`. The styles reach only pages that use the block, and their bytes
count towards `output.maxInlineBytes` and appear as `bytes` in the build's extension report.
```yaml
kind: block
name: metric-card
description: One metric with its value and trend.
staticEquivalent: A bordered notice with the metric name and its value.
forms: [leaf, container]
attributes:
title: { type: string, required: true }
value: { type: string, required: true }
trend: { type: enum, values: [up, down, flat], default: flat }
template: template.md
styles: block.css
examples: [example-one.md, example-two.md]
```
**`kind: provider`** adds `command`, an argv run without a shell in the extension directory, and
`timeoutMs` (default 10000, at most 120000). The build runs it once per distinct use with JSON
`{ name, attributes, content, language, data, source: { file, line } }` on standard input and reads
Markdown from standard output; that Markdown is checked and sanitized as authored. `data` holds the page's
data files (the `data` field) parsed, under the name each is addressed by in the text (`data/run.json` →
`data.run`), and is `{}` when the page declares none; this is how a provider reads data kept beside the
page. The build has already read those files inside the source root, so the provider receives no path and
nothing the page did not declare. A change of a data file changes the provider's input and reruns it. The program gets only `PATH`,
`HOME`, the temporary-directory, locale and Windows system variables of the environment. A timeout
(`EXTENSION_PROVIDER_TIMEOUT`), more than 1 MB of output (`EXTENSION_PROVIDER_OUTPUT_TOO_LARGE`), a
non-zero exit (`EXTENSION_PROVIDER_FAILED`, with `details.stderr`) or output that is not UTF-8
(`EXTENSION_PROVIDER_OUTPUT_INVALID`) fails the build at the author's directive.
**`kind: island`** adds `entry`, an `.html` file, and `assets`, the files it references. The author writes
`:::island{name="…" hydrate="load|idle|visible|none" height="28rem" title="…"}` with a required Markdown
body, the static equivalent shown in print, without scripts and until the island is ready. `hydrate`
defaults to `visible`; without `height` the frame follows the height the island reports. The island runs
in `