@rimori/client 2.0.0 → 2.1.1

package/README.md

@@ -1,23 +1,35 @@
 # Rimori Client Package
 
-The **@rimori/client** package is a comprehensive React library that enables plugins to seamlessly integrate with the Rimori learning platform. It provides database access, AI/LLM integration, inter-plugin communication, community features, and pre-built UI components.
+The `@rimori/client` package is the framework-agnostic runtime and CLI that powers Rimori plugins. Use it inside plugin iframes, workers, and build scripts to access Rimori platform features such as database access, AI, shared content, and the event bus. All React-specific helpers and UI components are now published separately in `@rimori/react-client`.
 
 ## Table of Contents
-
+- [Overview](#overview)
 - [Installation](#installation)
-- [Quick Start Plugin Development](#quick-start-plugin-development)
-- [Releasing Your Plugin to Rimori](#releasing-your-plugin-to-rimori)
+- [Relationship to @rimori/react-client](#relationship-to-rimori-react-client)
 - [Quick Start](#quick-start)
-- [Core API - usePlugin Hook](#core-api---useplugin-hook)
-- [Database Integration](#database-integration)
-- [LLM Integration](#llm-integration)
-- [Event System](#event-system)
-- [Community Features](#community-features)
-- [Components](#components)
-- [Hooks](#hooks)
+- [CLI Tooling](#cli-tooling)
+- [Runtime API](#runtime-api)
+  - [Bootstrapping](#bootstrapping)
+  - [Plugin Interface](#plugin-interface)
+  - [Database Access](#database-access)
+  - [AI & Voice](#ai--voice)
+  - [Event Bus & Actions](#event-bus--actions)
+  - [Community Content](#community-content)
+  - [Workers & Standalone Development](#workers--standalone-development)
 - [Utilities](#utilities)
 - [TypeScript Support](#typescript-support)
-- [Examples](#examples)
+- [Example Integration](#example-integration)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+`@rimori/client` gives you direct, typed access to the Rimori platform:
+- Bootstrap authenticated plugin sessions and fetch Rimori context.
+- Run Supabase queries against your plugin's dedicated schema.
+- Call AI services for text, structured data, or voice.
+- Communicate with Rimori and other plugins through the event bus.
+- Share content with the community and emit accomplishments.
+- Ship and upgrade plugins by using the bundled CLI.
 
 ## Installation
 
@@ -27,1190 +39,196 @@ npm install @rimori/client
 yarn add @rimori/client
 ```
 
-## Quick Start Plugin Development
-
-The Rimori Client package includes powerful CLI tools to eliminate the tedious setup process and get you building your plugin fast. The initialization script handles authentication, plugin registration, environment setup, and all necessary boilerplate configuration.
-
-### Prerequisites
-
-Before initializing your plugin, ensure you have:
-
-1. **Node.js and yarn/npm installed**
-2. **A Rimori account** - You'll need to login during initialization to receive your access token
+## Relationship to @rimori/react-client
 
-### Initializing a New Plugin
-
-Open Lovable and vibe code the look of your plugin.
-
-Then connect it to your Github account.
-
-Clone the git repository:
+If you are building a React-based plugin UI, install the companion package:
 
 ```bash
-git clone ...
-cd my-awesome-plugin
-
-# Initialize with Rimori Client (this handles everything!)
-npx @rimori/client rimori-init
+npm install @rimori/react-client
 ```
 
-### What the Init Script Does
-
-The `rimori-init` command automates the entire plugin setup process:
-
-1. **🔐 Authentication**: Prompts for your Rimori credentials and authenticates with the platform
-2. **🚀 Plugin Registration**: Automatically registers your plugin and generates a unique plugin ID
-3. **🔑 Access Token**: Provides you with an access token for future plugin releases
-4. **📦 Package Configuration**: Updates `package.json` with plugin-specific settings
-5. **⚙️ Environment Setup**: Creates `.env` files with your credentials
-6. **📁 File Structure**: Copies all necessary boilerplate files and examples
-7. **🎨 Configuration**: Sets up Vite, Tailwind, and router configurations
-8. **📖 Documentation**: Provides example documentation and getting started guides
+`@rimori/react-client` wraps this core runtime with React context, hooks, and prebuilt UI components. Use it for UI concerns (`PluginProvider`, `useRimori`, `useChat`, widgets). Keep importing non-UI functionality such as `RimoriClient`, `StandaloneClient`, `setupWorker`, or the CLI directly from `@rimori/client`.
 
-### Upgrade Mode
+## Quick Start
 
-If you need to upgrade an existing plugin's configuration without changing the plugin ID:
+Instantiate the client once in your application entry point and reuse it everywhere:
 
-```bash
-yarn rimori-init --upgrade
-```
+```ts
+import { RimoriClient } from "@rimori/client";
 
-### Development Setup
+async function bootstrap() {
+  const client = await RimoriClient.getInstance("your-plugin-id");
 
-After initialization, start developing immediately:
+  const user = client.plugin.getUserInfo();
+  const { data } = await client.db
+    .from("notes")
+    .select("*")
+    .eq("user_id", user.profile_id);
 
-```bash
-# Start development server
-yarn dev
+  console.log("Loaded notes", data);
+}
 
-# Your plugin will be available at:
-# http://localhost:3000 (or your chosen port)
+bootstrap().catch(console.error);
 ```
 
-Rimori client comes pre-configured with:
+The instance exposes high-level controllers grouped under properties such as `plugin`, `db`, `ai`, `event`, `community`, `runtime`, and `navigation`.
 
-- ✅ **Hot reload** for instant development feedback
-- ✅ **TypeScript support** with full type safety
-- ✅ **TailwindCSS** for modern styling
-- ✅ **React Router** for navigation
-- ✅ **Example components** and documentation
+## CLI Tooling
 
-## Releasing Your Plugin to Rimori
+Two CLI commands ship with the package (also available through `npx`):
 
-Publishing your plugin to the Rimori platform is streamlined through the built-in `rimori-release` CLI tool. The release process handles database updates, file uploads, and plugin activation automatically.
+### `rimori-init`
 
-### Prerequisites
+- Authenticates against Rimori using your developer credentials.
+- Registers the plugin and writes the plugin ID (`r_id`) into `package.json`.
+- Provisions environment files, Vite/Tailwind scaffolding, worker configuration, and sample assets.
 
-1. **Plugin must be initialized** - Use `rimori-init` first to set up your plugin
-2. **Build your plugin** - Ensure your plugin is built and the output is in the `dist/` directory
-3. **Environment configured** - Your `.env` file should contain `RIMORI_TOKEN` (set during initialization)
-
-### Quick Release (Recommended)
-
-During plugin initialization, convenient release scripts are automatically added to your `package.json`. These scripts handle building and releasing in one command:
+Usage:
 
 ```bash
-# Quick release commands (build + release)
-yarn release:alpha     # Build and release to alpha channel
-yarn release:beta      # Build and release to beta channel
-yarn release:stable    # Build and release to stable channel
+npx @rimori/client rimori-init
+npx @rimori/client rimori-init --upgrade   # refresh config without changing the plugin ID
 ```
 
-### Manual Release Process
+### `rimori-release`
 
-If you prefer more control or need to understand the underlying process, you can use the `rimori-release` command directly:
+- Builds (optionally) and uploads the plugin bundle to Rimori.
+- Updates release metadata, database migrations, and activates the chosen channel (`alpha`, `beta`, `stable`).
+
+Usage:
 
 ```bash
-# Build your plugin first
 yarn build
-
-# Then release to different channels
-yarn rimori-release alpha    # For alpha testing
-yarn rimori-release beta     # For beta releases
-yarn rimori-release stable   # For production releases
+npx @rimori/client rimori-release alpha
 ```
 
-The plugin version is automatically read from your `package.json`, and the plugin ID is retrieved from the `r_id` field (set during initialization).
-
-### What the Release Script Does
-
-The `rimori-release` command performs a complete release workflow:
-
-1. **📋 Configuration Upload**: Sends plugin metadata and configuration to the platform
-2. **🗄️ Database Updates**: Updates plugin information and release records
-3. **📁 File Upload**: Uploads all files from your `dist/` directory to the platform
-4. **🚀 Plugin Activation**: Activates the new version on the specified release channel
-
-### Release Channels
-
-- **`alpha`**: Early development releases for internal testing
-- **`beta`**: Pre-release versions for beta testers
-- **`stable`**: Production-ready releases for all users
+During initialization, convenience scripts (`release:alpha`, `release:beta`, `release:stable`) are added to your project automatically.
 
-### Automatic Configuration
+## Runtime API
 
-During plugin initialization, the following are automatically configured:
+### Bootstrapping
 
-- `RIMORI_TOKEN`: Your authentication token (stored in `.env`)
-- `r_id`: Your unique plugin ID (stored in `package.json`)
-- **Release scripts**: `yarn release:alpha`, `yarn release:beta`, `yarn release:stable`
-- **Build configuration**: TypeScript checking, Vite setup, and worker builds
-
-### Troubleshooting
-
-If you encounter release issues:
-
-1. **Missing token**: Ensure `RIMORI_TOKEN` is in your `.env` file
-2. **No plugin ID**: Verify `r_id` exists in your `package.json`
-3. **Build errors**: Run `yarn build` successfully before releasing
-4. **Authentication**: Your token may have expired - re-run `rimori-init` if needed
-
-#### Worker Process Errors
-
-If you encounter errors like:
-
-```
-ReferenceError: process is not defined
-```
-
-**Root Cause**: Your plugin is importing a library that tries to access `process` or `process.env` in the worker context. Web workers don't have access to Node.js globals like `process`.
-
-**Debugging Steps**:
-
-1. **Check your imports**: Look through the files used in the worker which might import libraries that might access `process.env`:
-   - React libraries (React Router, React Query, etc.)
-   - UI component libraries (Material-UI, Ant Design, etc.)
-   - Utility libraries that check for environment variables
-
-2. **Verify Rimori Client imports**: Ensure you're importing from `@rimori/client/core` and not from `@rimori/client`:
-
-   ```typescript
-   // ✅ Correct - import from rimori client
-   import { RimoriClient } from '@rimori/client/core';
-
-   // ❌ Incorrect - direct imports that might access process.env directly or through their dependencies
-   import { Avatar } from '@rimori/client';
-   import { useQuery } from '@tanstack/react-query';
-   ```
-
-3. **Check your dependencies**: Look at your `package.json` for libraries that might be bundled into the worker:
-   - UI frameworks (React, Vue, etc.)
-   - State management libraries
-   - Routing libraries
-   - Any library that checks `process.env.NODE_ENV`
-
-**Solution**: Use only `@rimori/client/core` exports in your worker code. The Rimori client provides all necessary functionality without requiring Node.js globals.
-
-**Note**: The worker bundling order is determined by the build system and cannot be controlled. Libraries that access `process.env` will always cause this error in the worker context.
-
-````
-
-## Core API - usePlugin Hook
-
-The `useRimori()` hook is the main interface for accessing Rimori platform features:
-
-```typescript
-import { useRimori } from "@rimori/client";
-
-const MyComponent = () => {
-  const client = useRimori();
-
-  // Access all client features
-  const { db, llm, event, community, plugin } = client;
-
-  return <div>My Plugin Content</div>;
-};
-````
+- `RimoriClient.getInstance(pluginId)` – connect the sandboxed iframe to Rimori.
+- `StandaloneClient` – authenticate when developing a plugin outside Rimori.
+- `setupWorker()` – register worker scripts that need the Rimori runtime.
 
 ### Plugin Interface
 
-```typescript
-const { plugin } = useRimori();
+Access metadata and settings through `client.plugin`:
 
-// Plugin information and settings
-plugin.pluginId: string                              // Current plugin ID
-plugin.getSettings<T>(defaultSettings: T): Promise<T>  // Get plugin settings
-plugin.setSettings(settings: any): Promise<void>    // Update plugin settings
-plugin.getInstalled(): Promise<Plugin[]>            // Get all installed plugins
-plugin.getUserInfo(): Promise<UserInfo>             // Get current user information
-```
+- `plugin.pluginId` – current plugin identifier.
+- `plugin.getSettings(defaults)` / `plugin.setSettings(settings)` – persist configuration.
+- `plugin.getPluginInfo()` – read active/installed plugin information.
+- `plugin.getUserInfo()` – obtain user profile details (language, name, guild, etc.).
+- `plugin.getTranslator()` – lazily initialize the translator for manual i18n.
 
-**Example: Managing Flashcard Plugin Settings**
+### Database Access
 
-```typescript
-interface FlashcardSettings {
-  dailyGoal: number;
-  reviewInterval: 'easy' | 'medium' | 'hard';
-  showAnswerDelay: number;
-  enableAudioPronunciation: boolean;
-  difficultyAlgorithm: 'spaced-repetition' | 'random' | 'progressive';
-}
+`client.db` wraps the Supabase client that is scoped to your plugin tables:
 
-const FlashcardSettingsComponent = () => {
-  const { plugin } = useRimori();
-  const [settings, setSettings] = useState<FlashcardSettings>();
-
-  useEffect(() => {
-    const loadSettings = async () => {
-      const defaultSettings: FlashcardSettings = {
-        dailyGoal: 20,
-        reviewInterval: 'medium',
-        showAnswerDelay: 3,
-        enableAudioPronunciation: true,
-        difficultyAlgorithm: 'spaced-repetition'
-      };
-
-      const currentSettings = await plugin.getSettings(defaultSettings);
-      setSettings(currentSettings);
-    };
-
-    loadSettings();
-  }, []);
-
-  const updateSettings = async (newSettings: Partial<FlashcardSettings>) => {
-    const updated = { ...settings, ...newSettings };
-    await plugin.setSettings(updated);
-    setSettings(updated);
-  };
-
-  return (
-    <div className="flashcard-settings">
-      <label>
-        Daily Goal: {settings?.dailyGoal} cards
-        <input
-          type="range"
-          min="5"
-          max="100"
-          value={settings?.dailyGoal}
-          onChange={(e) => updateSettings({ dailyGoal: parseInt(e.target.value) })}
-        />
-      </label>
-
-      <label>
-        Review Interval:
-        <select
-          value={settings?.reviewInterval}
-          onChange={(e) => updateSettings({ reviewInterval: e.target.value as any })}
-        >
-          <option value="easy">Easy (longer intervals)</option>
-          <option value="medium">Medium</option>
-          <option value="hard">Hard (shorter intervals)</option>
-        </select>
-      </label>
-
-      <label>
-        <input
-          type="checkbox"
-          checked={settings?.enableAudioPronunciation}
-          onChange={(e) => updateSettings({ enableAudioPronunciation: e.target.checked })}
-        />
-        Enable Audio Pronunciation
-      </label>
-    </div>
-  );
-};
-```
-
-## Database Integration
-
-Access your plugin's dedicated database tables with full TypeScript support:
-
-```typescript
-const { db } = useRimori();
-
-// Database interface
-db.from(tableName)                    // Query builder for tables/views - supports ALL Supabase operations
-db.storage                           // File storage access
-db.tablePrefix: string               // Your plugin's table prefix
-db.getTableName(table: string): string  // Get full table name with prefix
-```
-
-The `db.from()` method provides access to the complete Supabase PostgREST API, supporting all database operations including:
-
-- **CRUD Operations**: `insert()`, `select()`, `update()`, `delete()`, `upsert()`
-- **Filtering**: `eq()`, `neq()`, `gt()`, `gte()`, `lt()`, `lte()`, `like()`, `ilike()`, `is()`, `in()`, `contains()`, `containedBy()`, `rangeLt()`, `rangeGt()`, `rangeGte()`, `rangeLte()`, `rangeAdjacent()`, `overlaps()`, `textSearch()`, `match()`, `not()`, `or()`, `filter()`
-- **Modifiers**: `order()`, `limit()`, `range()`, `single()`, `maybe_single()`, `csv()`, `geojson()`, `explain()`
-- **Aggregations**: `count()`, `sum()`, `avg()`, `min()`, `max()`
-- **Advanced Features**: Row Level Security (RLS), real-time subscriptions, stored procedures, and custom functions
-
-All operations automatically use your plugin's table prefix for security and isolation.
-
-**Column deprecation and removal (short policy)**
-
-- To remove a column, use a two-step process:
-  1. Mark the column with `deprecated: true` in your `rimori/db.config.ts` and release. The backend renames the column to `<name>_old`.
-  2. In a subsequent release, remove the column from the config. The backend drops `<name>_old`.
-
-**Example: CRUD Operations**
-
-```typescript
-interface StudySession {
-  id?: string;
-  user_id: string;
-  topic: string;
-  duration: number;
-  completed_at: string;
-}
-
-const StudySessionManager = () => {
-  const { db } = useRimori();
-
-  // Create a new study session
-  const createSession = async (session: Omit<StudySession, 'id'>) => {
-    const { data, error } = await db
-      .from('study_sessions')  // Automatically prefixed
-      .insert(session)
-      .select()
-      .single();
-
-    if (error) throw error;
-    return data;
-  };
-
-  // Get user's study sessions
-  const getUserSessions = async (userId: string) => {
-    const { data, error } = await db
-      .from('study_sessions')
-      .select('*')
-      .eq('user_id', userId)
-      .order('completed_at', { ascending: false });
-
-    if (error) throw error;
-    return data;
-  };
-
-  // Update session
-  const updateSession = async (id: string, updates: Partial<StudySession>) => {
-    const { data, error } = await db
-      .from('study_sessions')
-      .update(updates)
-      .eq('id', id)
-      .select()
-      .single();
-
-    if (error) throw error;
-    return data;
-  };
-
-  return (
-    <div>
-      {/* Your component UI */}
-    </div>
-  );
-};
-```
-
-**File Storage Example**
-
-```typescript
-const FileManager = () => {
-  const { db } = useRimori();
-
-  const uploadFile = async (file: File) => {
-    const fileName = `uploads/${Date.now()}-${file.name}`;
-
-    const { data, error } = await db.storage
-      .from('plugin-files')
-      .upload(fileName, file);
-
-    if (error) throw error;
-    return data;
-  };
-
-  const downloadFile = async (filePath: string) => {
-    const { data, error } = await db.storage
-      .from('plugin-files')
-      .download(filePath);
-
-    if (error) throw error;
-    return data;
-  };
-
-  return <div>File Manager UI</div>;
-};
+```ts
+const { data, error } = await client.db
+  .from("study_sessions")
+  .select("*")
+  .order("completed_at", { ascending: false });
 ```
 
-## LLM Integration
-
-Powerful AI/Language Model capabilities built-in:
-
-```typescript
-const { llm } = useRimori();
-
-// Text generation
-llm.getText(messages: Message[], tools?: Tool[]): Promise<string>
-
-// Streaming text generation
-llm.getSteamedText(messages: Message[], onMessage: OnLLMResponse, tools?: Tool[]): void
+Helpers:
 
-// Structured object generation
-llm.getObject(request: ObjectRequest): Promise<any>
+- `db.tablePrefix` – plugin-specific prefix applied to all tables.
+- `db.getTableName("notes")` – resolve the fully qualified table name.
+- Supabase query builder methods (`insert`, `update`, `delete`, `eq`, `limit`, etc.) are available out of the box.
 
-// Text-to-speech
-llm.getVoice(text: string, voice?: string, speed?: number, language?: string): Promise<Blob>
+### AI & Voice
 
-// Speech-to-text
-llm.getTextFromVoice(file: Blob): Promise<string>
-```
-
-**Example: AI Chat Assistant**
+The `client.ai` controller surfaces AI capabilities:
 
-```typescript
-import { useChat } from "@rimori/client";
+- `getText(messages, tools?)` – chat completion (string result).
+- `getSteamedText(messages, onMessage, tools?)` – streamed responses.
+- `getObject(request)` – structured JSON generation.
+- `getVoice(text, voice?, speed?, language?)` – text-to-speech (returns `Blob`).
+- `getTextFromVoice(file)` – speech-to-text transcription.
 
-const ChatAssistant = () => {
-  const { messages, append, isLoading } = useChat();
-  const [input, setInput] = useState('');
+Use `client.runtime.fetchBackend` for authenticated calls to Rimori-managed HTTP endpoints.
 
-  const sendMessage = () => {
-    if (!input.trim()) return;
+### Event Bus & Actions
 
-    append([{
-      role: 'user',
-      content: input
-    }]);
+`client.event` lets you collaborate with Rimori and other plugins:
 
-    setInput('');
-  };
+- `emit(topic, data?)`, `request(topic, data?)` – publish and request data.
+- `on(topic, handler)` / `once(topic, handler)` / `respond(topic, handler)` – subscribe and reply (each call returns an object with `off()` for cleanup).
+- `emitAccomplishment(payload)` / `onAccomplishment(topic, handler)` – report learning milestones.
+- `emitSidebarAction(pluginId, actionKey, text?)` – trigger sidebar plugins.
+- `onMainPanelAction(handler, actionsToListen?)` – react to dashboard actions.
+- `client.navigation.toDashboard()` – navigate the user back to Rimori.
 
-  return (
-    <div className="chat-container">
-      <div className="messages">
-        {messages.map((message, index) => (
-          <div key={index} className={`message ${message.role}`}>
-            {message.content}
-          </div>
-        ))}
-        {isLoading && <div className="message assistant">Thinking...</div>}
-      </div>
-
-      <div className="input-area">
-        <input
-          value={input}
-          onChange={(e) => setInput(e.target.value)}
-          onKeyPress={(e) => e.key === 'Enter' && sendMessage()}
-          placeholder="Ask anything..."
-        />
-        <button onClick={sendMessage} disabled={isLoading}>
-          Send
-        </button>
-      </div>
-    </div>
-  );
-};
-```
-
-**Example: Structured Data Generation**
-
-```typescript
-const QuizGenerator = () => {
-  const { llm } = useRimori();
-
-  const generateQuiz = async (topic: string) => {
-    const quiz = await llm.getObject({
-      schema: {
-        type: "object",
-        properties: {
-          title: { type: "string" },
-          questions: {
-            type: "array",
-            items: {
-              type: "object",
-              properties: {
-                question: { type: "string" },
-                options: { type: "array", items: { type: "string" } },
-                correctAnswer: { type: "number" },
-                explanation: { type: "string" }
-              }
-            }
-          }
-        }
-      },
-      prompt: `Create a quiz about ${topic} with 5 multiple choice questions.`
-    });
-
-    return quiz;
-  };
-
-  return <div>Quiz Generator UI</div>;
-};
-```
+### Community Content
 
-**Example: Voice Integration**
+`client.community.sharedContent` exposes helpers to share or consume content:
 
-```typescript
-const VoiceAssistant = () => {
-  const { llm } = useRimori();
+- `get(contentType, id)`
+- `getList(contentType, filter?, limit?)`
+- `getNew(contentType, instructions, filter?, options?)`
+- `create(payload)`
+- `update(id, payload)`
+- `remove(id)`
+- `complete(contentType, assignmentId)`
 
-  const speakText = async (text: string) => {
-    const audioBlob = await llm.getVoice(text, "alloy", 1, "en");
-    const audioUrl = URL.createObjectURL(audioBlob);
-    const audio = new Audio(audioUrl);
-    audio.play();
-  };
+The controller handles topic generation, metadata, and completion tracking automatically.
 
-  const transcribeAudio = async (audioFile: File) => {
-    const transcript = await llm.getTextFromVoice(audioFile);
-    return transcript;
-  };
+### Workers & Standalone Development
 
-  return <div>Voice Assistant UI</div>;
-};
-```
-
-## Event System
-
-Robust inter-plugin communication and platform integration:
-
-```typescript
-const { event } = useRimori();
-
-// Event methods
-event.emit(topic: string, data?: any, eventId?: number): void
-event.request<T>(topic: string, data?: any): Promise<EventBusMessage<T>>
-event.on<T>(topic: string | string[], callback: EventHandler<T>): string[]
-event.once<T>(topic: string, callback: EventHandler<T>): void
-event.respond<T>(topic: string, data: EventPayload | Function): void
-
-// Accomplishments
-event.emitAccomplishment(payload: AccomplishmentPayload): void
-event.onAccomplishment(topic: string, callback: Function): void
-
-// Sidebar actions
-event.emitSidebarAction(pluginId: string, actionKey: string, text?: string): void
-```
-
-**Example: Plugin Communication**
-
-```typescript
-const PluginCommunicator = () => {
-  const { event } = useRimori();
-
-  useEffect(() => {
-    // Listen for messages from other plugins
-    const unsubscribe = event.on('flashcards.newCard', (message) => {
-      console.log('New flashcard created:', message.data);
-    });
-
-    // Listen for global events
-    event.on('global.userProgress', (message) => {
-      console.log('User progress updated:', message.data);
-    });
-
-    return () => {
-      // Cleanup subscriptions
-      unsubscribe.forEach(id => event.off(id));
-    };
-  }, []);
-
-  const shareData = () => {
-    // Emit data to other plugins
-    event.emit('studyplan.dataUpdate', {
-      type: 'session_completed',
-      sessionId: '123',
-      score: 85
-    });
-  };
-
-  const requestData = async () => {
-    // Request data from another plugin
-    const response = await event.request('flashcards.getStats', {
-      timeframe: 'week'
-    });
-
-    console.log('Flashcard stats:', response.data);
-  };
-
-  return (
-    <div>
-      <button onClick={shareData}>Share Progress</button>
-      <button onClick={requestData}>Get Flashcard Stats</button>
-    </div>
-  );
-};
-```
-
-**Example: Accomplishment System**
-
-```typescript
-const AccomplishmentTracker = () => {
-  const { event } = useRimori();
-
-  const trackAccomplishment = () => {
-    event.emitAccomplishment({
-      type: 'study_milestone',
-      title: 'Study Streak',
-      description: 'Completed 7 days of studying',
-      points: 100,
-      metadata: {
-        streakDays: 7,
-        subject: 'Spanish'
-      }
-    });
-  };
-
-  useEffect(() => {
-    // Listen for accomplishments from this plugin
-    event.onAccomplishment('study_milestone', (accomplishment) => {
-      console.log('New accomplishment:', accomplishment);
-      // Show notification, update UI, etc.
-    });
-  }, []);
-
-  return <div>Accomplishment Tracker UI</div>;
-};
-```
-
-**Example: Sidebar Integration**
-
-```typescript
-const SidebarIntegration = () => {
-  const { event } = useRimori();
-
-  const openTranslator = (text: string) => {
-    // Trigger translator plugin in sidebar
-    event.emitSidebarAction('translator', 'translate', text);
-  };
-
-  const openFlashcards = () => {
-    // Open flashcards plugin
-    event.emitSidebarAction('flashcards', 'review');
-  };
-
-  return (
-    <div>
-      <button onClick={() => openTranslator('Hello world')}>
-        Translate "Hello world"
-      </button>
-      <button onClick={openFlashcards}>
-        Review Flashcards
-      </button>
-    </div>
-  );
-};
-```
-
-## Community Features
-
-Share and discover content created by other users:
-
-```typescript
-const { community } = useRimori();
-
-// Shared content methods
-community.sharedContent.get<T>(contentType: string, id: string): Promise<BasicAssignment<T>>
-community.sharedContent.getList<T>(contentType: string, filter?: SharedContentFilter, limit?: number): Promise<BasicAssignment<T>[]>
-community.sharedContent.getNew<T>(contentType: string, instructions: SharedContentObjectRequest, filter?: SharedContentFilter, privateTopic?: boolean): Promise<BasicAssignment<T>>
-community.sharedContent.create<T>(content: SharedContent<T>): Promise<BasicAssignment<T>>
-community.sharedContent.update<T>(id: string, content: Partial<SharedContent<T>>): Promise<BasicAssignment<T>>
-community.sharedContent.remove(id: string): Promise<BasicAssignment<any>>
-community.sharedContent.complete(contentType: string, assignmentId: string): Promise<void>
-```
-
-**Example: Exercise Sharing Platform**
-
-```typescript
-interface Exercise {
-  title: string;
-  description: string;
-  difficulty: 'beginner' | 'intermediate' | 'advanced';
-  questions: Array<{
-    question: string;
-    answer: string;
-    hints?: string[];
-  }>;
-}
-
-const ExerciseManager = () => {
-  const { community } = useRimori();
-  const [exercises, setExercises] = useState<BasicAssignment<Exercise>[]>([]);
-
-  // Load community exercises
-  const loadExercises = async () => {
-    const exerciseList = await community.sharedContent.getList<Exercise>(
-      'grammar_exercises',
-      { column: 'difficulty', value: 'beginner' },
-      10
-    );
-    setExercises(exerciseList);
-  };
-
-  // Create new exercise
-  const createExercise = async (exercise: Exercise) => {
-    const newExercise = await community.sharedContent.create({
-      content_type: 'grammar_exercises',
-      content: exercise,
-      metadata: {
-        difficulty: exercise.difficulty,
-        questionCount: exercise.questions.length
-      }
-    });
-
-    return newExercise;
-  };
-
-  // Generate AI exercise
-  const generateExercise = async (topic: string) => {
-    const aiExercise = await community.sharedContent.getNew<Exercise>(
-      'grammar_exercises',
-      {
-        prompt: `Create a grammar exercise about ${topic}`,
-        schema: {
-          type: "object",
-          properties: {
-            title: { type: "string" },
-            description: { type: "string" },
-            difficulty: { type: "string", enum: ["beginner", "intermediate", "advanced"] },
-            questions: {
-              type: "array",
-              items: {
-                type: "object",
-                properties: {
-                  question: { type: "string" },
-                  answer: { type: "string" },
-                  hints: { type: "array", items: { type: "string" } }
-                }
-              }
-            }
-          }
-        }
-      },
-      { column: 'difficulty', value: 'beginner' }
-    );
-
-    return aiExercise;
-  };
-
-  // Complete exercise
-  const completeExercise = async (exerciseId: string) => {
-    await community.sharedContent.complete('grammar_exercises', exerciseId);
-    // Exercise is now marked as completed for the user
-  };
-
-  return (
-    <div>
-      <button onClick={loadExercises}>Load Exercises</button>
-      <button onClick={() => generateExercise('present tense')}>
-        Generate Present Tense Exercise
-      </button>
-      {/* Exercise list UI */}
-    </div>
-  );
-};
-```
-
-## Components
-
-Pre-built React components for common functionality:
-
-### MarkdownEditor
-
-Rich text editor with markdown support:
-
-```typescript
-import { MarkdownEditor } from "@rimori/client";
-
-const EditorExample = () => {
-  const [content, setContent] = useState('');
-
-  return (
-    <MarkdownEditor
-      value={content}
-      onChange={setContent}
-      placeholder="Start writing..."
-    />
-  );
-};
-```
-
-### PlayButton
-
-Audio playback component:
-
-```typescript
-import { PlayButton } from "@rimori/client";
-
-const AudioPlayer = () => {
-  return (
-    <PlayButton
-      audioUrl="https://example.com/audio.mp3"
-      onPlay={() => console.log('Audio playing')}
-      onPause={() => console.log('Audio paused')}
-    />
-  );
-};
-```
-
-### AI Components
-
-```typescript
-import { Avatar, Assistant } from "@rimori/client";
-
-const AIInterface = () => {
-  return (
-    <div>
-      <Avatar
-        name="AI Assistant"
-        status="online"
-        size="large"
-      />
-
-      <Assistant
-        onMessage={(message) => console.log('AI message:', message)}
-        placeholder="Ask the AI assistant..."
-      />
-    </div>
-  );
-};
-```
-
-## Hooks
-
-### useChat
-
-Manage AI chat conversations:
-
-```typescript
-import { useChat } from "@rimori/client";
-
-const ChatExample = () => {
-  const { messages, append, isLoading, setMessages } = useChat([
-    // Optional tools for the AI
-    {
-      name: "get_weather",
-      description: "Get current weather",
-      parameters: {
-        type: "object",
-        properties: {
-          location: { type: "string" }
-        }
-      }
-    }
-  ]);
-
-  const sendMessage = (content: string) => {
-    append([{ role: 'user', content }]);
-  };
-
-  return (
-    <div>
-      {messages.map((msg, index) => (
-        <div key={index}>{msg.content}</div>
-      ))}
-      {isLoading && <div>AI is typing...</div>}
-    </div>
-  );
-};
-```
-
-### useTranslation
-
-Internationalization (i18n) support built on i18next:
-
-```typescript
-import { useTranslation } from "@rimori/client";
-
-const TranslatedComponent = () => {
-  const { t, ready } = useTranslation();
- 
-  if (!ready) {
-    return <div>Loading translations...</div>;
-  }
- 
-  return (
-    <div>
-      <h1>{t('discussion.title')}</h1>
-      <p>{t('discussion.whatToTalkAbout')}</p>
-    </div>
-  );
-};
-```
-
-## Translation Feature
-
-Rimori includes a comprehensive internationalization (i18n) system built on i18next that allows plugins to support multiple languages with minimal developer effort.
-
-### How it works
-
-- **Developer Focus**: Developers only need to ensure their interface works in English
-- **Automatic Translations**: With every release, translations for all other languages are generated automatically
-- **Local Testing**: For local development, you can test translations by:
-  1. Setting your user language to a non-English locale (e.g., German)
-  2. Creating a local translation file with "local-" prefix (e.g., `local-de.json`) in the `public/locales/` directory
-  3. The translator will automatically use the local translation file in development mode
-- **Manual Translations**: If developers want to manually translate files, they should place the language file manually in the `public/locales/` folder with the language code as filename (e.g., `de.json`, `fr.json`)
-
-### Usage
-
-#### Using the Hook (Recommended)
-
-```typescript
-import { useTranslation } from "@rimori/client";
-
-function MyComponent() {
-  const { t, ready } = useTranslation();
- 
-  if (!ready) {
-    return <div>Loading translations...</div>;
-  }
- 
-  return (
-    <div>
-      <h1>{t('discussion.title')}</h1>
-      <p>{t('discussion.whatToTalkAbout')}</p>
-    </div>
-  );
-}
-```
-
-#### Using the Translator Instance
-
-```typescript
-import { useRimori } from "@rimori/client";
-
-const { plugin } = useRimori();
-const translator = await plugin.getTranslator()
-
-const translatedText = translator.t("discussion.title");
-```
-
-### Translation File Structure
-
-- **Location**: `public/locales/`
-- **Production Files**: Must be named `{language}.json` (e.g., `en.json`, `de.json`, `fr.json`)
-- **Local Development Files**: Must be named `local-{language}.json` (e.g., `local-de.json`, `local-fr.json`)
-- **Format**: Standard JSON with nested objects for organization
-- **English Requirement**: `en.json` is required as the base language
-- **Release Process**: Files starting with "local-" are ignored during the release process
-
-Example translation file structure:
-
-```json
-{
-  "discussion": {
-    "title": "Discussion",
-    "whatToTalkAbout": "What do you want to talk about?",
-    "topics": {
-      "everyday": {
-        "title": "Everyday Conversations",
-        "description": "Ordering coffee, asking for directions, etc."
-      }
-    }
-  }
-}
-```
-
-### Features
-
-- **I18next Support**: All i18next features work with these translations including:
-  - Variable interpolation: `{{name}}`
-  - Pluralization
-  - Fallback mechanisms
-- **Automatic Fallback**: If a translation is missing, it falls back to English
-- **Development Mode**: Local translation files are prioritized in development
-- **Production Ready**: Automatic translation generation for production releases
-
-### Limitations
-
-- Only one translation file per language is allowed
-- Namespaces are not supported
-- Production translation files must be named `{language}.json` and placed in `public/locales/`
-- Local development files must be named `local-{language}.json` and placed in `public/locales/`
-- English (`en.json`) is required as the base language
-- Local files (prefixed with "local-") are ignored during the release process
+- `setupWorker()` wires the Rimori event bus into worker contexts.
+- `StandaloneClient.getInstance()` signs in against Rimori when your plugin runs outside the platform (e.g., local development).
+- `client.getQueryParam(key)` reads values provided by Rimori through the sandbox handshake (such as `applicationMode` or theme information).
 
 ## Utilities
 
-### difficultyConverter
-
-Convert between different difficulty representations:
-
-```typescript
-import { difficultyConverter } from '@rimori/client';
-
-const difficulty = difficultyConverter.toNumber('intermediate'); // Returns: 2
-const difficultyText = difficultyConverter.toString(3); // Returns: 'advanced'
-```
-
-### PluginUtils
-
-Various utility functions:
-
-```typescript
-import { PluginUtils } from '@rimori/client';
-
-// Utility functions for common plugin operations
-const utils = PluginUtils.getInstance();
-// Access various helper methods
-```
+Import additional helpers as needed:
 
-### Language Utilities
-
-Language detection and processing:
-
-```typescript
-import { Language } from '@rimori/client';
-
-// Language-related utility functions
-const languageCode = Language.detectLanguage(text);
-const isSupported = Language.isSupported('es');
-```
+- `AudioController` – high-level audio playback/recording utilities for non-React environments.
+- `Translator` – encapsulated i18next integration for manual translation flows.
+- `difficultyConverter` – convert between textual and numeric difficulty levels.
+- Type definitions for AI messages, shared content, triggers, accomplishments, and more.
 
 ## TypeScript Support
 
-The package is fully typed with comprehensive TypeScript definitions:
-
-```typescript
-import type {
-  MainPanelAction,
-  Message,
-  Tool,
-  EventPayload,
-  AccomplishmentPayload,
-  SharedContent,
-  BasicAssignment,
-  UserInfo,
-} from '@rimori/client';
-
-// All interfaces and types are exported for use in your plugin
-interface MyPluginData extends SharedContent<any> {
-  // Your custom properties
-}
-```
-
-The SharedContent has this type definition:
+All exports are fully typed. You can import the type definitions directly:
 
+```ts
+import type { Message, Tool, SharedContent, MacroAccomplishmentPayload } from "@rimori/client";
 ```
-export interface SharedContent<T> {
-  /** The type/category of the content (e.g. 'grammar_exercises', 'flashcards', etc.) */
-  contentType: string;
 
-  /** The human readable title/topic of the content */
-  topic: string;
+The generated declaration files cover every controller and helper to keep plugins strictly typed.
 
-  /** Array of keywords/tags associated with the content for search and categorization */
-  keywords: string[];
+## Example Integration
 
-  /** The actual content data of type T */
-  data: T;
+React users should install `@rimori/react-client` and wrap their app:
 
-  /** Whether this content should only be visible to the creator. Defaults to false if not specified */
-  privateTopic?: boolean;
-}
-```
+```tsx
+import { PluginProvider, useRimori, useChat } from "@rimori/react-client";
 
-## Examples
-
-### Complete Plugin Example
-
-```typescript
-import React, { useState, useEffect } from 'react';
-import {
-  PluginProvider,
-  usePlugin,
-  MarkdownEditor,
-  Spinner,
-  useChat
-} from '@rimori/client';
-import { HashRouter, Route, Routes } from 'react-router-dom';
-
-const StudyNotesPlugin = () => {
-  const { db, llm, plugin, community } = useRimori();
-  const [notes, setNotes] = useState([]);
-  const [isLoading, setIsLoading] = useState(true);
+function Dashboard() {
+  const client = useRimori();
   const { messages, append } = useChat();
 
-  useEffect(() => {
-    loadNotes();
-  }, []);
-
-  const loadNotes = async () => {
-    try {
-      const { data } = await db.from('notes').select('*').order('created_at', { ascending: false });
-      setNotes(data || []);
-    } catch (error) {
-      console.error('Error loading notes:', error);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  const saveNote = async (content: string) => {
-    const { data } = await db.from('notes').insert({
-      content,
-      created_at: new Date().toISOString()
-    }).select().single();
-
-    setNotes([data, ...notes]);
-
-    // Share with community
-    await community.sharedContent.create({
-      content_type: 'study_notes',
-      content: { text: content },
-      metadata: { wordCount: content.length }
-    });
-  };
-
-  const generateSummary = async (noteContent: string) => {
-    const summary = await llm.getText([
-      { role: 'user', content: `Summarize this study note: ${noteContent}` }
-    ]);
-
-    return summary;
-  };
-
-  if (isLoading) return <Spinner size="large" />;
+  // interact with the core API through the client instance
+  // e.g. client.db.from("notes")...
+}
 
+export function App() {
   return (
-    <div className="study-notes-plugin">
-      <h1>Study Notes</h1>
-
-      <div className="notes-grid">
-        {notes.map(note => (
-          <div key={note.id} className="note-card">
-            <MarkdownEditor
-              value={note.content}
-              onChange={(content) => {/* Update logic */}}
-            />
-            <button onClick={() => generateSummary(note.content)}>
-              Generate Summary
-            </button>
-          </div>
-        ))}
-      </div>
-
-      <div className="ai-chat">
-        <h2>Study Assistant</h2>
-        {messages.map((msg, index) => (
-          <div key={index} className={`message ${msg.role}`}>
-            {msg.content}
-          </div>
-        ))}
-        <button onClick={() => append([{ role: 'user', content: 'Help me study' }])}>
-          Get Study Help
-        </button>
-      </div>
-    </div>
+    <PluginProvider pluginId="your-plugin-id">
+      <Dashboard />
+    </PluginProvider>
   );
-};
-
-const App = () => (
-  <PluginProvider pluginId="study-notes-plugin">
-    <HashRouter>
-      <Routes>
-        <Route path="/" element={<StudyNotesPlugin />} />
-      </Routes>
-    </HashRouter>
-  </PluginProvider>
-);
-
-export default App;
+}
 ```
 
-## Best Practices
+Non-React projects can interact with the same client instance directly via the examples in the sections above.
+
+## Troubleshooting
 
-1. **Performance**: Use lazy loading for pages and implement proper loading states
-2. **State Management**: Leverage React hooks and context when needed
-3. **Type Safety**: Use TypeScript interfaces for all data structures
-4. **Event Cleanup**: Always unsubscribe from events in useEffect cleanup
-5. **Responsive Design**: Use TailwindCSS classes for responsive layouts
+- **`ReferenceError: process is not defined` in workers** – ensure worker bundles only import from `@rimori/client`. Packages that reference `process.env` are not compatible with Rimori workers.
+- **Missing plugin ID or token** – re-run `rimori-init` to regenerate configuration and authentication secrets.
+- **Event bus listeners firing twice** – store the listener returned by `event.on` and call `listener.off()` during cleanup (React users get this cleanup inside the hooks provided by `@rimori/react-client`).