docs: add language spec, domain glossary, and fixture update

.claude/adr/0001-step-reference-syntax.md

@@ -0,0 +1,44 @@
+# ADR 0001 — Step Reference Syntax
+
+**Status**: Accepted
+
+## Context
+
+KitchenMD supports Combined Recipes: files whose sole purpose is to sequence steps from two or more other Recipe Files into a single cooking order (e.g. "penne alla vodka + italian meatballs").
+To express this, a Combined Recipe needs to embed specific steps from other files — not entire files or sections, but individual lines of instruction.
+
+Obsidian's existing transclusion syntax (`![[file#heading]]`) transclude a section from heading to the next heading.
+It has no native concept of step-level granularity.
+
+Two approaches were considered:
+
+**Option A — Extend Obsidian's anchor syntax with a `:N` suffix**
+`![[file#section:N]]` for a named section, `![[file#N]]` for a headingless recipe.
+The `:N` part is a KitchenMD-specific extension; vanilla Obsidian does not recognise it and renders an "unable to find" error for the anchor.
+
+**Option B — Use Obsidian block references**
+Obsidian supports `![[file#^blockid]]` to transclude a specific block.
+Authors would manually assign block IDs to every step (e.g. `^step-1`, `^step-2`).
+This is valid Obsidian syntax and would render correctly without KitchenMD tooling.
+
+## Decision
+
+**Option A** — extend Obsidian's anchor syntax with `:N` for section-scoped steps and bare `#N` for headingless recipes.
+
+## Rationale
+
+Option B (block references) requires authors to manually annotate every step with a block ID, which is tedious, error-prone, and pollutes the source file with machine IDs (`^step-1`) that are meaningless to human readers.
+The authoring cost is too high for a format designed to be written naturally.
+
+Option A requires no author effort beyond normal recipe writing.
+Step numbers are derived automatically by the parser from document structure.
+The compatibility cost is acceptable: vanilla Obsidian renders a visible "unable to find" error rather than silently corrupting content, so the break is obvious and recoverable.
+Combined Recipes are a specialised document type — authors who create them are expected to use KitchenMD tooling.
+
+Step numbers are **section-local** (reset at each heading) rather than global, so adding or removing steps in one section does not renumber steps in other sections and does not break existing Step References elsewhere.
+
+## Consequences
+
+- Combined Recipe files will not render correctly in vanilla Obsidian without the KitchenMD plugin; they will show "unable to find" errors for step anchors.
+- Individual Recipe Files (non-combined) are unaffected — they contain no Step References and render correctly in vanilla Obsidian.
+- The KitchenMD parser and future Obsidian plugin must implement step counting to resolve `![[file#section:N]]` and `![[file#N]]` references.