@machinemetrics/mm-react-components 0.2.3-3 → 0.2.3-30

package/README.md

@@ -1,5 +1,7 @@
 # @machinemetrics/mm-react-components
 
+> **🤖 FOR AI AGENTS:** This library has [extensive AI agent documentation](./agent-docs/agent-documentation-reference.md) for setup and Chakra UI migration. See the [`agent-docs/`](./agent-docs/) folder for comprehensive guides.
+
 A comprehensive React component library designed specifically for MachineMetrics industrial and manufacturing applications.
 
 ## Features
@@ -10,6 +12,7 @@ A comprehensive React component library designed specifically for MachineMetrics
 - 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
 - ♿ **Accessible**: WCAG 2.1 AA compliant components
 - 🚀 **Performance**: Optimized for real-time data display and monitoring
+- 🤖 **AI-Agent Ready**: [Comprehensive AI agent documentation](./agent-docs/) with automated setup and migration tools
 
 ## Installation
 
@@ -17,6 +20,37 @@ A comprehensive React component library designed specifically for MachineMetrics
 npm install @machinemetrics/mm-react-components
 ```
 
+**Required Dependencies:**
+
+- React 19+
+- React DOM 19+
+
+**Optional Dependencies (only if using `/themes/carbide`):**
+
+- Tailwind CSS 4.0+
+- PostCSS 8.5+
+- Autoprefixer 10+
+
+> 💡 **Note:** When using `/styles` (recommended), no build tools are required! The CSS is fully compiled.
+
+## 🤖 For AI Agents
+
+**This library has comprehensive documentation for AI-assisted development!**
+
+- **New Project Setup:** [`agent-docs/ai-agent-init-guide.md`](./agent-docs/ai-agent-init-guide.md)
+- **Chakra UI Migration:** [`agent-docs/ai-agent-guide.md`](./agent-docs/ai-agent-guide.md)
+- **Component Mappings (83 components):** [`agent-docs/component-mapping-summary.md`](./agent-docs/component-mapping-summary.md)
+- **Full Documentation Index:** [`agent-docs/agent-documentation-reference.md`](./agent-docs/agent-documentation-reference.md)
+
+**Automated Tools:**
+
+- ✅ Init script: `npx @machinemetrics/mm-react-components init`
+- ✅ Migration script: `npx @machinemetrics/mm-react-components chakra-to-shadcn`
+- ✅ 98% automation rate for Chakra UI conversion
+- ✅ Zero-config setup option (no build tools needed!)
+
+---
+
 ## Quick Start
 
 ### 🚀 Automated Setup (Recommended)
@@ -43,13 +77,23 @@ This will automatically:
 
 If you prefer manual setup:
 
-#### 1. Install Dependencies
+#### 1. Install the Library
 
 ```bash
-npm install @machinemetrics/mm-react-components tailwindcss postcss autoprefixer
+npm install @machinemetrics/mm-react-components
 ```
 
-#### 2. Configure Tailwind CSS
+**Optional:** Only install Tailwind if you want to use `/themes/carbide` instead of `/styles`:
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+```
+
+#### 2. (Optional) Configure Tailwind CSS
+
+> 💡 Skip this step if using `/styles` - Tailwind configuration is not needed!
+
+**Only if using `/themes/carbide`:**
 
 ```bash
 cp node_modules/@machinemetrics/mm-react-components/tailwind.config.export.js tailwind.config.js
@@ -57,29 +101,22 @@ cp node_modules/@machinemetrics/mm-react-components/tailwind.config.export.js ta
 
 Note: The exported config is the main config (no preview-only utilities). The preview app in this repo uses a separate `tailwind.preview.config.js` that imports the main config and adds preview utilities.
 
-#### 3. Import Theme (Recommended: JS imports)
+#### 3. Import Styles
 
-Use app-level JavaScript/TypeScript imports so bundlers resolve package subpaths consistently and you can toggle themes at runtime:
+Import the complete styles including Tailwind CSS, base styles, and Carbide theme:
 
 ```ts
 // In your main entry (e.g., src/main.tsx)
 import '@machinemetrics/mm-react-components/styles';
