@interopio/io-assist-ng 0.1.1-beta.0 → 1.0.1

package/README.md

@@ -1,6 +1,26 @@
 # @interopio/io-assist-ng
 
-Angular library for integrating io.Intelligence AI assistance capabilities into Angular applications (Angular 20.3+).
+A full-featured AI assistant component for Angular applications. Drop a single `<io-assist>` tag into your app and get a conversational AI chat interface backed by any [AG-UI Protocol](https://docs.ag-ui.com) compatible agent server — with streaming responses, persistent threads, a prompt library, MCP tool access, working context awareness, and built-in sampling/elicitation handling.
+
+Built on [io.Connect](https://interop.io/) and [@interopio/ai-web](https://www.npmjs.com/package/@interopio/ai-web).
+
+## Features
+
+- **Conversational AI chat** — Streaming responses, markdown rendering, code highlighting
+- **Persistent conversation threads** — Thread history with resume, rename, and delete
+- **Prompt library** — Categorized pre-written prompts with favorites (persisted via IO Preferences)
+- **MCP tool access** — Built-in io.Intelligence MCP server, extensible with remote and third-party servers
+- **MCP Apps** — Custom HTML applications rendered inline in chat or in io.Connect workspace windows
+- **Sampling & elicitation** — Built-in confirmation/input UI for MCP server requests (replaceable with custom handlers)
+- **Working context** — Live data from io.Connect contexts passed to the agent with every message
+- **Theming** — Automatic dark/light mode sync with io.Connect
+
+## Prerequisites
+
+- **Angular** 20.3+
+- **Node.js** 20.19+ (< 22)
+- **npm** 10+
+- An **AG-UI Protocol compatible agent server** (e.g. [Mastra](https://mastra.ai/))
 
 ## Installation
 
@@ -8,211 +28,610 @@ Angular library for integrating io.Intelligence AI assistance capabilities into
 npm install @interopio/io-assist-ng
 ```
 
-## Prerequisites
+**Install at least one platform package** — you always need to import and pass the factory in your `connectConfig`:
+
+```bash
+# For io.Connect Browser (most common)
+npm install @interopio/browser
+
+# For io.Connect Desktop
+npm install @interopio/desktop
+
+# For both (if your app supports both environments)
+npm install @interopio/browser @interopio/desktop
+```
+
+The following packages are bundled as `dependencies` and are installed automatically:
+
+> `zod`, `ngx-remark`, `remark-gfm`, `remark-parse`, `unified`, `@interopio/ai-web`, `@interopio/ng`, `@interopio/working-context`, `@ngrx/store`, `@ngrx/effects`, `@ngrx/store-devtools`, `rxjs`
+
+The following are `peerDependencies` and must be present in your project. They are usually already installed in any Angular 20+ project:
+
+```bash
+npm install @angular/cdk @angular/common @angular/core @angular/forms @angular/platform-browser
+```
+
+---
+
+## Agent Server
+
+io.Assist requires an **AG-UI Protocol compatible agent server** to handle chat requests. The recommended way to get started is with [Mastra](https://mastra.ai/).
+
+### Quick setup with Mastra
+
+```bash
+npx create-mastra@latest
+```
+
+This scaffolds a fully working Mastra project. Follow the prompts, then start the server:
+
+```bash
+npm run dev
+```
+
+By default the server runs on `http://localhost:4111` — the same URL used in the Quickstart examples below.
+
+**Required environment variables:**
+
+```env
+# At least one LLM provider key
+OPENAI_API_KEY=your-key
+ANTHROPIC_API_KEY=your-key
+```
+
+> For full Mastra documentation — including custom agents, tools, memory, and deployment — see [mastra.ai/docs](https://mastra.ai/docs).
+
+## Quickstart
 
-- Angular 20.3 or higher
-- Node.js 20.19+ (< 22)
-- npm 10.0.0 or higher
+### New Angular project
 
-## Setup
+If you don't have an Angular project yet, create one first:
 
-### 1. Import Styles
+```bash
+npm install -g @angular/cli
+ng new my-app
+cd my-app
+npm install @interopio/io-assist-ng @interopio/browser
+```
 
-Add the library styles to your Angular application:
+> See the full Angular setup guide at [angular.dev/installation](https://angular.dev/installation).
+
+### Existing Angular project
+
+```bash
+npm install @interopio/io-assist-ng @interopio/browser
+```
+
+---
+
+### 1. Add the stylesheet
+
+```css title="src/styles.css"
+@import "@interopio/io-assist-ng/styles.css";
+```
+
+Or in `angular.json`:
 
-**Option A: In `angular.json`**
 ```json
-{
-  "projects": {
-    "your-app": {
-      "architect": {
-        "build": {
-          "options": {
-            "styles": [
-              "node_modules/@interopio/io-assist-ng/styles.css",
-              "src/styles.css"
-            ]
-          }
-        }
-      }
-    }
-  }
-}
+"styles": [
+    "node_modules/@interopio/io-assist-ng/styles.css",
+    "src/styles.css"
+]
 ```
 
-**Option B: In `styles.css`/`styles.scss`**
-```css
-@import '@interopio/io-assist-ng/styles.css';
+### 2. Configure providers
+
+```typescript title="src/app/app.config.ts"
+import { ApplicationConfig } from '@angular/core';
+import { provideIoAssist } from '@interopio/io-assist-ng';
+import IOBrowser from '@interopio/browser';
+
+export const appConfig: ApplicationConfig = {
+    providers: [
+        provideIoAssist({
+            connectConfig: {
+                browser: {
+                    factory: IOBrowser,
+                },
+            },
+            aiWebConfig: {
+                agentServer: {
+                    baseUrl: 'http://localhost:4111',
+                },
+            },
+        }),
+    ],
+};
 ```
 
-### 2. Import Components
+### 3. Add the component
 
-Import the components you need in your Angular component:
+The component requires a `[config]` input with the current user's identity. Pass a signal so the assistant can react to auth state changes:
 
-```typescript
-import { Component } from '@angular/core';
-import { IoAssist } from '@interopio/io-assist-ng';
+```typescript title="src/app/app.component.ts"
+import { Component, signal } from '@angular/core';
+import { IoAssist, IoAssistDynamicConfig } from '@interopio/io-assist-ng';
 
 @Component({
-  selector: 'app-root',
-  standalone: true,
-  imports: [IoAssist],
-  template: `
-    <io-assist [config]="assistConfig"></io-assist>
-  `
+    selector: 'app-root',
+    imports: [IoAssist],
+    template: `<io-assist [config]="dynamicConfig()" />`,
 })
 export class AppComponent {
-  assistConfig = {
-    // Your configuration here
-  };
+    readonly dynamicConfig = signal<IoAssistDynamicConfig>({
+        // id: Your access/auth token of choice
+        // name: UI name tha will be displayed
+        user: { id: 'yourIdOfChoice', name: 'Jane Doe' },
+        agentServer: {
+            headers: {
+                Authorization: `Bearer ${import.meta.env.VITE_AUTH_TOKEN}`,
+            }
+        },
+    });
 }
 ```
 
-## Configuration
-
-The `IoAssist` component accepts a configuration object via the `[config]` input:
-
-```typescript
-import { IoAssistTempConfig } from '@interopio/io-assist-ng';
+### 4. Run
 
-const assistConfig: IoAssistTempConfig = {
-  // Configuration options
-  apiEndpoint: 'https://your-api-endpoint.com',
-  theme: 'light', // or 'dark'
-  // Add other configuration options as needed
-};
+```bash
+ng serve
 ```
 
-## Components
+Open http://localhost:4200. **io.Assist is live.**
 
-### IoAssist
+---
 
-Main component for AI assistance functionality.
+### Quickstart with Login
 
-**Usage:**
-```html
-<io-assist 
-  [config]="assistConfig"
-></io-assist>
-```
+This pattern shows how to pair io.Assist with a login flow — the user's identity is only passed to the assistant after authentication.
 
-**Inputs:**
-- `config: IoAssistTempConfig` - Configuration object for the assistant
+Follow steps 1–2 from the basic quickstart, then:
 
-## Styling
+**Login service**
 
-The library uses TailwindCSS for styling. The styles are pre-compiled and included in the distribution.
+```typescript title="src/app/auth/auth.service.ts"
+import { Injectable, signal } from '@angular/core';
 
-### Custom Theming
+@Injectable({ providedIn: 'root' })
+export class AuthService {
+    private readonly _userId = signal<string>('');
+    readonly userId = this._userId.asReadonly();
 
-To customize the appearance, override CSS variables in your application:
+    login(userId: string, password: string): boolean {
+        // Replace with your own authentication logic
+        const isValid = password === 'secret';
+        if (isValid) this._userId.set(userId);
+        return isValid;
+    }
 
-```css
-:root {
-  --io-assist-primary-color: #your-color;
-  --io-assist-background: #your-background;
-  /* Add other custom variables */
+    logout(): void {
+        this._userId.set('');
+    }
 }
 ```
 
-## Examples
+**Login component**
 
-### Basic Integration
+```typescript title="src/app/login/login.component.ts"
+import { Component, inject, signal } from '@angular/core';
+import { Router } from '@angular/router';
+import { AuthService } from '../auth/auth.service';
 
-```typescript
-import { Component } from '@angular/core';
-import { IoAssist, IoAssistTempConfig } from '@interopio/io-assist-ng';
+@Component({
+    selector: 'app-login',
+    template: `
+        <input [value]="username()" (input)="username.set($any($event.target).value)" placeholder="Username" />
+        <input [value]="password()" (input)="password.set($any($event.target).value)" type="password" placeholder="Password" />
+        <button (click)="submit()">Sign in</button>
+    `,
+})
+export class LoginComponent {
+    private readonly _auth = inject(AuthService);
+    private readonly _router = inject(Router);
+
+    protected readonly username = signal('');
+    protected readonly password = signal('');
+
+    protected submit(): void {
+        const success = this._auth.login(this.username(), this.password());
+        if (success) this._router.navigate(['/assistant']);
+    }
+}
+```
+
+**Assistant component** — pass the user identity as `[config]`
+
+```typescript title="src/app/assistant/assistant.component.ts"
+import { Component, computed, inject } from '@angular/core';
+import { IoAssist, IoAssistDynamicConfig } from '@interopio/io-assist-ng';
+import { AuthService } from '../auth/auth.service';
 
 @Component({
-  selector: 'app-dashboard',
-  standalone: true,
-  imports: [IoAssist],
-  template: `
-    <div class="dashboard">
-      <h1>My Dashboard</h1>
-      <io-assist [config]="config"></io-assist>
-    </div>
-  `
+    selector: 'app-assistant',
+    imports: [IoAssist],
+    template: `<io-assist [config]="dynamicConfig()" />`,
 })
-export class DashboardComponent {
-  config: IoAssistTempConfig = {
-    apiEndpoint: 'https://api.example.com/assist',
-    theme: 'light'
-  };
+export class AssistantComponent {
+    private readonly _auth = inject(AuthService);
+
+    protected readonly dynamicConfig = computed<IoAssistDynamicConfig>(() => ({
+        user: { id: this._auth.userId() },
+    }));
 }
 ```
 
-## Browser Support
+Once the user logs in, `dynamicConfig` updates and io.Assist loads threads scoped to that user.
+
+---
+
+### What you get with the minimal config
 
-- Chrome/Edge (latest 2 versions)
-- Firefox (latest 2 versions)
-- Safari (latest 2 versions)
+With just the three required fields (`user`, `connectConfig`, `aiWebConfig.agentServer`), io.Assist provides:
 
-## Dependencies
+- Full conversational AI chat with streaming markdown responses
+- Persistent conversation threads (scoped to `user.id`)
+- Automatic agent selection (first available agent from your server)
+- Built-in sampling and elicitation UI panels (confirmation dialogs when MCP servers request them)
+- Built-in io.Intelligence MCP server connection (local mode)
+- Dark/light theme sync with io.Connect
+- Auto-injected fonts and syntax highlighting
 
-This library has peer dependencies on:
-- `@angular/core`: ^20.3.0
-- `@angular/common`: ^20.3.0
-- `@interopio/intel-web`: Latest
+No prompts, no working context, and no MCP Apps — those require additional configuration below.
+
+---
+
+## Configuration
 
-These will be automatically installed with npm 7+.
+io.Assist uses two separate configuration objects:
 
-## TypeScript Support
+- **`IoAssistStaticConfig`** — passed to `provideIoAssist()` at application bootstrap. Contains infrastructure settings that don't change at runtime.
+- **`IoAssistDynamicConfig`** — passed as `[config]` input to `<io-assist>` in your template. Contains the active user's identity, which may only be known after login.
 
-Full TypeScript support with type definitions included.
+### Static configuration (`IoAssistStaticConfig`)
+
+Passed to `provideIoAssist()`. Validated at bootstrap with Zod — throws if invalid.
+
+**Required fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `connectConfig` | `IOConnectNgSettings` | io.Connect platform settings. Must include `browser` or `desktop`. |
+| `aiWebConfig.agentServer.baseUrl` | `string` | Base URL of your AG-UI compatible agent server. |
+
+**Optional fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `aiWebConfig.agentServer.retries` | `number` | Number of retry attempts on failure. |
+| `aiWebConfig.agentServer.backoffMs` | `number` | Initial backoff delay in milliseconds. |
+| `aiWebConfig.agentServer.maxBackoffMs` | `number` | Maximum backoff delay. |
+| `aiWebConfig.agentServer.credentials` | `'omit' \| 'same-origin' \| 'include'` | Fetch credentials mode. |
+| `aiWebConfig.mcp` | `object` | MCP configuration — remote servers, MCP Apps, sampling/elicitation overrides. |
+| `defaultAgentName` | `string` | Agent to select on startup. Falls back to first available if not found. |
+| `defaultPrompts` | `IoAssistPromptCategory[]` | Categorized prompt library entries. |
+| `workingContext` | `object` | Live context collection from io.Connect. |
+
+### Dynamic configuration (`IoAssistDynamicConfig`)
+
+Passed as `[config]` input to `<io-assist>` in your template. Validated in `ngOnInit` with Zod — throws `ZodError` if invalid. Typically computed from your authentication state:
 
 ```typescript
-import type { IoAssistTempConfig, IoAssistResponse } from '@interopio/io-assist-ng';
+protected readonly dynamicConfig = computed<IoAssistDynamicConfig>(() => ({
+    user: { id: this._auth.userId(), name: this._auth.displayName() },
+}));
+```
+
+```html
+<io-assist [config]="dynamicConfig()" />
 ```
 
-## Troubleshooting
+| Field | Type | Description |
+|-------|------|-------------|
+| `user.id` | `string` | **Required.** Unique user identifier. Scopes conversation threads — each user sees only their own threads. |
+| `user.name` | `string?` | Display name shown in the chat UI and thread history. |
+| `agentServer.headers` | `Record<string, string>?` | Request headers sent with every agent call. Use for auth tokens or per-user context. |
 
-### Styles Not Loading
+---
 
-Ensure you've imported the styles in `angular.json` or your main stylesheet:
-```json
-"styles": [
-  "node_modules/@interopio/io-assist-ng/styles.css"
-]
+## Configuration Examples
+
+### Standard — with prompts and named agent
+
+```typescript title="app.config.ts"
+import { ApplicationConfig } from '@angular/core';
+import { provideIoAssist } from '@interopio/io-assist-ng';
+import IOBrowser from '@interopio/browser';
+
+export const appConfig: ApplicationConfig = {
+    providers: [
+        provideIoAssist({
+            connectConfig: {
+                browser: { factory: IOBrowser },
+            },
+            aiWebConfig: {
+                agentServer: {
+                    baseUrl: 'http://localhost:4111',
+                },
+            },
+            defaultAgentName: 'my-agent',
+            defaultPrompts: [
+                {
+                    category: 'General',
+                    prompts: [
+                        { name: 'Summarize', prompt: 'Please summarize the following content:' },
+                        { name: 'Explain', prompt: 'Please explain this in simple terms:' },
+                    ],
+                },
+                {
+                    category: 'Code',
+                    prompts: [
+                        { name: 'Review Code', prompt: 'Please review this code and suggest improvements:' },
+                        {
+                            name: 'Add Comments',
+                            prompt: 'Annotate this code with detailed comments:',
+                            iconResource: {
+                                type: 'svg',
+                                data: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="..."/></svg>',
+                            },
+                        },
+                    ],
+                },
+            ],
+        }),
+    ],
+};
 ```
 
-### Component Not Found
-
-Make sure you've imported the component in your standalone component or module:
-```typescript
-imports: [IoAssist]
+**What this adds over minimal:**
+
+- **Named agent** pre-selected at startup
+- **Prompt library** with two categories — users can browse, search, and favorite prompts
+
+### Advanced — custom handlers, MCP Apps, working context
+
+```typescript title="app.config.ts"
+import { ApplicationConfig } from '@angular/core';
+import { provideIoAssist } from '@interopio/io-assist-ng';
+import { IoAiWeb } from '@interopio/ai-web';
+import IOBrowser from '@interopio/browser';
+import { IoIntelWorkingContextFactory, IoIntelWorkingContext } from '@interopio/working-context';
+
+export const appConfig: ApplicationConfig = {
+    providers: [
+        provideIoAssist({
+            connectConfig: {
+                browser: { factory: IOBrowser },
+            },
+            aiWebConfig: {
+                agentServer: {
+                    baseUrl: 'http://localhost:4111',
+                },
+                mcp: {
+                    // Custom sampling handler — replaces the built-in confirmation panel
+                    clientsConfig: {
+                        enforceStrictCapabilities: false,
+                        capabilities: {
+                            sampling: {
+                                handler: async (
+                                    serverId: string,
+                                    params: IoAiWeb.SamplingRequestParams,
+                                ): Promise<IoAiWeb.SamplingSuccessResponse> => {
+                                    // Your custom logic — show your own UI, call your own APIs, etc.
+                                    return {
+                                        model: 'gpt-4',
+                                        role: 'assistant',
+                                        content: { type: 'text', text: 'Custom sampling response' },
+                                        stopReason: 'endTurn',
+                                    };
+                                },
+                            },
+                            elicitation: {
+                                handler: async (
+                                    serverId: string,
+                                    params: IoAiWeb.ElicitationRequestParams,
+                                ): Promise<IoAiWeb.ElicitationResponse> => {
+                                    // Your custom logic — build a form, collect user input, etc.
+                                    return { action: 'accept', content: { confirmed: true } };
+                                },
+                            },
+                            // Required for MCP Apps
+                            extensions: {
+                                'io.modelcontextprotocol/ui': {
+                                    mimeTypes: ['text/html;profile=mcp-app'],
+                                },
+                            },
+                        },
+                    },
+                    // MCP Apps — interactive UI panels in chat or workspace windows
+                    mcpApps: {
+                        sandboxProxyUrl: 'http://localhost:6565/index.html',
+                        displayMode: 'workspace', // or 'inline'
+                    },
+                    // Remote MCP servers
+                    ioIntel: {
+                        remote: {
+                            streamableHttp: {
+                                url: 'http://localhost:8989/mcp',
+                                name: 'remote-io-mcp-server',
+                            },
+                        },
+                    },
+                    remoteServers: [
+                        {
+                            streamableHttp: {
+                                url: 'http://localhost:8081/mcp',
+                                name: 'third-party-server',
+                            },
+                        },
+                    ],
+                },
+            },
+            defaultAgentName: 'my-agent',
+            defaultPrompts: [
+                {
+                    category: 'General',
+                    prompts: [
+                        { name: 'Summarize', prompt: 'Please summarize the following content:' },
+                    ],
+                },
+            ],
+            workingContext: {
+                factory: IoIntelWorkingContextFactory,
+                config: {
+                    schema: {
+                        userId: {
+                            type: 'string',
+                            description: "Current user's identifier",
+                            source: {
+                                context: {
+                                    location: { global: { names: ['UserSession'] } },
+                                    path: 'user.id',
+                                },
+                            },
+                        },
+                        selectedClient: {
+                            type: 'string',
+                            description: 'Client currently selected in the workspace',
+                            source: {
+                                context: {
+                                    location: { workspace: {} },
+                                    path: 'client.name',
+                                },
+                            },
+                        },
+                    },
+                } as IoIntelWorkingContext.Config,
+            },
+        }),
+    ],
+};
 ```
 
-### Type Errors
+**What this adds over standard:**
 
-Ensure your TypeScript version is 5.0 or higher and `strict` mode is enabled in `tsconfig.json`.
+- **Custom sampling handler** — replaces the built-in confirmation panel. When an MCP server makes a sampling request, your handler runs instead.
+- **Custom elicitation handler** — replaces the built-in elicitation panel. When an MCP server requests user input, your handler runs instead.
+- **MCP Apps** — interactive HTML panels that MCP tools can render inline in chat or in io.Connect workspace windows. Requires both `mcpApps` config and the `io.modelcontextprotocol/ui` extension.
+- **Remote MCP servers** — switch io.Intelligence MCP to a remote endpoint and/or add third-party MCP servers.
+- **Working context** — io.Assist reads live data from io.Connect contexts and passes it to the agent with every message.
 
-## Development
+> **Component usage:** In all examples above, pair `provideIoAssist()` with `<io-assist [config]="dynamicConfig()" />` in your template. Refer to the [Quickstart with Login](#quickstart-with-login) section for a full component example.
 
-This library is built with:
-- Angular 20.3
-- TailwindCSS 4.1
-- TypeScript 5.x
+---
 
-## Support
+## MCP Apps
 
-For issues, questions, or contributions, please visit:
-- GitHub: [io.Intelligence JS Repository]
-- Documentation: [Coming Soon]
-- Issues: [GitHub Issues]
+MCP Apps are fully interactive UI applications that MCP tools can display directly inside the assistant. Instead of returning only text, a tool can ship a complete HTML application that the user interacts with in context.
 
-## License
+**Requirements** — two config sections must both be present:
+
+1. **`mcpApps`** — enables the MCP Apps runtime:
+   ```typescript
+   mcpApps: {
+       sandboxProxyUrl: 'http://localhost:6565/index.html',
+       displayMode: 'workspace', // 'workspace' | 'inline' (optional, auto-detects if omitted)
+   },
+   ```
+
+2. **`extensions`** — tells MCP servers that this client supports UI:
+   ```typescript
+   capabilities: {
+       extensions: {
+           'io.modelcontextprotocol/ui': {
+               mimeTypes: ['text/html;profile=mcp-app'],
+           },
+       },
+   },
+   ```
+
+Without both, MCP servers will not expose UI metadata on tool definitions and no apps will be created.
+
+**Display modes:**
+
+| Mode | Behavior |
+|------|----------|
+| `'inline'` | App renders inside the chat message flow |
+| `'workspace'` | App opens in a separate io.Connect workspace window (falls back to inline if workspaces unavailable) |
+
+**Sandbox proxy** — MCP Apps run inside a sandboxed iframe. The `sandboxProxyUrl` points to an HTML file that bridges communication between the host and the app. This proxy page must be served alongside your application.
+
+---
+
+## Sampling & Elicitation
+
+When an MCP server sends a sampling or elicitation request:
+
+| Scenario | Behavior |
+|----------|----------|
+| **No custom handler** | io.Assist shows a built-in confirmation panel (uses io.Connect modal if available, otherwise an overlay panel) |
+| **Custom handler provided** | Your handler function runs instead — full control over UI and response |
+| **Request from background thread** | Automatically rejected (user must be on the active thread) |
+
+**Sampling** — the MCP server asks the client to generate a model response. The built-in handler shows a "Permission to proceed" dialog. On accept, it calls your agent server and returns the result.
 
-ISC License
+**Elicitation** — the MCP server asks the client to collect user input via a form schema. The built-in handler presents accept/decline options.
 
-## Changelog
+See the advanced configuration example above for custom handler signatures.
 
-### 0.0.0 (Initial Release)
-- Initial release with core `IoAssist` component
-- TailwindCSS styling support
-- TypeScript type definitions
-- Angular 20.3 compatibility
+---
+
+## Public API
+
+```typescript
+import { IoAssist, provideIoAssist } from '@interopio/io-assist-ng';
+import type {
+    IoAssistStaticConfig,
+    IoAssistDynamicConfig,
+    AIWebConfig,
+    IoAssistUserConfig,
+    IO_ASSIST_CONFIG,
+    IO_ASSIST_DYNAMIC_CONFIG,
+    IoAssistPrompt,
+    IoAssistPromptCategory,
+    IconResource,
+    IconType,
+} from '@interopio/io-assist-ng';
+```
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `IoAssist` | Component | The `<io-assist>` root component. Requires `[config]` input. |
+| `provideIoAssist(config)` | Function | Registers all providers — call once in `app.config.ts` |
+| `IoAssistStaticConfig` | Type | Static configuration shape passed to `provideIoAssist()` |
+| `IoAssistDynamicConfig` | Type | Runtime configuration shape passed as `[config]` to `<io-assist>` |
+| `AIWebConfig` | Type | Agent server + MCP config shape |
+| `IoAssistUserConfig` | Type | `{ id: string; name?: string }` |
+| `IO_ASSIST_CONFIG` | InjectionToken | DI token for the validated static config |
+| `IO_ASSIST_DYNAMIC_CONFIG` | InjectionToken | DI token for the `WritableSignal<IoAssistDynamicConfig>` (internal use) |
+| `IoAssistPrompt` | Type | Single prompt definition |
+| `IoAssistPromptCategory` | Type | Category with array of prompts |
+| `IconResource` | Type | `{ type: IconType; data: string }` |
+| `IconType` | Type | `'svg' \| 'url' \| 'data-url'` |
+
+---
+
+## Prompt Icons
+
+Each prompt can have an optional `iconResource`. Three formats are supported:
+
+| Type | Example | Notes |
+|------|---------|-------|
+| `'svg'` | `'<svg xmlns="..." viewBox="0 0 24 24">...</svg>'` | Auto-sanitized: `fill`, `width`, `height` stripped; hardcoded colors → `currentColor` |
+| `'url'` | `'/icons/summarize.svg'` | Must be an absolute URL or absolute path from document root |
+| `'data-url'` | `'data:image/svg+xml;base64,...'` | Base64-encoded SVG, PNG, or JPEG |
+
+Prompts without an icon show a default icon.
 
 ---
 
-**Note:** This library is currently in development. API and features may change before the stable 1.0.0 release.
+## Related Packages
+
+- [@interopio/ai-web](https://www.npmjs.com/package/@interopio/ai-web) — Core intelligence library
+- [@interopio/ng](https://www.npmjs.com/package/@interopio/ng) — io.Connect Angular integration
+- [@interopio/browser](https://www.npmjs.com/package/@interopio/browser) — io.Connect Browser platform
+- [@interopio/desktop](https://www.npmjs.com/package/@interopio/desktop) — io.Connect Desktop platform
+- [@interopio/working-context](https://www.npmjs.com/package/@interopio/working-context) — Working context collection
+
+## License
+
+[MIT](./LICENSE)