create-bluecopa-react-app 1.0.41 → 1.0.43

package/templates/latest/Agent.md

@@ -1,936 +1,759 @@
-# AI Agent Guide for Bluecopa React UI Template
+# CLAUDE.md — React MFE Boilerplate
 
-This guide helps AI assistants and developers understand the project structure, patterns, and best practices for working with this Bluecopa React application template.
+This file provides guidance to Claude Code when working with the Bluecopa React MFE (Micro-Frontend) boilerplate.
 
-## 🏗️ Project Architecture Overview
+## Project Overview
 
-### Core Stack
-- **React 18** with TypeScript
-- **React Router v7** with SSR support
-- **shadcn/ui** components built on Radix UI
-- **Bluecopa UI** components from `@bluecopa-ui` registry (built on Radix UI)
-- **Tailwind CSS v4** with CSS variables
-- **Vite 6** for build tooling
-- **TanStack Query** (via @bluecopa/react)
+A production-ready React microfrontend template for building apps that run inside the Bluecopa platform. Uses single-spa for MFE orchestration, Module Federation for runtime loading, and the Dream Light design system for UI.
 
-### Key Directories
-```
-app/
-├── components/          # Reusable UI components
-│   ├── ui/             # Bluecopa UI or shadcn/ui components
-│   ├── app-sidebar.tsx # Main navigation
-│   ├── data-table.tsx  # TanStack Table wrapper
-│   └── chart-*.tsx     # Recharts components
-├── hooks/              # Custom React hooks
-├── lib/                # Utilities and configurations
-├── routes/             # React Router pages
-└── dashboard/          # Sample data and components
+## Quick Start
+
+```bash
+pnpm dev          # Dev server on port 8080
+pnpm build        # TypeScript check + production build
+pnpm start        # Serve built MFE on port 3001
+pnpm typecheck    # TypeScript validation only
 ```
 
-## 🎨 Component Patterns
+## Architecture
 
-### UI Component Registries
+### Entry Points
 
-This project supports components from two registries:
+| File | Mode | Router | Use Case |
+|------|------|--------|----------|
+| `app/main.tsx` | Standalone | `BrowserRouter` | Local development |
+| `app/single-spa.tsx` | MFE | `MemoryRouter` | Deployed inside Bluecopa shell |
 
-1. **Bluecopa UI Registry** (Preferred for Bluecopa-specific components)
-   - Registry URL: https://blui.vercel.app
-   - Registry JSON: https://blui.vercel.app/r/registry.json
-   - Custom Bluecopa components built on Radix UI
+### MFE Props Interface
 
-2. **shadcn/ui Registry** (Standard components)
-   - Registry URL: https://ui.shadcn.com
-   - Standard shadcn/ui components built on Radix UI
+```typescript
+interface MfeProps {
+  apiBaseUrl?: string;     // Bluecopa API URL
+  workspaceId?: string;    // Workspace context
+  accessToken?: string;    // JWT auth token
+  userId?: string;         // Current user ID
+  basename?: string;       // Router basename
+}
+```
 
-Both registries:
-- Located in `app/components/ui/` after installation
-- Built on Radix UI primitives
-- Styled with Tailwind CSS
-- Use `cn()` utility for class merging
-- Support dark mode via CSS variables
+Props are passed from the host app via single-spa `customProps` or `manualMount()`.
 
-### Adding Components
+### Key Files
 
-#### From Bluecopa UI Registry
+| File | Purpose |
+|------|---------|
+| `app/app.tsx` | Root component — QueryClient, ChartProvider, MFE config, AppProvider |
+| `app/app.css` | Tailwind v4 config + Dream Light theme tokens |
+| `app/contexts/app-context.tsx` | User, workspace settings, admin role context |
+| `app/routes/index.tsx` | Route definitions (all wrapped in AppLayout) |
+| `app/utils/utils.ts` | `cn()` utility with `copa` prefix support |
+| `app/utils/component-style.ts` | Unprefixed style tokens (source of truth) |
+| `app/utils/style-drivers.ts` | Auto-prefixes style tokens with `copa:` |
+| `vite.config.ts` | Vite + Module Federation + Tailwind v4 |
+| `components.json` | shadcn CLI config (prefix: `copa`) |
 
-To add a component from the Bluecopa UI registry (preferred for Bluecopa-specific components):
+### Directory Layout
 
-```bash
-pnpm dlx shadcn@latest add @bluecopa-ui/button
-pnpm dlx shadcn@latest add @bluecopa-ui/card
-pnpm dlx shadcn@latest add @bluecopa-ui/dialog
+```
+app/
+├── components/
+│   ├── ui/              # shadcn/Dream Light components (prefixed)
+│   ├── charts/          # ECharts-based chart components (BarChart, DonutChart, etc.)
+│   └── layouts/         # AppLayout, AppSidebar, SiteHeader, NavMain, NavUser
+├── constants/           # Route paths, API defaults, query defaults, breakpoints
+├── contexts/            # AppContext (user, workspace, settings)
+├── hooks/               # use-mobile.ts (768px breakpoint)
+├── pages/               # Page components (dashboard, settings, etc.)
+├── routes/              # Route config
+├── types/               # MfeProps, AppUser, WorkspaceDataSettings
+└── utils/               # cn(), style drivers
 ```
 
-#### From shadcn/ui Registry
-
-To add a component from the standard shadcn/ui registry:
+### Layout Structure
 
-```bash
-pnpm dlx shadcn@latest add button
-pnpm dlx shadcn@latest add card
-pnpm dlx shadcn@latest add dialog
 ```
-
-The registries are configured in `components.json`:
-```json
-{
-  "registries": {
-    "@bluecopa-ui": "https://blui.vercel.app/r/{name}.json"
-  }
-}
+AppLayout (SidebarProvider)
+├── AppSidebar (collapsible, Cmd/Ctrl+B toggle)
+│   ├── NavMain (navigation items)
+│   └── NavUser (user menu footer)
+└── SidebarInset
+    ├── SiteHeader (breadcrumbs, user dropdown)
+    └── <Outlet /> (page content)
 ```
 
-**Note**: When no registry prefix is specified, components are added from the default shadcn/ui registry. Use `@bluecopa-ui/` prefix for Bluecopa-specific components.
+## Tailwind v4 + `copa:` Prefix — CRITICAL
 
-### Custom Components
-- Use TypeScript interfaces for props
-- Follow React best practices (hooks, memo, etc.)
-- Implement proper accessibility
-- Use semantic HTML elements
+All Tailwind classes MUST use the `copa:` prefix for MFE CSS isolation.
 
