ascribe.toml format contract

The normative contract for the content model file, with the rules a loader enforces and the decisions behind them.

This is the normative contract for ascribe.toml, the content model file (SPEC §7). It defines every table and key, the short syntax for field and attribute types, and every rule a loader enforces. The loader in tessera-model implements it. For a guide to writing one, see the ascribe.toml reference.

SPEC.md is normative for the language. This document is normative for the file format. Where it settles something the spec leaves open, the item is listed in Decisions.

Example files, each valid under this reference:

• examples/content-models/minimal.toml: the smallest valid model.
• examples/content-models/quill.toml: the model SPEC Appendix B assumes.
• examples/content-models/full.toml: every section and key.

Contents

1. Conventions
2. Map of SPEC §7.2 to this file
3. Top level: spec
4. [project]
5. [types.<name>] and [fragments]
6. Field and attribute types
7. [dimensions.<name>]
8. [versions]
9. [lifecycle.<state>]
10. [features.<key>]
11. [notes.<type>]
12. [phrases]
13. [glossary]
14. [images]
15. [widgets.<name>]
16. [consumer]
17. [builds.<name>]
18. [editor]
19. [sources.<name>]
20. Defaults: what an absent section means
21. Validation rules
22. Decisions

1. Conventions

1.1 The file

• The content model is a TOML 1.0 file named ascribe.toml. The directory that contains it is the project root. Every path in the file is relative to the project root unless a key says otherwise.

• The file is UTF-8.

• TOML’s equivalent spellings are all accepted: a table can be written as a [header] section, as an inline table (key = { … }), or with dotted keys. This reference shows the most readable form for each section. For example, these are the same:

  [dimensions.pm]
  values = ["npm", "pnpm", "yarn"]
  
  # same as
  dimensions.pm.values = ["npm", "pnpm", "yarn"]

• Keys are kebab-case (content-root, trailing-slash), matching Ascribe’s attribute keys. TOML allows hyphens in bare keys, so they need no quotes.

• Unknown keys are errors, everywhere, with a did-you-mean suggestion. A misspelled key is otherwise a silently ignored setting. The exceptions are the tables whose keys are names the project chooses ([phrases], [types], [dimensions], and so on); their keys are validated as names instead.

• Declaration order is kept where it matters. The loader MUST preserve the order in which attribute keys are declared ([images.attributes], [widgets.<name>.attributes]), because canonical form writes attributes in declared order (SPEC §8.3). It MUST also preserve the order of the [dimensions] tables, which is the canonical order of @variant attributes and decides which dimension a tab group syncs on (the element contract, §3). Loaders SHOULD also preserve order elsewhere, for stable output (for example, the order of dimension values in a tab switcher is the order of values). Nothing else in the model depends on order.

1.2 Names

Several kinds of name appear in the file. Each has a grammar from SPEC Appendix A or from this reference:

Dimension names follow the stricter key rule, not just name-word, because they’re also written as attribute keys in @variant {deployment=cloud} (SPEC §3.3, §4.3).

Build names allow . so that names like self-managed-3.3 work. A name containing . must be quoted in a TOML header: [builds."self-managed-3.3"].

Names are case-sensitive and spelled exactly as declared (SPEC §4.4).

1.3 Paths and patterns

• Paths use / as the separator on every platform.

• Filesystem paths in [project] and [sources] are relative to the project root. They MUST NOT be absolute, and they MAY use ...

• A glossary term’s link (§13) is written like a link destination in a document (SPEC §5.2), relative to the content root.

• Patterns (globs) are matched against a source file’s path relative to the content root, including its extension, with / separators. They are case-sensitive. The syntax:

  Syntax	Matches
  *	Any run of characters within one path segment, not including /
  **	Any number of whole segments, including none. It MUST be a whole segment (a/**/b, a/**, **/b)
  ?	Any one character except /
  {a,b}	Either alternative. Alternatives don’t nest
  \	Escapes the next character

  Every other character matches itself. A pattern MUST NOT start with / and MUST NOT contain a .. segment. Patterns only ever apply to Markdown source files (*.md); other files under the content root are assets. The exception is a source’s include and ignore (§19), which are matched against any file’s path relative to the source’s folder.

