Build Outputs

braised build produces outputs in three locations. This page is a map — each section describes what lives where and links to the page that covers it in depth.

your-project/
├── dist/           ← serve this; everything a browser or agent needs
├── artifacts/      ← structured JSON for braised mcp serve
└── .braised/       ← local build state; add to .gitignore

dist/

The complete site, ready to deploy. Copy dist/ to any static host.

dist/
├── index.html
├── getting-started/
│   └── installation/
│       ├── index.html     ← clean URL page
│       └── index.md       ← companion Markdown (agent-readable)
├── assets/
│   ├── braised.css
│   └── braised.js
├── llms.txt               ← site index for AI agents
└── manifest.jsonl         ← content chunks for embedding pipelines

Output	Purpose
**/*.html	HTML pages with clean URLs.
**/index.md	Companion Markdown for every page — the same content, no HTML. Agents and tools read these directly without parsing HTML.
assets/	Compiled CSS and JS bundles.
llms.txt	Site content map for AI agents and tools. Lists every page title, URL, and description in a standard format.
manifest.jsonl	Newline-delimited JSON stream of content chunks and deletion records for embedding pipelines and vector stores.
sitemap.xml	Standard XML sitemap for search engine crawlers. Only generated when site.url is set in braised.yaml.

dist/ is safe to serve directly and safe to commit if you deploy via git. See Deployment for hosting options and sub-path configuration.

For manifest.jsonl field details and how to consume it in a pipeline script, see Manifest Reference and Writing a Pipeline Script.

artifacts/

Structured JSON files loaded by braised mcp serve at startup to answer MCP tool calls. Not served to browsers — these are for programmatic consumption.

artifacts/
├── nav-structure.json      ← full navigation tree
├── frontmatter-index.json  ← per-page metadata for all built pages
└── sources-index.json      ← provenance index from :::sources blocks

All three share a common JSON envelope with artifact_type, schema_version, and generated_at fields. See Artifacts Reference for schemas and field tables.

artifacts/ can be committed or kept out of git — it is reproducible from any build and does not contain secrets.

.braised/

Local build state. Add this directory to .gitignore — it is machine-specific and should not be shared.

.braised/
├── index-state.json   ← per-file hashes and chunk IDs from the last build
└── last_build.json    ← timestamp and per-step status of the last build

index-state.json

Tracks a content hash (FNV-32a) and the chunk IDs produced for every source file. Braised compares this against the current file hashes on each build to determine:

• which pages changed and need new chunk records in manifest.jsonl
• which old chunk IDs to emit as deletion records

Without this file (first build, or after deleting it), braised treats all pages as changed and emits a full set of chunk records with no deletions. This is safe — it just loses the incremental benefit.

In CI, cache .braised/ between runs to preserve incremental builds. Without the cache, every CI build is a full rebuild.

last_build.json

Written at the end of every build — including failed ones — so CI scripts, deployment tools, and braised mcp serve can inspect what happened without parsing log output.

{
  "completed_at": "2026-04-24T12:00:00Z",
  "steps": {
    "pages":     "ok",
    "manifest":  "ok",
    "assets":    "ok",
    "llms_txt":  "ok",
    "pipeline":  "ok",
    "artifacts": "ok",
    "sitemap":   "ok"
  }
}

Step values: ok, failed, partial (some pages built, some did not), skipped.

A missing or unparseable last_build.json means the previous build was killed or crashed before it finished — braised writes this file only after all steps complete.