Extracts hand-written Markdown guides, with optional YAML frontmatter.

Module documentation covers the code; guides cover everything else — getting started pages, architecture notes, runbooks, policy documents. This extractor walks one or more base directories recursively for .md files and turns each into a content entry:

%{
  "id" => "getting-started",
  "title" => "Getting Started",
  "kind" => "guide",
  "ast" => [...],
  "meta" => %{"audience" => "operators", "source_path" => "guides/getting-started.md"}
}

Frontmatter

A file may open with a YAML block delimited by --- lines:

---
id: getting-started
title: Getting Started
audience: operators
---

# Getting started with the platform

The parsed frontmatter becomes the entry's meta verbatim, plus a source_path key, so hosts can carry arbitrary facets — audience, locale, product area, ordering — without DocShell needing to know what they mean. DocShell.Presentation.StaticGenerator reads audience and locale from there; everything else passes straight through to the renderer.

id and title are read from frontmatter when present. Otherwise the id falls back to the filename without its extension and the title to the first Markdown H1, which means a guide with no frontmatter at all still produces a sensible entry.

Frontmatter that is not a YAML mapping, or whose opening --- is never closed, is an error rather than something to shrug off — a typo there otherwise silently reclassifies a document.

Files are sorted by path so the artifact is stable across builds.