1.4 How this reference describes keys

Each section has a table of keys with these columns:

• Type: the TOML type. “Field type”, “attribute type”, and “availability spec” are strings with the grammars in §6 and SPEC §4.4.
• Default: the value when the key is absent, or required.
• Description.

2. Map of SPEC §7.2 to this file

Every declaration SPEC §7.2 lists, and every setting SPEC §9.3 and §9.5 need, maps to one section:

3. Top level: spec

spec = "0.1"

The only other top-level keys are the tables in §4–§19. Anything else is an unknown key.

4. [project]

Where the source lives and where builds write.

[project]
content-root = "docs"
output-dir = ".ascribe/build"

Rules (§21): both paths are relative (model-path-absolute). The output directory MUST NOT be inside the content root, the content root MUST NOT be inside the output directory, and they MUST NOT be the same directory (model-output-overlaps-content); otherwise a build would read its own output as source, or delete source as stale output. Paths are compared after normalizing . and .. segments and, when both exist, after resolving symbolic links.

The defaults: ".ascribe/build" keeps generated output out of the way of both the source and a consumer’s own dist/.

5. [types.<name>] and [fragments]

5.1 Page types

A content type is a frontmatter schema for a kind of page, plus the files it applies to.

[types.guide]
default = true

[types.guide.frontmatter]
title = "string"
description = "string?"

[types.reference]
files = ["reference/**"]

[types.reference.frontmatter]
title = "string"
api-version = "string"

<name> is the type’s name (key rule). It appears in diagnostics and in generated code (the Zod schema’s name).

Which type applies to a page. For each page (not fragments; see §5.3):

1. If exactly one type’s files match the page, that type applies.
2. If several types’ files match, it’s an error on the page: the page is ambiguous. There’s no precedence between types.
3. If none match and a default type exists, the default applies.
4. If none match and there’s no default type, it’s an error on the page.

A type with neither files nor default = true could never apply, and is an error (model-type-unreachable). The rules in steps 2 and 4 are document diagnostics, listed in SPEC §8.2.

The page title. Every page type MUST declare title as a required string field (model-type-title). The frontmatter title is the page’s title wherever the spec needs one, such as the replacement text of an empty link to a page (SPEC §5.2). The field MAY accept phrases (§12).

Reserved keys. available (SPEC §4.4) and variant (SPEC §4.3) are reserved frontmatter keys. Every page accepts them, with the meaning the spec gives, whether or not its type mentions them, and a type MUST NOT declare them (model-field-reserved). Generated consumer schemas include them automatically. Under the astro profile, slug is reserved too: Astro’s content loader uses a page’s frontmatter slug as its entry id in place of its path, which would publish the page at a URL Ascribe never computed, so a type MUST NOT declare it (model-field-reserved).

Unknown frontmatter keys. A page whose frontmatter has a key its type doesn’t declare (and that isn’t reserved) is an error on the page.

5.2 Frontmatter values

Frontmatter is YAML. For type checking, processors parse it with the YAML 1.2 core schema: true and false are booleans (yes, no, on, and off are strings), and 3.10 is the number 3.1. So a string field whose value is 3.10 unquoted is a type error, and the message suggests quoting it.

5.3 Fragments

[fragments]
patterns = ["includes/**", "**/*.partial.md"]

[fragments.frontmatter]
owner = "string?"

Content types never apply to fragments, even when a type’s files match a fragment’s path.

Reserved keys on fragments. The spec defines available and variant for pages only. A fragment’s frontmatter MUST NOT use them (an error on the fragment), and [fragments.frontmatter] MUST NOT declare them (model-field-reserved). Use @available inside the fragment instead.

6. Field and attribute types

Two related type languages:

