rift-ds 1.6.0 → 1.8.0

package/README.md

@@ -9,17 +9,15 @@
 <!-- npm-badge:end -->
 [![license: MIT](https://img.shields.io/badge/license-MIT-4c1)](LICENSE)
 
-An open source React design system built for AI products and coding agents: components on a three-tier token architecture, complete theme presets that restyle everything with one attribute, and machine surfaces (an MCP endpoint, per-component contracts, an installable agent skill) so your coding agent knows the library as well as you do.
+An open source React design system built for AI products and coding agents: components on a three-tier token architecture, complete theme presets that restyle everything with one attribute, and machine surfaces (an MCP endpoint, per-component contracts, installable agent skills) so your coding agent knows the library as well as you do.
 
 ## Why Rift DS
 
-- **One package, zero dependencies.** React is the only required peer dependency; recharts is optional and only for the charts entry. No configuration API, no providers, no build-tool integration: theming is plain CSS custom properties, so it works in any bundler, in any stack, beside anything you already use.
-- **Free, open source, consumed your way.** MIT end to end, no pro tier, no paywalled components. Install the npm package, pull single components as source through the shadcn CLI, or clone the repo and own every line; all three are first-class paths.
-- **A few primitives re-theme everything.** Every semantic token chains to a primitive, so a handful of overrides cascade through every component, the charts, and the ambient background, in both colour modes. Your brand is a short CSS block, not a fork.
-- **The shipped themes prove it.** Each one is the same system under different primitives, saved as a complete look: colour modes, a type pairing with self-hosted fonts, type weight and tracking, icon weight, radius, density, motion, elevation, the chart palette. Setting `data-brand` on the root element applies all of it with zero runtime JavaScript, the build holds every theme's action colours to WCAG AA in both modes, and the playground builds yours the same way.
-- **The AI product set is in the box.** Composer, streaming chat thread, tool calls, reasoning, thread panel and tabs: the components an assistant UI needs, the same set this repo's own site chat is built from.
-- **Legible to coding agents.** One command installs the agent skill and prints the MCP connect line, and the MCP tools and per-component markdown are generated from the same JSDoc that builds the shipped `.d.ts`: an agent reads the exact contract npm ships, no key, no account.
-- **Docs that cannot lie.** Every count, list, and prop table is generated from source registries and build-validated; CI fails on drift, and every component story ships through an accessibility audit. What the docs say is what ships.
+- **<!-- component-count -->150<!-- /component-count --> components.** Buttons, forms and tables through to charts, navigation and overlays, each typed and documented with live examples. React is the only required peer dependency.
+- **AI patterns, the whole chat and templates, ready to use.** Composer, streaming chat thread, tool calls, reasoning and thread panel are in the box, the complete AI chat ships assembled as one widget that one command scaffolds, and the docs site has complete template screens built from them.
+- **Fully themeable.** The shipped themes are complete looks to start from, each in light and dark. One `data-brand` attribute applies a theme, and a few CSS overrides make your own.
+- **Ready for coding agents.** One command installs the agent skills, and a public MCP endpoint serves every component's props, so your agent builds with the library as it actually is. No key, no account.
+- **Free, consumed your way.** MIT, with no pro tier. Install the npm package, pull single components as source through the shadcn CLI, or clone the repo.
 
 ## Documentation
 
@@ -38,11 +36,33 @@ import 'rift-ds/tokens/tokens.css';
 import { Button, Card, Badge } from 'rift-ds';
 ```
 
-React 19+ is a peer dependency. The package is ESM-only and resolved via `exports` subpaths: use a bundler that handles CSS and font imports from `node_modules` (Vite, Next.js, webpack) and set TypeScript's `moduleResolution` to `"bundler"` or `"nodenext"`. The Recharts-backed charts live behind `rift-ds/charts`, so the optional `recharts` peer dependency is only needed if you use them. Prefer owning the source? Pull single components through the shadcn CLI (`npx shadcn@latest add https://rift-ds.com/r/button.json`, with details in the [get-started guide](https://rift-ds.com/docs/get-started)), or clone this repo and build on it directly; all of it is MIT.
+React 19+ is a peer dependency. The package is ESM-only and resolved via `exports` subpaths: use a bundler that handles CSS and font imports from `node_modules` (Vite, Next.js, webpack) and set TypeScript's `moduleResolution` to `"bundler"` or `"nodenext"`. The Recharts-backed charts live behind `rift-ds/charts`, so the optional `recharts` peer dependency is only needed if you use them. The chat widget's subpaths bring their own optional peers (`react-markdown` and `remark-gfm` for the panel, `@anthropic-ai/sdk` for the server handlers, `@upstash/ratelimit` and `@upstash/redis` for the guardrails), needed only if you use them. Prefer owning the source? Pull single components through the shadcn CLI (`npx shadcn@latest add https://rift-ds.com/r/button.json`, with details in the [get-started guide](https://rift-ds.com/docs/get-started)), or clone this repo and build on it directly; all of it is MIT.
+
+## The chat widget
+
+The whole AI chat ships as one widget: the panel with its docked, overlay and takeover forms, the streaming engine, the threads, the rich cards, and the server handlers that call the model. One command scaffolds it into a Next.js app, and a scripted mode runs it with no key, so you see it working before you wire a model.
+
+```bash
+npx rift-ds init chat
+```
+
+The panel alone, with no route behind it, is three imports:
+
+```tsx
+import 'rift-ds/chat/chat.css';
+import { ChatProvider, ChatLauncher } from 'rift-ds/chat';
+import { createDemoTransport, DEMO_RENDERERS } from 'rift-ds/chat/demo';
+
+<ChatProvider transport={createDemoTransport()} renderers={DEMO_RENDERERS}>
+  <ChatLauncher label="Ask" />
+</ChatProvider>
+```
+
+Swap the scripted transport for `createFetchTransport('/api/chat')` and the panel talks to your route. Every prop it takes is on [its component page](https://rift-ds.com/components/ai-chat), and the three ways to add it, with the protocol and the server options, are on [the AI chat docs page](https://rift-ds.com/docs/chat).
 
 ## Set up your agent
 
-One command teaches a coding agent the system: it installs the generated agent skill into your project and prints the MCP connect line.
+One command teaches a coding agent the system: it installs the generated agent skills into your project and prints the MCP connect line. The skills cover the library's rules, moving existing screens onto the tokens and components, and auditing styles against them.
 
 ```bash
 npx rift-ds init
@@ -54,7 +74,7 @@ The MCP endpoint serves the component catalogue, per-component prop APIs, the to
 claude mcp add --transport http rift-ds https://rift-ds.com/api/mcp
 ```
 
-Every component's prop contract is also plain markdown (append `.md` to its docs URL), and [llms.txt](https://rift-ds.com/llms.txt) indexes every machine surface. Then just ask: "Build a settings page with Rift components."
+Every component's prop contract is also plain markdown (append `.md` to its docs URL), and [llms.txt](https://rift-ds.com/llms.txt) indexes every machine surface. A theme made in the [playground](https://rift-ds.com/playground) exports as CSS, a THEME.md and a setup prompt, so the agent can read the look as well as the code. Then just ask: "Build a settings page with Rift components."
 
 ## Theming
 
@@ -67,19 +87,20 @@ import 'rift-ds/tokens/presets/presets.css';
 ```
 
 - **Dark mode**: `data-theme="dark"` on the root element; light is the default.
+- **Page colours**: the token stylesheet defines custom properties and styles no element, so paint the page once: set `background: var(--color-bg-page-primary)`, `color: var(--color-text-primary)` and `font-family: var(--font-family-primary)` on `body`. Without it a dark theme lands as dark components on a white page.
 - **Your own brand**: every semantic token chains to a primitive, so overriding one primitive re-themes everything built on it. The [playground](https://rift-ds.com/playground) restyles the system live and copies out a complete, paste-ready override.
 - **Fonts**: the base theme bundles no text face, and the whole scale chains to `--font-family-primary` (split heading and body faces via `--font-family-heading` and `--font-family-body`); point them at any font you load. Only the preset stylesheets carry faces, each self-hosting its own, and only the presets you import pull them in.
 - **Icons**: a Material Symbols Rounded variable font is bundled and components import it themselves, with every Google axis exposed as a custom property. Every icon prop also takes your own element, so any icon set drops in.
 
 ## Components
 
-<!-- component-count -->149<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
+<!-- component-count -->150<!-- /component-count --> components, including a chat set for AI products (Chat thread, Composer, Tool call, Reasoning, Thread panel) and Shader field, a WebGL2 ambient background whose light sources read your colour tokens at runtime, so it re-themes with everything else. Details and live examples are on the [docs site](https://rift-ds.com/components).
 
 <details>
 <summary>The full list</summary>
 
 <!-- component-list:start -->
-Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
+Accordion · Agent plan · Agent rail · Agent status · AI button · Alert · Alert dialog · Anchor nav · Animated number · App layout · App sidebar · Area chart · Attachment drop zone · Attachment group · Attachment tile · Attachment viewer · Avatar · Avatar group · Badge · Banner · Bar chart · Bottom nav · Breadcrumb · Button · Button group · Card · Card stack · Carousel · Chat header · Chat marker · Chat message · Chat thread · Checkbox · Chip · Circular button · Code block · Code diff · Colour picker · Combo chart · Combobox · Command palette · Composer · Contact card · Context menu · Contribution graph · Data table · Date input · Date picker · Dialog · Divider · Document chip · Drawer · Dropdown · Dropdown menu · Empty state · Entity card · Event calendar · Field · Figure · File input · Filter bar · Funnel chart · Gantt chart · Gauge · Globe · Hover card · Image compare · Input · Inspector colour picker · Inspector dropdown · Inspector input · Inspector section · Inspector segments · Inspector slider · Inspector toggle switch · Instructions · Interrupt card · Kbd · Legend tile · Lightbox · Line chart · Link list · Map callout · Map legend · Mention · Message actions · Message card · Meter · Model picker · Nav · Nav list · Notification centre · Number input · Pagination · Panel · Pie chart · Pin input · Pixel avatar · Popover · Progress bar · Prompt suggestions · Prose · Quote · Radar chart · Radial chart · Radio button · Rating · Reasoning · Rich dropdown · Scatter chart · Section title · Segmented control · Selection card · Shader field · Sidebar panel · Skeleton · Slider · Source chip · Source trail · Sparkline · Spinner · Split button · Split pane · Stacked bar chart · Stat · Status dot · Stepper · Streaming text · Swatch · Table · Tabs · Tag input · Textarea · Thread panel · Thread tabs · Time picker · Timeline · Toast · Toggle group · Toggle switch · Tool call · Toolbar · Tooltip · Top app bar · Tree view · Treemap · Usage card · Waveform · Widget · World map
 <!-- component-list:end -->
 
 </details>

package/bin/rift-ds.mjs

@@ -1,70 +1,237 @@
 #!/usr/bin/env node
 /**
- * The package's one command: `npx rift-ds init`.
+ * The package's one bin: `npx rift-ds init` and `npx rift-ds init chat`.
  *
- * Fetches the generated agent skill (SKILL.md + references/components.md)
- * from the live site into the project's .claude/skills/ folder, then prints
- * the MCP connect line. The files are fetched rather than bundled because
- * they regenerate with every site deploy, while the package moves only on a
- * release — a bundled copy would always be the staler one. Re-running the
- * command overwrites the pair; that is the refresh story.
+ * `init` fetches the generated agent skills from the live site into the
+ * project's .claude/skills/ folder, one folder per skill, then prints the
+ * MCP connect line. Which skills exist and which files each holds comes
+ * from the site's /skill/manifest.json, never from a list in this file:
+ * the skills regenerate with every site deploy while the package moves
+ * only on a release, so a bundled list (or a bundled copy of the files)
+ * would always be the staler one. Re-running overwrites what is there;
+ * that is the refresh story.
+ *
+ * `init chat` scaffolds the chat widget into a Next.js app router project:
+ * the three route files under app/api/chat/, the guardrails module beside
+ * them, the mount component and its model list under components/chat/, and
+ * an .env.chat.example at the project root. These templates ride inside
+ * the package (dist/bin/templates/chat/, copied from src/cli/templates/chat/
+ * by build-package.mjs) rather than being fetched, because they import the
+ * installed version's own subpaths and must match it. It never overwrites:
+ * a file that exists is skipped and listed, so re-running is safe.
+ *
+ * The manifest is data from the network that decides where this command
+ * writes, so every name and path in it is checked before anything touches
+ * the disk: a skill name is one kebab-case folder, a file is a plain
+ * relative path, and nothing may climb out of the target folder.
  *
  * Zero dependencies by design: global fetch plus node:fs, so npx never
- * installs anything beyond the package itself. SITE_ORIGIN, SKILL_NAME
- * and MCP_SERVER_NAME are stamped by build-package.mjs from
+ * installs anything beyond the package itself. SITE_ORIGIN, SKILL_NAME,
+ * MCP_SERVER_NAME and PACKAGE_NAME are stamped by build-package.mjs from
  * scripts/brand.mjs (the one home for brand facts); running this file
  * straight from source fails fast rather than guessing a domain.
+ * SKILL_NAME is the library skill, kept only for --out without --skill,
+ * which has always meant that one.
  */
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const SITE_ORIGIN = 'https://rift-ds.com';
 const SKILL_NAME = 'rift-design-system';
 const MCP_SERVER_NAME = 'rift-ds';
-const SKILL_FILES = ['SKILL.md', 'references/components.md'];
-const DEFAULT_OUT = join('.claude', 'skills', SKILL_NAME);
+const PACKAGE_NAME = 'rift-ds';
+const MANIFEST_URL = `${SITE_ORIGIN}/skill/manifest.json`;
+const DEFAULT_DIR = join('.claude', 'skills');
+const TEMPLATES_DIR = join(dirname(fileURLToPath(import.meta.url)), 'templates', 'chat');
+
+/* What `init chat` needs installed beside the package. The optional peers
+   each chat subpath imports; the demo's recharts is only for the scripted
+   preview and goes when the demo import does. */
+const CHAT_PEERS = [
+  'react-markdown',
+  'remark-gfm',
+  '@anthropic-ai/sdk',
+  '@upstash/ratelimit',
+  '@upstash/redis',
+  'recharts',
+];
+
+const USAGE = `Usage: npx ${PACKAGE_NAME} init [--skill <name>] [--dir <dir>]
+       npx ${PACKAGE_NAME} init chat [--app <dir>] [--dry-run]
+
+init
+  Fetches the agent skills for this package from ${SITE_ORIGIN} into
+  ${DEFAULT_DIR}/, one folder per skill, so a skill-capable coding agent
+  carries the library's install, theming and catalogue rules into every
+  session. Re-run any time to refresh; the files regenerate with every
+  site deploy.
 
-const USAGE = `Usage: npx rift-ds init [--out <dir>]
+  --skill <name>  Install one skill instead of all of them
+  --dir <dir>     Folder that receives one folder per skill (default: ${DEFAULT_DIR})
+  --out <dir>     Deprecated: write one skill's files straight into <dir>
+                  (${SKILL_NAME} unless --skill names another). Use --dir.
 
-Fetches the agent skill for this package from ${SITE_ORIGIN} into
-${DEFAULT_OUT}/ so a skill-capable coding agent carries the
-library's install, theming and catalogue rules into every session.
-Re-run any time to refresh; the files regenerate with every site deploy.
+init chat
+  Scaffolds the chat widget into a Next.js app router project: the chat,
+  follow-ups and feedback routes under app/api/chat/, the guardrails beside
+  them, the mount and its model list under components/chat/, and an
+  .env.chat.example. Existing files are never overwritten.
 
-Options:
-  --out <dir>   Write the skill somewhere else (default: ${DEFAULT_OUT})
-  --help        Show this message`;
+  --app <dir>     The app router folder (default: app/ or src/app/, whichever exists)
+  --dry-run       Print what would be written and write nothing
+
+  --help          Show this message
+
+The list of skills is at ${MANIFEST_URL}`;
 
 function fail(message) {
   console.error(`✗ ${message}`);
   process.exit(1);
 }
 
-async function init(outDir) {
-  if (SITE_ORIGIN.startsWith('__')) {
-    fail('this copy was not built: run the published bin (npx rift-ds init).');
+async function get(url) {
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    fail(`could not reach ${url} (${error?.message ?? error}). Check your network and retry.`);
+  }
+  if (!response.ok) {
+    fail(`${url} answered ${response.status}. The site may be mid-deploy; retry in a minute.`);
   }
-  for (const file of SKILL_FILES) {
-    const url = `${SITE_ORIGIN}/skill/${SKILL_NAME}/${file}`;
-    let response;
-    try {
-      response = await fetch(url);
-    } catch (error) {
-      fail(`could not reach ${url} (${error?.message ?? error}). Check your network and retry.`);
+  return response.text();
+}
+
+/** The manifest's skills, with every name and path checked before use. */
+async function readManifest() {
+  let manifest;
+  try {
+    manifest = JSON.parse(await get(MANIFEST_URL));
+  } catch {
+    fail(`${MANIFEST_URL} is not valid JSON. The site may be mid-deploy; retry in a minute.`);
+  }
+  const skills = manifest?.skills;
+  if (!Array.isArray(skills) || skills.length === 0) {
+    fail(`${MANIFEST_URL} lists no skills. Update the package (npm install ${PACKAGE_NAME}@latest) and retry.`);
+  }
+  const segment = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+  for (const skill of skills) {
+    const filesOk =
+      Array.isArray(skill?.files) &&
+      skill.files.length > 0 &&
+      skill.files.every(
+        (file) => typeof file === 'string' && file.split('/').every((part) => segment.test(part))
+      );
+    if (typeof skill?.name !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(skill.name) || !filesOk) {
+      fail(`${MANIFEST_URL} holds an entry this command will not write to disk. Nothing was installed.`);
     }
-    if (!response.ok) {
-      fail(`${url} answered ${response.status}. The site may be mid-deploy; retry in a minute.`);
+  }
+  return skills;
+}
+
+async function init({ only, dir, out }) {
+  const skills = await readManifest();
+  const wanted = only ?? (out ? SKILL_NAME : null);
+  const selected = wanted ? skills.filter((skill) => skill.name === wanted) : skills;
+  if (selected.length === 0) {
+    fail(`no skill named "${wanted}". Available: ${skills.map((skill) => skill.name).join(', ')}.`);
+  }
+  for (const skill of selected) {
+    const target = out ?? join(dir, skill.name);
+    for (const file of skill.files) {
+      const text = await get(`${SITE_ORIGIN}/skill/${skill.name}/${file}`);
+      const path = join(target, ...file.split('/'));
+      mkdirSync(dirname(path), { recursive: true });
+      writeFileSync(path, text);
+      console.log(`▸ ${path}`);
     }
-    const target = join(outDir, file);
-    mkdirSync(dirname(target), { recursive: true });
-    writeFileSync(target, await response.text());
-    console.log(`▸ ${target}`);
   }
-  console.log(`✓ Agent skill installed. Skill-capable agents load it automatically.`);
+  const names = selected.map((skill) => skill.name).join(', ');
+  console.log(
+    selected.length === 1
+      ? `✓ Agent skill installed: ${names}. Skill-capable agents load it automatically.`
+      : `✓ ${selected.length} agent skills installed: ${names}. Skill-capable agents load them automatically.`
+  );
+  if (out) {
+    console.log(`\n--out is deprecated. Use --dir to choose the folder that holds the skill folders.`);
+  }
   console.log(`\nFor on-demand lookups too, connect the MCP endpoint:`);
   console.log(`  claude mcp add --transport http ${MCP_SERVER_NAME} ${SITE_ORIGIN}/api/mcp`);
 }
 
+/** Every template file, as a path relative to the templates folder (forward slashes). */
+function templateFiles(dir = TEMPLATES_DIR) {
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...templateFiles(full));
+    else out.push(relative(TEMPLATES_DIR, full).split('\\').join('/'));
+  }
+  return out.sort();
+}
+
+/**
+ * Where a template lands. `app/**` goes into the app router folder,
+ * `components/**` beside it (src/components when the app is src/app), and
+ * the env example at the project root.
+ */
+function destinationFor(file, appDir) {
+  if (file.startsWith('app/')) return join(appDir, ...file.slice('app/'.length).split('/'));
+  if (file.startsWith('components/')) return join(dirname(appDir), ...file.split('/'));
+  return join(process.cwd(), ...file.split('/'));
+}
+
+function initChat({ app, dryRun }) {
+  if (!existsSync(TEMPLATES_DIR)) {
+    fail('this copy carries no chat templates: run the published bin (npx ' + PACKAGE_NAME + ' init chat).');
+  }
+  const appDir = app ?? ['app', join('src', 'app')].map((d) => resolve(d)).find((d) => existsSync(d));
+  if (!appDir) {
+    fail('no app/ or src/app/ folder found. Run this inside a Next.js app router project, or pass --app <dir>.');
+  }
+
+  const files = templateFiles();
+  const written = [];
+  const skipped = [];
+  for (const file of files) {
+    const dest = destinationFor(file, appDir);
+    if (existsSync(dest)) {
+      skipped.push(dest);
+      continue;
+    }
+    if (!dryRun) {
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, readFileSync(join(TEMPLATES_DIR, ...file.split('/'))));
+    }
+    written.push(dest);
+    console.log(`${dryRun ? '○' : '▸'} ${relative(process.cwd(), dest)}`);
+  }
+  for (const dest of skipped) {
+    console.log(`· ${relative(process.cwd(), dest)} exists, left as it is`);
+  }
+
+  console.log(
+    dryRun
+      ? `\n✓ Dry run: ${written.length} files would be written, ${skipped.length} left alone.`
+      : `\n✓ Chat scaffolded: ${written.length} files written, ${skipped.length} left alone.`
+  );
+  console.log(`\nNext:`);
+  console.log(`  1. Install the peers the chat imports:\n       npm install ${CHAT_PEERS.join(' ')}`);
+  console.log(
+    `  2. Render <ChatMount /> at the end of your root layout's body, after the page content:\n` +
+      `       import { ChatMount } from '${relative(appDir, join(dirname(appDir), 'components', 'chat', 'ChatMount')).split('\\').join('/')}';`
+  );
+  console.log(
+    `  3. Copy .env.chat.example into .env.local. With NEXT_PUBLIC_CHAT_DEMO=true the widget plays a scripted\n` +
+      `     conversation and needs no key; set ANTHROPIC_API_KEY and CHAT_ENABLED=true to go live.`
+  );
+  console.log(
+    `  4. Your layout's viewport should set interactiveWidget: "resizes-content", so the phone takeover ends above the keyboard.`
+  );
+  console.log(`\nThe widget's props, protocol and server options: ${SITE_ORIGIN}/chat`);
+}
+
 const args = process.argv.slice(2);
 if (args.includes('--help') || args.includes('-h') || args.length === 0) {
   console.log(USAGE);
@@ -73,10 +240,30 @@ if (args.includes('--help') || args.includes('-h') || args.length === 0) {
 if (args[0] !== 'init') {
   fail(`unknown command "${args[0]}"\n\n${USAGE}`);
 }
-const outFlag = args.indexOf('--out');
-let outDir = DEFAULT_OUT;
-if (outFlag !== -1) {
-  if (!args[outFlag + 1]) fail('--out needs a directory');
-  outDir = resolve(args[outFlag + 1]);
+if (SITE_ORIGIN.startsWith('__')) {
+  fail(`this copy was not built: run the published bin (npx ${PACKAGE_NAME} init).`);
+}
+/** The value after a flag, or undefined when the flag is absent. */
+function option(flag, what) {
+  const at = args.indexOf(flag);
+  if (at === -1) return undefined;
+  const value = args[at + 1];
+  if (!value || value.startsWith('--')) fail(`${flag} needs ${what}`);
+  return value;
+}
+
+if (args[1] === 'chat') {
+  const appFlag = option('--app', 'a directory');
+  initChat({ app: appFlag ? resolve(appFlag) : undefined, dryRun: args.includes('--dry-run') });
+} else {
+  if (args[1] && !args[1].startsWith('--')) fail(`unknown init target "${args[1]}"\n\n${USAGE}`);
+  const only = option('--skill', 'a skill name');
+  const dirFlag = option('--dir', 'a directory');
+  const outFlag = option('--out', 'a directory');
+  if (dirFlag && outFlag) fail('use --dir or --out, not both');
+  await init({
+    only,
+    dir: dirFlag ? resolve(dirFlag) : DEFAULT_DIR,
+    out: outFlag ? resolve(outFlag) : undefined,
+  });
 }
-await init(outDir);

package/bin/templates/chat/.env.chat.example

@@ -0,0 +1,21 @@
+# The chat widget's environment. Copy what you need into .env.local.
+
+# Demo mode: the widget plays a scripted conversation in the browser, with
+# no model, route or key. Set to false (or remove) to go live.
+NEXT_PUBLIC_CHAT_DEMO=true
+
+# Live mode. Both must be set for the routes to call a model; until then they
+# answer with a polite notice.
+CHAT_ENABLED=false
+ANTHROPIC_API_KEY=
+
+# Guardrails over Upstash Redis (optional). Unset, every request is allowed
+# and nothing is logged. Set all three to get per-visitor rate limits, a
+# daily budget with model tiers, the exchange log and the feedback store.
+KV_REST_API_URL=
+KV_REST_API_TOKEN=
+CHAT_VISITOR_SALT=
+
+# The daily breaker, in messages and US cents (defaults shown).
+CHAT_DAILY_MESSAGE_CAP=300
+CHAT_DAILY_SPEND_CAP_CENTS=500

package/bin/templates/chat/app/api/chat/feedback/route.ts

@@ -0,0 +1,12 @@
+import { createFeedbackHandler } from 'rift-ds/chat/server';
+import { guardrails } from '../guardrails';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+/** Thumbs verdicts on answers, stored against the exchange the chat route logged. */
+const handler = createFeedbackHandler({ guardrails });
+
+export async function POST(request: Request): Promise<Response> {
+  return handler(request);
+}

package/bin/templates/chat/app/api/chat/followups/route.ts

@@ -0,0 +1,23 @@
+import { createFollowupsHandler } from 'rift-ds/chat/server';
+import { FOLLOWUP_MODEL } from '../../../../components/chat/models';
+import { guardrails } from '../guardrails';
+
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+/**
+ * The three follow-up questions offered under a finished answer, written by
+ * a small model from the question-and-answer pair. Say what the chat is
+ * about in `about`, so the questions stay on your subject.
+ */
+const handler = createFollowupsHandler({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  enabled: process.env.CHAT_ENABLED === 'true' && Boolean(process.env.ANTHROPIC_API_KEY),
+  model: FOLLOWUP_MODEL,
+  about: 'this product and its documentation',
+  guardrails,
+});
+
+export async function POST(request: Request): Promise<Response> {
+  return handler(request);
+}

package/bin/templates/chat/app/api/chat/guardrails.ts

@@ -0,0 +1,18 @@
+import { createUpstashGuardrails } from 'rift-ds/chat/upstash';
+
+/**
+ * Rate limits, a daily budget with model tiers, the exchange log and the
+ * feedback store, over Upstash Redis. Shared by the three chat routes.
+ *
+ * Fails open: with KV_REST_API_URL and KV_REST_API_TOKEN unset, every
+ * request is allowed and nothing is logged, so the chat works on day one
+ * and the limits arrive when you add the two variables. Set CHAT_VISITOR_SALT
+ * too: it salts the hashed visitor address the limits key on.
+ */
+export const guardrails = createUpstashGuardrails({
+  url: process.env.KV_REST_API_URL,
+  token: process.env.KV_REST_API_TOKEN,
+  salt: process.env.CHAT_VISITOR_SALT,
+  dailyMessageCap: Number(process.env.CHAT_DAILY_MESSAGE_CAP ?? 300),
+  dailySpendCapCents: Number(process.env.CHAT_DAILY_SPEND_CAP_CENTS ?? 500),
+});

package/bin/templates/chat/app/api/chat/route.ts

@@ -0,0 +1,31 @@
+import { createChatHandler } from 'rift-ds/chat/server';
+import { CHAT_MODELS, DEFAULT_CHAT_MODEL } from '../../../components/chat/models';
+import { guardrails } from './guardrails';
+
+export const runtime = 'nodejs';
+export const maxDuration = 60;
+export const dynamic = 'force-dynamic';
+
+/**
+ * What the assistant knows and how it behaves. Replace this with your own
+ * instructions and whatever the model should read: your docs, your product's
+ * facts, your rules. Put `cache_control` on the block that holds the bulk
+ * of it, so repeat visitors hit the prompt cache.
+ */
+const SYSTEM = `You are the assistant on this site. Answer from what you know about the product, plainly and briefly. If you do not know, say so.`;
+
+const handler = createChatHandler({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  // Off until both are set, so a deploy ahead of its environment answers
+  // politely rather than throwing.
+  enabled: process.env.CHAT_ENABLED === 'true' && Boolean(process.env.ANTHROPIC_API_KEY),
+  system: [{ type: 'text', text: SYSTEM, cache_control: { type: 'ephemeral' } }],
+  models: CHAT_MODELS,
+  defaultModel: DEFAULT_CHAT_MODEL,
+  // tools: [], // Deterministic lookups the model may call; a tool can answer with a card.
+  guardrails,
+});
+
+export async function POST(request: Request): Promise<Response> {
+  return handler(request);
+}

package/bin/templates/chat/components/chat/ChatMount.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+/**
+ * The chat, mounted once. Render <ChatMount /> at the end of your root
+ * layout's body, after the page content, so the panel sits last in the tab
+ * order and survives client-side navigation.
+ *
+ * Two modes, switched by NEXT_PUBLIC_CHAT_DEMO in .env.local:
+ *   - demo: a scripted conversation plays back in the browser. No model, no
+ *     route, no key. Use it to see the widget working and to show it round.
+ *   - live: the widget posts to /api/chat, which this scaffold also
+ *     wrote. Set ANTHROPIC_API_KEY and CHAT_ENABLED=true there.
+ *
+ * The demo imports rift-ds/chat/demo, which needs the optional `recharts`
+ * peer for its chart cards. Once you are live for good, delete the demo
+ * import and the peer with it.
+ */
+import { ChatLauncher, ChatProvider } from 'rift-ds/chat';
+import { DEMO_RENDERERS, DEMO_STARTERS, createDemoTransport } from 'rift-ds/chat/demo';
+import 'rift-ds/chat/chat.css';
+import { CHAT_MODELS, DEFAULT_CHAT_MODEL } from './models';
+
+const DEMO = process.env.NEXT_PUBLIC_CHAT_DEMO === 'true';
+
+/** What the widget says about itself. Edit freely. */
+const WIDGET = {
+  title: 'Assistant',
+  tagline: 'How can I help you today?',
+  starters: DEMO
+    ? DEMO_STARTERS
+    : [
+        { id: 'start', label: 'How do I get started?' },
+        { id: 'pricing', label: 'What do the plans include?' },
+        { id: 'help', label: 'Where can I read more?' },
+      ],
+  models: CHAT_MODELS,
+  defaultModel: DEFAULT_CHAT_MODEL,
+  disclaimer: 'Answers may be wrong.',
+};
+
+export function ChatMount() {
+  return (
+    <ChatProvider
+      transport={DEMO ? createDemoTransport() : undefined}
+      renderers={DEMO ? DEMO_RENDERERS : undefined}
+      followups={DEMO ? false : '/api/chat/followups'}
+      feedback={DEMO ? false : '/api/chat/feedback'}
+    >
+      <ChatLauncher label={`Ask ${WIDGET.title}`} widget={WIDGET} />
+    </ChatProvider>
+  );
+}

package/bin/templates/chat/components/chat/models.ts

@@ -0,0 +1,29 @@
+import type { ChatModelOption } from 'rift-ds/chat';
+
+/**
+ * The models your chat offers. The widget's picker shows `label` and
+ * `description`; the client sends `value`; the server calls `id`. Shared by
+ * the route and the mount so the two can never disagree. Edit freely.
+ */
+export const CHAT_MODELS: ChatModelOption[] = [
+  {
+    value: 'haiku',
+    id: 'claude-haiku-5-5',
+    label: 'Haiku 5.5',
+    description: 'Fast answers, the everyday pick.',
+    adaptiveThinking: true,
+  },
+  {
+    value: 'sonnet',
+    id: 'claude-sonnet-5-5',
+    label: 'Sonnet 5.5',
+    description: 'More depth for harder questions.',
+    adaptiveThinking: true,
+  },
+];
+
+/** What serves when the visitor has not chosen. */
+export const DEFAULT_CHAT_MODEL = CHAT_MODELS[0].value;
+
+/** The model that writes the three follow-up questions under an answer. */
+export const FOLLOWUP_MODEL = 'claude-haiku-5-5';

package/chat/AssistantTurn.d.ts

@@ -0,0 +1,5 @@
+import { ChatTurn, LiveResponse } from './types';
+export declare function AssistantTurn({ turn, live }: {
+    turn?: ChatTurn;
+    live?: LiveResponse;
+}): import("react").JSX.Element;