docs: portable demos, an honest quick start, and an agent-readable surface

[rpvilo]

Why

A developer tried to install @intentface/chat with an agent and couldn't reproduce the styled interface. Three verified causes, all in the docs rather than the package:

1. The styled layer had no address. installation.mdx told readers that each component page's "View source" link was the styled component to copy — but page-actions.tsx built that URL as packages/chat/src/${source}, the headless primitive they'd already installed from npm. components/ai/ was referenced nowhere in content/.
2. The docs were unreadable to agents. /docs-markdown/[...slug] and readDocsPage returned raw MDX, so an agent received <ComponentPreview name="…" /> — an opaque tag with no code in it. The source existed only in the rendered page's code tab.
3. The promise was repeated at the source. packages/chat/README.md advertised a "shadcn-style styled layer from the docs" — the first thing read after install.

Positioning is now settled as the Base UI model, not shadcn: no registry, no npx shadcn add. The demos are the styled reference.

What changed

1. Honest quick start — deleted the theming page (its CSS was a hand-maintained copy that had already drifted from app/globals.css: 114 tokens vs 131), replaced installation.mdx with quick-start.mdx in Base UI's shape, retargeted seven identical broken pointers, and relabelled "View source" → "Primitive source". The Set up section documents isolation: isolate, a real constraint that was undocumented — the package portals to document.body in four places.

2. Self-contained demos — all 14 rewritten to import only @intentface/chat/* and react, with icons inlined and sample data local. Colocated under content/docs/**/demos/. Colours and geometry are derived from the four theme seeds rather than approximated. ComponentPreview and components/docs/previews/ are gone; <Demo> replaces them. Quick start also gains package-manager tabs.

Three package-behaviour bugs surfaced while writing them, now fixed in the docs: the ask-user section referenced a <Composer.AskUser /> that doesn't exist in the package, the attachments section claimed Composer.Attachments renders a file strip (it carries policy and a hidden input), and headless/index.mdx still described a copy-paste styled layer we'd removed.

3. Agent-readable surface — lib/docs/expand-demos.ts rewrites each <Demo> into a fenced block with the real source and strips the imports that fed it, applied to both the markdown route and the readDocsPage tool. The composer page goes 31k → 61k characters of genuinely copyable code. <InstallationBlock> expands too, so the install command is no longer invisible to agents. Adds a generated /llms.txt.

Verification

• biome check, tsc --noEmit, and bun run build all clean
• New CI step: tsconfig.demos.json maps @intentface/chat/* to packages/chat/dist/* and defines no @/* alias, so demos must compile against the published package. Proven against both failure modes — an app-internal import gives TS2307, a missing package export gives TS2305
• No demo imports @/components, @/lib, @/hooks, lucide-react, motion/react, or next/image
• No components/ai, /docs/theming, or /docs/installation references remain in content/

Not included

• The build-a-chat staged guide (next)
• Documenting the className callback — it already works via the vendored render machinery, but is undocumented and unused; 51 of 67 parts declare no state, which needs a decision
• A manual render check: one demo pasted into a bare React 19 + Tailwind project. The CI gate proves it compiles standalone, not that it renders correctly.

Note on structure

Three commits, one PR. Each depends on the one before — the hero demo slots into the page the first commit creates, and the expander needs the <Demo> component from the second — so separate branches off main would each be broken alone.

[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 12:03pm