• Field types describe frontmatter fields ([types.<name>.frontmatter], [fragments.frontmatter]). They cover the SPEC §7.2 set: string, number, boolean, date, enumeration, list, and object, each optional or with a default.
• Attribute types describe attributes on images and widgets ([images.attributes], [widgets.<name>.attributes]). They cover SPEC §3.3’s set: string, enumeration, boolean, and number, plus set-valued keys.

Each entry is written either in short form, a string, or in table form, when it needs a default, a description, phrases, enumeration values that aren’t simple words, or nested fields.

[types.guide.frontmatter]
title = "string"                                   # required string
description = "string?"                            # optional string
level = "enum(beginner, intermediate, advanced)"   # required, one of three
tags = "list(string)?"                             # optional list of strings
updated = "date?"                                  # optional date
status = { type = "enum(draft, published)", default = "published" }
author = { type = "object?", fields = { name = "string", url = "string?" } }

6.1 Short form

A field is required unless its type ends in ? or it has a default. The same holds for attributes: lab = "string" means every use of the widget must give lab.

Grammar (ABNF, with the rules of SPEC Appendix A):

field-type      = field-base [ "?" ]
field-base      = scalar / enum / list-type / "object"    ; "object" in table form only
scalar          = "string" / "number" / "boolean" / "date"
list-type       = "list" "(" OWS ( scalar / enum / "object" ) OWS ")"
                                        ; "list(object)" in table form only

attribute-type  = attribute-base [ "?" ]
attribute-base  = "string" / "number" / "boolean" / enum / set-type
set-type        = "set" "(" OWS ( "string" / enum ) OWS ")"

enum            = "enum" [ "(" OWS enum-value *( OWS "," OWS enum-value ) OWS ")" ]
                                        ; bare "enum" in table form only, with "values"
enum-value      = 1*( ALPHA / DIGIT / "-" / "_" / "." )

Spaces are allowed only where OWS appears. The canonical spelling has no spaces except one after each comma: enum(a, b).

6.2 Table form

Nesting beyond one level of fields is allowed but discouraged; keep frontmatter flat.

7. [dimensions.<name>]

A dimension is an axis content varies along (SPEC §4.3), and whose values are availability targets (SPEC §4.4).

[dimensions.deployment]
label = "Deployment"
values = ["cloud", "self-managed"]
versionless = ["cloud"]
labels = { cloud = "Quill Cloud", self-managed = "Self-managed" }

<name> is the dimension’s name (key rule, §1.2). It’s written as an attribute key in @variant, as a key in variant frontmatter and build selections, and as a target in availability specs, where it stands for all its values.

Rules. A value MUST belong to only one dimension (model-dimension-value-shared); otherwise a bare target in an availability spec would be ambiguous. Dimension names and values also take part in the one-role rule (§21).

8. [versions]

How versions in availability specs are compared (SPEC §4.4).

[versions]
scheme = "numeric"

The numeric scheme. A version is any string matching SPEC Appendix A’s version rule: numbers separated by dots (3, 3.4, 3.4.1). Versions compare component by component, numerically, from the left, with missing trailing components treated as 0: 3.4 equals 3.4.0, 3.10 is later than 3.9, and 4 is later than 3.99.1. Leading zeros don’t matter (3.04 equals 3.4). This is semantic versioning’s major.minor.patch ordering. It has no pre-release or build suffixes, because the spec’s grammar doesn’t allow them; express a pre-release with a lifecycle state (preview 3.4) instead.

No other scheme is defined. The table exists so a later spec version can add one without changing the file’s shape. The scheme is named numeric, not “semantic versioning”, because it accepts any number of components and has no pre-release syntax.

9. [lifecycle.<state>]

Lifecycle states (SPEC §4.4). Five are built in:

A project adds states by declaring them, and MAY change the available flag or label of a built-in state. Built-in states can’t be removed.

[lifecycle.sunset]
available = false
label = "sunset"

[lifecycle.ga]
label = "Generally available"

<state> is the state’s name (name-word).

Rules. ga MUST count as available (model-lifecycle-ga-unavailable), because content with no state is ga (SPEC §4.4). Lifecycle states take part in the one-role rule, including the built-in ones: a dimension value named beta is an error.

10. [features.<key>]

