feat: add topology graph v0.2.2 contract

docs/source/2026-06-17-markitdown-reference-notes.md

@@ -0,0 +1,17 @@
+# MarkItDown Reference Notes
+
+Source reviewed: Microsoft `markitdown`, official repository and README.
+
+## Useful Patterns
+
+- Keep conversion and extraction units narrow. MarkItDown separates `accepts()` from `convert()`, which maps well to this engine's separation between candidate selection, locator verification, replay, and failure records.
+- Prefer a registry-style extraction pipeline when multiple strategies may apply. MarkItDown registers specific converters before generic HTML/plain-text fallbacks; a future topology engine can use the same pattern for snapshot extraction strategies without becoming a generic crawler.
+- Preserve machine-friendly output over high-fidelity rendering. MarkItDown targets Markdown for LLM/text pipelines, not perfect visual reproduction. This matches this project's graph-artifact boundary.
+- Normalize output centrally. MarkItDown trims trailing line whitespace and collapses excessive blank lines after converter execution; this project now uses graph summaries and JSON Schema validation as artifact-level normalization checks.
+- Keep security boundaries explicit. MarkItDown warns that URI/file conversion performs I/O with current process privileges and recommends narrow conversion APIs. This project should keep navigation scopes, timeouts, and risk policy explicit rather than adding broad fetch/convert behavior.
+
+## Non-Adopted Items
+
+- Do not add MarkItDown as a runtime dependency for v0.2.2.
+- Do not emit Markdown as the primary artifact. Markdown can be future evidence or summaries, but the project contract remains `TopologyGraph`.
+- Do not add LLM/OCR/cloud conversion plugins to this repository.