-### Example Component Structure
-```tsx
-import { cn } from "~/lib/utils"
+### Prefix Order Rule
 
-interface ComponentProps {
-  className?: string
-  children: React.ReactNode
-}
+**Prefix ALWAYS comes first**, then variants, then utility:
 
-export function Component({ className, children }: ComponentProps) {
-  return (
-    <div className={cn("base-styles", className)}>
-      {children}
-    </div>
-  )
-}
+```
+{prefix}:{variants}:{utility}
 ```
 
-## 🔧 Development Patterns
-
-### State Management
-- Use React hooks (useState, useReducer, useContext)
-- TanStack Query for server state
-- Local state for UI interactions
-- Avoid prop drilling with context
-
-### Data Fetching
-- Use `@bluecopa/react` hooks for API calls
-- Implement loading and error states
-- Use TanStack Query for caching
-- Handle optimistic updates
-
-# @bluecopa/react [![npm version](https://img.shields.io/npm/v/@bluecopa/react)](https://www.npmjs.com/package/@bluecopa/react) [![License](https://img.shields.io/npm/l/@bluecopa/react)](https://github.com/bluecopa/blui/blob/main/packages/react/LICENSE)
-
-## A Comprehensive React Query Integration for Bluecopa
-
-A React library providing opinionated custom hooks for TanStack React Query integration with Bluecopa core API. This package enables efficient data fetching, caching, and synchronization with the Bluecopa platform while maintaining type safety and developer experience.
-
-## Table of Contents
-
-- [AI Agent Guide for Bluecopa React UI Template](#ai-agent-guide-for-bluecopa-react-ui-template)
-  - [🏗️ Project Architecture Overview](#️-project-architecture-overview)
-    - [Core Stack](#core-stack)
-    - [Key Directories](#key-directories)
-  - [🎨 Component Patterns](#-component-patterns)
-    - [UI Component Registries](#ui-component-registries)
-    - [Adding Components](#adding-components)
-      - [From Bluecopa UI Registry](#from-bluecopa-ui-registry)
-      - [From shadcn/ui Registry](#from-shadcnui-registry)
-    - [Custom Components](#custom-components)
-    - [Example Component Structure](#example-component-structure)
-  - [🔧 Development Patterns](#-development-patterns)
-    - [State Management](#state-management)
-    - [Data Fetching](#data-fetching)
-- [@bluecopa/react  ](#bluecopareact--)
-  - [A Comprehensive React Query Integration for Bluecopa](#a-comprehensive-react-query-integration-for-bluecopa)
-  - [Table of Contents](#table-of-contents)
-  - [Features](#features)
-  - [Installation](#installation)
-    - [Peer Dependencies](#peer-dependencies)
-  - [Usage](#usage)
-    - [Query Provider Setup](#query-provider-setup)
-    - [Boilerplate Integration](#boilerplate-integration)
-    - [Hook Examples](#hook-examples)
-      - [`useUser` - Fetch authenticated user](#useuser---fetch-authenticated-user)
-      - [`useDataset` - Fetch dataset with query controls](#usedataset---fetch-dataset-with-query-controls)
-  - [API Documentation](#api-documentation)
-    - [`useUser(options?)`](#useuseroptions)
-    - [`useDataset(datasetId, options?)`](#usedatasetdatasetid-options)
-    - [`useDatasetSample(datasetId, options?)`](#usedatasetsampledatasetid-options)
-    - [`useMetric(metricId, options?)`](#usemetricmetricid-options)
-    - [`useInputTable(inputTableId, options?)`](#useinputtableinputtableid-options)
-    - [`useGetFileUrlByFileId(fileId, options?)`](#usegetfileurlbyfileidfileid-options)
-    - [`useGetPublishedWorkbookById(workbookId, options?)`](#usegetpublishedworkbookbyidworkbookid-options)
-    - [`useGetTableById(tableId, options?)`](#usegettablebyidtableid-options)
-    - [`useGetWorkbooksByType(workbookType, options?)`](#usegetworkbooksbytypeworkbooktype-options)
-    - [`useGetWorkflowInstanceStatusById(instanceId, options?)`](#usegetworkflowinstancestatusbyidinstanceid-options)
-    - [`useGetWorksheets(options?)`](#usegetworksheetsoptions)
-    - [`useGetWorksheetsByType(worksheetType, options?)`](#usegetworksheetsbytypeworksheettype-options)
-    - [`useRunDefinition(definitionId, options?)`](#userundefinitiondefinitionid-options)
-    - [`useRunPublishedDefinition(publishedDefinitionId, options?)`](#userunpublisheddefinitionpublisheddefinitionid-options)
-    - [`useRunSampleDefinition(sampleDefinitionId, options?)`](#userunsampledefinitionsampledefinitionid-options)
-    - [`useTriggerHttpWorkflow(workflowId, payload, options?)`](#usetriggerhttpworkflowworkflowid-payload-options)
-    - [`useTriggerWorkflow(workflowId, options?)`](#usetriggerworkflowworkflowid-options)
-    - [`useWorkbook(workbookId, options?)`](#useworkbookworkbookid-options)
-    - [`useWorkflow(workflowId, options?)`](#useworkflowworkflowid-options)
-    - [`useWorksheet(worksheetId, options?)`](#useworksheetworksheetid-options)
-  - [Configuration](#configuration)
-    - [Default Query Configuration](#default-query-configuration)
-    - [Customizable Parameters](#customizable-parameters)
-  - [Advanced Usage](#advanced-usage)
-    - [Error Handling](#error-handling)
-    - [Manual Refetching](#manual-refetching)
-  - [Re-exports](#re-exports)
-    - [Styling Guidelines](#styling-guidelines)
-  - [📊 Data Visualization](#-data-visualization)
-    - [Charts (Recharts)](#charts-recharts)
-    - [Tables (TanStack Table)](#tables-tanstack-table)
-  - [🎯 Common Tasks \& Solutions](#-common-tasks--solutions)
-    - [Adding New Pages](#adding-new-pages)
-    - [Adding New Components](#adding-new-components)
-    - [Working with Forms](#working-with-forms)
-    - [API Integration](#api-integration)
-  - [🚀 Performance Optimization](#-performance-optimization)
-    - [Code Splitting](#code-splitting)
-    - [Bundle Optimization](#bundle-optimization)
-    - [Runtime Performance](#runtime-performance)
-  - [🧪 Testing Strategies](#-testing-strategies)
-    - [Component Testing](#component-testing)
-    - [Integration Testing](#integration-testing)
-  - [🔒 Security Considerations](#-security-considerations)
-    - [Data Handling](#data-handling)
-  - [📱 Responsive Design](#-responsive-design)
-    - [Breakpoints](#breakpoints)
-    - [Layout Patterns](#layout-patterns)
-  - [🌙 Dark Mode Implementation](#-dark-mode-implementation)
-    - [Theme System](#theme-system)
-    - [Component Theming](#component-theming)
-  - [🐛 Debugging Tips](#-debugging-tips)
-    - [Common Issues](#common-issues)
-    - [Development Tools](#development-tools)
-  - [📚 Useful Resources](#-useful-resources)
-    - [Documentation](#documentation)
-    - [Bluecopa Specific](#bluecopa-specific)
-  - [🎯 Best Practices Summary](#-best-practices-summary)
-  - [🔄 Common Workflows](#-common-workflows)
-    - [Adding a New Feature](#adding-a-new-feature)
-    - [Debugging Issues](#debugging-issues)
-
-## Features
-
-- ✅ First-class TypeScript support with strict type definitions
-- 🔁 Seamless integration with TanStack React Query (v5+)
-- 🛡 Comprehensive error handling patterns
-- ⚙ Optimized default query configuration
-- 📦 Re-exports of core TanStack React Query utilities
-- 📊 Sample data preview capabilities
-- 🧩 Customizable query parameters (limit, caching, retries)
-
-## Installation
+```tsx
+// CORRECT
+className="copa:flex copa:items-center copa:hover:bg-accent copa:md:block"
+className="copa:group-data-[state=open]:block"
 