The features registry (SPEC §4.4): named availability specs, so a feature going generally available takes one edit.

[features.streaming-sync]
name = "Streaming sync"
available = "cloud, self-managed preview 3.4"

<key> is the feature key (name-word). Writing it as a whole @available primary, or as the whole available frontmatter value, stands for the spec.

Rules. The spec is checked like one written in a document: it MUST parse (model-availability-syntax); every target MUST be a declared dimension value or dimension name, and every state a declared state (model-availability-unknown-name); versionless targets and dimension names take no versions (model-availability-versionless); histories MUST be in chronological order (model-availability-history-order). It MUST NOT be a feature key itself (model-feature-nested), so features never refer to each other. Feature keys take part in the one-role rule.

11. [notes.<type>]

Note types (SPEC §4.5), the values of @note’s type attribute. Five are built in: note, tip, important, warning, and caution. A project adds types by declaring them, and MAY relabel a built-in type. Built-in types can’t be removed.

[notes.security]
label = "Security"

[notes.tip]
label = "Pro tip"

<type> is the note type (key rule).

Under [notes], the inline form security = { label = "Security" } is equivalent.

12. [phrases]

The phrases registry (SPEC §5.1).

[phrases]
product = "Quill"
cloud = "Quill Cloud"
version = "3.4.1"
api = "https://api.quill.dev/v3/"

Every key is a phrase key (key rule, the same rule as SPEC Appendix A’s phrase), and every value MUST be a TOML string (model-phrase-value-type). version = 3.4 is a float and an error; that’s the kind of silent type change TOML exists to prevent (SPEC §7.1). Values are inserted as literal text (SPEC §5.1).

Phrases in frontmatter. SPEC §5.1 lets the content model decide which frontmatter fields accept phrases. A field accepts them when its table form sets phrases = true (§6.2):

[types.guide.frontmatter]
title = { type = "string", phrases = true }

Only string and list(string) fields can accept phrases (model-phrases-field-type). By default, no field does. The setting lives on the field, not in [phrases], so that a phrase key can never collide with a setting’s name.

13. [glossary]

The glossary (SPEC §5.4): terms, their definitions, and how occurrences are matched. Authors don’t mark terms in source; processors link them (SPEC §9.2 step 7).

[glossary]
match = "first"
case-sensitive = false

[glossary.terms.api-key]
term = "API key"
aliases = ["API keys"]
definition = "A secret token that authenticates the Quill agent to Quill Cloud."
link = "/reference/glossary.md#api-key"

13.1 Settings

13.2 Terms

Matching: occurrences match whole words only; the longest matching term wins where terms overlap (API key over API); matching applies to prose only, never to headings, link text, code, raw HTML, or text inside a directive’s primary identifier. A term with no link isn’t linked in the site or plain-markdown output; its definition still reaches the editor and the JSON output. SPEC §5.4 says only that occurrences are linked to definitions.

Rules. No two terms or aliases may be the same text (compared ignoring case when either is case-insensitive; model-glossary-duplicate-term). The link file MUST exist and not be a fragment (model-glossary-link); its #id is checked with the page-level link checks, since ids depend on parsing.

14. [images]

Image attributes (SPEC §5.3): which keys may appear in an attribute block after an image, and their types.

[images.attributes]
width = "number?"
height = "number?"
loading = { type = "enum(lazy, eager)", default = "lazy" }

Alt text and titles aren’t attributes; they use CommonMark’s syntax (SPEC §5.3). Presentation choices aren’t image attributes either. Keys HTML already uses on <img> (src, alt, title, and its global attributes) are rejected (model-attribute-reserved), since the site output writes image attributes onto the <img> element (SPEC §7.2).

15. [widgets.<name>]

Project widgets (SPEC §6): directives a documentation set defines. Each declaration is a directive schema with the same parts a built-in directive’s schema has (SPEC §3, §4).

[widgets.quill-labspace]
description = "An embedded, runnable Quill lab."
forms = ["line"]
binding = "self"
plain-fallback = "Try this in the Quill lab at labs.quill.dev."

