docs: restructure into a handbook and match the reference to the package

[rpvilo]

Builds on #60. Base is feature/docs-portable-demos; GitHub will retarget this to main when #60 merges.

Why

Two problems, found by auditing rather than reading.

The reference pages documented an API that doesn't exist. Resolving every documented part, prop and attribute against the package turned up contradictions on four of seven primitive pages — including message.mdx, which documented seven parts (Markdown, Copy, Action, Source, Attachment, Selection, plus a "structural parts" list) when the namespace exports three. This is the same root cause as #60: the docs described the playground's styled layer as if it were the package.

Pages existed because a reference site had them. The Accessibility page had a "Color contrast" section whose content was that the package renders no colour. The Animation page cited ShimmerPrimitive and --shimmer-duration, neither of which exist anywhere in the repo.

Corrections

Page	Was documented	Reality
message.mdx	7 parts + a sticky prop on Turn	Namespace is Root, Text, Turn; MessageTurnProps is a bare PrimitiveProps<"div">
composer.mdx	Composer.AskUser*, data-composer-ask-user-*	App-layer parts; package emits data-ask-user-*
thread.mdx	Thread.ScrollButton	Not a part — built from useThread()
reasoning.mdx	Trigger.label, Trigger.getThinkingMessage	Neither exists
attachments.mdx	Root.show, Item.item, Dropzone.variant, data-media-type	None exist; Dropzone takes visible, keepMounted, portalSelector

The Anatomy examples on attachments.mdx used three of those props, so they would not have compiled.

Structure

Seventeen pages down to thirteen. Removed: Releases, Streaming performance, Two layers, Animation, TypeScript, Composer state — each either duplicated a primitive page or asserted nothing. Added: Styling (data attributes, the className/style state callbacks, previously undocumented, and the render prop), Composition, Accessibility.

The group is now /docs/handbook/* rather than /docs/headless/*, matching its sidebar label.

Agent surface

.md appended to any docs URL now serves that page as text/markdown, the convention agents expect and can guess from a page URL. /llms.txt uses it, is linked from the sidebar and from Quick start, and its header carries two operating instructions — how to fetch a page, and that the demos assume Tailwind v4.

The gate

scripts/audit-docs.mjs resolves each part's props and state through the TypeScript compiler — not regex, which cannot see multi-line types or inherited props — and fails CI on any contradiction. My first three regex attempts at this both over- and under-reported; the compiler version does not.

Verified it fails on a real contradiction, not just passes on a clean tree.

Known gap

@intentface/chat/types is now undocumented — 16 exports including five part type guards (isTextPart, isToolPart, …). Deliberate call to delete rather than rewrite; worth revisiting.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
intentface-chat	Ready	Preview	Aug 7, 2026 2:06pm