-```bash
-npm install @bluecopa/react
-# or with pnpm
-pnpm add @bluecopa/react
+// WRONG — silently fails, no CSS generated, no errors
+className="hover:copa:bg-accent"   // ← variant before prefix
+className="md:copa:block"          // ← breakpoint before prefix
 ```
 
-### Peer Dependencies
+### CSS Architecture (app.css)
 
-This package requires the following in your application:
+Three layers in order:
 
-```bash
-npm install react@^18.0.0 react-dom@^18.0.0
+1. **`@theme` (build-time)** — Resolved at compile time. Cannot use `var()` refs to runtime CSS variables. Must hardcode values.
+2. **`@theme inline` (runtime)** — Binds to CSS variables from `.mfe-root`. Used for dynamic radius, colors.
+3. **`.mfe-root` (scoped vars)** — All CSS variables scoped here, NOT `:root`. This prevents MFE style leaking.
+
+### cn() Utility
+
+```typescript
+import { cn } from "~/utils/utils";
+
+// Handles copa: prefix correctly via extendTailwindMerge({ prefix: "copa" })
+<div className={cn("copa:flex copa:gap-2", isActive && "copa:bg-accent", className)} />
 ```
 
-## Usage
+### Style Drivers
 
-### Query Provider Setup
+For reusable style tokens, define unprefixed in `component-style.ts`, consume prefixed from `style-drivers.ts`:
 
-Wrap your application with the React Query provider:
+```typescript
+// component-style.ts (write unprefixed)
+export const styles = {
+  card: "rounded-lg border bg-card text-card-foreground shadow-sm",
+};
 
-```tsx
-import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      staleTime: 60 * 1000, // 1 minute
-      refetchOnWindowFocus: false,
-    },
-  },
-});
+// style-drivers.ts (auto-prefixes)
+// "rounded-lg border ..." → "copa:rounded-lg copa:border ..."
 
-function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <YourApp />
-      <ReactQueryDevtools initialIsOpen={false} />
-    </QueryClientProvider>
-  );
-}
+// Usage
+import { prefixedStyles } from "~/utils/style-drivers";
+<div className={prefixedStyles.card} />
 ```
 
-### Boilerplate Integration
+## @bluecopa/react — API Integration
 
-For projects using the Bluecopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically:
+React Query hooks wrapping `@bluecopa/core`. All data fetching uses these hooks.
 
-```tsx
-// src/providers/query-provider.tsx
-import { ReactQueryDevtools, reactQuery, copaSetConfig } from "@bluecopa/react";
-import { useEffect, useState } from "react";
-
-const { QueryClient, QueryClientProvider } = reactQuery;
-
-export default function QueryProvider({ children }: { children: React.ReactNode }) {
-  const [queryClient] = useState(() => new QueryClient({
-    defaultOptions: {
-      queries: {
-        staleTime: 60 * 1000, // 1 minute
-        refetchOnWindowFocus: false,
-      },
-    },
-  }));
-
-  useEffect(() => {
-    let copaUser: any = {};
-    try {
-      const copaToken = import.meta.env.VITE_BLUECOPA_API_TOKEN
-        ? atob(import.meta.env.VITE_BLUECOPA_API_TOKEN)
-        : "{}";
-      
-      copaUser = JSON.parse(copaToken);
-    } catch (error) {
-      console.warn("Failed to parse VITE_BLUECOPA_API_TOKEN:", error);
-    }
-
-    copaSetConfig({
-      apiBaseUrl: import.meta.env.VITE_BLUECOPA_API_URL || "https://develop.bluecopa.com/api/v1",
-      workspaceId: import.meta.env.VITE_BLUECOPA_WORKSPACE_ID || "",
-      accessToken: copaUser?.accessToken || "",
-    });
-  }, []);
+### Setup Flow
 
-  return (
-    <QueryClientProvider client={queryClient}>
-      {children}
-      <ReactQueryDevtools initialIsOpen={false} />
-    </QueryClientProvider>
-  );
-}
-```
+1. `copaSetConfig()` called in `app.tsx` useEffect with MFE props or env vars
+2. `QueryClientProvider` wraps the app (staleTime: 5min, retry: 1)
+3. Hooks become available in all child components
 
-**Required Environment Variables:**
+### Configuration
 
-| Variable | Description | Example |
-|----------|-------------|---------|
-| `VITE_BLUECOPA_API_URL` | Base URL for Bluecopa API | `https://develop.bluecopa.com` |
-| `VITE_BLUECOPA_WORKSPACE_ID` | Your workspace identifier | `my-workspace-123` |
-| `VITE_BLUECOPA_API_TOKEN` | Base64-encoded JSON string containing `accessToken` | `eyJhY2Nlc3NUb2tlbiI6IjEyMzQ1In0=` |
+```typescript
+import { copaSetConfig } from "@bluecopa/react";
 
-**Example `.env` file:**
-```
-VITE_BLUECOPA_API_URL=https://develop.bluecopa.com
-VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
-VITE_BLUECOPA_API_TOKEN=base64-encoded-json-here
+copaSetConfig({
+  apiBaseUrl: "https://develop.bluecopa.com/api/v1",
+  workspaceId: "your-workspace-id",
+  accessToken: "your-jwt-token",
+  userId: "user-id",
+});
 ```
 
-Then wrap your application with this provider:
+### Environment Variables
 
-```tsx
-import QueryProvider from './providers/query-provider';
+```bash
+VITE_BLUECOPA_API_URL=https://develop.bluecopa.com/api/v1
+VITE_BLUECOPA_WORKSPACE_ID=prod
+```
 