[widgets.quill-labspace.attributes]
lab = "string"
height = "number?"

<name> is the widget’s name (SPEC A widget-name: lowercase, with at least one hyphen). Names starting with ascribe- are reserved for Ascribe’s element library, and the names HTML reserves for itself (annotation-xml, color-profile, font-face, font-face-src, font-face-uri, font-face-format, font-face-name, missing-glyph) aren’t allowed, because the site output emits a widget as a custom element with the widget’s name (SPEC §9.4).

Binding values:

Rules (§21):

• A widget with container form MUST NOT have a required primary, since a container opener’s primary is empty (SPEC §3.5). A container-only widget’s primary MUST be "none" (model-widget-container-primary).
• A groupable widget MUST be container-only, since group arms are containers (SPEC §3.6) (model-widget-groupable-form).
• binding is required with line form and not allowed without it (model-widget-binding).

The site output’s element for a widget (tag name and attributes) is defined by the element contract, not here.

16. [consumer]

The consumer profile (SPEC §9.5): how the site output fits a specific consumer. Spec 0.1’s toolchain implements one profile, astro (SPEC §9.6). The profile sets defaults for every other key; a key given here overrides them, within the values the profile supports.

[consumer]
profile = "astro"
site = "https://docs.quill.dev"
base-path = "/"
trailing-slash = "always"
slugger = "github"

Heading ids, image attributes, and assets (SPEC §9.5) are part of the profile, not keys. The astro profile has exactly one way to do each, defined by the contracts:

• Heading ids and image attributes: the site output writes each as a <ascribe-attributes> marker that the consumer’s markdown plugin applies, so the consumer keeps its own heading, table-of-contents, and image processing. See contracts/site-render.md.
• Assets: copies mirror their source paths inside each output, and images are referenced relatively so Astro’s image processing still applies. Other files a page links to are published under _ascribe/files/. See contracts/assets.md.

A later profile that offers a choice adds a key for it then.

How file paths become routes (the astro profile, verified against Astro): a page’s route is base-path, then its path relative to the content root with the .md extension removed and each segment slugged the way Astro’s content loader computes entry ids; a final index segment is dropped (guides/index.md → /guides/); then the trailing slash per trailing-slash. The root index.md (Astro’s entry id index) is at base-path, which under trailing-slash = "never" loses its final / unless it’s /. Two pages with one entry id (My File.md and my-file.md, or index.md and index/index.md) can’t both be published, and ascribe build --emit site fails, naming them. The same router answers the reverse question, which page a route-like link names, for the link-route warning and its fix. Source files never contain routes (SPEC §5.2).

The astro profile’s site, base-path, and trailing-slash repeat settings from astro.config. The Astro integration checks that they agree, and fails the build, naming each difference, when they don’t. It compares base-path as a path with a leading and a trailing /, treats Astro’s trailingSlash: "ignore" as agreeing with either value, and compares site by origin when both sides set it.

17. [builds.<name>]

Named builds (SPEC §9.3). Each sets a variant mode and an availability mode. These are SPEC §9.3’s examples, in ascribe.toml:

[builds.site]
variants = "switch"
availability = "badge"

[builds.cloud-pdf]
variants = { deployment = "cloud" }
availability = { filter = "cloud" }

[builds."sm-3.3"]
variants = "switch"
availability = { filter = "self-managed 3.3" }

<name> is the build name (§1.2). It names the build on the command line (ascribe build --build cloud) and in output paths.

Rules. Build names MUST be unique ignoring case (model-build-name-case), since they become directory names and some file systems ignore case. A build that filters for a target its own selection excludes (for example, selecting deployment = "cloud" and filtering for self-managed 3.3) is legal but almost certainly a mistake, so the loader warns (model-build-filter-excluded).

18. [editor]

Settings for the authoring environment (SPEC §10).

[editor]
build = "site"

Default. If only one build exists, that build. Otherwise, the build named site, if there is one. Otherwise the key is required (model-editor-build-required).

19. [sources.<name>]

