Welcome to the Reports

Why a reports section

The trade-offs, patterns, and architecture pages are deliberately opinionated — they freeze a point of view in HTML. Reports are where we get to be timely: case studies, postmortems, retros, and field notes that don't belong in the evergreen guide.

Each report is a single Markdown file in reports/. Drop one in, add it to the manifest, and it shows up here.

How a report is structured

Every report starts with YAML frontmatter that drives the header card and the article hero:

---
title: A useful, scannable title
description: A one-line summary that shows on the index page.
date: 2026-05-06
author: Your name
image: images/your-header.svg
imageAlt: Description of the image, for screen readers.
tags: [post-incident, caching]
---

The body is plain Markdown. Headings, links, lists, and fenced code blocks all work out of the box.

function pickEvil(options: Tradeoff[]): Tradeoff {
  return options.sort((a, b) => a.regret - b.regret)[0];
}

Quotes use the same border-and-italic treatment as the field guide itself, so reports feel native rather than tacked on.

Adding a new report

1. Create reports/your-slug.md with frontmatter at the top.
2. Drop a header image into reports/images/ (SVG, PNG, or JPG).
3. Add an entry to reports/index.json:

{ "slug": "your-slug", "file": "your-slug.md" }

4. Reload the page. The new report appears at the top of the list, sorted by date.

That's it — no build step, no database, no CMS. The site is still served straight out of nginx.