-function App() {
-  return (
-    <QueryProvider>
-      <YourApp />
-    </QueryProvider>
-  );
-}
+### Available Hooks
+
+#### User & Auth
+- `useUser()` — Current user details
+- `useGetAllUsers()` — All workspace users
+
+#### Datasets & Tables
+- `useDataset(id, { limit })` — Dataset records
+- `useDatasetSample(id)` — Sample data
+- `useRows(tableId, { filters, limit, offset, order, order_by })` — Supabase-style filtered rows
+- `useInputTable(id, { limitParams, pageParams, sortParams })` — Input table data
+- `useGetTableById(id)` — Table metadata
+- `useInsertRow()` — Insert row (mutation, auto-invalidates)
+- `useUpdateRow()` — Update row (mutation)
+- `useDeleteRow()` — Delete row (mutation)
+
+#### Metrics
+- `useMetric(id)` — Metric data
+
+#### Workbooks & Worksheets
+- `useGetWorkbooksByType(type)` — Filter workbooks
+- `useGetPublishedWorkbookById(id)` — Published workbook
+- `useGetWorkbookDetails(id)` — Detailed info
+- `useSaveWorkbook()` — Save (mutation)
+- `usePublishWorkbook()` — Publish (mutation)
+- `useGetWorksheets()` — All worksheets
+- `useGetWorksheetsByType(type)` — Filter by type
+
+#### Views & Runs
+- `useGetViewById(id)` — View details
+- `useGetViewsBySheetId(id)` — Views for sheet
+- `useGetRunsByViewId(id)` — Run history
+- `useGetRunResultById(id)` — Run result
+
+#### Workflows
+- `useTriggerWorkflow()` — Trigger execution (mutation)
+- `useTriggerHttpWorkflow()` — HTTP trigger (mutation)
+- `useGetWorkflowInstanceStatusById(id)` — Check status
+- `useGetAllHttpTriggers()` — List triggers
+
+#### Definitions
+- `useRunDefinition()` — Execute definition (mutation)
+- `useRunPublishedDefinition()` — Published definition (mutation)
+- `useRunSampleDefinition()` — Sample definition (mutation)
+
+#### Files
+- `useFileUpload()` — Upload to S3 (mutation)
+- `useFileDownload()` — Download file (mutation)
+- `useGetFileUrlByFileId(id)` — Get file URL
+
+#### Forms
+- `useGetFormById(id)` — Form details
+- `useGetFormSchema(id)` — Form schema
+- `useGetFormData(id)` — Form data
+- `useCreateOrUpdateForm()` — Create/update (mutation)
+
+#### Chat & Comments
+- `useCreateThread()` — Create thread (mutation)
+- `useGetCommentsByThreadId(id)` — Thread comments
+- `usePostComment()` — Post comment (mutation)
+- `useUpdateComment()` / `useDeleteComment()` — Manage comments
+
+#### Tasks & Inbox
+- `useGetTaskDetails(id)` — Task details
+- `useMarkTaskDone()` — Complete task (mutation)
+- `useReassignTask()` — Reassign (mutation)
+- `useGetAllInboxItems()` — Inbox items
+- `useMarkItemAsRead()` / `useMarkItemAsUnread()` — Read state
+
+#### Statements
+- `useCreateStatementRun()` — Create run (mutation)
+- `useGetStatementData(id)` — Statement data
+
+#### Audit & Recon
+- `useGetAuditLogs()` — Audit logs
+- `useCreateAuditLog()` — Create entry (mutation)
+- `useGetAllRecon()` — Reconciliations
+- `useRunRecon()` — Run recon (mutation)
+
+#### Pipelines
+- `useGetAllTemplatedPipelines()` — Template pipelines
+
+### Re-exports
+
+```typescript
+// Available from @bluecopa/react
+export * as reactQuery from "@tanstack/react-query";   // QueryClient, useQuery, etc.
+export * from "@bluecopa/core";                        // copaSetConfig, copaApi, copaUtils
+export { ReactQueryDevtools } from "@tanstack/react-query-devtools";
 ```
 
-This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.
+### Hook Usage Pattern
 
-### Hook Examples
+```tsx
+import { useDataset } from "@bluecopa/react";
 
-#### `useUser` - Fetch authenticated user
+function MyPage() {
+  const { data, isLoading, error, refetch } = useDataset("dataset-id", { limit: 100 });
 
-```tsx
-import { useUser } from '@bluecopa/react';
-
-function UserProfile() {
-  const { data, isLoading, error } = useUser({
-    staleTime: 5 * 60 * 1000, // 5 minutes
-    retry: 2
-  });
-  
-  if (isLoading) return <div>Loading...</div>;
+  if (isLoading) return <Skeleton />;
   if (error) return <div>Error: {error.message}</div>;
-  
-  return <div>Welcome, {data?.name}!</div>;
-}
-```
-
-#### `useDataset` - Fetch dataset with query controls
 
-```tsx
-import { useDataset } from '@bluecopa/react';
-
-function DatasetViewer({ datasetId }) {
-  const { data, isLoading } = useDataset(datasetId, {
-    limit: 500,
-    staleTime: 10 * 60 * 1000 // 10 minutes
-  });
-  
-  if (isLoading) return <div>Loading dataset...</div>;
-  return <div>{data?.name} ({data?.records?.length} records)</div>;
+  // Parse response (handles multiple formats)
+  const rows = data?.records || data?.data || data?.rows || (Array.isArray(data) ? data : []);
+  return <DataTable data={rows} />;
 }
 ```
 
-## API Documentation
-
-### `useUser(options?)`
+## @bluecopa/core — API SDK
 
-Fetches authenticated user details with query controls.
+Low-level TypeScript SDK. Prefer `@bluecopa/react` hooks in components, use `copaApi` directly only when needed outside React.
 
-**Parameters:**  
-- `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
+### Authentication
 
-**Returns:**  
-- `data`: User object or `undefined`
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+Custom header-based auth (not Bearer tokens):
+- `X-COPA-TOKEN`: Access token
+- `X-COPA-WORKSPACE-ID`: Workspace context
 
-### `useDataset(datasetId, options?)`
+### Direct API Usage
 
-Fetches dataset data by ID with configurable parameters.
+```typescript
+import { copaApi } from "@bluecopa/react";
 
-**Parameters:**  
-- `datasetId`: ID of the dataset to fetch
-- `options` (optional): Query options with:
-  - `limit`: Maximum records to fetch
-  - `staleTime`: Duration (ms) before data is considered stale
+const user = await copaApi.user.getLoggedInUserDetails();
+const rows = await copaApi.inputTable.getRows("table-id", { limit: 50 });
+await copaApi.inputTable.insertRow("table-id", { name: "New", value: 42 });
+```
 
-**Returns:**  
-- `data`: Dataset object containing name and records
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+### WebSocket Integration
 
-### `useDatasetSample(datasetId, options?)`
+```typescript
+import { copaUtils } from "@bluecopa/react";
 
-Fetches a representative sample of dataset data.
+const ws = copaUtils.websocketUtils.WebsocketContextFactory.create("centrifugo", {
+  connectionUrl: "wss://...",
+  token: "...",
+  userId: "...",
+});
+ws.connect();
+ws.bind("channel", "event", (data) => console.log(data));
+```
 
-**Parameters:**  
-- `datasetId`: ID of the dataset
-- `options` (optional): Query options with `enabled` flag
+## AppContext
+
+Provides user data, workspace settings, and role info to all components.
+
+### Available Values
+
+```typescript
+const {
+  user,                      // { userId, email, name, role, currentWorkspace, ... }
+  isLoading,                 // User fetch loading state
+  error,                     // User fetch error
+  refetch,                   // Refetch user data
+  isAdmin,                   // Derived: any team contains "admin"
+  workspaceIds,              // User's workspace IDs
+  teams,                     // User's teams
+  users,                     // All workspace users
+  currentWorkspaceSettings,  // { currency, timezone, dateFormat, fiscalYear, numberSettings, weekStartDay }
+  setCurrency,               // Override currency
+} = useAppContext();
+```
 
