Foldkit Documentation Audit

Foldkit's docs are unusually well-engineered — llms.txt, llms-full.txt, per-page .md exports, an OpenAPI 3.1 spec, a versioned read-only Content API with RFC 9457 errors, and live HTTP behavior that matches what the docs claim. But the flagship feature of this docs site — its machine-readable, agent-first surface — silently drops the named code examples across core pages, and the API deprecation policy's own example contradicts the policy two sentences above it.

1. Agent-facing Markdown exports silently drop captioned code examples while the prose keeps referencing them (critical)

Location: https://foldkit.dev/core/http.md, https://foldkit.dev/testing.md, https://foldkit.dev/core/query.md, https://foldkit.dev/llms-full.txt (same gap at the corresponding sections, e.g. "HTTP Command", "Delayed-reset Story test", "Weather search Scene test", "Using makeApplication without routing", "Defining a Query for posts", "Redacting a short-lived access token")

Problem: llms.txt tells agents: "Fetch any page below as Markdown by appending .md to its URL" and offers llms-full.txt as "Every documentation page concatenated into one Markdown file." But the Markdown exports omit the site's captioned example blocks. On /core/http.md, the caption "HTTP Command" is followed directly by the next heading "## Customizing the Client" — no code — while the HTML page contains the FetchCount example (the identifier appears 10 times in the HTML and 0 times in the .md). On /testing.md, "Delayed-reset Story test" and "Weather search Scene test" are bare caption lines with no code, while the HTML contains the test code (ClickedResetAfterDelay present in HTML, absent in .md). Worse, the surrounding prose narrates the missing code as if it were there: /core/query.md says "In this definition: - data and error determine the AsyncData and Message Schemas" under a caption with no definition shown, and the DevTools page says "The numbered comments trace the Model-to-request path through the example" — an example the Markdown reader never receives.

Consequence: The exact audience this surface was built for gets the worst version of the docs. An agent consuming llms-full.txt or the .md pages reads commentary about code it cannot see, and will either hallucinate the missing example (inventing Query.define or Story API shapes from prose) or fail silently. Plain fenced code blocks do survive the export (llms-full.txt has ~2,078 fences), so the gap is invisible unless you diff against the HTML — the most dangerous kind of omission.