Braised Docs

Documentation Provenance

:::sources blocks let you record which source files a doc page is derived from. Combined with the sources-index artifact, they give an AI agent the information it needs to check whether the documentation still matches the code — without crawling the whole repo.

:::sources blocks

Place a :::sources block at the very end of any doc file. The content is a YAML list of source references:

:::sources
- braised:internal/config/config.go
- braised:internal/chunk/chunk.go
:::

The block is stripped from the file before Goldmark processes it. It never appears in the built HTML or companion Markdown — it is purely a build-time provenance record.

Rules:

  • Only the last :::sources block in a file is extracted. An earlier occurrence is passed through to the block renderer unchanged (treated as an unknown block and silently ignored).
  • The block must have a closing ::: on its own line. Unclosed blocks are silently skipped.

Source registry

Entries can be full URLs or shorthand that expands using the sources registry in braised.yaml.

Full URL — passes through as-is:

:::sources
- https://github.com/postgres/postgres/blob/master/src/backend/parser/gram.y
:::

Registry shorthand — requires a matching key in sources:

# braised.yaml
sources:
  pg-parser:
    label: "PostgreSQL Parser"
    prefix: "https://github.com/postgres/postgres/blob/master/src/backend/parser/"

:::sources
- pg-parser:gram.y
- pg-parser:analyze.c
:::

pg-parser:gram.y expands to https://github.com/postgres/postgres/blob/master/src/backend/parser/gram.y. Double slashes at the join point are normalised automatically.

An unrecognised registry prefix (a key with a colon that doesn't appear in sources) generates a build warning. The entry is stored verbatim so the artifact records what the author wrote.

sources-index artifact

After every build, braised writes artifacts/sources-index.json. The artifact has three sections:

{
  "data": {
    "by_page": {
      "/configuration/braised-yaml/": [
        "https://github.com/…/internal/config/config.go",
        "https://github.com/…/internal/chunk/chunk.go"
      ]
    },
    "by_source": {
      "https://github.com/…/internal/config/config.go": [
        "/configuration/braised-yaml/"
      ]
    },
    "coverage": {
      "uncovered_pages": [
        "/",
        "/agentic/authoring/",
        "…"
      ],
      "by_group": {
        "pg-parser": { "pages_citing": 4 }
      }
    }
  }
}

See Artifacts Reference for the full field schema.

The artifact is always written — with empty maps when no :::sources blocks exist in the site.

Running a provenance audit

The sources-index artifact gives an agent the full dependency graph: which pages cite which sources. The audit task is to check whether the documentation still accurately describes the code.

Effective audit prompts share three properties:

  • Two-directional. Check claims in the docs against the source code, AND enumerate what the source exposes and verify the docs cover it. One direction misses half the gaps.
  • Pre-enumerated. Read sources-index.json yourself and pass the file→source mappings explicitly. Asking the agent to discover them wastes effort and risks scope drift.
  • Coverage-confirmed. Ask the agent to state which sections of each doc it reviewed before reporting. This makes the audit auditable — a finding omission is visible.

Step 1 — Read the artifact first.

Open artifacts/sources-index.json. The by_page map tells you exactly which doc files have source provenance and which source files they claim to describe. Note coverage.uncovered_pages — pages with no :::sources are outside the audit scope but may be worth flagging.

Step 2 — Enumerate the file pairs in your prompt.

Do not ask the agent to discover the mappings. Paste the by_page entries directly into the prompt. For each source file, provide its confirmed local path (or full URL) so the agent does not guess.

Step 3 — Require both directions.

The most common omission in a one-shot audit prompt is checking only claims (docs → code). This catches wrong values and stale descriptions, but misses features the code implements that the docs never mention. Require both checks explicitly:

  • Claims check: for every claim in the doc, does the source match?
  • Completeness check: for every exported type, field, and behavior in the source, is it documented?

Step 4 — Require a coverage confirmation before findings.

Ask the agent to list which sections of each doc it reviewed before producing the finding list. Without this, there is no way to distinguish "no finding" from "not checked." A short coverage statement — "reviewed sections: Fields, Scope; skipped: Custom metadata (no sources relation)" — is enough.

Step 5 — Interpret the output.

Two independent agents running the same prompt are unlikely to produce identical findings. Treat high-severity items confirmed by both as actionable. Items found by only one agent warrant a manual check before fixing — the finding may be real, or it may reflect a reading error.

You are performing a documentation provenance audit for [PROJECT NAME].
Do not reference prior agent runs — start fresh.

## Files to audit

[Copy from artifacts/sources-index.json → data.by_page]
- `docs/[path].md` → sources: `[source file 1]`, `[source file 2]`
- `docs/[path].md` → sources: `[source file 1]`

## Source file locations

[Provide confirmed local paths for each unique source file]
- `[registry-id:path]` → `/path/to/local/repo/[path]`

## For each doc + source pairing, run two checks

**Check 1 — Claims (docs → code)**
Read every claim in the doc about that source file's domain: config fields,
option values, enums, defaults, behaviors, constraints. For each claim,
verify it against the source code. Look for:
- Config fields or options documented but not implemented
- Enum values, defaults, or option names that don't match the source
- Behaviors described that the code does not perform

**Check 2 — Completeness (code → docs)**
Enumerate every exported type, config field, and public-facing behavior in
the source file. For each, verify it is either documented in the referenced
doc, or clearly internal/unexported and not user-facing. Look for:
- Exported fields or types present in the source that the doc omits
- Features implemented in the source but absent from the documentation

## Coverage confirmation

Before listing findings, state which sections of each doc file you reviewed.
Format: "Reviewed [doc path]: sections [list]. Skipped: [list + reason]."

## Output format

Return a numbered list. For each finding:
- **Severity**: HIGH / MEDIUM-HIGH / MEDIUM / LOW
- **File**: doc file path
- **Claim**: exact quote from the doc, or "missing — not documented" for completeness gaps
- **Reality**: what the source code actually does, with line numbers
- **Source**: source file and line number

Be specific. Quote doc text exactly. Cite line numbers in the source.