-**Returns:**  
-- `data`: Object containing sample data
-- `isLoading`: Boolean indicating loading state
-- `refetch`: Function to manually trigger refetch
+### Workspace Settings Shape
 
-### `useMetric(metricId, options?)`
+```typescript
+{
+  currency: "USD",
+  timezone: "UTC",
+  dateFormat: "MM/DD/YYYY HH:mm:ss",
+  fiscalYear: { yearType: "calendar_year", startMonth?, startDate? },
+  numberSettings: { numberSystem: "intl", defaultPrecision: 2, nullPlaceholder? },
+  weekStartDay: "SUNDAY",
+}
+```
 
-Fetches metric data by ID.
+## Dream Light Design System
 
-**Parameters:**  
-- `metricId`: ID of the metric
-- `options` (optional): Query options
+The UI design system. Source: `[https://blui.vercel.app/](https://blui.vercel.app/)`
+Registry base URL: `https://blui.vercel.app/r/registry.json`
 
-**Returns:**  
-- `data`: Metric object with name and value
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+### Adding Components
 
-### `useInputTable(inputTableId, options?)`
+From either registry via shadcn CLI:
 
-Fetches input table data with limit parameters.
+```bash
+# Dream Light / Bluecopa UI (preferred)
+pnpm dlx shadcn@latest add @bluecopa-ui/button
+pnpm dlx shadcn@latest add @bluecopa-ui/dialog
+pnpm dlx shadcn@latest add @bluecopa-ui/data-table
 
-**Parameters:**  
-- `inputTableId`: ID of the input table
-- `options` (optional): Query options with `limitParams`:
-  - `limit`: Maximum rows to fetch
-  - `limitFrom`: Direction to apply limit from ('top' or 'bottom')
+# Standard shadcn/ui (fallback)
+pnpm dlx shadcn@latest add button
+```
 
-**Returns:**  
-- `data`: Input table object with rows
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+Registry URL: `https://blui.vercel.app/r/{name}.json`
 
-### `useGetFileUrlByFileId(fileId, options?)`
+### Available Dream Light Components (70+)
 
-Fetches the URL for a file by its ID.
+**Inputs**: button, input, textarea, checkbox, radio-group, switch, select, select-advanced, combobox, number-input, pills, date-picker, date-range-picker, calendar, toggle
 
-**Parameters:**
-- `fileId`: ID of the file to fetch URL for
-- `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
+**Navigation**: tabs, horizontal-tabs, vertical-tabs, breadcrumb, pagination, dropdown-menu, command, sidebar, sidebar-with-icons
 
-**Returns:**
-- `data`: Object containing file URL
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+**Display**: text, badge, alert, avatar, toast, tooltip, spinner, loading-state, skeleton, empty-state, error-boundary, progress, kpi-card, ag-grid-table, data-table
 
-### `useGetPublishedWorkbookById(workbookId, options?)`
+**Containers**: card, section-card, dialog, sheet, side-panel, popover, accordion, scroll-area, separator, stack, kanban, tree-menu, topbar
 
-Fetches published workbook details by ID.
+**Layout**: scaffold, page-container, section, page-header
 
-**Parameters:**
-- `workbookId`: ID of the published workbook
-- `options` (optional): Query options
+**Forms**: form-field, form-section, form-error-summary, label, search-box
 
-**Returns:**
-- `data`: Published workbook object
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+**Advanced**: filter-builder, stepper, brand-logo, listing-view, listing-table, listing-header
 
-### `useGetTableById(tableId, options?)`
+### Design Tokens
 
-Fetches table metadata by ID.
+#### Colors (OKLCH)
 
-**Parameters:**
-- `tableId`: ID of the table
-- `options` (optional): Query options
+```css
+--primary: #3548ff;                        /* Bluecopa blue */
+--primary-foreground: oklch(100% 0 0);     /* White on primary */
+--background: oklch(0.975 0.005 280);      /* Near-white */
+--foreground: oklch(0.145 0 0);            /* Near-black */
+--destructive: oklch(0.577 0.245 27.325);  /* Red */
+--border: oklch(0.92 0.005 280);           /* Light gray */
+--muted: oklch(0.97 0.003 280);
+--muted-foreground: oklch(0.556 0 0);
+--accent: oklch(0.97 0.003 280);
 
-**Returns:**
-- `data`: Table metadata object
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+/* Semantic status */
+--status-success: oklch(0.72 0.19 142);
+--status-warning: oklch(0.80 0.18 85);
+--status-error: oklch(0.63 0.24 25);
 
-### `useGetWorkbooksByType(workbookType, options?)`
+/* Sidebar */
+--sidebar: oklch(1 0 0);                   /* White */
+--sidebar-foreground: oklch(0.145 0 0);
+--sidebar-border: oklch(0.92 0.004 280);
+```
 
-Fetches workbooks filtered by type.
+#### Typography Scale
+
+```css
+/* Fluid type scale */
+--text-xs: 0.702rem;       /* Small captions */
+--text-sm: 0.835rem;       /* Body text, labels */
+--text-md: 1.004rem;       /* Prominent body */
+--text-lg: 1.21rem;        /* Subheadings */
+--text-xl: 1.452rem;       /* Section headers */
+--text-2xl: 1.742rem;      /* Large headings */
+--text-3xl: 2.093rem;
+--text-4xl: 2.505rem;
+--text-5xl: 3.013rem;      /* Hero display */
+
+/* Heading tokens */
+--text-h1: 3rem;           /* 700 weight */
+--text-h2: 2.25rem;        /* 700 */
+--text-h3: 1.875rem;       /* 600 */
+--text-h4: 1.5rem;         /* 400 */
+--text-h5: 1.25rem;        /* 600 */
+--text-h6: 1rem;           /* 400 */
+
+/* Font: Satoshi (sans-serif) */
+```
 
-**Parameters:**
-- `workbookType`: Type of workbooks to fetch
-- `options` (optional): Query options
+#### Custom Typography Utilities (defined in app.css)
 
-**Returns:**
-- `data`: Array of workbook objects
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+```
+.text-page-title     → 1.5rem, semibold
+.text-section-title  → 0.9375rem, semibold
+.text-label          → 0.75rem, uppercase, tracked
+.text-value          → 1.75rem, bold
+.text-nav-section    → 0.6875rem, uppercase, tracked
+```
 
-### `useGetWorkflowInstanceStatusById(instanceId, options?)`
+#### Spacing
 
-Fetches workflow instance status by ID.
+```css
+--radius: 1rem;
+--card-radius: 1.25rem;
+--rounded-input: 12px;
 