A source is a folder outside the project’s content that its pages may take code examples from (SPEC §4.8, §7.3). It’s the only way a page can read a file outside the project’s folder.

[sources.code]
path = ".."
include = ["crates/**", "examples/**"]
ignore = ["**/target/**"]

<name> is the source’s name (§1.2), which a snippet’s address starts with: code:examples/quill/ascribe.toml#dimensions.

git and branch are reserved for a source in another repository; using either is an error.

Rules (§21.8): path is relative (model-path-absolute), and names an existing directory (model-source-path-missing) inside the project’s repository (model-source-outside-repository). git and branch are rejected (model-source-remote).

20. Defaults: what an absent section means

A file containing only spec = "0.1" is valid. It means:

21. Validation rules

A loader MUST enforce every rule below when it loads ascribe.toml, and report each violation at the span of the offending key or value. Every rule is an error unless marked warning. A model with errors doesn’t load, and no document is checked against it; warnings don’t stop loading.

• Slugs are stable identifiers, for tests and for the diagnostics registry, tests/conformance/diagnostics.toml, which gives each one a code. Only model-name-multiple-roles corresponds to a row of SPEC §8.2 (“Content model”); the rest are loader rules this reference adds.
• Messages are templates. {name} is a placeholder. Where a rule has several messages, each covers one case of it.
• Rules about documents, such as a page matching no content type or an unknown frontmatter key, aren’t loader rules.
• Filesystem rules (model-content-root-missing, model-glossary-link, model-source-path-missing, model-source-outside-repository) need the project directory. A loader given only the file’s text, such as an unsaved editor buffer or a unit test, skips them; ascribe check and the language server always run them.

21.1 File and structure

21.2 Project

21.3 Content types, fragments, and fields

21.4 Dimensions, names, lifecycle, notes, and features

21.5 Versions, phrases, glossary, and images

[versions] scheme is covered by model-invalid-value. Image attribute types are covered by the rules in §21.3.

21.6 Widgets

primary, title, and binding values are covered by model-invalid-value; attribute types by §21.3.

21.7 Consumer, builds, and editor

21.8 Sources

22. Decisions

Each item settles a gap in SPEC.md. All 21 were decided on 2026-09-28 as recommended below, except item 12, which was settled when the site-render and asset contracts were written. Items 1, 2, 3, 4, and 6 are now also stated in SPEC.md (§2.1, §5.2, §7.2, §8.2). Each item keeps the alternatives that were considered.

