AI Configuration

Configure AI assistants using the centralized .ai folder system.

Overview

AppLighter uses a centralized .ai/ folder as the single source of truth for all AI configuration. This folder generates configuration files for Claude Code, Cursor, and other AI assistants automatically.

Never Edit Generated Files

Do not manually edit these auto-generated files:

• CLAUDE.md
• .cursorrules
• .claude/ folder
• .cursor/ folder

These files are automatically generated from the .ai/ folder and will be overwritten when you run npm run ai:sync.

Supported AI Editors

Claude Code

Claude Code is Anthropic's AI coding assistant that understands your codebase and helps you write, debug, and refactor code.

Generated config: CLAUDE.md and .claude/ folder

Key features:

• Slash commands (/new-screen, /new-component, etc.)
• Project context awareness
• Multi-file editing
• TodoWrite for task tracking

Basic usage:

# Ask about your codebase
claude "How does authentication work?"

# Generate new features
claude "Add a settings screen with dark mode toggle"

# Use slash commands
/new-screen
/new-component
/review

Cursor

Cursor is an AI-first code editor built on VS Code with intelligent code completion, chat, and editing features.

Generated config: .cursorrules and .cursor/ folder

Key features:

• Chat (Cmd+L) - Ask questions about your codebase
• Inline Edit (Cmd+K) - Select code and describe changes
• Composer (Cmd+I) - Multi-file edits and new features
• Rules for consistent code generation

Keyboard shortcuts:

| Shortcut | Action | |----------|--------| | Cmd+L | Open chat | | Cmd+K | Inline edit | | Cmd+I | Open composer | | Tab | Accept suggestion |

The .ai/ Folder

All AI configuration lives in the .ai/ folder at the project root:

.ai/
├── base.md                 # Core AI instructions (shared by all editors)
├── project.md              # Architecture documentation & code templates
├── scratchpad-template.md  # Template for working memory file
├── .claude/
│   └── base.md             # Claude Code specific additions
├── .cursor/
│   └── base.md             # Cursor specific additions
├── docs/                   # Reference documentation for AI
│   └── *.md
└── commands/               # Custom AI commands
    └── *.md

Sync Command

Generate AI configuration files from the .ai/ folder:

npm run ai:sync

What Gets Generated