-**Parameters:**
-- `instanceId`: ID of the workflow instance
-- `options` (optional): Query options
+/* Motion */
+--duration-fast: 100ms;
+--duration-normal: 200ms;
+--ease-default: cubic-bezier(0.4, 0, 0.2, 1);
+```
 
-**Returns:**
-- `data`: Workflow status object
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+#### Custom Shadow Utilities
 
-### `useGetWorksheets(options?)`
+```
+.shadow-soft-xs      → Subtle card shadow
+.shadow-card         → Multi-layer card shadow
+.shadow-card-hover   → Elevated hover state
+```
 
-Fetches all available worksheets.
+### Chart Colors
 
-**Parameters:**
-- `options` (optional): Query options
+```css
+--chart-1: oklch(0.55 0.15 255);  /* Blue */
+--chart-2: oklch(0.62 0.12 175);  /* Teal */
+--chart-3: oklch(0.70 0.13 80);   /* Green */
+--chart-4: oklch(0.55 0.14 295);  /* Purple */
+--chart-5: oklch(0.62 0.12 15);   /* Red */
+```
 
-**Returns:**
-- `data`: Array of worksheet objects
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+## Build System
 
-### `useGetWorksheetsByType(worksheetType, options?)`
+### Vite + Module Federation
 
-Fetches worksheets filtered by type.
+```
+Build Output:
+  dist/assets/remoteEntry.js    ← Module Federation entry (SystemJS format)
+  dist/assets/remoteEntry.css   ← Single bundled CSS file
+```
 
-**Parameters:**
-- `worksheetType`: Type of worksheets to fetch
-- `options` (optional): Query options
+- **Federation name**: `__copa_ext_app__react_route`
+- **Exposed module**: `./App` → `./app/single-spa.tsx`
+- **Shared**: `react`, `react-dom` (externalized in build)
+- **Format**: SystemJS (for single-spa compatibility)
+- **CSS**: Single file, no code splitting
 
-**Returns:**
-- `data`: Array of worksheet objects
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+### TypeScript Config
 
-### `useRunDefinition(definitionId, options?)`
+- Path alias: `~/` → `./app/` (via `tsconfig.json` paths + `vite-tsconfig-paths`)
+- Target: ES2020, JSX: react-jsx, strict mode
 
-Executes a run definition.
+### Docker
 
-**Parameters:**
-- `definitionId`: ID of the run definition
-- `options` (optional): Query options
+```bash
+docker build -t bluecopa-mfe .
+# Serves dist/ via lightweight HTTP server
+```
 
-**Returns:**
-- `data`: Execution result
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+## MFE Integration
 
-### `useRunPublishedDefinition(publishedDefinitionId, options?)`
+### How the Host App Loads This MFE
 
-Executes a published run definition.
+```javascript
+// 1. Load Module Federation entry
+System.import("__copa_ext_app__react_route/App");
 
-**Parameters:**
-- `publishedDefinitionId`: ID of the published definition
-- `options` (optional): Query options
+// 2. Register with single-spa
+registerApplication({
+  name: "bluecopa-preview",
+  app: () => System.import("__copa_ext_app__react_route/App"),
+  activeWhen: ["/app/external"],
+  customProps: {
+    apiBaseUrl: "https://develop.bluecopa.com/api/v1",
+    accessToken: "eyJ...",
+    workspaceId: "prod",
+    userId: "user-123",
+  },
+});
+```
 
-**Returns:**
-- `data`: Execution result
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+### Single-spa Lifecycle
 
-### `useRunSampleDefinition(sampleDefinitionId, options?)`
+- **bootstrap**: No-op
+- **mount**: Creates React root in `#single-spa-application:bluecopa-preview`, renders `<MemoryRouter><App {...props} /></MemoryRouter>`
+- **unmount**: Calls `root.unmount()`
+- **errorBoundary**: Catches errors, renders fallback UI
 
-Executes a sample run definition.
+### Manual Mount API (for non-single-spa hosts)
 
-**Parameters:**
-- `sampleDefinitionId`: ID of the sample definition
-- `options` (optional): Query options
+```typescript
+import { manualMount, manualUnmount } from "./single-spa";
 
-**Returns:**
-- `data`: Sample execution result
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+await manualMount({
+  domElement: document.getElementById("mfe-container"),
+  apiBaseUrl: "https://...",
+  accessToken: "...",
+  workspaceId: "...",
+  userId: "...",
+  basename: "/app",
+});
+```
 
-### `useTriggerHttpWorkflow(workflowId, payload, options?)`
+## Charts (ECharts)
 
-Triggers an HTTP workflow execution.
+Chart components live in `app/components/charts/` and are powered by Apache ECharts via `echarts-for-react`. The `<ChartProvider>` in `app.tsx` bridges CSS design tokens to the ECharts theme.
 
-**Parameters:**
-- `workflowId`: ID of the workflow
-- `payload`: Request payload
-- `options` (optional): Query options
+### Architecture
 
-**Returns:**
-- `data`: Workflow execution response
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+| File | Purpose |
+|------|---------|
+| `chart-provider.tsx` | React context — registers ECharts theme from CSS tokens, auto-refreshes on theme change |
+| `chart-theme.ts` | Reads `--chart-*` vars from `.mfe-root`, converts OKLCH to hex, builds ECharts theme object |
+| `chart-utils.ts` | Composable option builders: `chartTooltip()`, `chartLegend()`, `chartGrid()`, `chartCategoryAxis()`, `chartValueAxis()`, `chartTitle()`, `chartAnimation()`, `chartColors()`, `formatChartValue()`, `formatChartCurrency()` |
+| `base-chart.tsx` | Thin wrapper around `echarts-for-react` with loading/empty states, accessibility, responsive resize |
+| `bar-chart.tsx` | Configurable bar chart (vertical/horizontal, stacked, click events, value labels) |
+| `donut-chart.tsx` | Donut/pie chart with center text, legend, slice interactions |
+| `index.ts` | Barrel exports |
 
-### `useTriggerWorkflow(workflowId, options?)`
+### Available Chart Components
 
-Triggers a workflow execution.
+#### BarChart
 
-**Parameters:**
-- `workflowId`: ID of the workflow
-- `options` (optional): Query options
+```tsx
+import { BarChart } from "~/components/charts";
+
+<BarChart
+  data={{
+    categories: ["Jan", "Feb", "Mar"],
+    series: [{ name: "Revenue", data: [4200, 3800, 5100] }],
+  }}
+  height={280}
+  horizontal={false}       // swap to horizontal bars
+  stacked={false}          // stack multiple series
+  showValues={false}       // show value labels on bars
+  showLegend={true}        // auto-shows if >1 series
+  formatValue={(v) => `$${(v / 1000).toFixed(1)}K`}
+  onBarClick={({ name, seriesName, value }) => console.log(name, value)}
+  loading={false}
+  empty={false}
+/>
+```
 
-**Returns:**
-- `data`: Workflow execution response
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+#### DonutChart
 
-### `useWorkbook(workbookId, options?)`
+```tsx
+import { DonutChart } from "~/components/charts";
+
+<DonutChart
+  data={{
+    items: [
+      { name: "Payroll", value: 42 },
+      { name: "Operations", value: 28 },
+      { name: "Marketing", value: 16 },
+    ],
+  }}
+  height={280}
+  centerText="100%"        // large text in donut center
+  centerSubText="Total"    // smaller text below center
+  thickness={60}           // donut ring thickness (%)
+  showLegend={true}
+  showLabels={false}       // show labels on slices
+  onSliceClick={(params) => console.log(params)}
+/>
+```
 
