Artifacts Reference

Every braised build writes a set of structured JSON files to artifacts/. These are the data source for braised mcp serve — each tool call reads from an in-memory copy loaded at startup. They are also machine-readable directly: any script, CI job, or custom tool can parse them.

artifacts/ is distinct from dist/manifest.jsonl. The manifest is a flat stream of content chunks for embedding pipelines (one record per section). Artifacts are structured documents for deterministic lookups: navigation tree, page metadata, source provenance.

Common envelope

Every artifact file shares the same JSON wrapper:

{
  "artifact_type": "nav-structure",
  "project":       "My Docs",
  "generated_at":  "2026-04-24T12:00:00Z",
  "schema_version": "1",
  "data": { ... }
}

Field	Type	Description
`artifact_type`	string	Identifies the artifact. Built-in values: `nav-structure`, `frontmatter-index`, `sources-index`.
`project`	string	Value of `site.title` from `braised.yaml`.
`generated_at`	string	ISO 8601 UTC timestamp of the build that produced the file.
`schema_version`	string	Schema version for the `data` payload. Currently `"1"` for all built-in types. Adding optional fields is non-breaking and does not bump this value; removing fields or changing types does.
`data`	object	Artifact-type-specific payload. See each section below.

nav-structure.json

The full site navigation tree as braised resolved it from nav.yaml, after nav_title overrides are applied.

{
  "artifact_type": "nav-structure",
  "schema_version": "1",
  "data": {
    "roots": [
      {
        "label": "Getting Started",
        "url": "",
        "children": [
          {"label": "Installation", "url": "/getting-started/installation/", "children": []},
          {"label": "Your First Site", "url": "/getting-started/first-site/", "children": []}
        ]
      }
    ]
  }
}

data fields:

Field	Type	Description
`roots`	[]NavNode	Top-level navigation entries. Never null — empty array when nav is empty.

NavNode:

Field	Type	Description
`label`	string	Display label from `nav.yaml` or `nav_title` frontmatter override.
`url`	string	Output URL with trailing slash. Empty string for section headers with no page of their own.
`children`	[]NavNode	Nested entries. Never null — leaf nodes emit `[]`.

frontmatter-index.json

One entry per successfully built page, sorted by URL. Pages with llm_exclude: true are filtered out.

{
  "artifact_type": "frontmatter-index",
  "schema_version": "1",
  "data": {
    "pages": [
      {
        "url":             "/getting-started/installation/",
        "title":           "Installation Guide",
        "layout":          "default",
        "llm_description": "How to install braised on macOS, Linux, and Windows.",
        "llm_exclude":     false,
        "in_nav":          true
      }
    ]
  }
}

data fields:

Field	Type	Description
`pages`	[]PageEntry	All non-excluded built pages.

PageEntry:

Field	Type	Description
`url`	string	Output URL with trailing slash.
`title`	string	Page title from frontmatter.
`layout`	string	Layout template in use. `"default"` unless overridden in frontmatter.
`llm_description`	string	Agent-facing description. Resolved from `llm_description` frontmatter; falls back to the first paragraph of page content if omitted.
`llm_exclude`	bool	Always `false` here — excluded pages are not written to this artifact.
`in_nav`	bool	Whether the page URL appears in the resolved nav tree.

sources-index.json

Provenance index built from :::sources backmatter blocks across the site. Always written — empty maps when no :::sources blocks exist.

{
  "artifact_type": "sources-index",
  "schema_version": "1",
  "data": {
    "by_page": {
      "/agentic/mcp-serve/": ["https://modelcontextprotocol.io/spec/2024-11-05"]
    },
    "by_source": {
      "https://modelcontextprotocol.io/spec/2024-11-05": ["/agentic/mcp-serve/"]
    },
    "coverage": {
      "uncovered_pages": ["/getting-started/installation/", "/getting-started/first-site/"],
      "by_group": {
        "mcp-spec": {"pages_citing": 1},
        "unmatched": {"pages_citing": 0}
      }
    }
  }
}

data fields:

Field	Type	Description
`by_page`	map[string][]string	Maps each page URL to its resolved source URLs. Only pages with at least one `:::sources` entry are present.
`by_source`	map[string][]string	Inverted index — maps each source URL to the page URLs that cite it.
`coverage.uncovered_pages`	[]string	Page URLs with no `:::sources` block. Null (not `[]`) when all pages have sources.
`coverage.by_group`	map[string]SourcesGroupCount	Per-registry-group citation counts. Omitted when no `sources` registry is configured in `braised.yaml`. Key `"unmatched"` collects source URLs that match no registered prefix.

SourcesGroupCount:

Field	Type	Description
`pages_citing`	int	Number of pages citing at least one source in this group.

See Documentation Provenance for how :::sources blocks work and how to configure the registry.

Inspecting artifacts

All artifact files are pretty-printed JSON — readable directly with any JSON tool.

# Check when the last build ran and what it produced
cat .braised/last_build.json

# Count pages in the index
jq '.data.pages | length' artifacts/frontmatter-index.json

# List all pages not in nav
jq -r '.data.pages[] | select(.in_nav == false) | .url' artifacts/frontmatter-index.json

# Show the full nav tree
jq '.data.roots' artifacts/nav-structure.json

# List pages with no sources declared
jq -r '.data.coverage.uncovered_pages[]?' artifacts/sources-index.json

For inspecting manifest.jsonl — which is a flat NDJSON stream rather than a structured JSON file — see Writing a Pipeline Script and scripts/inspect-manifest.sh.

theme-variables.json (optional)

Not generated by default. When present in artifacts/, braised mcp serve registers it as the get_theme_variables tool. This artifact is produced by an optional CSS extractor pipeline step — until that step is configured, get_theme_variables returns a not-found response and the tool is absent from tools/list.