# RootCX App Builder Skill

You are building a RootCX Build Mode application. Follow these guidelines precisely.

## When This Skill Activates

This skill activates when:
- User asks to create, build, or modify a RootCX app
- User wants to add components, data hooks, or integrations
- Working in a directory with `.rootcx/project.json`
- User mentions "Build Mode", "business app", or "RootCX"

## Critical Rules

1. **ALWAYS use Business Design System components** - Use `mcp__rootcx__search_components` and `mcp__rootcx__get_component_docs` to find the right components
2. **ALWAYS use `useAppCollection` for data** - Never use fetch() or direct API calls for data
3. **ALWAYS call `mcp__rootcx__verify_build` after writing files** - Only say "DONE" when it passes
4. **NEVER invent component names** - Search first, use exact names from docs

## Project Structure

```
project/
├── .rootcx/
│   └── project.json    # Project configuration (don't modify)
├── manifest.json       # App metadata and data contracts
├── App.tsx             # Main entry point (MUST have export default)
├── types/
│   └── index.ts        # TypeScript interfaces
├── components/         # Custom components
│   └── *.tsx
└── hooks/              # Custom hooks
    └── *.ts
```

## Component Usage

### Finding Components

```typescript
// ALWAYS search before using a component
mcp__rootcx__search_components({ query: "button" })
mcp__rootcx__search_components({ query: "table" })
mcp__rootcx__search_components({ query: "form" })
```

### Getting Documentation

```typescript
// Get full props and examples
mcp__rootcx__get_component_docs({ name: "BusinessButton" })
mcp__rootcx__get_component_docs({ name: "SheetTableOSView" })
```

### Import Pattern

```tsx
// Components are available globally - import from @/components/business
import {
  BusinessButton,
  BusinessCard,
  BusinessLayout,
  BusinessLayoutContent,
  BusinessText,
  BusinessTopBar,
} from '@/components/business';
```

## Data Hooks

### useAppCollection

The primary hook for all data operations:

```tsx
const {
  collection,    // { entities: T[], loading, error }
  loading,       // boolean
  create,        // (data: Partial<T>) => Promise<T>
  update,        // (id: string, data: Partial<T>) => Promise<T>
  delete: remove // (id: string) => Promise<void>
} = useAppCollection<Contact>('crm', 'contact');

// Access entities
const contacts = collection?.entities || [];
```

### Cross-App Data

```tsx
// Access data from ANY installed app
const { collection: invoices } = useAppCollection('invoices', 'invoice');
const { collection: tasks } = useAppCollection('taskmanager', 'task');
```

### Finding Available Data

```typescript
// List all apps in the organization
mcp__rootcx__list_installed_apps()

// Get schema for a specific app
mcp__rootcx__get_app_schema({ appId: "crm" })
```

## Integration Hooks

### Finding Integrations

```typescript
mcp__rootcx__list_integrations()
mcp__rootcx__get_integration_capabilities({ type: "gmail" })
```

### Using Integration Hooks

```tsx
// Gmail example
import { useGmailSend, useGmailThreads } from '@/hooks/integrations/gmail';

const { send, sending } = useGmailSend();
const { threads, loading } = useGmailThreads({ maxResults: 10 });
```

## App.tsx Template

```tsx
import React, { useState } from 'react';
import {
  BusinessLayout,
  BusinessLayoutContent,
  BusinessTopBar,
  BusinessButton,
  BusinessText,
  BusinessCard,
} from '@/components/business';

interface Item {
  id: string;
  name: string;
  // ... other fields
}

export default function App() {
  const { collection, create, update, delete: remove } = useAppCollection<Item>('appId', 'entityName');
  const items = collection?.entities || [];
  const loading = collection?.loading;

  if (loading) {
    return (
      <BusinessLayout>
        <BusinessLayoutContent padding="md">
          <BusinessText>Loading...</BusinessText>
        </BusinessLayoutContent>
      </BusinessLayout>
    );
  }

  return (
    <BusinessLayout
      header={
        <BusinessTopBar>
          <BusinessTopBar.Left>
            <BusinessText variant="title-small">My App</BusinessText>
          </BusinessTopBar.Left>
          <BusinessTopBar.Right>
            <BusinessButton onClick={() => create({ name: 'New Item' })}>
              Add Item
            </BusinessButton>
          </BusinessTopBar.Right>
        </BusinessTopBar>
      }
    >
      <BusinessLayoutContent padding="md">
        {items.map(item => (
          <BusinessCard key={item.id}>
            <BusinessText>{item.name}</BusinessText>
          </BusinessCard>
        ))}
      </BusinessLayoutContent>
    </BusinessLayout>
  );
}
```

## Build Verification

After EVERY file modification:

```typescript
mcp__rootcx__verify_build()
```

The tool will:
- Validate TypeScript/TSX syntax
- Check for required exports (App.tsx needs `export default`)
- Validate cross-file references

**Only say "DONE" when verify_build returns success!**

## Common Patterns

### Loading States

```tsx
if (loading) {
  return <BusinessLoadingSpinner />;
}
```

### Error Handling

```tsx
if (error) {
  return (
    <BusinessCard variant="destructive">
      <BusinessText>Error: {error.message}</BusinessText>
    </BusinessCard>
  );
}
```

### Empty States

```tsx
if (items.length === 0) {
  return (
    <BusinessEmptyState
      icon={<FolderIcon />}
      title="No items yet"
      description="Create your first item to get started"
      action={<BusinessButton onClick={handleCreate}>Create Item</BusinessButton>}
    />
  );
}
```

### Forms

```tsx
// Use BusinessForm components
<BusinessForm onSubmit={handleSubmit}>
  <BusinessFormField label="Name" required>
    <BusinessInput value={name} onChange={setName} />
  </BusinessFormField>
  <BusinessButton type="submit">Save</BusinessButton>
</BusinessForm>
```

### Tables

```tsx
// SheetTableOSView for data tables
<SheetTableOSView
  data={items}
  columns={[
    { key: 'name', label: 'Name' },
    { key: 'status', label: 'Status' },
  ]}
  onRowClick={(row) => handleSelect(row)}
/>
```

## Don'ts

- **DON'T** use raw HTML elements (div, span) - use Business components
- **DON'T** use fetch() for data - use useAppCollection
- **DON'T** hardcode API URLs - data comes from hooks
- **DON'T** skip verify_build - always validate before saying done
- **DON'T** invent component names - search and use exact names
- **DON'T** use external libraries without checking if Business Design System has an alternative

## Checklist Before Saying DONE

1. [ ] All components are from Business Design System
2. [ ] Data uses useAppCollection or integration hooks
3. [ ] App.tsx has `export default`
4. [ ] `verify_build` passes without errors
5. [ ] Code follows the patterns above