codicent-app-sdk 0.4.14 → 0.4.17

package/README.md

@@ -1,521 +1,556 @@
-# Codicent App SDK
-
-![Build Status](https://img.shields.io/github/actions/workflow/status/izaxon/codicent-app-sdk/main.yml?branch=main)
-![License](https://img.shields.io/github/license/izaxon/codicent-app-sdk)
-![Version](https://img.shields.io/badge/version-0.4.0-blue)
-
-**A comprehensive SDK for building AI-powered, chat-centric web applications with Codicent.**
-
-Codicent App SDK provides React components, hooks, and utilities to help you quickly build, customize, and deploy modern AI-powered apps. It is designed for rapid prototyping and production use, with built-in support for chat, markdown rendering, file uploads, and more.
-
----
-
-## 🚀 Quick Start (v2 - Simplified Bootstrap)
-
-**New in v0.4.0:** Create a complete Codicent app with a single function call!
-
-```tsx
-import { createCodicentApp } from 'codicent-app-sdk';
-
-const app = createCodicentApp({
-  name: "My CRM",
-  apiBaseUrl: "https://codicent.com/",
-  buttons: [
-    { title: "Customers", url: "./#/list?tag=customer2" },
-    { title: "Quotes", url: "./#/list?tag=offertjson" },
-    { title: "Chat", url: "./#/chat" },
-  ],
-  listDefinitions: {
-    customer2: [
-      { key: "name", title: "Name", filterable: true },
-      { key: "email", title: "Email" },
-      { key: "phone", title: "Phone" },
-    ],
-  },
-  translations: {
-    en: { "Kunder": "Customers", "Offerter": "Quotes" },
-    sv: { "Customers": "Kunder", "Quotes": "Offerter" },
-  },
-  modules: { 
-    sales: true, 
-    voice: true,
-    search: true,
-  },
-  chatInstructions: "You are a helpful CRM assistant.",
-});
-
-// Render to DOM
-app.render("#root");
-```
-
-That's it! You now have a fully configured Codicent vertical app with:
-- ✅ Auth0 authentication
-- ✅ Navigation buttons
-- ✅ List views with filtering and sorting
-- ✅ i18n support
-- ✅ AI chat integration
-- ✅ Module-based feature flags
-
----
-
-## Installation
-
-### From GitHub (Recommended)
-```bash
-npm install github:izaxon/codicent-app-sdk
-# or
-yarn add github:izaxon/codicent-app-sdk
-```
-
-### From npm
-```bash
-npm install codicent-app-sdk
-# or
-yarn add codicent-app-sdk
-```
-
----
-
-## Usage
-
-### Option 1: Simplified Bootstrap (v2 - Recommended)
-
-Use `createCodicentApp()` for the fastest setup. This handles all initialization, routing, and authentication automatically.
-
-```tsx
-import { createCodicentApp } from 'codicent-app-sdk';
-
-const app = createCodicentApp({
-  name: "My App",
-  apiBaseUrl: "https://codicent.com/",
-  // ... config
-});
-
-app.render("#root");
-```
-
-See the [API Reference](#api-reference) below for all configuration options.
-
-### Option 2: Manual Initialization (v1 - Still Supported)
-
-Before using the SDK, initialize it with your app’s settings:
-
-```tsx
-import { initCodicentApp } from 'codicent-app-sdk';
-
-initCodicentApp({
-  API_BASE_URL: 'https://codicent.com/',
-  APP_NAME: 'my-app',
-  // ...other config
-});
-```
-
-
-#### Configuration Options
-
-**Required:**
-```js
-API_BASE_URL: string // e.g. 'https://codicent.com/' or 'https://api.yourdomain.com/' (custom domains supported)
-APP_NAME: string     // e.g. 'my-app'
-APP_PREFIX: string   // e.g. 'myapp'
-USER_PREFIX: string  // e.g. 'users'
-```
-
-**Optional:**
-```js
-BUTTON_BORDER_RADIUS: string
-BUTTON_BACKGROUND_COLOR: string
-DEFAULT_LANGUAGE: string
-SUBSCRIPTION_NEEDED: boolean
-REALTIME_VOICE_MODEL: string // Voice model: "alloy", "shimmer", or "echo" (default: "alloy")
-USE_REALTIME_SESSION_ENDPOINT: boolean // Use secure session endpoint (default: true)
-
-// Compose page location options:
-COMPOSE_HIDE_LOCATION: string  // Set to "true" to hide the GPS toggle button entirely
-COMPOSE_AUTO_LOCATION: string  // Set to "true" to automatically capture GPS on compose page load
-// ...and more
-```
-
-#### Compose page GPS / location
-
-The `Compose` page (route `/new`) supports GPS location tagging. When a location is attached, a `#gps(lat,lon)` tag is appended to the message content — readable by the AI chat instructions and queryable via tag search.
-
-| Option | Value | Behaviour |
-|--------|-------|-----------|
-| `COMPOSE_HIDE_LOCATION` | `"true"` | Hides the GPS toggle button; users cannot attach location |
-| `COMPOSE_HIDE_LOCATION` | `"false"` (default) | Shows the GPS toggle button; users opt-in per post |
-| `COMPOSE_AUTO_LOCATION` | `"true"` | GPS is fetched **automatically** when the compose page opens — no button tap required. The toggle button is still shown so users can remove it if desired |
-
-Example — always capture location (e.g. a spot-logging app):
-```js
-COMPOSE_HIDE_LOCATION: "false",
-COMPOSE_AUTO_LOCATION: "true",
-```
-
-For AI voice configuration and security, see the [Voice Upgrade Guide](VOICE_UPGRADE_GUIDE.md).
-
-#### Using Custom Domains
-
-The SDK fully supports custom domains for self-hosted or white-label deployments. Simply configure your custom API base URL:
-
-```tsx
-import { initCodicentApp } from 'codicent-app-sdk';
-
-// Using a custom domain
-initCodicentApp({
-  API_BASE_URL: 'https://api.yourdomain.com/',  // Your custom API endpoint
-  APP_NAME: 'my-app',
-  APP_PREFIX: 'myapp',
-  USER_PREFIX: 'users',
-  // ... other config
-});
-```
-
-All API calls, including authentication, chat, file uploads, and data operations, will automatically route to your custom domain. Both the SDK and the underlying codicentjs library support custom base URLs.
-
-📄 **For complete custom domain setup, see the [Custom Domain Configuration Guide](docs/CUSTOM_DOMAIN_GUIDE.md)**
-
----
-
-## API Reference
-
-### `createCodicentApp(config)`
-
-Creates a fully-configured Codicent app instance.
-
-**Parameters:**
-
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `name` | `string` | ✅ | Application name |
-| `apiBaseUrl` | `string` | ✅ | API base URL (e.g., "https://codicent.com/") |
-| `appPrefix` | `string` | | App-specific URL prefix (defaults to kebab-cased name) |
-| `userPrefix` | `string` | | User namespace prefix (default: "users") |
-| `buttons` | `ButtonConfig[]` | | Navigation buttons |
-| `listDefinitions` | `ListDefinitions` | | List view column definitions per tag |
-| `translations` | `Translations` | | i18n translation maps by language |
-| `defaultLanguage` | `string` | | Default language code (default: "en") |
-| `modules` | `ModuleFlags` | | Feature module flags (sales, voice, forms, etc.) |
-| `chatInstructions` | `string` | | AI chat system prompt |
-| `voiceInstructions` | `string` | | AI voice system prompt |
-| `auth0` | `Auth0Config` | | Auth0 configuration |
-| `stripe` | `StripeConfig` | | Stripe configuration |
-| `theme` | `ThemeConfig` | | Theme/branding configuration |
-
-**Returns:** `CodicentApp` instance with:
-- `render(container)` - Render app to a DOM element
-- `unmount()` - Unmount the app
-- `getConfig()` - Get current configuration
-
-**Example:**
-
-```tsx
-const app = createCodicentApp({
-  name: "Sales CRM",
-  apiBaseUrl: "https://codicent.com/",
-  buttons: [
-    { title: "Dashboard", url: "./#/" },
-    { title: "Customers", url: "./#/list?tag=customer2" },
-  ],
-  listDefinitions: {
-    customer2: [
-      { key: "name", title: "Customer Name", filterable: true },
-      { key: "email", title: "Email" },
-    ],
-  },
-  modules: { sales: true, voice: false },
-});
-
-app.render("#root");
-```
-
----
-
-## TypeScript Types
-
-All public types are fully documented with JSDoc and exported from `codicent-app-sdk`:
-
-```tsx
-import type {
-  ButtonConfig,
-  ColumnDefinition,
-  ListDefinitions,
-  ModuleFlags,
-  Translations,
-  UserInfo,
-  DataMessage,
-  CodicentAppState,
-  // ... and more
-} from 'codicent-app-sdk';
-```
-
-See [src/types/index.ts](src/types/index.ts) for the complete type definitions.
-
----
-
-## Components
-
-### Standalone Components
-
-The SDK exports several standalone React components that can be used independently:
-
-#### `Chat`
-
-AI chat interface component (exported from pages).
-
-```tsx
-import { Chat } from 'codicent-app-sdk';
-
-<Chat />
-```
-
-For detailed usage, see [src/pages/Chat.tsx](src/pages/Chat.tsx).
-
-#### `ListView`
-
-Display tabular data with sorting, filtering, and actions. While ListView is currently in the `codicentapp` package, you can import the types from the SDK:
-
-```tsx
-import type { ColumnDefinition, ListViewProps } from 'codicent-app-sdk';
-```
-
-See [codicentapp/src/components/ListView.tsx](../codicentapp/src/components/ListView.tsx) for the reference implementation.
-
----
-
-### CRUD Operations
-
-The SDK provides comprehensive CRUD (Create, Read, Update, Delete) methods for managing structured data. For detailed documentation and examples, see:
-
-📄 **[CRUD Method Usage Guide](../CRUD_METHOD_USAGE.md)** - Complete guide covering:
-- CodicentService CRUD methods
-- Usage patterns for project/task management and business records
-- JavaScript library (codicentjs) API
-- Best practices and complete examples
-
-### Example: Simple Chat App
-
-```tsx
-import React from 'react';
-import { CodicentService, useChat, Markdown, initCodicentApp } from 'codicent-app-sdk';
-
-initCodicentApp({
-  API_BASE_URL: 'https://codicent.com/',
-  APP_NAME: 'my-app',
-  APP_PREFIX: 'myapp',
-  USER_PREFIX: 'users',
-});
-
-const App = () => {
-  const codicentService = new CodicentService();
-  const { messages, sendMessage } = useChat(codicentService);
-
-  return (
-    <div>
-      {messages.map(msg => (
-        <div key={msg.id}>
-          <Markdown content={msg.content} />
-        </div>
-      ))}
-      <button onClick={() => sendMessage('Hello world')}>Send</button>
-    </div>
-  );
-};
-```
-
----
-
-## Features
-
-- **React Components:** Chat UI, Markdown, File Upload, Audio, and more
-- **Hooks:** Chat state, authentication, localization, theme, and more
-- **AI Voice:** Realtime voice AI with secure session endpoint support (see [Voice Upgrade Guide](VOICE_UPGRADE_GUIDE.md))
-- **State Management:** Efficient state machine with caching capabilities (see [State Management Caching Improvements](STATE_MANAGEMENT_CACHING_IMPROVEMENTS.md))
-- **Utilities:** Helpers for app state, device, logging, and more
-- **TypeScript Support:** Full typings for all exports
-- **Customizable:** Theming and configuration options
-
----
-
-## Development
-
-### Building and Publishing
-
-The SDK uses GitHub Actions to automate the build and publishing process:
-
-1. On push to the main branch:
-   - The package is automatically built
-   - Documentation is deployed to GitHub Pages
-
-2. When a new version tag is pushed (e.g., `v0.3.12`):
-   - The package is built
-   - A GitHub Release is created with the built package
-   - The package is published to GitHub Packages
-
-### Release Process
-
-To release a new version:
-
-```bash
-# 1. Update version in package.json
-npm version patch|minor|major
-
-# 2. Push changes with tags
-git push --follow-tags
-```
-
-This will trigger the GitHub Actions workflow to create a release and publish the package.
-
-### Local Development
-
-For local development:
-
-```bash
-# Install dependencies
-npm install
-
-# Run in development mode with watch
-npm run dev
-
-# Build locally
-npm run build
-```
-
-The build process generates:
-- CommonJS modules in `dist/cjs`
-- ES modules in `dist/esm` 
-- TypeScript definitions
-
-### Testing Your Changes Locally
-
-You can test SDK changes in your project:
-
-```bash
-# In the SDK directory
-npm link
-
-# In your project directory
-npm link codicent-app-sdk
-```
-
-### Documentation
-
-Documentation is automatically deployed to GitHub Pages as part of the workflow when changes are pushed to the main branch.
-
-For manual deployment:
-
-```bash
-# To manually build and copy artifacts to docs directory
-npm run predeploy
-
-# To manually deploy documentation
-npm run deploy
-```
-
-## Publishing to npm
-
-To publish this package to npm:
-
-1. **Login to npm** (if you haven't already):
-   ```bash
-   npm login
-   ```
-
-2. **Build the package**:
-   ```bash
-   npm run build
-   ```
-
-3. **Publish to npm**:
-   ```bash
-   npm publish --access public
-   ```
-
-**Notes:**
-- Make sure the `"name"` field in `package.json` is set to `codicent-app-sdk` (no scope).
-- The package name must be unique on npm.
-- If you get a permissions error, ensure you are the owner of the package name on npm.
-
-## Documentation
-
-For full documentation, visit [our docs site](https://izaxon.github.io/codicent-app-sdk/).
-
-### Additional Documentation
-
-- **[Voice Upgrade Guide](VOICE_UPGRADE_GUIDE.md)** - Complete guide for implementing and upgrading realtime voice AI features
-- **[State Management Caching Improvements](STATE_MANAGEMENT_CACHING_IMPROVEMENTS.md)** - Comprehensive analysis and strategies for optimizing state management performance through intelligent caching
-- **[Implementation Guide](IMPLEMENTATION_GUIDE.md)** - ✅ **NEW!** How to enable and use the state management caching system (now implemented!)
-
-## License
-
-MIT © Codicent Inside AB
-
----
-
-## Fast Local SDK Testing Workflow
-
-To quickly test changes in your local SDK with your app project, you can use npm link or a local file dependency. This avoids publishing to npm for every change.
-
-### Option 1: Using `npm link`
-
-1. **Build your SDK in watch mode (if needed):**
-   - If your SDK uses TypeScript or a bundler (like rollup), run it in watch mode so changes are rebuilt automatically.
-     ```cmd
-     npm run build -- --watch
-     ```
-     Or for TypeScript:
-     ```cmd
-     npx tsc --watch
-     ```
-
-2. **Link your SDK globally:**
-   In your SDK root folder:
-   ```cmd
-   npm link
-   ```
-
-3. **Link your SDK in your app project:**
-   In your app project folder (the one that uses the SDK):
-   ```cmd
-   npm link codicent-app-sdk
-   ```
-   (Replace `codicent-app-sdk` with the actual name in your SDK’s `package.json` if different.)
-
-4. **Test changes instantly:**
-   Now, when you make changes to your SDK and rebuild, your app will use the updated local version immediately—no need to publish or reinstall from npm.
-
-5. **Unlink when done:**
-   When you want to go back to using the npm-published version, run in your app project:
-   ```cmd
-   npm uninstall codicent-app-sdk
-   npm install codicent-app-sdk
-   ```
-
-### Option 2: Using a Local File Dependency
-
-1. In your app’s `package.json`, set the dependency to point to your local SDK folder:
-   ```json
-   "dependencies": {
-     "codicent-app-sdk": "file:../codicent-app-sdk"
-   }
-   ```
-2. Run `npm install` in your app project.
-
----
-
-## Listening to `codicent-log` Events
-
-You can listen for SDK log events of type `codicent-log` in your application. This is useful for debugging or integrating with your own logging system.
-
-```tsx
-// Listen for log events
-window.addEventListener('codicent-log', (event) => {
-  // event.detail contains the log payload
-  console.log('Codicent Log:', event.detail);
-});
-```
-
-- The event is dispatched as a [CustomEvent](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) on the `window` object.
-- The `event.detail` property contains the log data (such as level, message, and context).
-
----
+# codicent-app-sdk
+
+React SDK for building AI-powered, multi-tenant white-label applications on top of the Codicent platform.
+
+**Current version:** 0.4.16 · **License:** MIT · **Peer deps:** React ≥16.8, Fluent UI v9, react-router-dom v6
+
+---
+
+## What it provides
+
+- `CodicentService` — data CRUD, chat, file upload, token management
+- React components — `Page`, `Content`, `Chat`, `ListView`, `Markdown`, `UploadFile`, and ~25 more
+- Pages — `AppFrame`, `Chat`, `Compose`, `Sales`, `Search`, `Snap`, `Login`, `Logout`, and more
+- Hooks — `useCodicentApp`, `useLocalization`, `useChat`, `useRealtimeVoiceAI`, `useAuthState`, and more
+- Global config — `initCodicentApp()` initializer consumed by all SDK components
+- Full TypeScript types
+
+This SDK is the primary dependency of `codicentapp/` (the modern white-label Vite app) in the monorepo. See `codicentapp/` for a complete real-world usage reference.
+
+---
+
+## Installation
+
+### From npm
+```bash
+npm install codicent-app-sdk
+```
+
+### Monorepo local dependency (recommended during development)
+In your app's `package.json`:
+```json
+"dependencies": {
+  "codicent-app-sdk": "file:../codicent-app-sdk"
+}
+```
+Then `npm install` in your app.
+
+### Peer dependencies
+Install these alongside the SDK:
+```bash
+npm install react react-dom react-router-dom @fluentui/react-components mermaid
+```
+
+---
+
+## Usage
+
+### 1. Initialize the SDK (once, at app startup)
+
+Call `initCodicentApp()` before rendering your React tree. It stores config globally so all SDK components and hooks can read it.
+
+```tsx
+// main.tsx
+import { initCodicentApp } from 'codicent-app-sdk';
+import { translations } from './services/translationService';
+import { getAppConfig } from './appconfig';
+
+initCodicentApp({
+  API_BASE_URL: 'https://codicent.com/',
+  APP_NAME: 'my-crm',
+  APP_PREFIX: 'mycrm',
+  USER_PREFIX: 'users',
+  APP_CONFIG: getAppConfig(),      // buttons, listDefinitions, chatInstructions
+  TRANSLATIONS: translations,      // { sv: {...}, en: {...}, ... }
+  USE_REALTIME_SESSION_ENDPOINT: true,
+});
+```
+
+### 2. Wrap with Auth0 and FluentProvider
+
+The SDK components depend on these providers being present in the React tree:
+
+```tsx
+// main.tsx (continued)
+import { Auth0Provider } from '@auth0/auth0-react';
+import { FluentProvider, webLightTheme } from '@fluentui/react-components';
+import { createRoot } from 'react-dom/client';
+
+createRoot(document.getElementById('root')!).render(
+  <Auth0Provider domain={AUTH0_DOMAIN} clientId={AUTH0_CLIENT_ID} authorizationParams={{ redirect_uri: window.location.origin }}>
+    <FluentProvider theme={webLightTheme}>
+      <App />
+    </FluentProvider>
+  </Auth0Provider>
+);
+```
+
+### 3. Use `useCodicentApp()` in your root App component
+
+```tsx
+// App.tsx
+import { useCodicentApp } from 'codicent-app-sdk';
+import { useAuth0 } from '@auth0/auth0-react';
+import { HashRouter, Routes, Route } from 'react-router-dom';
+import { Chat } from 'codicent-app-sdk';
+import { ListPage } from './pages/ListPage';
+
+export default function App() {
+  const auth0 = useAuth0();
+  const state = useCodicentApp({ auth0 });
+
+  if (!auth0.isAuthenticated) {
+    auth0.loginWithRedirect();
+    return null;
+  }
+
+  return (
+    <HashRouter>
+      <Routes>
+        <Route path="/chat" element={<Chat state={state} title="Chat" />} />
+        <Route path="/list" element={<ListPage state={state} />} />
+      </Routes>
+    </HashRouter>
+  );
+}
+```
+
+### 4. Build pages using SDK components
+
+```tsx
+// pages/ListPage.tsx
+import { Page, Content, ListView, useLocalization, CodicentAppState, DataMessage } from 'codicent-app-sdk';
+import { useEffect, useState } from 'react';
+import { APP_CONFIG } from '../appconfig';
+import { APP_BUTTONS } from '../constants';
+
+export const ListPage: React.FC<{ state: CodicentAppState }> = ({ state }) => {
+  const { service } = state;
+  const { t } = useLocalization();
+  const [data, setData] = useState<DataMessage[]>([]);
+
+  useEffect(() => {
+    service.readDataMessages('customer2').then(setData);
+  }, [service]);
+
+  const columns = APP_CONFIG.apps[APP_BUTTONS].listDefinitions['customer2'];
+
+  return (
+    <Page title={t('Kunder')}>
+      <Content>
+        <ListView data={data} columns={columns} />
+      </Content>
+    </Page>
+  );
+};
+```
+
+---
+
+## `initCodicentApp()` configuration options
+
+**Required:**
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `API_BASE_URL` | `string` | Codicent backend URL, e.g. `"https://codicent.com/"` |
+| `APP_NAME` | `string` | Application identifier |
+
+**Common optional:**
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `APP_PREFIX` | `string` | URL/namespace prefix for this app |
+| `USER_PREFIX` | `string` | User namespace prefix (default: `"users"`) |
+| `APP_CONFIG` | `AppConfig` | Per-app config: buttons, listDefinitions, chatInstructions |
+| `TRANSLATIONS` | `object` | i18n map `{ sv: {...}, en: {...} }`. Swedish strings are used as keys. |
+| `DEFAULT_LANGUAGE` | `string` | Default language code (e.g. `"sv"`, `"en"`) |
+| `USE_REALTIME_SESSION_ENDPOINT` | `boolean` | Use secure backend session token for voice AI (default: `true`) |
+| `REALTIME_VOICE_MODEL` | `string` | Voice model: `"alloy"`, `"shimmer"`, or `"echo"` (default: `"alloy"`) |
+| `SUBSCRIPTION_NEEDED` | `boolean` | Redirect to purchase page if no active subscription |
+| `BUTTON_BORDER_RADIUS` | `string` | CSS border-radius for nav buttons |
+| `BUTTON_BACKGROUND_COLOR` | `string` | Background color for nav buttons |
+
+**Compose page GPS options:**
+
+| Key | Value | Behaviour |
+|-----|-------|-----------|
+| `COMPOSE_HIDE_LOCATION` | `"true"` | Hides GPS toggle button entirely |
+| `COMPOSE_HIDE_LOCATION` | `"false"` (default) | Shows GPS toggle; users opt-in per post |
+| `COMPOSE_AUTO_LOCATION` | `"true"` | Captures GPS automatically on page open |
+
+When a location is attached, `#gps(lat,lon)` is appended to message content — queryable via tag search and readable by AI.
+
+---
+
+## API Reference
+
+### `CodicentService`
+
+The main service class for all data and chat operations. Access it via `state.service` from `useCodicentApp()`.
+
+**Data message CRUD:**
+```ts
+createDataMessage(tag: string, data: object, codicent?: string): Promise<string>
+
+readDataMessages(
+  tag: string,
+  search?: string,
+  codicent?: string,
+  start?: number,
+  length?: number,
+  afterTimestamp?: string,
+  beforeTimestamp?: string,
+  dataFilters?: Record<string, string>
+): Promise<DataMessage[]>
+
+readOneDataMessage(id: string): Promise<DataMessage | null>
+
+updateDataMessage(id: string, data: object, codicent?: string): Promise<string>
+
+deleteDataMessage(id: string, codicent?: string): Promise<string>
+
+getSchema(tag: string, codicent?: string): Promise<object | null>
+```
+
+**Chat and messages:**
+```ts
+sendMessage(message: string, parentId?: string, codicent?: string): Promise<Message>
+chat(message: string, messageId?: string, codicent?: string): Promise<Message>
+getMessages(tags: string[], codicent?: string, length?: number): Promise<Message[]>
+getMessagesFast(tags: string[], search?: string, length?: number, publicCodicent?: string, codicent?: string, start?: number): Promise<Message[]>
+```
+
+**Files:**
+```ts
+uploadFile(filename: string, formData: FormData): Promise<string>
+getFileInfo(fileId: string): Promise<FileInfo>
+static getImageUrl(fileId: string, width: number): string
+static getFileUrl(fileId: string, extension?: string): string
+```
+
+**Auth and tokens:**
+```ts
+getToken(): string
+generateApiToken(expires?: Date, forUserNickname?: string): Promise<string>
+```
+
+---
+
+### `useCodicentApp(options)`
+
+Core hook that bootstraps app state, authentication, and the `CodicentService` instance.
+
+```ts
+const state = useCodicentApp({
+  auth0: useAuth0(),       // Required: Auth0 hook result
+  toolsConfig?: object,    // Optional: custom AI tool handlers
+  authOptions?: object,    // Optional: override auth behaviour
+});
+```
+
+Returns `CodicentAppState`:
+```ts
+{
+  service: CodicentService;   // Use for all data/chat operations
+  context: StateContext;      // Project nickname, user info
+  auth: UseAuthState;
+  voice?: RealtimeVoice;      // Voice AI connection (when active)
+  audio: AudioRecorderState;
+  stateMachine: AppStateMachine;
+  state: string;              // Current state machine state
+  nickname: string;           // Active project nickname
+  error: string;
+  isBusy: () => boolean;
+  html: string;               // AI-generated HTML output
+  setHtml: (html: string) => void;
+}
+```
+
+### 5. Use `DataMessagePicker` for tagged record lookup
+
+```tsx
+import { DataMessagePicker } from 'codicent-app-sdk';
+
+<DataMessagePicker
+  service={state.service}
+  tag="customer2"
+  placeholder="Search customers"
+  primaryKey="Company Name"
+  displayKeys={["Company Name", "City"]}
+  secondaryKeys={["Customer Number", "City"]}
+  searchKeys={["Company Name", "Customer Number", "City"]}
+  onSelect={(selection) => {
+    console.log('Selected customer', selection.id, selection.data);
+  }}
+/>
+```
+
+The picker debounces lookups through `readDataMessages(...)`, shows compact autosuggest results, and returns the raw `DataMessage` plus a normalized selection payload.
+
+---
+
+### `useLocalization()`
+
+```ts
+const { t, tAsync, getLanguageInfo } = useLocalization();
+
+t('Kunder')                       // → "Customers" (in English)
+await tAsync('Kunder')            // → API-backed translation with fallback
+getLanguageInfo()                 // → { code: 'en', name: 'English', ... }
+```
+
+Swedish strings are used as keys. Pass your translation maps via `TRANSLATIONS` in `initCodicentApp()`.
+
+---
+
+### Components
+
+#### `Page`
+Full-screen layout wrapper with optional header and footer.
+```tsx
+<Page title="Customers" hideFooter={false} audio={state.audio} voice={state.voice}>
+  <Content>...</Content>
+</Page>
+```
+
+#### `Content`
+Flex content container — use inside `Page`.
+```tsx
+<Content>
+  <ListView data={data} columns={columns} />
+</Content>
+```
+
+#### `Chat` (page)
+Full chat UI with message history, input, typing indicators, file uploads.
+```tsx
+<Chat
+  state={state}
+  title="AI Assistant"
+  codicent="my-project"     // Optional: override which project to chat with
+  welcomeMessage="Hi!"      // Optional: shown when no messages exist
+  hideFooter={false}
+/>
+```
+
+#### `ListView`
+Tabular data view with sorting, filtering, and column actions.
+```tsx
+import { ListView } from 'codicent-app-sdk';
+
+<ListView
+  data={dataMessages}
+  columns={[
+    { key: 'name', title: 'Name', filterable: true },
+    { key: ['offer_number', 'offerNumber'], title: 'Quote #', filterable: true },
+    { key: 'grand_total', title: 'Total', format: formatNumber },
+    { key: 'pdf', title: 'PDF', type: 'file' },
+  ]}
+  onSelect={(item) => navigate(`/chat?id=${item.originalMessageId}`)}
+/>
+```
+
+Column definition options:
+- `key: string | string[]` — JSON field name; array = fallback chain
+- `format: (value) => string` — display transformer
+- `filterable: true` — per-column text filter
+- `type: "file"` — renders download link
+- `type: "checkbox"` — renders checkbox
+- `action` — icon button with click handler
+
+#### `AppFrame`
+Embeds an external URL in an iframe within the page layout.
+```tsx
+<AppFrame src="https://example.com/embed" title="External view" showFooter={true} />
+```
+
+#### `Markdown`
+Renders markdown content including GFM and Mermaid diagrams.
+```tsx
+<Markdown content={message.content} />
+```
+
+#### `UploadFile`
+File upload UI with progress.
+```tsx
+<UploadFile service={state.service} codicent="my-project" />
+```
+
+---
+
+### Hooks summary
+
+| Hook | Purpose |
+|------|---------|
+| `useCodicentApp()` | Core app state, service, auth |
+| `useLocalization()` | i18n translation |
+| `useChat(service)` | Chat message state and send |
+| `useRealtimeVoiceAI(options)` | Real-time voice AI connection |
+| `useAuthState(auth0)` | Auth lifecycle and token |
+| `useTheme()` | App theme/branding |
+| `useToaster()` | Toast notification helpers |
+| `useStateWithLocalStorage()` | Persistent local state |
+| `useAudioRecorder()` | Microphone recording |
+| `useTemplateVariables()` | Template string utilities |
+| `useTools()` | AI tool handler registration |
+| `useEmbeddings()` | Vector embedding operations |
+
+---
+
+## TypeScript types
+
+```tsx
+import type {
+  CodicentAppState,
+  ButtonConfig,
+  ColumnDefinition,
+  ListDefinitions,
+  DataMessage,
+  Message,
+} from 'codicent-app-sdk';
+```
+
+**`ButtonConfig`** — navigation button with optional RBAC claims:
+```ts
+{
+  title: string;
+  url: string;          // "#/list?tag=customer2", "voice:...", "mailto:...", etc.
+  claim?: string;       // Show only if user has this claim
+  notClaim?: string;    // Hide if user has this claim
+  subtitle?: string;
+  options?: ButtonConfig[];
+}
+```
+
+**`DataMessage`** — result from `readDataMessages()`:
+```ts
+{
+  id: string;
+  originalMessageId: string;       // Stable ID across updates — use this for references/tags
+  content: string;                 // Raw: "@project #data #tag\n{json}"
+  data: Record<string, unknown>;   // Parsed JSON payload
+  tags: string[];
+  createdAt: string;
+}
+```
+
+---
+
+## Alternative: `createCodicentApp()` factory
+
+For standalone deployments where you do not control the React entry point, `createCodicentApp()` wraps the full initialization (including Auth0Provider, FluentProvider, HashRouter) and renders to a DOM element:
+
+```tsx
+import { createCodicentApp } from 'codicent-app-sdk';
+
+const app = createCodicentApp({
+  name: 'My CRM',
+  apiBaseUrl: 'https://codicent.com/',
+  auth0: { domain: '...', clientId: '...' },
+  buttons: [
+    { title: 'Customers', url: './#/list?tag=customer2' },
+    { title: 'Chat', url: './#/chat' },
+  ],
+  listDefinitions: {
+    customer2: [
+      { key: 'name', title: 'Name', filterable: true },
+      { key: 'email', title: 'Email' },
+    ],
+  },
+  chatInstructions: 'You are a helpful CRM assistant.',
+  modules: { sales: true, voice: true },
+});
+
+app.render('#root');
+// app.unmount();
+// app.getConfig();
+```
+
+The `codicentapp/` reference implementation uses `initCodicentApp()` + manual React tree setup, which gives more control over routing and layout. `createCodicentApp()` is appropriate for simpler or standalone deployments.
+
+---
+
+## Local development workflow
+
+### Build the SDK
+
+```bash
+cd codicent-app-sdk
+npm install
+npm run build        # Output: dist/cjs/, dist/esm/, dist/index.d.ts
+npm run dev          # Watch mode
+```
+
+### Test in codicentapp (file: reference)
+
+In `codicentapp/package.json`:
+```json
+"codicent-app-sdk": "file:../codicent-app-sdk"
+```
+Then:
+```bash
+cd codicentapp
+npm install
+npm run build
+```
+
+### Test with npm link
+
+```bash
+# In SDK directory
+npm link
+
+# In your app directory
+npm link codicent-app-sdk
+```
+
+To restore npm version:
+```bash
+npm uninstall codicent-app-sdk
+npm install codicent-app-sdk
+```
+
+### Build output layout
+
+```
+dist/
+  cjs/        CommonJS modules
+  esm/        ES modules
+  index.d.ts  TypeScript definitions
+```
+
+### Release
+
+```bash
+npm version patch   # or minor / major
+npm run build
+npm publish --access public
+```
+
+---
+
+## Debugging
+
+The SDK emits `codicent-log` custom events on `window`:
+
+```tsx
+window.addEventListener('codicent-log', (event: CustomEvent) => {
+  console.log(event.detail);  // { level, message, context }
+});
+```
+
+---
+
+## Related
+
+- `codicentapp/` — primary consumer; complete reference implementation
+- `codicent-api-client/` — framework-agnostic fetch-based API client (shared with web components)
+- `codicent-components/` — zero-build Web Components library using the same Codicent API
+- [Voice Upgrade Guide](VOICE_UPGRADE_GUIDE.md) — real-time voice AI setup and security
+
+---
+
+## License
+
+MIT © Codicent Inside AB