-import '@machinemetrics/mm-react-components/themes/carbide';
 document.documentElement.classList.add('carbide');
 ```
 
-Alternatively, you can import the complete theme in CSS:
+**What's included in `/styles` (118 KB, 18 KB gzipped):**
 
-```css
-@import '@machinemetrics/mm-react-components/themes/complete';
-```
-
-**What's included:**
-
-- ✅ Tailwind CSS reset
+- ✅ Tailwind CSS reset and utilities (compiled)
 - ✅ Base theme variables (OKLCH color system)
 - ✅ Carbide industrial theme
-- ✅ All component styles
+- ✅ All component styles (focus states, rings, borders, etc.)
 - ✅ Dark mode support
 - ✅ Animations and utilities
 
@@ -100,9 +137,18 @@ function App() {
 
 ### 📚 Documentation
 
+**For AI Agents:**
+
+- [AI Agent Documentation Hub](./agent-docs/agent-documentation-reference.md) - Start here!
+- [Setup Guide for AI Agents](./agent-docs/ai-agent-init-guide.md)
+- [Chakra Migration for AI Agents](./agent-docs/ai-agent-guide.md)
+
+**For Developers:**
+
 - [Getting Started Guide](./docs/GETTING_STARTED.md) - Complete setup guide
 - [Tailwind Setup Guide](./docs/TAILWIND_SETUP.md) - Detailed configuration
-- [Quick Start Template](./templates/quick-start.html) - Live demo
+- [Chakra Migration Guide](./docs/CHAKRA_MIGRATION_GUIDE.md) - Detailed migration reference
+- [Component Mapping Summary](./docs/COMPONENT_MAPPING_SUMMARY.md) - All 83 component mappings
 
 ## Theme System
 
@@ -122,24 +168,40 @@ The component library includes a comprehensive theme system with two main themes
 - Enhanced component styling for industrial applications
 - Complete dark mode support
 
-### Using Themes
+### Import Options
+
+#### Option 1: Complete Styles (Recommended - 118 KB gzipped)
 
-#### Option 1: JS Imports (Recommended)
+Import everything including Tailwind utilities, theme, and animations:
 
 ```ts
 import '@machinemetrics/mm-react-components/styles';
-import '@machinemetrics/mm-react-components/themes/carbide';
 document.documentElement.classList.add('carbide');
 ```
 
-#### Option 2: Manual Theme Import
+**Includes:**
 
-```css
-/* Import themes separately for more control */
-@import '@machinemetrics/mm-react-components/themes/base';
-@import '@machinemetrics/mm-react-components/themes/carbide';
+- ✅ All Tailwind utilities (compiled)
+- ✅ Carbide theme variables
+- ✅ Component styles with focus states
+- ✅ Dark mode support
+- ✅ Animations
+
+#### Option 2: Theme Only (41 KB - if you already have Tailwind)
+
+Import just the Carbide theme variables and component overrides:
+
+```ts
+import '@machinemetrics/mm-react-components/themes/carbide';
+document.documentElement.classList.add('carbide');
 ```
 
+**Use this if:**
+
+- You already have Tailwind CSS in your project
+- You want to minimize bundle size
+- You're using our components with your own Tailwind config
+
 #### Option 3: Use Theme Utilities
 
 ```tsx
@@ -250,16 +312,13 @@ This includes:
 ### Alternative Import Methods
 
 ```css
-/* Import base theme only */
-@import '@machinemetrics/mm-react-components/themes/base';
-
-/* Import Carbide theme for industrial styling */
-@import '@machinemetrics/mm-react-components/themes/carbide';
+/* Import complete styles including Carbide theme */
+@import '@machinemetrics/mm-react-components/styles';
 ```
 
 ```tsx
 // Import in JavaScript/TypeScript