-Fetches workbook details by ID.
+#### BaseChart (escape hatch)
 
-**Parameters:**
-- `workbookId`: ID of the workbook
-- `options` (optional): Query options
+For custom ECharts configurations not covered by BarChart/DonutChart:
 
-**Returns:**
-- `data`: Workbook object
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+```tsx
+import { BaseChart } from "~/components/charts";
+import { chartTooltip, chartGrid, chartCategoryAxis, chartValueAxis } from "~/components/charts/chart-utils";
+
+<BaseChart
+  option={{
+    ...chartTooltip(),
+    ...chartGrid(),
+    xAxis: chartCategoryAxis(["A", "B", "C"]),
+    yAxis: chartValueAxis(),
+    series: [{ type: "line", data: [10, 20, 30], smooth: true }],
+  }}
+  height={300}
+  loading={false}
+  ariaLabel="Custom line chart"
+/>
+```
 
-### `useWorkflow(workflowId, options?)`
+### Chart Colors
 
-Fetches workflow configuration by ID.
+Defined as `--chart-1` through `--chart-5` in `.mfe-root` (app.css). Hardcoded hex fallbacks in `chart-theme.ts` ensure colors render even if CSS vars aren't resolved:
 
-**Parameters:**
-- `workflowId`: ID of the workflow
-- `options` (optional): Query options
+| Token | OKLCH | Hex Fallback | Color |
+|-------|-------|-------------|-------|
+| `--chart-1` | `oklch(0.55 0.15 255)` | `#2563eb` | Blue |
+| `--chart-2` | `oklch(0.62 0.12 175)` | `#0d9488` | Teal |
+| `--chart-3` | `oklch(0.70 0.13 80)` | `#ca8a04` | Gold |
+| `--chart-4` | `oklch(0.55 0.14 295)` | `#7c3aed` | Purple |
+| `--chart-5` | `oklch(0.62 0.12 15)` | `#dc2626` | Red |
 
-**Returns:**
-- `data`: Workflow configuration object
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+The theme auto-extends to 10 colors via tints/shades of the base 5.
 
-### `useWorksheet(worksheetId, options?)`
+### Adding New Chart Types
 
-Fetches worksheet details by ID.
+To add a new chart type (e.g., LineChart, PieChart), follow the pattern in `bar-chart.tsx`:
 
-**Parameters:**
-- `worksheetId`: ID of the worksheet
-- `options` (optional): Query options
+1. Create `app/components/charts/my-chart.tsx`
+2. Use `useMemo` to build an ECharts option from `chart-utils` helpers
+3. Render via `<BaseChart option={option} ... />`
+4. Export from `index.ts`
 
-**Returns:**
-- `data`: Worksheet object
-- `isLoading`: Boolean indicating loading state
-- `error`: Error object if request failed
-- `refetch`: Function to manually trigger refetch
+Source chart components from the Dream Light registry: `/Users/mahipat/projects/bluecopa/shadcn-ui-registry/src/components/charts/`
 
+## Toast Notifications
 