1. Frontmatter diagnostics (SPEC §8.2). §8.1 says file-level validation covers frontmatter, but §8.2 has no rows for it. Decision: add file-level error rows: unknown frontmatter key; missing required field; value doesn’t match the field’s type; reserved key (available, variant) on a fragment; page matches more than one content type; page matches no content type and there’s no default.
2. Assigning content types to pages (SPEC §7.2). The spec doesn’t say how a page gets its type. Decision: files patterns per type plus at most one default = true type; a page matching several types is an error, with no precedence. Considered: first match in file order (TOML tables are formally unordered); most specific pattern (hard to define); a frontmatter type key (would need a new reserved key).
3. Page titles (SPEC §5.2). Empty link text uses “the page title”, but the spec doesn’t say where it comes from. Decision: the frontmatter title, which every page type must declare as a required string. Considered: fall back to the first level-1 heading.
4. Reserved keys in fragments (SPEC §2.1, §4.3, §4.4). available and variant are defined for pages. Decision: fragments can’t use them in spec 0.1; use @available inside the fragment. Considered: fragment available applies to everything the fragment contributes, like a section spec.
5. Version scheme name (SPEC §4.4). Decision: call the one scheme numeric: dotted numbers of any length, compared numerically with missing components as 0. The grammar has no pre-release syntax, so “semver” would overpromise. Considered: call it semver and cap versions at three components, which needs a new document diagnostic.
6. Name rules beyond the one-role rule (SPEC §4.3, §4.4, §7.2). Decision: (a) a dimension value belongs to only one dimension, since cloud in a spec must mean one thing; (b) dimension names follow the key rule, since they’re attribute keys; (c) warn on names that differ only in case. (a) and (b) are stated in SPEC §7.2.
7. Glossary (SPEC §5.4). The spec gives no format or matching rules. Decision: terms with a required plain-text definition and an optional link; occurrences link to link; terms without it aren’t linked in site or plain output. Whole-word matching, longest term wins, prose only (not headings, link text, or code), first per resolved page by default. No term element is needed: in the site output an occurrence is an ordinary link whose title is the definition (see the element contract).
8. Widget plain fallback (SPEC §6, §9.4). Decision: a static CommonMark string with phrases substituted and no attribute interpolation (no behavior); a widget that wraps content keeps that content in plain output unless plain-content = "drop", since silently losing content is worse than showing it. The spec’s “or nothing” then applies to the widget itself, not its content.
9. Widget schema constraints (SPEC §3.5, §3.6, §6). Decision: groupable widgets are container-only; widgets with container form have no required primary; names starting with ascribe- and HTML’s reserved custom-element names are rejected.
10. Absolute links in plain output (SPEC §9.4). Plain-markdown links are “absolute URLs”, which needs the site’s origin. Decision: optional [consumer] site; without it, links are root-relative and ascribe build warns.
11. HTML passthrough (SPEC §9.5). The site output depends on raw HTML (custom elements). Decision: keep the key, but the astro profile accepts only true until a profile needs false, rather than defining a degraded site output now.
12. Heading ids, image attributes, and asset placement (SPEC §9.4, §9.5). Decision: no keys. The profile named by profile fixes all three, and the astro profile has one way to do each: a <ascribe-attributes> marker for heading ids and image attributes (site-render contract), and mirrored asset copies with relative image references (asset contract). A key that accepts one value says nothing, and since unknown keys are errors, adding a key when a second profile needs a choice breaks no existing file, while removing one later would. Considered: the keys first drafted, heading-ids ("attribute" or "html"), image-attributes ("attribute" or "html"), assets ("beside-page" or "directory"), and assets-dir. Their alternatives were dropped: an {#id} attribute block is rewritten by Astro’s default smartypants and GFM processing before a plugin sees it (quotes, -- in ids), which the marker avoids; a raw HTML heading loses the consumer’s inline processing and, in Astro, its table-of-contents entry; a raw <img> bypasses Astro’s image processing; and a shared asset directory needs hashed names to avoid collisions, which mirroring avoids by construction. With them went the loader rule model-consumer-assets-dir.
13. Filter builds on versioned targets (SPEC §9.3). A filter is “given a target and, for versioned targets, a version”. Decision: the version is required for versioned targets, and not allowed for versionless ones. Considered: a versioned target with no version means “at every version”, but then the “state in effect” is undefined.
14. Project defaults. Decision: content-root = "docs", output-dir = ".ascribe/build"; paths relative to ascribe.toml, .. allowed, absolute paths rejected (keeps projects portable). The content root can’t be "." by default, because the output directory couldn’t then sit outside it.
15. YAML flavor for frontmatter. Decision: the YAML 1.2 core schema (yes is a string, 3.10 is a number), and date fields accept YYYY-MM-DD scalars, quoted or not.
16. The editor’s default build. Decision: the only build, else the build named site, else required.
17. Built-in lifecycle states and note types. Decision: built-ins can be relabeled, and states’ available flags changed, but not removed; ga must stay available; new states must set available explicitly; new note types need a label; built-in states take part in the one-role rule.
18. Implicit type and build. Decision: with no [types], one default type page with a required title; with no [builds], one build site (switch, badge). Declaring any type or build removes the implicit one.
19. Features referring to features (SPEC §4.4). Decision: not allowed, so there are no chains or cycles.
20. Phrases in frontmatter (SPEC §5.1). Decision: opt in per field with phrases = true, on string and list(string) fields only; off by default.
21. Spec version matching (SPEC §11). Decision: spec is a quoted string that must exactly equal a version the processor implements; "0.1" for now. Revisit compatibility ranges when 0.2 exists.