@aigentyc/chat-sdk 0.1.5 → 0.2.0

package/AGENTS.md

@@ -2,6 +2,8 @@
 
 Guide for AI coding assistants (Claude Code, Cursor, Windsurf, v0, Lovable, Bolt) using or contributing to this SDK. Humans: read `README.md` first.
 
+**Live docs (always current):** https://context7.com/llmstxt/unpkg_aigentyc_chat-sdk_0_1_5_llms_txt/llms.txt
+
 ---
 
 ## What this package is

package/bin/doctor.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+/**
+ * aigentyc doctor — diagnose Aigentyc Chat SDK install issues.
+ *
+ * Run inside a project that uses @aigentyc/chat-sdk:
+ *   npx aigentyc doctor
+ *
+ * Checks (in order):
+ *   1. Node >= 18
+ *   2. React >= 19 installed
+ *   3. @aigentyc/chat-sdk installed + version
+ *   4. CSS imported somewhere in source
+ *   5. Env vars (PROJECT_ID, API_ENDPOINT) present
+ *   6. API endpoint reachable
+ *   7. API key (if present) authorized for project
+ *   8. CORS allowed-origins includes localhost dev URL (best-effort)
+ *
+ * Exit code: 0 on all-pass, 1 if any check failed.
+ */
+
+import { readFile, readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const argv = process.argv.slice(2);
+const sub = argv[0];
+if (sub && sub !== "doctor") {
+  console.error(`Unknown command: ${sub}\nUsage: npx aigentyc doctor`);
+  process.exit(2);
+}
+
+const CWD = process.cwd();
+const C = {
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+
+const results = [];
+function pass(msg, hint) { results.push({ status: "ok", msg, hint }); }
+function warn(msg, hint) { results.push({ status: "warn", msg, hint }); }
+function fail(msg, hint) { results.push({ status: "fail", msg, hint }); }
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function readJson(path) {
+  try { return JSON.parse(await readFile(path, "utf8")); } catch { return null; }
+}
+
+async function readEnv() {
+  const candidates = [".env.local", ".env", ".env.development"];
+  const out = {};
+  for (const f of candidates) {
+    const path = join(CWD, f);
+    if (!existsSync(path)) continue;
+    const raw = await readFile(path, "utf8").catch(() => "");
+    for (const line of raw.split("\n")) {
+      const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+      if (!m) continue;
+      let v = m[2].trim();
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+      }
+      if (out[m[1]] === undefined) out[m[1]] = v;
+    }
+  }
+  return out;
+}
+
+async function* walk(dir, depth = 0) {
+  if (depth > 4) return;
+  let entries;
+  try { entries = await readdir(dir); } catch { return; }
+  for (const name of entries) {
+    if (name === "node_modules" || name === ".next" || name === "dist" || name.startsWith(".")) continue;
+    const full = join(dir, name);
+    let s;
+    try { s = await stat(full); } catch { continue; }
+    if (s.isDirectory()) {
+      yield* walk(full, depth + 1);
+    } else if (/\.(tsx?|jsx?|mjs|cjs)$/.test(name)) {
+      yield full;
+    }
+  }
+}
+
+async function findCssImport() {
+  for await (const file of walk(CWD)) {
+    const src = await readFile(file, "utf8").catch(() => "");
+    if (/@aigentyc\/chat-sdk\/theme\/styles\.css/.test(src)) {
+      return file;
+    }
+  }
+  return null;
+}
+
+function semverMajor(v) {
+  if (!v) return 0;
+  const m = String(v).match(/(\d+)/);
+  return m ? Number(m[1]) : 0;
+}
+
+async function pingEndpoint(url) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 5000);
+  try {
+    const res = await fetch(url, { method: "GET", signal: ctrl.signal });
+    clearTimeout(t);
+    return { ok: res.ok || res.status < 500, status: res.status };
+  } catch (err) {
+    clearTimeout(t);
+    return { ok: false, error: String(err?.message || err) };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Checks
+// ---------------------------------------------------------------------------
+
+async function run() {
+  console.log(C.bold("\n  aigentyc doctor"));
+  console.log(C.dim(`  cwd: ${CWD}\n`));
+
+  // 1. Node version
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  if (nodeMajor >= 18) pass(`Node ${process.versions.node}`);
+  else fail(`Node ${process.versions.node} (need >= 18)`, "Update Node: https://nodejs.org");
+
+  // 2. package.json + React + SDK
+  const pkg = await readJson(join(CWD, "package.json"));
+  if (!pkg) {
+    fail("No package.json found in current directory.", `Run from your project root.`);
+    return finish();
+  }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+  const reactV = deps.react;
+  if (!reactV) fail("`react` not in dependencies.", "npm install react@^19 react-dom@^19");
+  else if (semverMajor(reactV) < 19)
+    fail(`React ${reactV} (need >= 19)`, "npm install react@^19 react-dom@^19");
+  else pass(`React ${reactV}`);
+
+  const sdkV = deps["@aigentyc/chat-sdk"];
+  if (!sdkV) {
+    fail("`@aigentyc/chat-sdk` not in dependencies.", "npm install @aigentyc/chat-sdk");
+  } else {
+    pass(`@aigentyc/chat-sdk ${sdkV}`);
+  }
+
+  // 3. CSS import
+  const cssFile = await findCssImport();
+  if (cssFile) pass(`CSS imported in ${cssFile.replace(CWD + "/", "")}`);
+  else fail(
+    "Missing CSS import.",
+    `Add to your entry/layout file:\n     import "@aigentyc/chat-sdk/theme/styles.css"`
+  );
+
+  // 4. Env vars
+  const env = await readEnv();
+  const isNext = !!deps.next;
+  const prefix = isNext ? "NEXT_PUBLIC_AIGENTYC" : "VITE_AIGENTYC";
+
+  const projectId = env[`${prefix}_PROJECT_ID`];
+  const apiEndpoint = env[`${prefix}_API_ENDPOINT`];
+  const apiKey = env[`${prefix}_API_KEY`];
+
+  if (!projectId || projectId === "replace-me") {
+    fail(
+      `${prefix}_PROJECT_ID missing or placeholder.`,
+      "Get your projectId from https://app.aigentyc.ai/dashboard"
+    );
+  } else if (!/^proj_/.test(projectId)) {
+    warn(
+      `${prefix}_PROJECT_ID does not look like a project slug (expected proj_...).`,
+      `Got: ${projectId}`
+    );
+  } else {
+    pass(`${prefix}_PROJECT_ID = ${projectId}`);
+  }
+
+  if (!apiEndpoint) {
+    fail(
+      `${prefix}_API_ENDPOINT missing.`,
+      `Add ${prefix}_API_ENDPOINT=https://app.aigentyc.ai`
+    );
+  } else {
+    pass(`${prefix}_API_ENDPOINT = ${apiEndpoint}`);
+  }
+
+  if (apiKey) {
+    if (!/^tyco_pk_/.test(apiKey)) {
+      warn(
+        `${prefix}_API_KEY does not look like an Aigentyc key (expected tyco_pk_...).`,
+        `Got: ${apiKey.slice(0, 12)}...`
+      );
+    } else {
+      pass(`${prefix}_API_KEY = ${apiKey.slice(0, 12)}...`);
+    }
+  } else {
+    warn(
+      `${prefix}_API_KEY not set.`,
+      "OK if your project is public; required otherwise. Create one at https://app.aigentyc.ai/dashboard/<projectId>/api-keys"
+    );
+  }
+
+  // 5. Endpoint reachable
+  if (apiEndpoint) {
+    const ping = await pingEndpoint(apiEndpoint);
+    if (ping.ok) pass(`Reachable: ${apiEndpoint} (HTTP ${ping.status})`);
+    else fail(
+      `Cannot reach ${apiEndpoint}`,
+      ping.error ? `Network error: ${ping.error}` : `HTTP ${ping.status}`
+    );
+  }
+
+  // 6. CORS hint
+  const dev = isNext ? "http://localhost:3000" : "http://localhost:5173";
+  warn(
+    "CORS",
+    `Make sure your API key allows origin: ${dev} (set in dashboard → API Keys → Allowed Origins)`
+  );
+
+  finish();
+}
+
+function finish() {
+  console.log("");
+  let failed = 0;
+  for (const r of results) {
+    const tag =
+      r.status === "ok" ? C.green("✓") :
+      r.status === "warn" ? C.yellow("⚠") :
+      C.red("✗");
+    console.log(`  ${tag}  ${r.msg}`);
+    if (r.hint && r.status !== "ok") {
+      console.log(`     ${C.dim(r.hint)}`);
+    }
+    if (r.status === "fail") failed++;
+  }
+  console.log("");
+  if (failed === 0) {
+    console.log(C.green("  All checks passed."));
+    console.log(C.dim("  Run `npm run dev` and your chat should work.\n"));
+    process.exit(0);
+  } else {
+    console.log(C.red(`  ${failed} check${failed === 1 ? "" : "s"} failed. Fix the items above and rerun.\n`));
+    process.exit(1);
+  }
+}
+
+run();

package/dist/llms-full.txt

@@ -0,0 +1,769 @@
+# @aigentyc/chat-sdk — full LLM context
+
+This file is the deep reference for AI coding tools (Cursor, Claude Code, Windsurf, v0). It is generated from the published types and aggregated docs at build time. For a short overview, read `llms.txt`.
+
+---
+
+## README.md
+
+# @aigentyc/chat-sdk
+
+> React SDK for building AI-powered chat interfaces connected to the Aigentyc platform.
+
+## Features
+- Drop-in `<Chat />` and `<ChatWidget />` components
+- Full slot system — replace any UI piece
+- Headless mode with `useAigentycChat` hook
+- Backend-driven tool rendering (visualization, json-render, custom HTML)
+- Live chat handoff with Socket.IO
+- Built-in i18n (en, he) — extensible with `addLanguage()`
+- React 19, SSR-compatible (Next.js App Router)
+- Multi-instance support — multiple chats on one page
+- White-label — zero forced branding
+
+## Quickest start — scaffold a new app
+
+```bash
+npm create aigentyc-chat@latest my-app
+cd my-app && npm install && npm run dev
+```
+
+Picks Vite or Next.js, wires your `projectId`, drops in `<Chat />`. Done.
+
+## Add to an existing app
+
+```bash
+npm install @aigentyc/chat-sdk
+```
+
+That's it — core chat, streaming, and tool rendering work out of the box.
+
+Optional peer deps — install only if you use that feature:
+- `socket.io-client` — live chat handoff
+- `recharts` — visualization tool renderer
+- `@json-render/core @json-render/react @json-render/shadcn zod` — json-render tools
+
+## Quick Start
+
+```tsx
+import { Chat } from "@aigentyc/chat-sdk"
+import "@aigentyc/chat-sdk/theme/styles.css"
+
+export function App() {
+  return (
+    <Chat
+      projectId="your-project-id"
+      apiEndpoint="https://app.aigentyc.ai"
+      apiKey="your-api-key"
+    />
+  )
+}
+```
+
+## Four Levels of Control
+
+### Level 1 — Drop-in
+```tsx
+<Chat projectId="..." apiEndpoint="..." />
+```
+
+### Level 2 — Customize with slots + theme
+```tsx
+<Chat
+  projectId="..." apiEndpoint="..."
+  theme={{ primaryColor: "#3b82f6" }}
+  slots={{ header: MyHeader, input: MyInput }}
+  onMessageSent={(msg) => analytics.track('chat', msg)}
+/>
+```
+
+### Level 3 — Compose components
+```tsx
+<ChatProvider projectId="..." apiEndpoint="...">
+  <MyLayout>
+    <ChatInterface />
+    <ChatInput />
+  </MyLayout>
+</ChatProvider>
+```
+
+### Level 4 — Headless
+```tsx
+const { messages, sendMessage, status } = useAigentycChat({
+  projectId: "...", apiEndpoint: "..."
+})
+```
+
+## Slots
+
+| Slot | Replaces |
+| --- | --- |
+| `header` | Chat header bar |
+| `welcome` | Welcome / empty state |
+| `message` | Individual message bubble |
+| `input` | Composer / input box |
+| `footer` | Footer below input |
+| `loader` | Loading indicator |
+| `suggestions` | Suggested prompts |
+| `tools` | Per-tool renderers (keyed by tool name) |
+
+## Tool Rendering
+Tools created in the Aigentyc platform come with rendering instructions. The SDK auto-renders based on `uiRenderMode`:
+- `visualization` → recharts
+- `json_render` → component spec via @json-render/shadcn
+- `legacy` → custom HTML/CSS template
+- `preset` → built-in renderers
+
+Override per-tool:
+```tsx
+<Chat slots={{ tools: { searchProducts: MyProductGrid } }} />
+```
+
+## Theming
+All theme tokens are CSS variables under `[data-aigentyc-chat]`. Override via `theme` prop or your own CSS.
+
+## i18n
+Built-in: `en`, `he`. Add custom languages:
+```tsx
+import { addLanguage } from "@aigentyc/chat-sdk/i18n"
+addLanguage("fr", { welcomeTitle: "Bienvenue", ... })
+```
+
+## Live Chat
+Enable Socket.IO-based live chat handoff:
+```tsx
+<Chat enableLiveChat chatServiceUrl="wss://..." />
+```
+
+## Next.js / SSR
+All components have `"use client"` directives. Works in App Router and Pages Router.
+
+## Storybook
+```bash
+npm run storybook
+```
+
+## Demo
+```bash
+cd demo && npm install && npm run dev
+```
+
+## Package Exports
+- `@aigentyc/chat-sdk` — main (Chat, ChatWidget, ChatProvider)
+- `@aigentyc/chat-sdk/core` — types, transport, utils
+- `@aigentyc/chat-sdk/hooks` — all hooks
+- `@aigentyc/chat-sdk/components` — individual chat components
+- `@aigentyc/chat-sdk/ai-elements` — Message, Conversation, etc.
+- `@aigentyc/chat-sdk/tools` — ToolRenderer, VisualizationRenderer
+- `@aigentyc/chat-sdk/json-render` — json-render system
+- `@aigentyc/chat-sdk/ui` — shadcn primitives
+- `@aigentyc/chat-sdk/theme` — ThemeProvider + styles.css
+- `@aigentyc/chat-sdk/i18n` — translations
+
+## License
+MIT
+
+---
+
+## AGENTS.md
+
+# AGENTS.md — @aigentyc/chat-sdk
+
+Guide for AI coding assistants (Claude Code, Cursor, Windsurf, v0, Lovable, Bolt) using or contributing to this SDK. Humans: read `README.md` first.
+
+**Live docs (always current):** https://context7.com/llmstxt/unpkg_aigentyc_chat-sdk_0_1_5_llms_txt/llms.txt
+
+---
+
+## What this package is
+
+React 19 SDK for embedding an AI chat UI backed by the Aigentyc platform. Ships as a set of subpath exports so consumers only pull what they need.
+
+- Package name: `@aigentyc/chat-sdk`
+- Peer deps (required): `react>=19`, `react-dom>=19`
+- Bundled internally (no install needed): `@ai-sdk/react`, `ai`
+- Peer deps (optional, install only for that feature): `socket.io-client` (live chat), `recharts` (viz), `@json-render/*` + `zod` (json-render)
+- SSR: all client components emit `"use client"`; safe for Next.js App Router.
+
+---
+
+## Canonical install + usage (paste-ready)
+
+**New project?** Use the scaffolder — it's the lowest-risk path:
+
+```bash
+npm create aigentyc-chat@latest my-app -- --template=next --project-id=YOUR_ID
+```
+
+**Adding to an existing app:**
+
+```bash
+npm install @aigentyc/chat-sdk
+```
+
+```tsx
+import { Chat } from "@aigentyc/chat-sdk"
+import "@aigentyc/chat-sdk/theme/styles.css"
+
+export default function Page() {
+  return (
+    <Chat
+      projectId="YOUR_PROJECT_ID"
+      apiEndpoint="https://api.aigentyc.com"
+      apiKey="YOUR_API_KEY"
+    />
+  )
+}
+```
+
+**Required:** the CSS import. Without it the chat renders unstyled.
+
+---
+
+## Decision tree: which API to use
+
+```
+Need a full chat UI with zero config?           → <Chat />
+Need a floating bubble widget?                  → <ChatWidget />
+Need to customize header/input/messages only?   → <Chat slots={{...}} />
+Need custom layout around the chat?             → <ChatProvider> + <ChatInterface /> + <ChatInput />
+Need your own UI entirely?                      → useAigentycChat() (headless)
+Need to override one tool's rendering?          → slots.tools[toolName]
+```
+
+Don't reach for the headless hook just to change styling — use `theme` or `slots` first.
+
+---
+
+## Entry points (import from these, never from `dist/`)
+
+| Import | What you get |
+| --- | --- |
+| `@aigentyc/chat-sdk` | `Chat`, `ChatWidget`, `ChatProvider` |
+| `@aigentyc/chat-sdk/hooks` | `useAigentycChat`, other hooks |
+| `@aigentyc/chat-sdk/components` | Granular composable chat pieces |
+| `@aigentyc/chat-sdk/ai-elements` | `Message`, `Conversation` primitives |
+| `@aigentyc/chat-sdk/tools` | `ToolRenderer`, `VisualizationRenderer` |
+| `@aigentyc/chat-sdk/json-render` | json-render integration |
+| `@aigentyc/chat-sdk/ui` | shadcn-style primitives |
+| `@aigentyc/chat-sdk/theme` | `ThemeProvider`; CSS at `.../theme/styles.css` |
+| `@aigentyc/chat-sdk/i18n` | `addLanguage`, built-in `en`, `he` |
+| `@aigentyc/chat-sdk/core` | Types, transport, utilities |
+
+---
+
+## Slots
+
+`slots` prop on `<Chat>` / `<ChatWidget>`:
+
+- `header`, `welcome`, `message`, `input`, `footer`, `loader`, `suggestions`
+- `tools`: `Record<toolName, ComponentType>` — override per-tool rendering
+
+Each slot receives typed props — consult `.d.ts` of the entry points for exact signatures. Don't invent prop names.
+
+---
+
+## Tool rendering
+
+Tool results come back from the backend with a `uiRenderMode`:
+
+- `visualization` → recharts (requires `recharts` peer)
+- `json_render` → `@json-render/shadcn` (requires `@json-render/*` + `zod` peers)
+- `legacy` → HTML/CSS template from backend
+- `preset` → built-in renderer
+
+If a peer is missing, that tool's UI falls back; install the peer or override via `slots.tools[name]`.
+
+---
+
+## Theming
+
+CSS variables scoped under `[data-aigentyc-chat]`. Two ways to customize:
+
+```tsx
+<Chat theme={{ primaryColor: "#3b82f6" }} />
+```
+
+or plain CSS targeting `[data-aigentyc-chat]`. Do **not** edit `dist/styles.css` directly.
+
+---
+
+## i18n
+
+Built-in: `en`, `he`. Add more:
+
+```tsx
+import { addLanguage } from "@aigentyc/chat-sdk/i18n"
+addLanguage("fr", { welcomeTitle: "Bienvenue" })
+```
+
+---
+
+## Live chat handoff
+
+```tsx
+<Chat enableLiveChat chatServiceUrl="wss://..." />
+```
+
+Requires `socket.io-client`. Omit both props for AI-only mode.
+
+---
+
+## Rules for agents editing consumer projects
+
+**Do:**
+- Use the canonical quick start above verbatim for first-time setup.
+- Import CSS once, at the app root or layout file.
+- Prefer `slots` + `theme` before going headless.
+- Use React 19 features (Actions, `use`) — this SDK targets React 19.
+- Check `.d.ts` files under the published package for exact prop types.
+
+**Don't:**
+- Don't install React 18 — peer is `>=19`. If the project is on React 18, warn the user and stop.
+- Don't import from `@aigentyc/chat-sdk/dist/*` — those paths are not public API.
+- Don't reimplement message rendering when `slots.message` exists.
+- Don't call the Aigentyc API directly from the client — the SDK owns transport.
+- Don't add `"use client"` to files that wrap the SDK unnecessarily; it's already inside.
+- Don't commit `apiKey` to source control; use env vars (`NEXT_PUBLIC_*` only if the project is OK exposing it; otherwise proxy through a server route).
+
+---
+
+## Troubleshooting quick table
+
+| Symptom | Likely cause |
+| --- | --- |
+| Unstyled / broken layout | Missing `import "@aigentyc/chat-sdk/theme/styles.css"` |
+| "Cannot find module @ai-sdk/react" | Stale install — delete `node_modules` and reinstall (these are now bundled) |
+| Tool renders blank | Peer for that `uiRenderMode` not installed |
+| SSR hydration warning | Wrapping `<Chat>` in a non-client component — it's fine, the SDK handles `"use client"` internally; check for other client-only code in the tree |
+| React version error | Upgrade to React 19 |
+
+---
+
+## Repository layout (for contributors)
+
+- `src/` — source; barrel files per entry point
+- `dist/` — build output (tsup); do not edit
+- `stories/` — Storybook
+- `demo/` — local demo app (standalone Vite)
+- `src/styles/index.css` — Tailwind entry compiled to `dist/styles.css`
+
+Scripts: `pnpm build`, `pnpm storybook`, `pnpm test`, `pnpm lint`.
+
+---
+
+## Versioning
+
+- Current: `0.1.0` (pre-1.0 — API may shift).
+- Pin exact versions in consumer projects until 1.0.
+
+---
+
+## llms.txt (overview, recipes, troubleshooting)
+
+# @aigentyc/chat-sdk
+
+> React 19 SDK for embedding AI-powered chat UIs connected to the Aigentyc platform. Ships drop-in components, a composable component layer, and a fully headless hook. SSR-safe (Next.js App Router). White-label, themeable, i18n-ready, with backend-driven tool rendering and optional live-chat handoff.
+
+## Fastest path — scaffold a starter
+
+```bash
+npm create aigentyc-chat@latest my-app
+```
+
+Prompts for template (`vite-react` or `next`) and `projectId`, then produces a working app. Non-interactive:
+
+```bash
+npm create aigentyc-chat@latest my-app -- --template=next --project-id=YOUR_ID
+```
+
+## Installation (add to existing app)
+
+```bash
+npm install @aigentyc/chat-sdk
+```
+
+Only `react>=19` and `react-dom>=19` are required peers. Everything else needed for core chat (streaming, tools, transport) is bundled.
+
+Optional peers — install only if you use that feature:
+- `socket.io-client` — live chat handoff
+- `recharts` — visualization tool renderer
+- `@json-render/core @json-render/react @json-render/shadcn zod` — json-render tools
+
+## Golden-path quick start
+
+```tsx
+import { Chat } from "@aigentyc/chat-sdk"
+import "@aigentyc/chat-sdk/theme/styles.css"
+
+export function App() {
+  return (
+    <Chat
+      projectId="your-project-id"
+      apiEndpoint="https://app.aigentyc.ai"
+      apiKey="your-api-key"
+    />
+  )
+}
+```
+
+Peer deps required: `react>=19`, `react-dom>=19`. The CSS import is required for theming.
+
+## Four levels of control
+
+1. **Drop-in** — `<Chat projectId apiEndpoint />`
+2. **Customize** — add `theme`, `slots`, event handlers like `onMessageSent`
+3. **Compose** — `<ChatProvider>` + individual components (`ChatInterface`, `ChatInput`)
+4. **Headless** — `useAigentycChat({ projectId, apiEndpoint })` returns `{ messages, sendMessage, status }`
+
+## Package entry points
+
+- `@aigentyc/chat-sdk` — `Chat`, `ChatWidget`, `ChatProvider` (main)
+- `@aigentyc/chat-sdk/hooks` — `useAigentycChat` and other hooks
+- `@aigentyc/chat-sdk/components` — granular chat components
+- `@aigentyc/chat-sdk/ai-elements` — `Message`, `Conversation`, primitives
+- `@aigentyc/chat-sdk/tools` — `ToolRenderer`, `VisualizationRenderer`
+- `@aigentyc/chat-sdk/json-render` — json-render integration
+- `@aigentyc/chat-sdk/ui` — shadcn-style UI primitives
+- `@aigentyc/chat-sdk/theme` — `ThemeProvider`; CSS at `@aigentyc/chat-sdk/theme/styles.css`
+- `@aigentyc/chat-sdk/i18n` — `addLanguage`, built-in `en`, `he`
+- `@aigentyc/chat-sdk/core` — types, transport, utils
+
+## Slots
+
+Replace any UI piece via the `slots` prop:
+
+`header`, `welcome`, `message`, `input`, `footer`, `loader`, `suggestions`, `tools` (keyed per tool name).
+
+## Tool rendering
+
+The Aigentyc backend returns a `uiRenderMode` per tool result. The SDK auto-dispatches:
+- `visualization` → recharts
+- `json_render` → `@json-render/shadcn` component spec
+- `legacy` → custom HTML/CSS template
+- `preset` → built-in renderer
+
+Override a specific tool:
+```tsx
+<Chat slots={{ tools: { searchProducts: MyProductGrid } }} />
+```
+
+## Theming
+
+All tokens are CSS variables scoped under `[data-aigentyc-chat]`. Override via the `theme` prop or plain CSS. No forced branding.
+
+## i18n
+
+```tsx
+import { addLanguage } from "@aigentyc/chat-sdk/i18n"
+addLanguage("fr", { welcomeTitle: "Bienvenue" })
+```
+
+## Live chat
+
+```tsx
+<Chat enableLiveChat chatServiceUrl="wss://..." />
+```
+Requires `socket.io-client`.
+
+## Next.js / SSR
+
+All client components declare `"use client"`. Works in App Router and Pages Router without extra config.
+
+## Recipes (copy-paste patterns)
+
+### Recipe: brand colors + custom font
+
+```tsx
+<Chat
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  theme={{
+    primaryColor: "#eb1d22",
+    fontFamily: "Inter, sans-serif",
+    userBubbleColor: "#eb1d22",
+    assistantBubbleColor: "#f5f5f5",
+  }}
+/>
+```
+
+### Recipe: change welcome message
+
+```tsx
+<Chat
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  language="en"
+  translations={{
+    en: { welcomeTitle: "Hi! How can I help?", welcomeSubtitle: "Ask me anything." },
+  }}
+/>
+```
+
+### Recipe: track every user message (analytics)
+
+```tsx
+<Chat
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  onMessageSent={(m) => analytics.track("chat_message_sent", { id: m.id, content: m.content })}
+  onMessageReceived={(m) => analytics.track("chat_message_received", { id: m.id })}
+  onError={(err) => Sentry.captureException(err)}
+/>
+```
+
+### Recipe: show citation sources under assistant replies
+
+```tsx
+<Chat projectId="..." apiEndpoint="https://app.aigentyc.ai" showSources />
+```
+
+### Recipe: replace the input bar with a custom one
+
+```tsx
+import { Chat } from "@aigentyc/chat-sdk";
+
+function MyInput({ DefaultComponent, props }) {
+  // Add a button next to the default input, or replace it entirely.
+  return (
+    <div className="my-composer">
+      <DefaultComponent {...props} />
+      <button onClick={() => alert("uploaded")}>📎</button>
+    </div>
+  );
+}
+
+<Chat slots={{ input: MyInput }} projectId="..." apiEndpoint="..." />
+```
+
+### Recipe: per-tool custom rendering (e.g. product cards)
+
+```tsx
+import type { ToolRendererProps } from "@aigentyc/chat-sdk";
+
+function ProductGrid({ result }: ToolRendererProps) {
+  const products = (result?.data as { items: any[] })?.items ?? [];
+  return (
+    <div className="grid grid-cols-2 gap-2">
+      {products.map((p) => <div key={p.id}>{p.title} — ${p.price}</div>)}
+    </div>
+  );
+}
+
+<Chat
+  projectId="..." apiEndpoint="..."
+  slots={{ tools: { searchProducts: ProductGrid } }}
+/>
+```
+
+### Recipe: Hebrew / RTL
+
+```tsx
+<Chat projectId="..." apiEndpoint="..." language="he" />
+```
+RTL direction is set automatically when `language === "he"`.
+
+### Recipe: floating widget on an existing site
+
+```tsx
+import { ChatWidget } from "@aigentyc/chat-sdk";
+import "@aigentyc/chat-sdk/theme/styles.css";
+
+<ChatWidget
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  theme={{ primaryColor: "#eb1d22" }}
+/>
+```
+Drop anywhere in your tree — it portals itself to the bottom-right corner.
+
+### Recipe: headless (build your own UI)
+
+```tsx
+"use client";
+import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";
+
+export default function MyChat() {
+  const { messages, status, sendMessage } = useAigentycChat({
+    projectId: "...",
+    apiEndpoint: "https://app.aigentyc.ai",
+  });
+  return (
+    <>
+      {messages.map((m) => <div key={m.id}>{m.role}: {m.content}</div>)}
+      <button disabled={status === "streaming"} onClick={() => sendMessage("hello")}>
+        Send
+      </button>
+    </>
+  );
+}
+```
+
+### Recipe: enable live-chat handoff
+
+```tsx
+<Chat
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  apiKey="tyco_pk_..."     // required for live chat
+  enableLiveChat
+/>
+```
+The AI can hand off to a human operator via the `requestHumanChat` tool. UI surfaces a queue + operator panel automatically.
+
+### Recipe: Next.js App Router page
+
+```tsx
+// app/chat/page.tsx
+import { Chat } from "@aigentyc/chat-sdk";
+import "@aigentyc/chat-sdk/theme/styles.css";  // import once, in layout.tsx is fine too
+
+export default function Page() {
+  return (
+    <main style={{ height: "100dvh" }}>
+      <Chat
+        projectId={process.env.NEXT_PUBLIC_AIGENTYC_PROJECT_ID!}
+        apiEndpoint={process.env.NEXT_PUBLIC_AIGENTYC_API_ENDPOINT!}
+        apiKey={process.env.NEXT_PUBLIC_AIGENTYC_API_KEY}
+      />
+    </main>
+  );
+}
+```
+
+### Recipe: persist conversations (default on)
+
+Persistence is on by default. To disable:
+
+```tsx
+<Chat projectId="..." apiEndpoint="..." persistMessages={false} />
+```
+
+Storage key: `aigentyc-messages-<projectId>` in `localStorage`.
+
+### Recipe: programmatically reset the conversation
+
+```tsx
+import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";
+
+const { newConversation, clearMessages } = useAigentycChat({ projectId: "...", apiEndpoint: "..." });
+
+<button onClick={newConversation}>New conversation</button>  // new sessionId + clears
+<button onClick={clearMessages}>Clear messages</button>      // clears, keeps session
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Unstyled / broken layout | Missing CSS import | `import "@aigentyc/chat-sdk/theme/styles.css"` |
+| 401 / 403 from API | `apiKey` missing or wrong scope | Create key with `Chat: Full` permission |
+| CORS error in browser | Allowed Origins on API key doesn't include current URL | Add `http://localhost:5173` (Vite) or `http://localhost:3000` (Next) to the key's Allowed Origins |
+| `Cannot find module @ai-sdk/react` | Stale install from old SDK version | `rm -rf node_modules package-lock.json && npm install` (peers are bundled now) |
+| Hebrew text shows LTR | Forgot `language="he"` | Pass `language="he"` to `<Chat>` |
+| Tool result shows raw JSON | Custom tool with no renderer | Add `slots.tools[toolName]` or set `uiRenderMode: "hidden"` server-side |
+| Chat doesn't render in Next.js | RSC issue | The SDK sets `"use client"`; if your wrapper is a Server Component, that's fine — don't add `"use client"` yourself |
+| `searchKnowledgeBase` JSON appears | (it shouldn't — hidden by default since 0.1.3) | Upgrade `@aigentyc/chat-sdk` |
+
+## Common pitfalls (do not)
+
+- Don't forget the CSS import — unstyled UI is almost always a missing `@aigentyc/chat-sdk/theme/styles.css`.
+- Don't import from `dist/` or deep subpaths — use the public entry points above.
+- Don't wrap in `<Chat>` twice; use `<ChatProvider>` + sub-components for layouts, not nested `<Chat>`.
+- React 18 is not supported — peer is `>=19`.
+- `apiKey` is optional for public/anon projects; required for authenticated ones.
+
+## Links
+
+- Package: https://www.npmjs.com/package/@aigentyc/chat-sdk
+- Scaffolder: `npm create aigentyc-chat@latest my-app`
+- Dashboard: https://app.aigentyc.ai
+
+## Files included in this package
+
+- `README.md` — install + quickstart
+- `AGENTS.md` — agent-oriented guide (rules, decision tree, troubleshooting)
+- `llms.txt` — this file (LLM-friendly summary)
+
+---
+
+## Public API surface (from .d.ts)
+
+Each entry below shows the typed exports for one subpath of the package. Use these as the source of truth for prop names, hook return types, and function signatures.
+
+
+### `@aigentyc/chat-sdk` — Main exports — Chat, ChatWidget, ChatProvider, useAigentycChat
+
+```ts
+export { a as ChatConfig, b as ChatEventCallbacks, c as ChatMessage, d as ComponentAction, L as Language, e as LiveChatMessage, f as LiveChatState, Q as QuestionConfig, S as SlotMap, T as ThemeConfig, g as ToolRendererProps, h as ToolResult } from './types-DKJ_-nbG.js';
+
+export { L as LiveChatReturn, U as UseAigentycChatOptions, a as UseAigentycChatReturn, u as useAigentycChat, b as useChatContext, c as useLiveChat, d as useSlot, e as useSlots } from './SlotsContext-CBtt36al.js';
+
+export { useTheme } from './theme.js';
+
+export { useI18n } from './i18n.js';
+
+export { Chat, ChatProvider, ChatProviderProps, ChatWidget };
+```
+
+
+### `@aigentyc/chat-sdk/hooks` — Hooks — useAigentycChat, useChatContext, useTheme, useI18n, useLiveChat, useSlots
+
+```ts
+export { L as LiveChatReturn, U as UseAigentycChatOptions, a as UseAigentycChatReturn, u as useAigentycChat, b as useChatContext, c as useLiveChat, d as useSlot, e as useSlots } from './SlotsContext-CBtt36al.js';
+
+export { useTheme } from './theme.js';
+
+export { useI18n } from './i18n.js';
+
+export { u as useInteractionTracker } from './interaction-tracker-D9P1Oq4j.js';
+
+export { useImageLoader, useIsMobile, useMultiImageLoader, useMultiOrderTracking, useOrderTracking, usePagination, usePreviewEmbed, useSliderDrag };
+```
+
+
+### `@aigentyc/chat-sdk/components` — Granular components — ChatInterface, ChatInput, ChatHeader, etc.
+
+```ts
+export { CartDrawer, ChatDrawer, ChatFooter, ChatHeader, ChatInput, ChatInputWithAttachments, ChatInterface, FloatingButton, LiveChatHeader, LiveChatPanel, LiveChatQueueBanner, PreviewEmbedPanel, QuickQuestions, SatisfactionRating, SystemMessage, VisitorIdentityForm, WelcomePage };
+```
+
+
+### `@aigentyc/chat-sdk/tools` — Tool rendering — ToolRenderer, SearchKnowledgeBaseRenderer
+
+```ts
+export { d as ComponentAction, h as ToolResult } from './types-DKJ_-nbG.js';
+
+export { J as JsonRenderResult } from './JsonRenderResult-Ftw4AKwb.js';
+
+export { ComponentRenderer, SearchKnowledgeBaseRenderer, ToolRenderer, ToolRendererProps, VisualizationRenderer };
+```
+
+
+### `@aigentyc/chat-sdk/theme` — Theming — ThemeProvider
+
+```ts
+export { T as ThemeConfig } from './types-DKJ_-nbG.js';
+
+export { ThemeProvider, useTheme };
+```
+
+
+### `@aigentyc/chat-sdk/i18n` — Internationalization — addLanguage
+
+```ts
+export { L as Language } from './types-DKJ_-nbG.js';
+
+export { I18nProvider, type I18nProviderProps, type TranslationKeys, type TranslationMap, addLanguage, isRTL, useI18n };
+```
+
+
+### `@aigentyc/chat-sdk/core` — Core types and utilities
+
+```ts
+export { b as ChatEventCallbacks, c as ChatMessage, C as ChatProviderProps, d as ComponentAction, L as Language, e as LiveChatMessage, f as LiveChatState, Q as QuestionConfig, S as SlotMap, i as SlotProps, T as ThemeConfig, g as ToolRendererProps, h as ToolResult } from './types-DKJ_-nbG.js';
+
+export { I as InteractionMetadata, a as InteractionType, T as TrackInteractionParams, U as UseInteractionTrackerOptions, g as generateSessionId, u as useInteractionTracker } from './interaction-tracker-D9P1Oq4j.js';
+
+export { ChatConfig, type CreateChatTransportOptions, INTERNAL_MESSAGE_PREFIX, type LiveChatConfig, type LiveChatEventMap, LiveChatTransport, type StoredMessage, USER_TYPES, USER_TYPE_LABEL_MAP, type UserType, addUtmParams, clearMessages, cn, createChatTransport, createChatTransportSync, debouncedSaveMessages, isInternalMessage, isSsr, loadMessages, minifyToolOutput, prepareMessages, processImagesInHtml, pruneExpiredMessages, saveMessages };
+```

package/llms.txt

@@ -107,6 +107,201 @@ Requires `socket.io-client`.
 
 All client components declare `"use client"`. Works in App Router and Pages Router without extra config.
 
+## Recipes (copy-paste patterns)
+
+### Recipe: brand colors + custom font
+
+```tsx
+<Chat
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  theme={{
+    primaryColor: "#eb1d22",
+    fontFamily: "Inter, sans-serif",
+    userBubbleColor: "#eb1d22",
+    assistantBubbleColor: "#f5f5f5",
+  }}
+/>
+```
+
+### Recipe: change welcome message
+
+```tsx
+<Chat
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  language="en"
+  translations={{
+    en: { welcomeTitle: "Hi! How can I help?", welcomeSubtitle: "Ask me anything." },
+  }}
+/>
+```
+
+### Recipe: track every user message (analytics)
+
+```tsx
+<Chat
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  onMessageSent={(m) => analytics.track("chat_message_sent", { id: m.id, content: m.content })}
+  onMessageReceived={(m) => analytics.track("chat_message_received", { id: m.id })}
+  onError={(err) => Sentry.captureException(err)}
+/>
+```
+
+### Recipe: show citation sources under assistant replies
+
+```tsx
+<Chat projectId="..." apiEndpoint="https://app.aigentyc.ai" showSources />
+```
+
+### Recipe: replace the input bar with a custom one
+
+```tsx
+import { Chat } from "@aigentyc/chat-sdk";
+
+function MyInput({ DefaultComponent, props }) {
+  // Add a button next to the default input, or replace it entirely.
+  return (
+    <div className="my-composer">
+      <DefaultComponent {...props} />
+      <button onClick={() => alert("uploaded")}>📎</button>
+    </div>
+  );
+}
+
+<Chat slots={{ input: MyInput }} projectId="..." apiEndpoint="..." />
+```
+
+### Recipe: per-tool custom rendering (e.g. product cards)
+
+```tsx
+import type { ToolRendererProps } from "@aigentyc/chat-sdk";
+
+function ProductGrid({ result }: ToolRendererProps) {
+  const products = (result?.data as { items: any[] })?.items ?? [];
+  return (
+    <div className="grid grid-cols-2 gap-2">
+      {products.map((p) => <div key={p.id}>{p.title} — ${p.price}</div>)}
+    </div>
+  );
+}
+
+<Chat
+  projectId="..." apiEndpoint="..."
+  slots={{ tools: { searchProducts: ProductGrid } }}
+/>
+```
+
+### Recipe: Hebrew / RTL
+
+```tsx
+<Chat projectId="..." apiEndpoint="..." language="he" />
+```
+RTL direction is set automatically when `language === "he"`.
+
+### Recipe: floating widget on an existing site
+
+```tsx
+import { ChatWidget } from "@aigentyc/chat-sdk";
+import "@aigentyc/chat-sdk/theme/styles.css";
+
+<ChatWidget
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  theme={{ primaryColor: "#eb1d22" }}
+/>
+```
+Drop anywhere in your tree — it portals itself to the bottom-right corner.
+
+### Recipe: headless (build your own UI)
+
+```tsx
+"use client";
+import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";
+
+export default function MyChat() {
+  const { messages, status, sendMessage } = useAigentycChat({
+    projectId: "...",
+    apiEndpoint: "https://app.aigentyc.ai",
+  });
+  return (
+    <>
+      {messages.map((m) => <div key={m.id}>{m.role}: {m.content}</div>)}
+      <button disabled={status === "streaming"} onClick={() => sendMessage("hello")}>
+        Send
+      </button>
+    </>
+  );
+}
+```
+
+### Recipe: enable live-chat handoff
+
+```tsx
+<Chat
+  projectId="..."
+  apiEndpoint="https://app.aigentyc.ai"
+  apiKey="tyco_pk_..."     // required for live chat
+  enableLiveChat
+/>
+```
+The AI can hand off to a human operator via the `requestHumanChat` tool. UI surfaces a queue + operator panel automatically.
+
+### Recipe: Next.js App Router page
+
+```tsx
+// app/chat/page.tsx
+import { Chat } from "@aigentyc/chat-sdk";
+import "@aigentyc/chat-sdk/theme/styles.css";  // import once, in layout.tsx is fine too
+
+export default function Page() {
+  return (
+    <main style={{ height: "100dvh" }}>
+      <Chat
+        projectId={process.env.NEXT_PUBLIC_AIGENTYC_PROJECT_ID!}
+        apiEndpoint={process.env.NEXT_PUBLIC_AIGENTYC_API_ENDPOINT!}
+        apiKey={process.env.NEXT_PUBLIC_AIGENTYC_API_KEY}
+      />
+    </main>
+  );
+}
+```
+
+### Recipe: persist conversations (default on)
+
+Persistence is on by default. To disable:
+
+```tsx
+<Chat projectId="..." apiEndpoint="..." persistMessages={false} />
+```
+
+Storage key: `aigentyc-messages-<projectId>` in `localStorage`.
+
+### Recipe: programmatically reset the conversation
+
+```tsx
+import { useAigentycChat } from "@aigentyc/chat-sdk/hooks";
+
+const { newConversation, clearMessages } = useAigentycChat({ projectId: "...", apiEndpoint: "..." });
+
+<button onClick={newConversation}>New conversation</button>  // new sessionId + clears
+<button onClick={clearMessages}>Clear messages</button>      // clears, keeps session
+```
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Unstyled / broken layout | Missing CSS import | `import "@aigentyc/chat-sdk/theme/styles.css"` |
+| 401 / 403 from API | `apiKey` missing or wrong scope | Create key with `Chat: Full` permission |
+| CORS error in browser | Allowed Origins on API key doesn't include current URL | Add `http://localhost:5173` (Vite) or `http://localhost:3000` (Next) to the key's Allowed Origins |
+| `Cannot find module @ai-sdk/react` | Stale install from old SDK version | `rm -rf node_modules package-lock.json && npm install` (peers are bundled now) |
+| Hebrew text shows LTR | Forgot `language="he"` | Pass `language="he"` to `<Chat>` |
+| Tool result shows raw JSON | Custom tool with no renderer | Add `slots.tools[toolName]` or set `uiRenderMode: "hidden"` server-side |
+| Chat doesn't render in Next.js | RSC issue | The SDK sets `"use client"`; if your wrapper is a Server Component, that's fine — don't add `"use client"` yourself |
+| `searchKnowledgeBase` JSON appears | (it shouldn't — hidden by default since 0.1.3) | Upgrade `@aigentyc/chat-sdk` |
+
 ## Common pitfalls (do not)
 
 - Don't forget the CSS import — unstyled UI is almost always a missing `@aigentyc/chat-sdk/theme/styles.css`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigentyc/chat-sdk",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "React SDK for building AI-powered chat interfaces connected to the Aigentyc platform",
   "type": "module",
   "sideEffects": [
@@ -114,14 +114,19 @@
   },
   "files": [
     "dist",
+    "bin",
     "README.md",
     "AGENTS.md",
     "llms.txt",
     "LICENSE"
   ],
+  "bin": {
+    "aigentyc": "./bin/doctor.mjs"
+  },
   "homepage": "https://www.npmjs.com/package/@aigentyc/chat-sdk",
   "scripts": {
-    "build": "tsup && pnpm build:css",
+    "build": "tsup && pnpm build:css && pnpm build:llms-full",
+    "build:llms-full": "node scripts/build-llms-full.mjs",
     "build:js": "tsup",
     "build:css": "tailwindcss -i ./src/styles/index.css -o ./dist/styles.css --minify || @tailwindcss/cli -i ./src/styles/index.css -o ./dist/styles.css --minify",
     "dev": "tsup --watch",