Foldkit Documentation Audit

Foldkit's docs are in unusually good shape for a pre-1.0 framework — llms.txt and llms-full.txt both resolve, every docs page is also served as Markdown by appending .md (verified for 30+ pages), all 167 internal and ~128 external links referenced from llms-full.txt return HTTP 200, npm package versions and engine requirements match the docs' claims exactly, and the docs were cleaned of a removed API (Update.noOp) within one release of its removal. The remaining issues are localized: the flagship testing example isn't runnable as written, and a couple of cross-page references assume knowledge the docs never supply.

1. "Testable by Design" Story example references an app that is never shown (significant)

Location: /core/commands (section "Testable by Design")

Problem: The page's headline testing example — Story.story(update, Story.with({ count: 5 }), Story.message(ClickedResetAfterDelay()), Story.Command.expectExact(DelayReset), Story.Command.resolve(DelayReset, CompletedDelayReset()), ...) — depends on update, ClickedResetAfterDelay, DelayReset, and CompletedDelayReset, none of which are defined or imported anywhere on the page. The counter app documented on /core/counter-example (the only complete app in the core docs) has no delay or DelayReset Command, so there is no documented app this test runs against. The only imports shown are Story from foldkit and expect, test from vitest.

Consequence: A developer (or AI agent — code verification is a stated consumer of these docs) who copies the snippet gets four undefined-identifier errors and must reverse-engineer an entire delayed-reset application (a Message, a Command with a timer Effect, a completion Message, and an update branch) just to make the docs' central testability claim executable. The docs sell "Commands aren't just a fancy way to organize side effects. They're the reason Foldkit programs are easy to test" — and then the proof can't be run.

The fix: Either show the delayed-reset app's Model/Message/Command/update definitions above the test (a ~30-line addition), or rewrite the Story example against the counter app already documented on /core/counter-example so the test is runnable by combining two adjacent pages.

2. The counter app is called "complete" but the two files shown cannot run without undocumented scaffold files (minor)

Location: /core/counter-example

Problem: The page opens with "Here's a complete counter application" and states "A Foldkit app lives in two files" — and . But mounts into , which requires an with a element, and the view is styled entirely with Tailwind utility classes (), which require the Tailwind entry point and Vite config. Those files exist only in the scaffold documented on a different page (Getting Started's project-structure table lists , , and ), and the counter-example page neither shows them nor links to that table.