| Source (edit this) | Output (auto-generated) | |-------------------|------------------------| | .ai/base.md + .ai/.claude/base.md | CLAUDE.md | | .ai/base.md + .ai/.cursor/base.md | .cursorrules | | .ai/project.md | .claude/PLAN.md, .cursor/PLAN.md | | .ai/scratchpad-template.md | SCRATCHPAD.md (created once) | | .ai/docs/*.md | .claude/docs/, .cursor/docs/ | | .ai/commands/*.md | .claude/commands/, .cursor/rules/ |

Example Output

$ npm run ai:sync

AI Sync

Entry points:
  → CLAUDE.md
  → .cursorrules

PLAN.md:
  → .claude/PLAN.md
  → .cursor/PLAN.md

Docs:
  → 3 files to .claude/docs/ & .cursor/docs/

Commands:
  → 5 files to .claude/commands/ & .cursor/rules/

✓ Done

File Reference

base.md - Core Instructions

The shared foundation for all AI assistants. This file is concatenated with editor-specific files to generate the final configuration.

Purpose: Define your tech stack, file conventions, coding rules, and patterns that apply to ALL AI assistants.

# AppLighter - AI Instructions

## Tech Stack

Expo 54, React Native 0.81, Expo Router 6, TanStack Query 5, NativeWind 4, Vibecode DB, TypeScript strict, lucide-react-native

## File Locations

| Type                | Location           | Export                        |
| ------------------- | ------------------ | ----------------------------- |
| Screens (protected) | `app/(app)/*.tsx`  | default                       |
| Screens (public)    | `app/(auth)/*.tsx` | default                       |
| Components          | `components/*.tsx` | named → `components/index.ts` |
| Hooks               | `src/hooks/*.ts`   | named → `src/hooks/index.ts`  |
| Schema              | `src/db/schema.ts` | inline                        |

## Do

- NativeWind `className` for all styling
- Check `{ error }` from all db operations
- Query keys: `['resource', userId]`
- Include `id`, `created_at`, `updated_at` on insert
- Export from index.ts
- `useCallback` for FlatList handlers
- `.limit(50)` for lists
- Filter by `user_id` for user data

## Don't

- `StyleSheet.create()` - use className
- Hardcoded colors - use theme variables
- `any` types - import from `src/db/client`
- Wrapper hooks for simple queries
- Expose raw errors - use `Alert.alert()`

project.md - Architecture & Templates

Detailed architecture documentation with data flow diagrams, auth flow, database operation examples, and ready-to-use code templates.

Purpose: Provide AI assistants with architecture context and copy-paste templates for consistent code generation.

# Architecture

## Data Flow

User Action → Component → useQuery/useMutation → vibecode client → Backend
                                    ↓
                            Query Cache (AsyncStorage)

## Auth Flow

App Start → _layout.tsx → getSession()
                ↓
         Has Session?
         ├─ Yes → /(app)/home
         └─ No  → /(auth)/signin

## Database Operations

// SELECT - chain: from → filters → order → limit → select
const { data, error } = await vibecode
  .from('posts')
  .eq('published', true)
  .order('created_at', { ascending: false })
  .limit(50)
  .select('*')
if (error) throw error

// INSERT
const { data, error } = await vibecode.from('posts').insert({
  id: crypto.randomUUID(),
  title,
  created_at: new Date().toISOString(),
  updated_at: new Date().toISOString(),
})

## Query Pattern

const query = useQuery({
  queryKey: ['posts', 'published'],
  queryFn: async () => {
    const { data, error } = await vibecode
      .from('posts')
      .eq('published', true)
      .order('created_at', { ascending: false })
      .limit(50)
      .select('*')
    if (error) throw error
    return data ?? []
  },
})

scratchpad-template.md - Working Memory Template

Template for SCRATCHPAD.md - a working memory file for AI assistants during development sessions.

Purpose: Provide a consistent template for AI working notes. This file is only created once and never overwritten.

# Scratchpad

Working memory for temporary notes, debug findings, and half-finished ideas.

---

## Current Focus

_Empty - add notes here as you work_

## Debug Notes

_Add debugging findings here_

## Ideas / Later

_Things to consider for future_

---

_Delete or prune this file regularly_

.ai/.claude/base.md - Claude Code Additions

Editor-specific configuration that gets appended to base.md when generating CLAUDE.md.

Purpose: Add Claude Code specific features like slash commands, resource locations, and behavior guidelines.

## Claude Code

### Resources
- Docs: `.claude/docs/`
- Plan: `.claude/PLAN.md`
- Commands: `.claude/commands/`

### Commands
- `/new-component` - Create component
- `/new-screen` - Create screen
- `/new-table` - Add database table
- `/refactor` - Refactor code
- `/review` - Review code

### Behavior
- Use TodoWrite for multi-step tasks
- Conventional commits: `type(scope): description`

Generated output (CLAUDE.md):

[Contents of base.md]

[Contents of .claude/base.md]

.ai/.cursor/base.md - Cursor Additions

Editor-specific configuration that gets appended to base.md when generating .cursorrules.

Purpose: Add Cursor specific features like rules locations and behavior guidelines.

## Cursor

### Resources
- Docs: `.cursor/docs/`
- Plan: `.cursor/PLAN.md`
- Rules: `.cursor/rules/`

### Rules
- `new-component.md` - Create component
- `new-screen.md` - Create screen
- `new-table.md` - Add database table
- `refactor.md` - Refactor code
- `review.md` - Review code

### Behavior
- Use project patterns from docs
- Suggest theme variables, not hardcoded colors

Generated output (.cursorrules):

[Contents of base.md]

[Contents of .cursor/base.md]

docs/ - Reference Documentation

Additional documentation files that AI assistants can reference.

Purpose: Provide detailed API reference, code templates, and coding rules that are too long for the main config files.

.ai/docs/
├── reference.md    # API and type reference
├── templates.md    # Code templates for screens, components
└── rules.md        # Detailed coding rules and patterns

commands/ - Custom AI Commands

Claude Code slash commands that help generate code quickly.

Purpose: Define reusable commands like /new-screen, /new-component that generate boilerplate code following your project's patterns.

.ai/commands/
├── new-screen.md      # /new-screen - Generate a new screen
├── new-component.md   # /new-component - Generate a component
├── new-table.md       # /new-table - Add database table
├── refactor.md        # /refactor - Refactor code
└── review.md          # /review - Code review

Example command file (new-component.md):

# /new-component

Generate a new reusable component with TypeScript types and NativeWind styling.

## When to Use
- Creating a new UI component
- Building reusable pieces

## Output
- Component file in `components/`
- TypeScript props interface
- Export added to `components/index.ts`

## Template

\`\`\`tsx
import { View, Text, Pressable } from 'react-native'

interface ComponentNameProps {
  title: string
  onPress?: () => void
}

export function ComponentName({ title, onPress }: ComponentNameProps) {
  return (
    <Pressable onPress={onPress} className="bg-card p-4 rounded-xl">
      <Text className="text-foreground font-medium">{title}</Text>
    </Pressable>
  )
}
\`\`\`

Editing AI Configuration

Where to Make Changes

| To Change | Edit This File | |-----------|----------------| | Core AI instructions | .ai/base.md | | Claude-specific config | .ai/.claude/base.md | | Cursor-specific config | .ai/.cursor/base.md | | Architecture & templates | .ai/project.md | | Reference docs for AI | .ai/docs/*.md | | Custom commands | .ai/commands/*.md |

Workflow

# 1. Edit the source file in .ai/
nano .ai/base.md

# 2. Run sync to regenerate output files
npm run ai:sync

# 3. Commit both source and generated files
git add .ai/ CLAUDE.md .cursorrules .claude/ .cursor/
git commit -m "chore: update AI configuration"

Adding Custom Commands

Create a new markdown file in .ai/commands/:

# Create command
touch .ai/commands/my-command.md

# Edit command
nano .ai/commands/my-command.md

# Sync to generate
npm run ai:sync

Command format:

# /my-command

Description of what this command does.

## When to Use
- Use case 1
- Use case 2

## Template
\`\`\`tsx
// Code template here
\`\`\`

After syncing, the command will be available in .claude/commands/ for Claude Code.

Best Practices

Keep AI Context Updated

When making significant changes to your app:

1. Update .ai/base.md with new patterns or conventions
2. Update .ai/project.md with architecture decisions
3. Run npm run ai:sync to propagate changes
4. Commit both source and generated files

Use SCRATCHPAD.md During Development

The SCRATCHPAD.md file is for temporary notes during development:

• Current task progress
• Debug findings
• Decisions made
• Next steps

This file is safe to edit directly as it's not overwritten by sync.

Be Specific with AI Prompts

# Good
Create a TaskCard component that shows task title, due date badge,
priority indicator (1-3 dots), and checkbox. Has onToggle and onPress props.

# Bad
Make a task card

Reference Existing Code

Create a ProfileSettings screen similar to the existing profile.tsx
but with sections for notification preferences and account management

Summary

| Task | Action | |------|--------| | Edit shared AI instructions | Modify .ai/base.md, run npm run ai:sync | | Edit Claude-specific config | Modify .ai/.claude/base.md, run npm run ai:sync | | Edit Cursor-specific config | Modify .ai/.cursor/base.md, run npm run ai:sync | | Add custom command | Create .ai/commands/name.md, run npm run ai:sync | | Update architecture docs | Modify .ai/project.md, run npm run ai:sync | | Add working notes | Edit SCRATCHPAD.md directly |

Next Steps

• Explore the Folder Structure
• Learn about Vibecode DB
• Set up Environment Variables