-## Configuration
+Uses [Sonner](https://sonner.emilkowal.dev/) for toast notifications. The `<Toaster />` component is rendered in `app.tsx`.
 
-### Default Query Configuration
+### Usage
 
 ```tsx
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      retry: 3,
-      staleTime: 1000 * 60 * 5, // 5 minutes
-      gcTime: 1000 * 60 * 10, // 10 minutes
-    },
-  },
-});
-```
+import { toast } from "sonner";
 
-### Customizable Parameters
+// Success
+toast.success("Record saved", { description: "Changes applied." });
 
-All hooks accept standard TanStack React Query options:
+// Error
+toast.error("Failed to save", { description: "Check your connection." });
 
-```ts
-interface QueryOptions {
-  enabled?: boolean;        // Enable/disable query
-  staleTime?: number;      // Duration (ms) before data is stale
-  gcTime?: number;         // Duration (ms) to keep data in cache
-  retry?: number | boolean; // Number of retries or disable retries
-  onSuccess?: (data: any) => void; // Success callback
-  onError?: (error: Error) => void; // Error callback
-}
-```
+// Warning
+toast.warning("Unsaved changes");
 
-## Advanced Usage
+// Info
+toast.info("New data available");
 
-### Error Handling
+// With action
+toast("Item deleted", {
+  action: { label: "Undo", onClick: () => undoDelete() },
+});
 
-```tsx
-useUser({
-  onError: (error) => {
-    console.error('User fetch failed:', error.message);
-    // Custom error recovery logic
-  }
+// Promise (loading → success/error)
+toast.promise(saveData(), {
+  loading: "Saving...",
+  success: "Saved!",
+  error: "Failed to save",
 });
 ```
 
-### Manual Refetching
+### Toaster Config
+
+The `<Toaster />` component from `~/components/ui/sonner` is pre-configured with Dream Light theme tokens. It renders in the app root (`app.tsx`) and is available globally — no additional setup needed.
+
+## Coding Conventions
+
+### Component Pattern
 
 ```tsx
-function ManualRefetch() {
-  const { data, refetch } = useUser();
-  
+import { cn } from "~/utils/utils";
+
+interface MyComponentProps {
+  className?: string;
+  children: React.ReactNode;
+}
+
+export function MyComponent({ className, children }: MyComponentProps) {
   return (
-    <div>
-      <button onClick={() => refetch()}>Refresh</button>
+    <div className={cn("copa:flex copa:items-center copa:gap-2", className)}>
+      {children}
     </div>
   );
 }
 ```
 
-## Re-exports
-
-This package re-exports core TanStack React Query utilities:
-
-```ts
-import { 
-  useQuery,
-  useMutation,
-  QueryClient,
-  QueryClientProvider,
-  ReactQueryDevtools 
-} from '@bluecopa/react';
-```
-
-### Styling Guidelines
-- Use Tailwind CSS classes
-- Leverage CSS variables for theming
-- Follow mobile-first responsive design
-- Use `cn()` utility for conditional classes
-
-## 📊 Data Visualization
-
-### Charts (Recharts)
-- Interactive charts with hover states
-- Responsive design
-- Customizable colors via CSS variables
-- Accessible with proper ARIA labels
-
-### Tables (TanStack Table)
-- Sortable columns
-- Filtering capabilities
-- Pagination support
-- Row selection
-- Custom cell renderers
-
-## 🎯 Common Tasks & Solutions
-
-### Adding New Pages
-1. Create route file in `app/routes/`
-2. Export default component
-3. Add navigation link in sidebar
-4. Implement proper TypeScript types
-
-### Adding New Components
-1. Add components from either registry:
-   - Bluecopa UI: `pnpm dlx shadcn@latest add @bluecopa-ui/component-name`
-   - shadcn/ui: `pnpm dlx shadcn@latest add component-name`
-2. Components are installed in `app/components/ui/`
-3. Prefer Bluecopa UI registry for Bluecopa-specific components
-4. Use shadcn/ui registry for standard components not available in Bluecopa UI
-5. Define TypeScript interface for props if extending components
-6. Implement responsive design
-7. Add proper accessibility attributes
-
-### Working with Forms
-1. Use form components from either registry:
-   - Bluecopa UI: `pnpm dlx shadcn@latest add @bluecopa-ui/form`
-   - shadcn/ui: `pnpm dlx shadcn@latest add form`
-2. Prefer Bluecopa UI form components when available
-3. Implement validation with Zod
-4. Handle form state with React hooks
-5. Show loading and error states
-6. Use proper form semantics
-
-### API Integration
-1. Use `@bluecopa/react` hooks
-2. Handle loading states
-3. Implement error boundaries
-4. Use TanStack Query for caching
-5. Add optimistic updates where appropriate
-
-## 🚀 Performance Optimization
-
-### Code Splitting
-- Use React.lazy() for route-based splitting
-- Implement proper loading states
-- Avoid unnecessary re-renders
-
-### Bundle Optimization
-- Use Vite's built-in optimizations
-- Implement proper tree shaking
-- Optimize images and assets
-
-### Runtime Performance
-- Use React.memo() for expensive components
-- Implement proper key props
-- Avoid inline object/function creation
-
-## 🧪 Testing Strategies
-
-### Component Testing
-- Test component behavior, not implementation
-- Use React Testing Library
-- Mock external dependencies
-- Test accessibility features
-
-### Integration Testing
-- Test user workflows
-- Mock API responses
-- Test error scenarios
-- Verify responsive behavior
-
-## 🔒 Security Considerations
-
-### Data Handling
-- Sanitize user inputs
-- Validate data on client and server
-- Use proper TypeScript types
-- Implement proper error handling
-
-## 📱 Responsive Design
-
-### Breakpoints
-- Mobile-first approach
-- Use Tailwind's responsive prefixes
-- Test on multiple devices
-- Implement touch-friendly interactions
-
-### Layout Patterns
-- Use CSS Grid and Flexbox
-- Implement proper spacing
-- Handle overflow scenarios
-- Ensure proper scrolling
-
-## 🌙 Dark Mode Implementation
-
-### Theme System
-- Use next-themes for theme switching
-- Implement CSS variables for colors
-- Test both light and dark modes
-- Ensure proper contrast ratios
-
-### Component Theming
-- Use semantic color tokens
-- Implement proper hover states
-- Test theme transitions
-- Ensure accessibility compliance
-
-## 🐛 Debugging Tips
-
-### Common Issues
-- Check TypeScript errors first
-- Verify component imports
-- Check Tailwind class names
-- Validate API responses
-
-### Development Tools
-- Use React DevTools
-- Leverage Vite's HMR
-- Check browser console
-- Use TypeScript strict mode
-
-## 📚 Useful Resources
-
-### Documentation
-- [React Router v7 Docs](https://reactrouter.com/)
-- [Bluecopa UI Registry](https://blui.vercel.app)
-- [shadcn/ui Components](https://ui.shadcn.com/)
-- [Tailwind CSS v4](https://tailwindcss.com/)
-- [TanStack Table](https://tanstack.com/table)
-- [Recharts](https://recharts.org/)
-
-### Bluecopa Specific
-- [@bluecopa/react Package](packages/react:1)
-- Bluecopa Design System
-- API Integration Patterns
-
-## 🎯 Best Practices Summary
-
-1. **Always use TypeScript** - Define proper interfaces and types
-2. **Use appropriate registry** - Prefer Bluecopa UI (`@bluecopa-ui/component-name`) for Bluecopa-specific components, use shadcn/ui (`component-name`) for standard components
-3. **Follow component patterns** - Use established component structure from both registries
-4. **Implement accessibility** - Use semantic HTML and ARIA attributes
-5. **Optimize for performance** - Use proper React patterns and code splitting
-6. **Test thoroughly** - Write tests for components and user workflows
-7. **Handle errors gracefully** - Implement proper error boundaries and fallbacks
-8. **Follow responsive design** - Mobile-first approach with proper breakpoints
-9. **Use proper state management** - Choose appropriate patterns for different data types
-10. **Implement proper loading states** - Show feedback during async operations
-11. **Follow security best practices** - Validate inputs and secure API calls
-
-## 🔄 Common Workflows
-
-### Adding a New Feature
-1. Create feature branch
-2. Add required UI components from appropriate registry:
-   - Bluecopa UI: `pnpm dlx shadcn@latest add @bluecopa-ui/component-name`
-   - shadcn/ui: `pnpm dlx shadcn@latest add component-name`
-3. Implement components with TypeScript
-4. Add proper styling with Tailwind
-5. Implement responsive design
-6. Add tests
-7. Update documentation
-8. Test in both light and dark modes
-
-### Debugging Issues
-1. Check browser console for errors
-2. Verify TypeScript compilation
-3. Test component isolation
-4. Check API responses
-5. Verify responsive behavior
-6. Test accessibility features
-
-This guide should help AI assistants and developers work effectively with this Bluecopa React template, ensuring consistent patterns and best practices are followed throughout development.
+### Adding a New Page
+
+1. Create page in `app/pages/my-page.tsx`
+2. Add route in `app/routes/index.tsx` inside the `<Route element={<AppLayout />}>` group
+3. Add navigation item in `app/components/layouts/app-sidebar.tsx`
+
+### Adding a New UI Component
+
+```bash
+# Preferred: Dream Light registry
+pnpm dlx shadcn@latest add @bluecopa-ui/component-name
+
+# Fallback: standard shadcn
+pnpm dlx shadcn@latest add component-name
+```
+
+Components install to `app/components/ui/` with `copa:` prefix pre-configured.
+
+### Icons
+
+Use `lucide-react` or `@tabler/icons-react` (both available).
+
+### State Management
+
+- **Server state**: `@bluecopa/react` hooks (React Query)
+- **App context**: `useAppContext()` for user/workspace/settings
+- **Local state**: `useState` / `useReducer`
+- **No global state library** — keep it simple
+
+### Responsive Design
+
+- Mobile breakpoint: 768px (`useIsMobile()` hook)
+- Sidebar: Desktop = collapsible panel, Mobile = sheet overlay
+- Use `copa:md:` prefix for desktop-only styles
+
+### Important Gotchas
+
+1. **Prefix order**: `copa:` MUST come before any variant. `copa:hover:bg-accent` not `hover:copa:bg-accent`
+2. **`@theme` is build-time**: Cannot reference `.mfe-root` CSS variables in `@theme` blocks. Use `@theme inline` for runtime bindings.
+3. **`.mfe-root` not `:root`**: All CSS variables scoped to `.mfe-root` for MFE isolation
+4. **Breakpoints with prefix**: Must explicitly define `--breakpoint-*` vars in `@theme` (Tailwind v4 doesn't auto-include them with prefix)
+5. **ReactQueryDevtools**: Only rendered in dev mode (`import.meta.env.DEV`)
+6. **Config before queries**: `copaSetConfig()` must complete before React Query hooks fire. The app gates rendering behind `isConfigured` state.