Foldkit's docs are unusually agent-friendly (llms.txt, llms-full.txt, per-page .md endpoints across 139 pages) and honest about the framework's pre-1.0 state, but they hide the single most consequential fact about the framework — its exact-pinned dependency on an Effect v4 beta — and the API reference contradicts its own guides on the framework's core primitive.
1. The Effect version requirement is undocumented — and it's an exact-pinned v4 beta (critical)
Location: Site-wide; verifiable against the npm registry entry for foldkit@0.127.0 and /core/http
Problem: The published foldkit package pins its peer dependencies to exact beta versions: "effect": "4.0.0-beta.88" and "@effect/platform-browser": "4.0.0-beta.88". No documentation page states which Effect version Foldkit requires — a grep across all 139 docs pages found zero mentions of the Effect peer dependency or any version constraint. The homepage and README repeatedly say "Built on Effect. Inside and out." and "If you already know Effect, Foldkit feels natural," and the /core/http guide imports from effect/unstable/http — an unstable module of a beta major — without comment. There is also no page showing how to install foldkit itself or its Effect peers: the only install path for the framework is npx create-foldkit-app@latest (the sole manual npm install in the docs is npm install -D @foldkit/devtools-mcp on /ai/mcp, for the optional dev tool), and Getting Started lists no Node.js prerequisite.
Consequence: A developer who "already knows Effect" almost certainly has stable Effect v3 installed. Adding foldkit to an existing project produces peer-dependency conflicts against an exact-pinned beta they were never told about, and the docs' own code (effect/unstable/http, S.decodeUnknownEffect, Effect.catch) won't typecheck against the Effect they know. Because the pin is exact, every Foldkit upgrade can force a lockstep Effect beta upgrade — a major adoption decision the docs never surface.
The fix: Add a "Requirements" section to Getting Started stating the exact Effect version pin, the fact that it is an Effect v4 beta, the Node.js requirement, and a manual-install snippet (npm install foldkit effect@4.0.0-beta.88 @effect/platform-browser@4.0.0-beta.88). Call out effect/unstable/http explicitly on the Http page.
2. API reference signature for Command.define contradicts every usage example (significant)
Problem: The rendered signature shows result schemas as a single positional parameter — (name: Name, results: Results) and (name: Name, args: Fields, results: Results) — but the source at the pinned commit (packages/foldkit/src/command/index.ts) declares a rest parameter: name: Name, ...results: Results. Every guide example passes results variadically, e.g. Command.define('FetchCount', SucceededFetchCount, FailedFetchCount) on /core/http. The reference, as rendered, reads as if you pass an array of schemas.
Consequence: Command.define is the core primitive for all side effects in Foldkit. A developer (or an AI agent parsing the reference) who follows the rendered signature writes Command.define('FetchCount', [SucceededFetchCount, FailedFetchCount]) and gets an opaque type error. Agents in particular treat reference signatures as ground truth and will generate broken code from this page.
The fix: Fix the signature renderer (or the doc extraction) so rest parameters keep their ...; the reference should show (name: Name, ...results: Results) matching the source and every guide.
3. GitHub README contradicts the docs on what create-foldkit-app scaffolds (significant)
Location: github.com/foldkit/foldkit README (Get Started) vs /tooling/oxlint-plugin and /get-started/getting-started
Problem: The README says create-foldkit-app "scaffolds a complete setup with Tailwind, TypeScript, ESLint, Prettier, and the Vite plugin." The docs' Getting Started page lists .oxlintrc.json in the generated project structure, and the Oxlint Plugin page says scaffolded projects include ".oxlintrc.json, a lint script, oxlint, and @foldkit/oxlint-plugin" — Oxlint, not ESLint.
Consequence: The README is many developers' (and agents') first touchpoint. Someone expecting ESLint will look for .eslintrc, try to add ESLint plugins, or ask an agent to configure ESLint in a project that ships Oxlint with a Foldkit-specific rule plugin. Agents that ingest both sources get contradictory facts about the same scaffolder and pick one silently.
The fix: Update the README's Get Started section to say Oxlint (and link the Oxlint Plugin docs page). Add a doc-vs-README consistency check to the release checklist.
4. Two dead GitHub source links, including the only in-production reference for a documented pattern (significant)
Location: /core/subscriptions and /example-apps/charting
Problem: Verified 404s in a probe of all 128 unique external links across the docs: (1) the Subscriptions page's documentDragStyles link points to packages/foldkit/src/ui/dragAndDrop/index.ts#L679-L701, but packages/foldkit/src/ui no longer exists on main — the UI code moved to packages/ui; (2) the Charting example's "View source on GitHub" points to examples/charting/src/main.ts, which doesn't exist — that example is split into model.ts, update.ts, view/, etc. All 26 other example pages' source links returned 200.
Consequence: The subscriptions link is the page's only pointer to "the DOM-state-only shape in production" — a pattern the docs describe but never show inline, so the 404 leaves readers with prose and no code. Line-pinned links to main are guaranteed to rot again as the repo is refactored.
The fix: Repoint both links (the UI one to packages/ui, the charting one to the example directory rather than a nonexistent main.ts), pin deep links to a commit SHA instead of main, and add a link checker to CI.
5. Examples import @foldkit/ui everywhere, but no page tells you to install it (significant)
Location: /ui/overview and example pages such as /example-apps/weather
Problem: The Weather example (and others) opens with import { Button, Input } from '@foldkit/ui'. @foldkit/ui is a separate npm package (@foldkit/ui@0.127.0), but the Foldkit UI overview page contains no install instruction, and — consistent with finding 1 — no docs page shows a manual install of @foldkit/ui (or of foldkit itself). The only documented path that provides @foldkit/ui is the scaffolder.
Consequence: Anyone who copies an example into a non-scaffolded or existing project hits "Cannot find module '@foldkit/ui'" with no documented resolution. Agents extracting the Weather example as a runnable unit fail the same way.
The fix: Add an install section to /ui/overview (npm install @foldkit/ui, including any peer constraints) and note on example pages which examples require the UI package.
6. The Runtime guide omits Runtime.embed, which the README calls the entry point for embedding (minor)
Location: /core/runtime
Problem: The Runtime guide presents makeApplication and makeElement as the entry points and never mentions Runtime.embed. The GitHub README explicitly names Runtime.embed as how you run "a Foldkit widget inside any existing app (React included)," and the dedicated Embedding page documents it — but a reader landing on the Runtime guide (the natural home for runtime entry points) sees only two of the three.
Consequence: A developer evaluating Foldkit's embed story from the Runtime guide concludes the API is makeElement alone and misses Ports and host handles entirely; makeElement's section even discusses widgets without linking to Embedding.
The fix: Add a short "embed" section (or at least a cross-link) to /core/runtime pointing to /core/embedding.
7. Getting Started's .md export collapses package-manager tabs into four unlabeled code fences (minor)
Location: /get-started/getting-started.md (the documented agent-facing export)
Problem: In the Markdown export the four dev-server commands render as four consecutive unlabeled code fences — pnpm dev, npm run dev, yarn dev, bun dev — with no tab labels, language tags, or connecting prose. The docs explicitly advertise these .md endpoints for agents in llms.txt.
Consequence: An agent (or a human reading the raw Markdown) sees four bare commands with no indication they are alternatives; a literal reader runs all four in sequence. The same tab-flattening presumably affects every tabbed block across the 139 exported pages.
The fix: Emit tab labels in the Markdown export (e.g. a bold label or comment line above each fence: # pnpm / # npm / …), so the alternatives are self-describing.
8. The release surface the docs point to lags npm by five versions (minor)
Location: /roadmap ("How to follow along") vs github.com/foldkit/foldkit releases and the npm registry
Problem: The Roadmap page tells readers that "releases land continuously" and directs them to the GitHub changelog to follow along, and the README points at the same changelog for breaking-change details. But GitHub's latest tagged release is foldkit@0.122.0 (2026-07-02) while npm's latest dist-tag is 0.127.0 — the GitHub release surface is five versions behind the package people actually install.
Consequence: For a pre-1.0 framework that explicitly warns "breaking changes may occur in minor releases," the designated place to track those changes trails what npm serves. A developer on 0.127.0 checking GitHub releases for what changed finds nothing past 0.122.0 and can't tell whether the gap is missing notes or missing releases.
The fix: Make tagging GitHub releases part of the publish pipeline so the release surface and npm stay in lockstep, or have the Roadmap link to a surface that is guaranteed current.
What they do well
Best-in-class agent surface: llms.txt with per-page descriptions, a 1.4 MB llms-full.txt, and every page available as Markdown via .md suffix.
Unusual benchmarking honesty: the performance page publishes numbers where Foldkit loses (403ms optimised vs React 19's 397ms unoptimised) and explains the gap instead of hiding it.
Code examples ship complete imports — the Weather example is copy-paste runnable in a scaffolded project, imports and all.
Top 3 recommendations
Document the Effect v4 beta peer-dependency pin, Node requirements, and a manual install path on Getting Started — this is the framework's biggest hidden adoption cost.
Fix the Command.define reference signature to show the rest parameter, and audit the signature renderer for the same bug elsewhere.
Reconcile the README with the docs (ESLint → Oxlint), fix the two dead GitHub links, and pin deep source links to commit SHAs with a CI link checker.
Fixed
0
Skip
13
Fail
1
Failing pages
https://foldkit.dev/example-apps/weather
Summary
Verified 29 documentation snippets across the audit's source pages: 15 PASS, 13 SKIP, 1 FAIL. Environment: Node v24.17.0, npm 11.13.0, pnpm 11.5.2 (yarn and bun unavailable). Browser-targeted TypeScript snippets were executed unmodified against the packages a fresh scaffold installs (foldkit@0.127.0, effect@4.0.0-beta.88) inside the scaffold's own documented test environment (vitest + happy-dom).
Highlights:
The npx create-foldkit-app@latest scaffolder works (driven via its documented --name/--example/--package-manager flags because the sandbox has no TTY for the interactive picker), and both npm run dev and pnpm dev boot the Vite dev server ("ready in ~510ms").
The README counter (src/main.ts + src/entry.ts) and the Runtime page's makeApplication snippet run end to end: the runtime boots and renders the counter UI into #root under happy-dom.
The MCP page's three setup steps all work: npx @foldkit/devtools-mcp init writes .mcp.json, the devDependency install succeeds, and the verbatim vite.config.ts snippet opens the documented WebSocket relay on port 9988.
FAIL — Weather example (/example-apps/weather): the page's full source calls AsyncData.matchDataSplitEmpty, which does not exist in foldkit@0.127.0 (npm latest exports only match, matchData, matchDataSplit). Rendering the example's own init() model through its view throws TypeError: AsyncData.matchDataSplitEmpty is not a function. The same code ships from the scaffolder: npx create-foldkit-app --example weather produces a project whose own npm run typecheck fails with TS2551: Property 'matchDataSplitEmpty' does not exist. Docs/examples are ahead of the published package.
Environmental note: oxlint 1.73.0 panics on any input in this sandbox (oxc_allocator unwrap panic, reproduced on a trivial one-line JS file with no config), so the .oxlintrc.json snippet was verified as valid JSON that byte-matches the scaffolder's generated config, per the validate-syntax-only rule for JSON.
Required credentials
None. No credentials were provided and no snippet in scope required any (no env vars, API keys, or placeholders appear in the verified snippets).
Exit 0; project scaffolded with deps installed. Interactive picker driven via documented flags (--name, --example counter, --package-manager) — sandbox has no TTY.
pnpm dev
PASS
In a pnpm-scaffolded project: VITE v8.1.4 ready in 511 ms. (Running pnpm dev in an npm-installed project triggers pnpm reinstall churn — package-manager mixing, not a docs bug.)
npm run dev
PASS
In an npm-scaffolded project: VITE v8.1.4 ready in 509 ms.
yarn dev
SKIP
Runtime unavailable — yarn not installed in sandbox.
bun dev
SKIP
Runtime unavailable — bun not installed in sandbox.
Module executed unmodified under vitest/happy-dom against foldkit@0.127.0: m(), curried Command.define, and imports foldkit, foldkit/message all resolve and run. (Model/Message are type-only references supplied by earlier page context.)
Type signatures / API reference rendering, not runnable code. (Runtime behavior of Command.define's variadic result form was exercised and worked in the Commands and Http snippets above.)
Module executed unmodified; the effect/unstable/http subpath (HttpClient, HttpClientRequest) and Http.layer resolve in effect@4.0.0-beta.88 / foldkit@0.127.0.
Valid JSON (validate-syntax-only rule); byte-identical to the config create-foldkit-app actually generates. Executing oxlint itself was impossible: oxlint 1.73.0 panics on any file in this sandbox (oxc_allocator unwrap), an environment issue, not a docs issue.
Module loads, but rendering the example's own init() model through its view throws TypeError: AsyncData.matchDataSplitEmpty is not a function against foldkit@0.127.0 (npm latest). foldkit.AsyncData exports only match, matchData, matchDataSplit. tsc confirms: TS2551: Property 'matchDataSplitEmpty' does not exist ... Did you mean 'matchDataSplit'?. Reproduced on the live page (/example-apps/weather.md), on GitHub main, and in a fresh create-foldkit-app --example weather scaffold, whose own npm run typecheck script fails. Diagnosis: docs/examples use an unreleased API — the site deploys from main while npm latest is 0.127.0. Suggested solution (not applied): publish the foldkit release containing matchDataSplitEmpty, or pin the docs example and scaffolder template to the released matchDataSplit API.
Same execution as Getting Started; note the README says the scaffold includes "ESLint" but the generated project actually ships oxlint (.oxlintrc.json, oxlint devDependency) — a prose inconsistency, not a snippet failure.