Braised Docs

Authoring for Agents

Writers have two frontmatter fields for controlling how their content appears to agents, a site-level config for the llms.txt preamble, and a diagnostic command for checking what an agent sees before deploying.

llm_description

Overrides the description used in llms.txt and the frontmatter-index artifact for this page.

---
title: Theme Variables
llm_description: Complete reference for all CSS custom properties and their defaults.
---

When llm_description is absent, braised resolves the description in priority order:

  1. llm_description: — explicit override, always wins
  2. description: — standard meta description field, used as a fallback when no extractable paragraph exists (useful for reference pages that open with a directive block rather than prose)
  3. First paragraph — extracted from the page body; braised descends one level into directive blocks (e.g. :::{.synopsis}, :::{.callout}) before looking for prose, so lead directives are not silently skipped

Use llm_description when the first paragraph is scene-setting prose for human readers rather than a concise statement of the page's purpose. The value does not affect chunk hashes — changing it never invalidates the RAG index.

llm_description affects two outputs: llms.txt (nav-listed pages only) and frontmatter-index (all built pages). Setting it on a page not in nav.yaml has no effect on llms.txt but is still surfaced via get_page_index().

llm_exclude

When true, excludes the page from all agent-facing outputs.

---
title: Internal Notes
llm_exclude: true
---

An excluded page is suppressed from:

  • llms.txt — omitted from the index entirely
  • manifest.jsonl — chunks not written; the page does not enter any downstream pipeline
  • frontmatter-index artifact — omitted from get_page_index() output
  • get_page(path) — returns the same not-found error as a genuine miss

The page is still built — HTML and companion .md are written to dist/ and accessible by direct URL. llm_exclude is an agent visibility control, not a build gate.

llms_txt.preamble in braised.yaml

Insert site-level context into llms.txt between the description line and the first section listing. Use it for facts an agent should know before reading any pages: version conventions, naming, architectural constraints.

# braised.yaml
llms_txt:
  preamble: |
    Config file: braised.yaml. Binary: braised.
    Directive syntax: :::block-name (not shortcodes).
    Theme extension uses CSS custom properties, not Sass variables.

When absent, no preamble is emitted. The value is inserted verbatim — no Markdown processing.

braised inspect --agent

Check what an agent sees for a specific page before deploying. Run braised build first — the companion .md and artifact sections require build output.

braised inspect --agent docs/theming/variables.md

Output:

FILE      /site/docs/theming/variables.md
SITE DIR  /site

─── AGENT DIAGNOSTICS

llms.txt
  included:     yes
  description:  llm_description  (explicit)
  text:         Complete reference for all CSS custom properties and their defaults.

companion .md
  status:       present  (dist/theming/variables/index.md)
  size:         4.2 KB

chunks  (6 total)
  /theming/variables/
    heading:    Theme Variables  (page root)
    content:    Theme Variables\n\nThis page lists all CSS custom properties...
    hash:       a3f9c2b1
  ...

artifacts
  frontmatter-index:  present
  layout:             page
  in_nav:             yes

llms.txt — Inclusion status, description source (llm_description or first_paragraph), and resolved text. Pages showing first_paragraph (fallback) are candidates for an explicit llm_description.

companion .md — Whether the file exists and its size. A very small size (under ~100 bytes) usually means the page is a section index with no body content — expected for organizational stub pages.

chunks — Every chunk the AST chunker produces: ID, heading level, first 120 characters of baked content, and hash. This is exactly what gets written to manifest.jsonl. Review this if a chunk looks wrong in your downstream pipeline.

artifacts — Whether the page appears in frontmatter-index and its resolved layout and in_nav values. Requires a prior build.

See CLI Reference for all inspect flags.