> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cubby.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# CUBBY.md File

> Provide context for AI tools building your app

# CUBBY.md File

The `CUBBY.md` file is a markdown document that provides context for AI coding assistants. Every Cubby app includes this file in the project root.

## Purpose

When using Claude, ChatGPT, or other AI tools to build your app, they need to understand:

* Cubby's platform constraints
* How to write API routes correctly
* Database access patterns
* What to avoid (auth libraries, hardcoded values)

`CUBBY.md` provides all this context in a format AI tools can reference.

## Location

The file lives in your project root:

```
my-app/
├── CUBBY.md          # AI context file
├── cubby.yaml        # Platform config
├── package.json
└── ...
```

## What's Included

The default `CUBBY.md` created by `cubby init` covers:

### Stack Information

```markdown theme={null}
## Stack

- Next.js 16 (App Router, Turbopack)
- Prisma ORM + SQLite (default; Neon Postgres on Builder/Pro)
- Docker container deployment
```

### Project Structure

```markdown theme={null}
## Project Structure

app/
  api/           -- API routes (server-only)
  page.tsx       -- Pages (server components by default)
lib/
  db.ts          -- Prisma client singleton
prisma/
  schema.prisma  -- Database schema
```

### CLI Commands

```markdown theme={null}
## CLI Commands

cubby dev          # Local development with hot reload
cubby deploy       # Build and deploy to production
cubby secrets set  # Manage environment variables
```

### API Route Patterns

The file includes complete examples for:

* Collection routes (GET all, POST create)
* Dynamic routes with async params (Next.js 16 pattern)
* Server components vs client components
* Form handling with Server Actions

### Platform Constraints

```markdown theme={null}
## Platform Constraints

### Environment Variables
- PORT -- Provided by runtime (default: 3000). Do not hardcode.
- DATABASE_URL -- Provisioned automatically. Never commit to repo.
- Use `cubby secrets` for production secrets, not .env files.

### Build Requirements
- next.config.ts must have output: "standalone" for Docker builds
```

### Authentication

```markdown theme={null}
## Authentication

Cubby handles authentication via platform SSO. Your app does NOT need its own auth system.

- Users authenticate once through the Cubby platform
- Authenticated user identity is passed via request headers
- Do not install auth libraries (NextAuth, Clerk, etc.)
```

### Forbidden Patterns

```markdown theme={null}
## Forbidden Patterns

- Do not use middleware.ts -- renamed to proxy.ts in Next.js 16
- Do not hardcode DATABASE_URL or commit .env files
- Do not install auth libraries -- Cubby SSO handles authentication
- Do not use prisma migrate dev in production
```

## Customizing CUBBY.md

You can extend `CUBBY.md` with app-specific context:

```markdown theme={null}
# My Todo App

A task management app with AI-powered suggestions.

## Custom Models

model Todo {
  id        String  @id
  title     String
  priority  Int     # 1 = high, 2 = medium, 3 = low
  userId    String  # Owner's Cubby user ID
}

## API Routes

- POST /api/todos - Create a new todo
- GET /api/todos - List user's todos
- PUT /api/todos/[id] - Update a todo
- DELETE /api/todos/[id] - Delete a todo

## Business Logic

- Users can only see their own todos (filter by userId)
- High priority todos appear first
- Completed todos move to bottom of list
```

## How AI Uses CUBBY.md

When you ask Claude or another AI to help with your app, the AI should:

1. Read `CUBBY.md` at the start of the conversation
2. Follow the patterns documented there
3. Avoid forbidden patterns
4. Use the correct API route signatures

<Tip>
  If your AI isn't following Cubby conventions, remind it to read `CUBBY.md` for context.
</Tip>

## Full Template

View the complete default `CUBBY.md` in the [GitHub repository](https://github.com/cubby-pro/cubby/blob/main/packages/cli/templates/nextjs-sqlite/CUBBY.md) or run `cubby init` to see it in your project.