-import '@machinemetrics/mm-react-components/themes/complete';
+import '@machinemetrics/mm-react-components/styles';
 ```
 
 ## TypeScript Support

package/agent-docs/agent-documentation-reference.md

@@ -0,0 +1,401 @@
+# AI Agent Documentation Reference
+
+> **🤖 AI AGENT NOTE:** This documentation is designed to be automatically discoverable. AI agents should find this via:
+>
+> - The main `README.md` with prominent AI agent section at the top
+> - This `agent-docs/` folder with descriptive naming
+> - Package.json exports this folder as `./agent-docs`
+
+## Library Foundation
+
+**@machinemetrics/mm-react-components** is a **traditional npm package** built on **[shadcn/ui](https://ui.shadcn.com/)** components (Radix UI + Tailwind CSS) with the Carbide industrial theme.
+
+**What this means for you:**
+
+- ✅ **Standard npm install**: `npm install @machinemetrics/mm-react-components`
+- ✅ **Import components**: `import { Button, DataTable } from '@machinemetrics/mm-react-components'`
+- ✅ **Pre-packaged & themed**: All components ready with Carbide industrial design
+- ✅ **Zero-config option**: Pre-compiled CSS included (no build tools required)
+- ✅ **Accessible & typed**: Full TypeScript support with Radix UI accessibility
+
+### Key Technologies
+
+- **React 19**: Latest React with modern patterns
+- **TypeScript 5**: Strict type safety throughout
+- **Tailwind CSS v4**: Modern CSS-first configuration (pre-compiled in distributed CSS)
+- **Radix UI**: Headless, accessible component primitives
+- **shadcn/ui**: Component foundation and patterns
+- **Carbide**: Industrial design system for manufacturing contexts
+
+## Overview
+
+This directory contains comprehensive documentation and tools for AI agents working with the MachineMetrics React Components library. The documentation is organized into two main categories: **Initialization Setup** and **Chakra UI Migration**.
+
+## Component Quick Reference
+
+### Core Components (shadcn/ui based)
+
+| Component       | Exports                        | Description                               |
+| --------------- | ------------------------------ | ----------------------------------------- |
+| **Button**      | `Button`, `buttonVariants`     | Primary interactive element with variants |
+| **Input**       | `Input`                        | Text input field                          |
+| **SearchInput** | `SearchInput`                  | Search-specific input with icon           |
+| **Label**       | `Label`                        | Form label component                      |
+| **Checkbox**    | `Checkbox`                     | Checkbox input                            |
+| **RadioGroup**  | `RadioGroup`, `RadioGroupItem` | Radio button groups                       |
+| **Switch**      | `Switch`                       | Toggle switch control                     |
+| **Slider**      | `Slider`, `LabeledSlider`      | Range slider with optional label          |
+| **Toggle**      | `Toggle`                       | Toggle button                             |
+| **Textarea**    | `Textarea`                     | Multi-line text input                     |
+
+### Layout & Navigation
+
+| Component      | Exports                                                                                                                           | Description                               |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
+| **Card**       | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`                                                 | Content container with sections           |
+| **Separator**  | `Separator`                                                                                                                       | Visual divider                            |
+| **Tabs**       | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`                                                                                  | Tabbed interface                          |
+| **Breadcrumb** | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | Navigation breadcrumbs                    |
+| **PageHeader** | `PageHeader` (+ types)                                                                                                            | Application page header with actions/tabs |
+
+### Overlays & Modals
+
+| Component       | Exports                                                                                                                                                                                                                                | Description                     |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| **Dialog**      | `Dialog`, `DialogClose`, `DialogContent`, `DialogDescription`, `DialogFooter`, `DialogHeader`, `DialogOverlay`, `DialogPortal`, `DialogTitle`, `DialogTrigger`                                                                         | Modal dialog                    |
+| **AlertDialog** | `AlertDialog`, `AlertDialogPortal`, `AlertDialogOverlay`, `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogHeader`, `AlertDialogFooter`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogAction`, `AlertDialogCancel` | Confirmation dialog             |
+| **Sheet**       | `Sheet`, `SheetTrigger`, `SheetClose`, `SheetContent`, `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`                                                                                                                  | Slide-out panel                 |
+| **Drawer**      | `Drawer`, `DrawerTrigger`, `DrawerClose`, `DrawerPortal`, `DrawerOverlay`, `DrawerContent`, `DrawerHeader`, `DrawerFooter`, `DrawerTitle`, `DrawerDescription`, `DrawerHandle`                                                         | Bottom drawer (mobile-friendly) |
+| **Popover**     | `Popover`, `PopoverTrigger`, `PopoverContent`                                                                                                                                                                                          | Floating content container      |
+| **Tooltip**     | `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`                                                                                                                                                                       | Hover tooltips                  |
+
+### Menus & Dropdowns
+
+| Component        | Exports                                                                                                                                                                                                                                                                                                                                                 | Description          |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| **DropdownMenu** | `DropdownMenu`, `DropdownMenuPortal`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuGroup`, `DropdownMenuLabel`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuSeparator`, `DropdownMenuShortcut`, `DropdownMenuSub`, `DropdownMenuSubTrigger`, `DropdownMenuSubContent` | Dropdown menu system |
+| **Select**       | `Select`, `SelectContent`, `SelectGroup`, `SelectItem`, `SelectLabel`, `SelectScrollDownButton`, `SelectScrollUpButton`, `SelectSeparator`, `SelectTrigger`, `SelectValue`                                                                                                                                                                              | Select dropdown      |
+
+### Data Display
+
+| Component          | Exports                                                                                                  | Description                                              |
+| ------------------ | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| **Badge**          | `Badge`, `badgeVariants`                                                                                 | Status/label badges                                      |
+| **Avatar**         | `Avatar`, `AvatarImage`, `AvatarFallback`                                                                | User avatar with fallback                                |
+| **Alert**          | `Alert`, `AlertTitle`, `AlertDescription`                                                                | Alert messages                                           |
+| **Table**          | `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`, `TableCell`, `TableCaption` | Basic table structure                                    |
+| **Skeleton**       | `Skeleton`                                                                                               | Loading placeholder                                      |
+| **Progress**       | `Progress`                                                                                               | Progress bar                                             |
+| **Spinner**        | `Spinner`                                                                                                | Basic loading spinner                                    |
+| **SpinnerCarbide** | `SpinnerCarbide`                                                                                         | Industrial-themed loading spinner with Carbide semantics |
+
+### Advanced Components
+
+| Component           | Exports                                                                                                                           | Description                                                                              |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| **DataTable**       | `DataTable`, `DataTablePagination`, `ResponsiveTable`, `TABLE_TOKENS`, column creators, hooks, toolbar, CSV export (+ types)      | Full-featured data table with sorting, filtering, pagination (client-side & server-side) |
+| **HeroMetricCard**  | `HeroMetricCard`, `HeroMetricCardItem` (+ types)                                                                                  | Metrics dashboard card with trends                                                       |
+| **Calendar**        | `Calendar`                                                                                                                        | Date picker calendar                                                                     |
+| **DatePicker**      | `DatePicker`                                                                                                                      | Single date selection with label and placeholder                                         |
+| **DateRangePicker** | `DateRangePicker`                                                                                                                 | Date range selection                                                                     |
+| **Dropzone**        | `Dropzone`, `DropzoneContent`, `DropzoneEmptyState`                                                                               | File upload drag-drop                                                                    |
+| **Chart**           | `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartStyle` (+ `ChartConfig` type) | Recharts integration                                                                     |
+
+### Interactive Elements
+
+| Component       | Exports                                                                                                       | Description                  |
+| --------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| **Accordion**   | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`                                          | Collapsible sections         |
+| **Collapsible** | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`                                                     | Simple collapse/expand       |
+| **Form**        | `useFormField`, `Form`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage`, `FormField` | React Hook Form integration  |
+| **Toaster**     | `Toaster`                                                                                                     | Toast notifications (Sonner) |
+
+### Utilities
+
+| Export          | Description                                                                                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `cn`            | Class name utility for merging Tailwind classes                                                                                                                                |
+| **Theme Utils** | `activateCarbideTheme`, `deactivateCarbideTheme`, `toggleCarbideTheme`, `isCarbideThemeActive`, `activateDarkMode`, `deactivateDarkMode`, `toggleDarkMode`, `isDarkModeActive` |
+
+### Total: 42+ Components
+
+All components follow shadcn/ui patterns with Carbide theme integration for industrial/manufacturing contexts.
+
+## Component Usage Guides
+
+### DataTable: Server-Side Pagination
+
+The `DataTable` component supports both client-side and server-side pagination. When implementing server-side pagination, use the following pattern:
+
+**Key Props for Server-Side Pagination:**
+
+- `manualPagination={true}` - Enables server-side pagination mode
+- `pageCount={number}` - **Required** when `manualPagination` is true. Total number of pages from server
+- `totalRowCount={number}` - **Recommended** for accurate display. Total rows across all pages
+- `onPaginationChange={(pageIndex, pageSize) => void}` - Callback to fetch new page data
+
+**Implementation Pattern:**
+
+```tsx
+<DataTable
+  columns={columns}
+  data={currentPageData} // Only current page's data
+  manualPagination={true}
+  pageCount={totalPages} // From server response
+  totalRowCount={totalRows} // From server response (recommended)
+  onPaginationChange={(pageIndex, pageSize) => {
+    // Fetch new page from server
+    fetchPage(pageIndex, pageSize);
+  }}
+/>
+```
+
+**Important Notes for AI Agents:**
+
+1. When `manualPagination` is true, the `data` prop should contain **only the current page's data**, not all data
+2. `pageCount` is required when using server-side pagination
+3. `totalRowCount` is recommended for accurate "Showing X to Y of Z items" display
+4. The component automatically handles edge cases (empty data, partial last page, etc.)
+5. See component README at `src/components/ui/data-table/README.md` for detailed examples
+
+## Directory Structure
+
+```
+agent-docs/
+├── agent-documentation-reference.md    # This reference file
+├── ai-agent-init-guide.md              # Main init setup guide
+├── setup-reference.md                  # Detailed setup reference
+├── init-troubleshooting.md             # Init setup troubleshooting
+├── init-readme.md                      # Init setup overview
+├── ai-agent-guide.md                   # Chakra migration guide
+├── component-mapping-reference.md      # Chakra migration reference
+├── chakra-migration-troubleshooting.md # Chakra migration troubleshooting
+└── chakra-migration-readme.md          # Chakra migration overview
+```
+
+## Documentation Categories
+
+### 1. Initialization Setup Documentation
+
+#### **ai-agent-init-guide.md**
+
+- **Purpose**: Comprehensive guide for AI agents on library setup
+- **Use Case**: When AI agents need to initialize the MachineMetrics React Components library
+- **Key Features**:
+  - Zero-config setup (no build tools required)
+  - Automated setup procedures
+  - Framework-specific instructions (React, Next.js, Vite)
+  - Troubleshooting guidance
+  - Validation checklists
+- **Target Audience**: AI agents performing automated setup
+- **When to Use**: Primary resource for init script setup
+
+#### **setup-reference.md**
+
+- **Purpose**: Detailed reference for setup procedures
+- **Use Case**: When AI agents need specific technical details about setup
+- **Key Features**:
+  - Complete dependency list
+  - Configuration file templates
+  - Framework-specific setup instructions
+  - Component usage patterns
+  - Performance optimization
+- **Target Audience**: AI agents needing technical reference
+- **When to Use**: Technical reference during setup or troubleshooting
+
+#### **init-troubleshooting.md**
+
+- **Purpose**: Common issues and solutions for init script problems
+- **Use Case**: When the init script fails or encounters issues
+- **Key Features**:
+  - Script execution issues
+  - Dependency installation problems
+  - Configuration issues
+  - Build and runtime problems
+  - Framework-specific troubleshooting
+- **Target Audience**: AI agents debugging setup issues
+- **When to Use**: When automated setup fails or encounters errors
+
+#### **init-readme.md**
+
+- **Purpose**: Overview and usage instructions for init setup
+- **Use Case**: Quick reference for init setup process
+- **Key Features**:
+  - Quick start instructions
+  - File descriptions
+  - Usage examples
+  - Validation steps
+- **Target Audience**: AI agents needing quick overview
+- **When to Use**: Initial understanding of init setup process
+
+### 2. Chakra UI Migration Documentation
+
+#### **ai-agent-guide.md**
+
+- **Purpose**: Comprehensive guide for AI agents on Chakra UI to MachineMetrics migration
+- **Use Case**: When AI agents need to migrate existing Chakra UI components
+- **Key Features**:
+  - Automated migration procedures
+  - Manual conversion steps
+  - Component mapping instructions
+  - Icon migration guidance
+  - Validation checklists
+- **Target Audience**: AI agents performing Chakra UI migration
+- **When to Use**: Primary resource for Chakra UI migration
+
+#### **component-mapping-reference.md**
+
+- **Purpose**: Detailed reference of component mappings for Chakra UI migration
+- **Use Case**: When AI agents need specific component mapping information
+- **Key Features**:
+  - Complete component mapping tables
+  - Prop mapping references
+  - Styling conversion guides
+  - Icon mapping tables
+  - Migration patterns
+- **Target Audience**: AI agents needing component mapping details
+- **When to Use**: Technical reference during Chakra UI migration
+
+#### **chakra-migration-troubleshooting.md**
+
+- **Purpose**: Common issues and solutions for Chakra UI migration problems
+- **Use Case**: When Chakra UI migration encounters issues
+- **Key Features**:
+  - Import errors and solutions
+  - Theme and styling issues
+  - Layout problems
+  - API changes
+  - Icon issues
+  - Form component problems
+- **Target Audience**: AI agents debugging migration issues
+- **When to Use**: When Chakra UI migration fails or encounters errors
+
+#### **chakra-migration-readme.md**
+
+- **Purpose**: Overview and usage instructions for Chakra UI migration
+- **Use Case**: Quick reference for Chakra UI migration process
+- **Key Features**:
+  - Migration overview
+  - File descriptions
+  - Usage examples
+  - Troubleshooting tips
+- **Target Audience**: AI agents needing quick migration overview
+- **When to Use**: Initial understanding of Chakra UI migration process
+
+## Usage Patterns
+
+### For AI Agents
+
+#### **Initialization Setup Workflow**
+
+1. **Start with**: `ai-agent-init-guide.md` for comprehensive setup instructions
+2. **Reference**: `setup-reference.md` for technical details
+3. **Troubleshoot**: `init-troubleshooting.md` if issues arise
+4. **Overview**: `init-readme.md` for quick reference
+
+#### **Chakra UI Migration Workflow**
+
+1. **Start with**: `ai-agent-guide.md` for comprehensive migration instructions
+2. **Reference**: `component-mapping-reference.md` for component details
+3. **Troubleshoot**: `chakra-migration-troubleshooting.md` if issues arise
+4. **Overview**: `chakra-migration-readme.md` for quick reference
+
+### For Developers
+
+#### **Quick Start**
+
+- Use `init-readme.md` for setup overview
+- Use `chakra-migration-readme.md` for migration overview
+
+#### **Detailed Implementation**
+
+- Use `ai-agent-init-guide.md` for setup implementation
+- Use `ai-agent-guide.md` for migration implementation
+
+#### **Troubleshooting**
+
+- Use `init-troubleshooting.md` for setup issues
+- Use `chakra-migration-troubleshooting.md` for migration issues
+
+## File Relationships
+
+### **Init Setup Files**
+
+```
+ai-agent-init-guide.md (main guide)
+├── setup-reference.md (technical reference)
+├── init-troubleshooting.md (issue resolution)
+└── init-readme.md (overview)
+```
+
+### **Chakra Migration Files**
+
+```
+ai-agent-guide.md (main guide)
+├── component-mapping-reference.md (technical reference)
+├── chakra-migration-troubleshooting.md (issue resolution)
+└── chakra-migration-readme.md (overview)
+```
+
+## Package.json Exports
+
+The following files are exported via package.json for AI agent access:
+
+### **Init Setup Exports**
+
+- `./init/guide` → `ai-agent-init-guide.md`
+- `./init/reference` → `setup-reference.md`
+- `./init/troubleshooting` → `init-troubleshooting.md`
+- `./init/readme` → `init-readme.md`
+
+### **Chakra Migration Exports**
+
+- `./migration/config` → `chakra-to-shadcn.config.json`
+- `./migration/guide` → `ai-agent-guide.md`
+- `./migration/reference` → `component-mapping-reference.md`
+- `./migration/troubleshooting` → `chakra-migration-troubleshooting.md`
+- `./migration/readme` → `chakra-migration-readme.md`
+
+## Best Practices
+
+### **For AI Agents**
+
+1. **Always start with the main guide** for comprehensive instructions
+2. **Use reference files** for technical details and specific information
+3. **Check troubleshooting guides** when issues arise
+4. **Use fallback scripts** when automated tools fail
+5. **Validate setup** using provided checklists
+
+### **For Documentation Maintenance**
+
+1. **Keep guides updated** with new components and features
+2. **Update troubleshooting guides** with new issues and solutions
+3. **Maintain reference files** with current dependency versions
+4. **Test fallback scripts** regularly to ensure they work
+5. **Update package.json exports** when adding new files
+
+## Support and Resources
+
+### **Documentation**
+
+- [Component Library Docs](https://components.machinemetrics.com)
+- [API Reference](https://components.machinemetrics.com/api)
+- [Getting Started Guide](https://components.machinemetrics.com/getting-started)
+
+### **Community Support**
+
+- [GitHub Issues](https://github.com/machinemetrics/mm-react-components/issues)
+- [Discord Community](https://discord.gg/machinemetrics)
+- [Stack Overflow](https://stackoverflow.com/questions/tagged/machinemetrics)
+
+### **Professional Support**
+
+- [MachineMetrics Support](https://support.machinemetrics.com)
+- [Enterprise Support](https://enterprise.machinemetrics.com)
+- [Consulting Services](https://consulting.machinemetrics.com)
+
+## Conclusion
+
+This documentation reference provides a comprehensive overview of all AI agent documentation and tools available for the MachineMetrics React Components library. Use this as a guide to understand which files to use for specific tasks and how they relate to each other.
+
+For AI agents, this reference ensures you have access to all necessary documentation and tools to successfully set up and migrate components. For developers, this reference provides a clear understanding of the available resources and how to use them effectively.