> For the complete documentation index, see [llms.txt](https://ascribed-dev.com/docs/llms.txt). This documentation describes Ascribe 0.4.4. Anything marked in main, not yet released isn't in that release yet.

# Diagnostics: the content model's builds and site

> Reference · The diagnostics about releases, phrases, widgets, the consumer, builds, the editor, permalinks, crawlers, listing, and checks in ascribe.toml, and how to fix each.

The problems Ascribe reports in `ascribe.toml`'s `[releases]`, phrases, widgets, consumer, builds, and editor, and in `[permalinks]`, `[crawlers]`, `[listing]`, and `[checks]`. One that's an error stops everything else: every other check depends on the [content model](https://ascribed-dev.com/docs/glossary.md#content-model). The rest of the content model's diagnostics, from the file to its names, are on [Diagnostics: the content model](https://ascribed-dev.com/docs/checks/diagnostics/content-model.md). Part of the [diagnostics reference](https://ascribed-dev.com/docs/checks/diagnostics.md), which says what an entry's severity, level, and next step mean, and has an index of every diagnostic.

## `[releases]`

### ASC204 `model-releases-target`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** A `[releases]` table names a target that's versionless, a [dimension](https://ascribed-dev.com/docs/glossary.md#dimension), or a name `[dimensions.release]` takes, or labels a target its dimension labels.

**Message:** `[releases.{target}]`: `{target}` is in no declared dimension, so it would be a value of the implicit dimension `release`, but `[dimensions.release]` takes that name; add `{target}` to a dimension's `values`, or rename `[dimensions.release]`

**Fix:** Name the table after the target a mark gives a version to, such as `[releases.self-managed]`: a versioned value of a declared dimension, or a name no dimension has, which makes it a value of the implicit dimension `release`. A versionless value has no versions to list. While a target is left to the implicit dimension, no declared dimension can be named `release`.

**Read more:** [`[releases.<target>]`](https://ascribed-dev.com/docs/content-model/variation.md#121-releasestarget) in the `ascribe.toml` reference.

### ASC205 `model-releases-line`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** A target's lines in `[releases]` aren't valid versions, are listed twice, or have different numbers of parts.

**Message:** `[releases.{target}]` mixes lines of different lengths, `{a}` and `{b}`; write every line of a target with the same number of parts

**Fix:** Write each line as a version, once, with as many parts as the target's other lines: `["3.4", "3.5"]` for a line for each minor release, or `["0.2.0"]` for one for each patch release. A line holds every version that starts with it.

**Read more:** [`[releases.<target>]`](https://ascribed-dev.com/docs/content-model/variation.md#121-releasestarget) in the `ascribe.toml` reference.

### ASC207 `model-releases-order`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** A target's planned line isn't newer than every live line, an archived line isn't older than every live one, or a line is in two lists.

**Message:** `[releases.{target}]`: the planned line `{line}` isn't newer than every live line, and the newest is `{live}`

**Fix:** Keep each line in one list, in the order the lists mean: `planned` lines are newer than every `live` line, and `archived` lines older. A line that has shipped moves from `planned` to `live`, and one that has left the window from `live` to `archived`.

**Read more:** [`[releases.<target>]`](https://ascribed-dev.com/docs/content-model/variation.md#121-releasestarget) in the `ascribe.toml` reference.

### ASC208 `model-releases-ends`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** `[releases.<target>.ends]` gives an end date to a line that isn't live.

**Message:** `[releases.{target}.ends]`: `{line}` isn't a live line; the live lines are {live}

**Fix:** Give an end date to a line in `live` only. A line whose support has ended and that has left the window goes in `archived`, with its date as `ended`.

**Read more:** [`[releases.<target>]`](https://ascribed-dev.com/docs/content-model/variation.md#121-releasestarget) in the `ascribe.toml` reference.

### ASC209 `model-versions-current`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** `ascribe.toml` has `[versions] current`, which is no longer a key.

**Message:** `[versions] current` is no longer a key; a target's current release is the newest line in `[releases.<target>] live`

**Fix:** Remove `current` from `[versions]`, and list the release in `[releases.<target>]`, as `live = ["3.4"]`, for the target it's a release of. Each target has its own current line, and a check that compared with `current`, `availability-left-behind`, compares each target's versions with that target's current line.

**Read more:** [`[releases.<target>]`](https://ascribed-dev.com/docs/content-model/variation.md#121-releasestarget) in the `ascribe.toml` reference.

## Phrases and the glossary

### ASC097 `model-phrase-value-type`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §5.1](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#51-phrases)

**When:** A phrase's value isn't a string, or a table naming a target's line.

**Message:** phrase `{key}` must be a quoted string, but it's {found}; write {key} = "{value}"

**Fix:** Quote the value. A phrase whose value is a target's current [release line](https://ascribed-dev.com/docs/glossary.md#release-line) is a table with one key, `line`: `release = { line = "self-managed" }`.

**Read more:** [`[phrases]`](https://ascribed-dev.com/docs/content-model/content.md#7-phrases) in the `ascribe.toml` reference.

### ASC215 `model-phrase-line`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §5.1](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#51-phrases)

**When:** A phrase is the line of a target that has no live line.

**Message:** phrase `{key}` is the line of `{target}`, which has no live line in `[releases]`

**Fix:** Name a target whose lines `[releases.<target>]` lists, with at least one in `live`, or list the target's lines there. The phrase is the target's current line: the newest live one.

**Read more:** [`[phrases]`](https://ascribed-dev.com/docs/content-model/content.md#7-phrases) in the `ascribe.toml` reference.

### ASC238 `model-glossary-page`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** A path in `[glossary] pages` doesn't exist, or is a [fragment](https://ascribed-dev.com/docs/glossary.md#fragment).

**Message:** `{path}` in `[glossary] pages` doesn't exist

**Fix:** Each path in `pages` is a page, from the content root, with its name's case as it is on disk: fix the path, or, for a fragment, list a page that includes it.

**Read more:** [`[glossary]`](https://ascribed-dev.com/docs/content-model/content.md#8-glossary) in the `ascribe.toml` reference.

## Widgets

### ASC100 `model-widget-reserved-name`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §6](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#6-project-widgets)

**When:** A widget's name is reserved by Ascribe's element library or by HTML.

**Message:** widget name `{name}` is reserved: names starting with ascribe- belong to Ascribe's element library

**Fix:** Rename the widget, for example with your project's name as its prefix: `quill-aside`.

**Read more:** [`[widgets.<name>]`](https://ascribed-dev.com/docs/content-model/content.md#10-widgetsname) in the `ascribe.toml` reference.

### ASC101 `model-widget-forms`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §6](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#6-project-widgets)

**When:** A widget's `forms` isn't one of the lists it allows.

**Message:** forms must be \["line"\], \["container"\], or \["line", "container"\]

**Fix:** Set `forms` to `["line"]`, `["container"]`, or `["line", "container"]`.

**Read more:** [`[widgets.<name>]`](https://ascribed-dev.com/docs/content-model/content.md#10-widgetsname) in the `ascribe.toml` reference.

### ASC102 `model-widget-binding`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §6](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#6-project-widgets)

**When:** A widget with a line form has no `binding`, or a container-only widget has one.

**Message:** widget `{name}` has a line form, so it needs a binding: "self", "heading", "block", or "heading-or-block"

**Fix:** Give a widget with a line form a `binding`. Remove `binding` from a container-only widget.

**Read more:** [`[widgets.<name>]`](https://ascribed-dev.com/docs/content-model/content.md#10-widgetsname) in the `ascribe.toml` reference.

### ASC103 `model-widget-container-primary`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §6](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#6-project-widgets)

**When:** A widget with a container form requires a primary, or a container-only widget takes one.

**Message:** widget `{name}` has a container form, whose opener has no primary, so its primary can't be required; use "{kind}?"

**Fix:** Make the primary optional (`"text?"`), or remove the widget's container form. A container-only widget takes no primary.

**Read more:** [`[widgets.<name>]`](https://ascribed-dev.com/docs/content-model/content.md#10-widgetsname) in the `ascribe.toml` reference.

### ASC104 `model-widget-groupable-form`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §6](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#6-project-widgets)

**When:** A groupable widget has a line form.

**Message:** widget `{name}` is groupable, so it must be container-only: forms = \["container"\]

**Fix:** Set `forms = ["container"]`, or remove `groupable`.

**Read more:** [`[widgets.<name>]`](https://ascribed-dev.com/docs/content-model/content.md#10-widgetsname) in the `ascribe.toml` reference.

### ASC105 `model-widget-plain-content`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §6](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#6-project-widgets)

**When:** A widget that doesn't wrap content sets `plain-content`.

**Message:** widget `{name}` doesn't wrap content, so plain-content has no effect; remove it

**Fix:** Remove `plain-content`.

**Read more:** [`[widgets.<name>]`](https://ascribed-dev.com/docs/content-model/content.md#10-widgetsname) in the `ascribe.toml` reference.

## The consumer, builds, and the editor

### ASC106 `model-consumer-unsupported`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.5](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#95-consumer-profile)

**When:** A `[consumer]` key has a value the consumer profile doesn't support.

**Message:** the {profile} profile doesn't support {key} = {value}; use {values}

**Fix:** Use one of the values the message lists.

**Read more:** [`[consumer]`](https://ascribed-dev.com/docs/content-model/output.md#15-consumer) in the `ascribe.toml` reference.

### ASC107 `model-consumer-site`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.5](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#95-consumer-profile)

**When:** `[consumer] site` isn't an origin alone, such as `https://docs.example.com`.

**Message:** site must be an origin such as "https://docs.example.com"; put any path in base-path

**Fix:** Set `site` to the origin alone, such as `"https://docs.example.com"`, and put any path in `base-path`.

**Read more:** [`[consumer]`](https://ascribed-dev.com/docs/content-model/output.md#15-consumer) in the `ascribe.toml` reference.

### ASC108 `model-consumer-base-path`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.5](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#95-consumer-profile)

**When:** `[consumer] base-path` doesn't start with `/`.

**Message:** base-path must start with "/", such as "/docs/"

**Fix:** Start `base-path` with `/`: `"/docs/"`.

**Read more:** [`[consumer]`](https://ascribed-dev.com/docs/content-model/output.md#15-consumer) in the `ascribe.toml` reference.

### ASC109 `model-build-name-case`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.3](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#93-build-modes)

**When:** Two builds' names differ only in case.

**Message:** builds `{a}` and `{b}` differ only in case, so they'd share an output directory on some file systems

**Fix:** Rename one of the builds.

**Read more:** [`[builds.<name>]`](https://ascribed-dev.com/docs/content-model/output.md#16-buildsname) in the `ascribe.toml` reference.

### ASC110 `model-build-variants`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.3](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#93-build-modes)

**When:** A build's `variants` isn't `"switch"` or a selection that names a dimension.

**Message:** variants must be "switch" or a selection such as { deployment = "cloud" }

**Fix:** Set `variants` to `"switch"`, or to a selection that names at least one dimension.

**Read more:** [`[builds.<name>]`](https://ascribed-dev.com/docs/content-model/output.md#16-buildsname) in the `ascribe.toml` reference.

### ASC111 `model-build-unknown-dimension`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.3](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#93-build-modes)

**When:** A build's selection names a dimension the content model doesn't declare.

**Message:** build `{build}` selects dimension `{dimension}`, which isn't declared

**Fix:** Correct the dimension's name, or declare the dimension in `[dimensions]`.

**Read more:** [`[builds.<name>]`](https://ascribed-dev.com/docs/content-model/output.md#16-buildsname) in the `ascribe.toml` reference.

### ASC112 `model-build-unknown-value`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.3](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#93-build-modes)

**When:** A build's selection names a value its dimension doesn't have.

**Message:** build `{build}`: `{value}` isn't a value of `{dimension}`; values: {values}

**Fix:** Use one of the values the message lists.

**Read more:** [`[builds.<name>]`](https://ascribed-dev.com/docs/content-model/output.md#16-buildsname) in the `ascribe.toml` reference.

### ASC113 `model-build-availability`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.3](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#93-build-modes)

**When:** A build's `availability` isn't `"badge"` or a filter.

**Message:** [availability](https://ascribed-dev.com/docs/glossary.md#availability) must be "badge" or { filter = "\<target> \<version>" }

**Fix:** Set `availability` to `"badge"`, or to `{ filter = "<target> <version>" }`.

**Read more:** [`[builds.<name>]`](https://ascribed-dev.com/docs/content-model/output.md#16-buildsname) in the `ascribe.toml` reference.

### ASC114 `model-build-filter-target`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.3](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#93-build-modes)

**When:** A build's filter names something other than a declared dimension value.

**Message:** build `{build}` filters for `{target}`, which isn't a declared dimension value

**Fix:** Filter for a declared dimension value, not a dimension name.

**Read more:** [`[builds.<name>]`](https://ascribed-dev.com/docs/content-model/output.md#16-buildsname) in the `ascribe.toml` reference.

### ASC115 `model-build-filter-version`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.3](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#93-build-modes)

**When:** A build's filter gives a versioned target no version, a versionless one a version, or a version that isn't valid.

**Message:** build `{build}` filters for `{target}`, which is versioned, so it needs a version, such as "{target} 3.3"

**Fix:** Give a versioned target a version (`"self-managed 3.3"`), and a versionless target none.

**Read more:** [`[builds.<name>]`](https://ascribed-dev.com/docs/content-model/output.md#16-buildsname) in the `ascribe.toml` reference.

### ASC116 `model-build-filter-excluded`

[Warning](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.3](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#93-build-modes)

**When:** A build filters for a target its own selection of variants leaves out.

**Message:** build `{build}` filters for `{target}`, but its selection keeps only {dimension} = {values}, so pages marked for `{target}` are dropped

**Fix:** Make the build's `variants` selection keep the target it filters for, or filter for a target it keeps.

**Read more:** [`[builds.<name>]`](https://ascribed-dev.com/docs/content-model/output.md#16-buildsname) in the `ascribe.toml` reference.

### ASC117 `model-editor-build-unknown`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §10](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#10-authoring-environment)

**When:** `[editor] build` names a build the content model doesn't declare.

**Message:** editor.build is `{build}`, which isn't a declared build; builds: {builds}

**Fix:** Set `[editor] build` to one of the builds the message lists.

**Read more:** [`[editor]`](https://ascribed-dev.com/docs/content-model/checks.md#23-editor) in the `ascribe.toml` reference.

### ASC118 `model-editor-build-required`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §10](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#10-authoring-environment)

**When:** The content model declares several builds, none named `site`, and `[editor] build` doesn't name one.

**Message:** there are several builds and none is named site; set \[editor\] build to the one the editor should check

**Fix:** Set `[editor] build` to the build the editor should check, or name one of the builds `site`.

**Read more:** [`[editor]`](https://ascribed-dev.com/docs/content-model/checks.md#23-editor) in the `ascribe.toml` reference.

### ASC162 `model-consumer-agents-site`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.5](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#95-consumer-profile)

**When:** `[consumer] agents = true` without `[consumer] site`.

**Message:** agents = true needs `site`: every link in llms.txt and the Markdown pages is an absolute URL

**Fix:** Set `site` in `[consumer]` to the published site's origin, such as `"https://docs.example.com"`, or remove `agents`.

**Read more:** [`[consumer]`](https://ascribed-dev.com/docs/content-model/output.md#15-consumer) in the `ascribe.toml` reference.

### ASC174 `model-consumer-permalink-path`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.5](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#95-consumer-profile)

**When:** `[consumer] permalink-path` doesn't start with `/`.

**Message:** [permalink](https://ascribed-dev.com/docs/glossary.md#permalink)-path must start with "/", such as "/go/"

**Fix:** Start `permalink-path` with `/`: `"/go/"`. It's a path from the site's root, not from `base-path`.

**Read more:** [`[consumer]`](https://ascribed-dev.com/docs/content-model/output.md#15-consumer) in the `ascribe.toml` reference.

### ASC206 `model-build-versions`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §9.3](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#93-build-modes)

**When:** A versioned build's target has no live line, or the build is filtered too.

**Message:** build `{build}` is versioned by `{target}`, which has no live line; list its lines in `[releases.{target}]`, such as `live = ["3.4"]`

**Fix:** Give the target its lines in `[releases.<target>]`, with `live`, or remove `versions` from the build. A build is either versioned, with one output for each live line, or filtered for one version; not both.

**Read more:** [`[builds.<name>]`](https://ascribed-dev.com/docs/content-model/output.md#16-buildsname) in the `ascribe.toml` reference.

## `[crawlers]`

### ASC183 `model-crawlers-line`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** A string in `[crawlers] lines` has a line break.

**Message:** `{key}` has a line break; each string in `lines` is one line of robots.txt

**Fix:** Split the string into one string per line: `lines = ["User-agent: *", "Disallow: /drafts/"]`.

**Read more:** [`[crawlers]`](https://ascribed-dev.com/docs/content-model/output.md#18-crawlers) in the `ascribe.toml` reference.

### ASC189 `model-crawlers-named-twice`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** `[crawlers]` names one crawler in two groups.

**Message:** `{key}` names `{token}`, which a group on line {line} names already; a crawler obeys only one group, so write everything for it in one

**Fix:** Name each crawler in one group. Move the lines for it into the first group that names it and remove the second `User-agent` line. For a crawler a disallowed purpose covers, the purpose's group already says `Disallow: /`: remove the group from `lines`, or allow the purpose and write the crawler's group whole in `lines`.

**Read more:** [`[crawlers]`](https://ascribed-dev.com/docs/content-model/output.md#18-crawlers) in the `ascribe.toml` reference.

## `[listing]`

### ASC185 `model-listing-folder`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** A folder in `[listing.folders]` doesn't exist, isn't a folder, or isn't written as a folder's path.

**Message:** `{folder}` in `[listing.folders]` doesn't exist under the content root

**Fix:** Write the folder's path from the content root, ending in `/`, with its name's case as it is on disk: `"internal/" = "unlisted"`. A rule is for a folder and everything under it; patterns aren't read.

**Read more:** [`[listing]`](https://ascribed-dev.com/docs/content-model/output.md#17-listing) in the `ascribe.toml` reference.

### ASC186 `model-listing-type`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** `[listing.types]` names something that isn't a content type.

**Message:** `{type}` in `[listing.types]` isn't a content type; use one of: {values}

**Fix:** Name a content type the project declares in `[types]`, or `page` when it declares none.

**Read more:** [`[listing]`](https://ascribed-dev.com/docs/content-model/output.md#17-listing) in the `ascribe.toml` reference.

### ASC187 `model-listing-looser`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#72-declarations)

**When:** A rule of `[listing]` is looser than a wider rule it's under.

**Message:** `{rule}` is looser than `{wider}` on line {line}, which it's under; a narrower rule can only restrict

**Fix:** Remove the narrower rule, or make it as strict as the one it's under, or stricter: `listed`, then `unquoted`, then `unlisted`. To list some pages more openly than the rest, loosen the wider rule, and restrict the others with rules of their own.

**Read more:** [`[listing]`](https://ascribed-dev.com/docs/content-model/output.md#17-listing) in the `ascribe.toml` reference.

## `[apis]`

### ASC259 `model-api-outside-repository`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.11](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#711-apis)

**When:** An API's spec is outside the project's repository, or, with no repository, outside the folder that was opened.

**Message:** the spec of API `{api}`, `{path}`, is outside the git repository the project is in

**Fix:** Give the API a `spec` inside the project's repository: a spec in another repository isn't read, so commit a copy of it, or the file your pipeline bundles. With no repository, the editor and `ascribe mcp` read a spec only inside the folder they were opened on: open the folder that contains it.

**Read more:** [`[apis.<name>]`](https://ascribed-dev.com/docs/content-model/sources.md#21-apisname) in the `ascribe.toml` reference.

### ASC260 `model-api-reference`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §7.11](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#711-apis)

**When:** An API's `reference` is an address pattern with a placeholder other than `{operationId}` and `{tag}`, or with no `{operationId}`.

**Message:** the reference of API `{api}` has no `{operationId}`, so every operation's address would be the same

**Fix:** Write the address pattern as your renderer addresses an operation, with `{operationId}` where the operation's id goes and `{tag}` for its first tag, such as `"/api/#/operations/{operationId}"` for Stoplight Elements. For Redoc, write `{ renderer = "redoc", at = "/api/" }` instead.

**Read more:** [`[apis.<name>]`](https://ascribed-dev.com/docs/content-model/sources.md#21-apisname) in the `ascribe.toml` reference.

## `[checks]`

### ASC142 `model-check-not-configurable`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §8.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#82-diagnostics)

**When:** `[checks]` sets the level of a check about whether the project is valid.

**Message:** `{check}` can't be set in \[checks\]: it reports whether the project is valid, which a project can't lower or turn off

**Fix:** Remove the check from `[checks]`. Only checks about the content's quality, which the [diagnostics reference](https://ascribed-dev.com/docs/checks/diagnostics.md) marks as configurable, can be set there; a diagnostic about whether the project is valid is always reported at its own severity.

**Read more:** [`[checks]`](https://ascribed-dev.com/docs/content-model/checks.md#22-checks) in the `ascribe.toml` reference.

### ASC146 `model-intended-check`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §4.9](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#49-intended)

**When:** An acknowledgement in `[[intended]]` names something that isn't a check, a check that isn't a review check, or one whose problems are acknowledged in the pages.

**Message:** `{check}` isn't a check

**Fix:** Name a check whose next step is review and whose problems are about a phrase, feature, glossary term, or image, by its name in the [diagnostics reference](https://ascribed-dev.com/docs/checks/diagnostics.md). A page's or a block's problem is acknowledged in the page itself.

**Read more:** [`[[intended]]`: acknowledgements](https://ascribed-dev.com/docs/content-model/checks.md#intended-acknowledgements) in the `ascribe.toml` reference.

### ASC147 `model-intended-entry`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [choose](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §4.9](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#49-intended)

**When:** An acknowledgement in `[[intended]]` doesn't name exactly one thing the content model declares, or its reason is still a placeholder.

**Message:** an acknowledgement in \[\[intended\]\] names what it's about with one of `phrase`, `feature`, or `image`

**Fix:** Give the acknowledgement exactly one of `phrase`, `feature`, or `image` (a path under the content root), naming something the content model declares, and a reason of your own in place of the placeholder the editor's quick fix writes.

**Read more:** [`[[intended]]`: acknowledgements](https://ascribed-dev.com/docs/content-model/checks.md#intended-acknowledgements) in the `ascribe.toml` reference.

### ASC167 `model-checks-vale`

[Error](https://ascribed-dev.com/docs/checks/diagnostics.md#severity) · [file level](https://ascribed-dev.com/docs/checks/diagnostics.md#file-level-and-page-level) · next step: [write](https://ascribed-dev.com/docs/checks/diagnostics.md#what-to-do-next) · [SPEC §8.2](https://github.com/ascribed-dev/ascribe/blob/main/SPEC.md#82-diagnostics)

**When:** `[checks.vale]` has both `preset` and `config`, or neither, or turns off a rule with `config` or one its preset doesn't have.

**Message:** `[checks.vale]` has both `preset` and `config`; pick one: Ascribe's preset, or the project's own `.vale.ini`

**Fix:** Give `[checks.vale]` one of `preset = "quiet"` or `config = "<path to .vale.ini>"`. `off` lists rules of the preset to turn off, by their names in alerts (`Ascribe.Repeated`), and is only for a preset.

**Read more:** [`[checks.vale]`](https://ascribed-dev.com/docs/content-model/checks.md#checksvale) in the `ascribe.toml` reference.