# Gencow Documentation — Complete Reference

> This file contains the full documentation for the Gencow framework.
> Use this as a single-file reference for AI-assisted development.

---

## Introduction

> Gencow — The fullstack framework for vibe coders

Gencow is a **fullstack backend framework** for vibe coders who want to ship fast without compromising on quality. Build complete backend APIs with TypeScript — auth, database, realtime, file storage, AI, and cloud deployment — all from a single `gencow/` folder.

Think of it as **Convex + Supabase**, but simpler:

- **Schema-first** — Define your database with TypeScript (Drizzle ORM)
- **Instant APIs** — Write queries & mutations, get type-safe endpoints automatically
- **Built-in Auth** — User management powered by better-auth (session-based, token-based)
- **Realtime** — WebSocket push model — `useQuery` auto-refreshes on data changes
- **File Storage** — `ctx.storage.store()` / `getUrl()` — Convex-compatible pattern
- **AI-Ready** — Add AI, RAG, Memory, Tools with `gencow add AI`
- **Cron Jobs** — Scheduled tasks with `cronJobs()` — interval, daily, weekly, cron
- **Cloud Deploy** — `gencow deploy` and you're live on `https://<app>.gencow.app`

### Why Gencow?

| Feature | Gencow | Convex | Supabase | Firebase |
|---|---|---|---|---|
| Schema | Drizzle (TypeScript) | Convex schema | SQL (Console) | NoSQL (Console) |
| Query/Mutation | `defineQuery` / `defineMutation` | `query` / `mutation` | SQL / REST | Firestore API |
| Auth | Built-in (better-auth) | Clerk/Auth0 | Built-in | Built-in |
| Realtime | WebSocket push | Reactive queries | Realtime extension | Firestore listeners |
| File Storage | `ctx.storage` | `ctx.storage` | Storage | Cloud Storage |
| AI Components | `gencow add AI` | Manual | Manual | Vertex AI |
| Cron Jobs | `cronJobs()` | `crons` | pg_cron | Cloud Functions |
| Deploy | `gencow deploy` | `npx convex deploy` | Dashboard | `firebase deploy` |
| Self-host | ✅ (Docker) | ❌ | ✅ | ❌ |
| Local Dev DB | PGlite (zero setup) | SQLite | PostgreSQL | Emulators |

### Who is this for?

- **Vibe coders** who use AI assistants (Cursor, Copilot, Claude) to build apps
- **Solo developers** who want a full backend in minutes
- **Indie hackers** who need auth + DB + AI + file storage without setup overhead
- **Agencies** building prototypes and MVPs for clients

### Tech Stack

| Layer | Technology |
|---|---|
| **Runtime** | Bun |
| **HTTP Server** | Hono |
| **Database** | PGlite (local) / PostgreSQL (production) |
| **ORM** | Drizzle ORM |
| **Auth** | better-auth (session-based + JWT) |
| **Validation** | Zod + built-in `v` validator |
| **Realtime** | Native WebSocket (push model) |
| **AI** | Vercel AI SDK (OpenAI GPT-4o/4o-mini) |
| **Cloud** | Gencow Platform (gencow.app) |

### Architecture

```
Your App
├── gencow/                  ← Backend code (this is what you write)
│   ├── schema.ts            ← Database tables (Drizzle ORM)
│   ├── auth-schema.ts       ← Auth tables (auto-generated)
│   ├── auth.ts              ← Auth config (defineAuth)
│   ├── tasks.ts             ← Your queries & mutations
│   ├── files.ts             ← File upload/download logic
│   ├── crons.ts             ← Scheduled jobs
│   ├── seed.ts              ← Seed data (optional)
│   ├── index.ts             ← Re-exports all modules
│   ├── api.ts               ← Auto-generated type-safe API client
│   └── README.md            ← Auto-generated AI guide
├── src/                     ← Frontend (React, Next.js, Vite, etc.)
├── gencow.config.ts         ← Project configuration
├── gencow.json              ← Cloud app ID (auto-created on deploy)
├── drizzle.config.ts        ← Database config (PGlite/PostgreSQL)
└── package.json
```

**How it works:**

1. You define database tables in `gencow/schema.ts` using Drizzle ORM
2. You write queries and mutations in `gencow/*.ts` using `defineQuery` / `defineMutation`
3. `gencow dev` starts a Hono server with hot-reload, auto-generates `api.ts`
4. Your React frontend uses `useQuery(api.tasks.list)` — data is reactive via WebSocket
5. `gencow deploy` ships everything to Gencow Cloud (PostgreSQL + isolated container)

### Next Steps

- [Installation](/docs/getting-started/installation) — Create your first project
- [Quickstart](/docs/getting-started/quickstart) — Build a Todo app in 5 minutes
- [Project Structure](/docs/getting-started/project-structure) — Understand every file

---

## Installation

> Install Gencow and create your first project

### Prerequisites

- **Bun** (recommended) or **Node.js 18+**
- **npm**, **pnpm**, or **bun** package manager

### Create a New Project

```bash
## Create in a new directory
npx gencow init my-app
cd my-app

## Or initialize in current directory
npx gencow init . --force
```

#### Flags

| Flag | Description |
|---|---|
| `--template <name>` or `-t` | Select a template (see below) |
| `--force` or `-f` | Initialize in a non-empty directory (preserves existing files, merges `package.json`) |

#### What Gets Created

```
my-app/
├── gencow/
│   ├── schema.ts          ← Your database tables
│   ├── auth-schema.ts     ← Auth tables (better-auth)
│   ├── auth.ts            ← Auth configuration
│   ├── crons.ts           ← Cron job scheduler (template)
│   ├── index.ts           ← Module re-exports
│   ├── SECURITY.md        ← Security checklist for AI coders
│   └── (template files)   ← Depends on chosen template
├── gencow.config.ts       ← Project configuration
├── drizzle.config.ts      ← Database config
├── tsconfig.json
├── package.json
├── .env                   ← Environment variables (local only)
└── .gitignore
```

#### Auto-Installed Dependencies

| Package | Purpose |
|---|---|
| `gencow` | CLI + bundled server runtime |
| `@gencow/core` | `defineQuery`, `defineMutation`, `cronJobs`, `v` validator |
| `drizzle-orm` | Type-safe SQL ORM |
| `drizzle-kit` | Schema migration tool |
| `better-auth` | Authentication framework |
| `@electric-sql/pglite` | Embedded PostgreSQL for local dev (zero setup) |
| `postgres` | PostgreSQL client for production |

### Available Templates

```bash
## Interactive selection (default)
npx gencow init my-app

## Or specify directly
npx gencow init my-app --template fullstack
```

| # | Template | Description | Includes |
|---|---|---|---|
| 1 | `default` | Empty project | Basic schema + index.ts |
| 2 | `task-app` | Task + Files CRUD backend | tasks.ts, files.ts with full CRUD |
| 3 | `fullstack` | Tasks + Files + AI Chat + Agent | All of task-app + ai.ts + prompt.md |
| 4 | `ai-chat` | AI Chatbot + Memory backend | chat.ts, ai.ts + prompt.md |

#### What `prompt.md` Contains

Templates `fullstack` and `ai-chat` include a `prompt.md` file — a **vibe-coding prompt** designed to be given to AI assistants (Cursor, Copilot, etc.). It includes:
- All available API endpoints with types
- Authentication setup instructions
- `useQuery` / `useMutation` usage patterns
- Security rules for backend code
- Recommended UI structure

### Start Development

```bash
gencow dev
```

This starts:
- 🔧 **Hono server** at `http://localhost:5456` with hot-reload
- 📊 **Admin Dashboard** at `http://localhost:5456/_admin` for data browsing
- 🗄️ **PGlite** embedded PostgreSQL (zero setup, zero config)
- 📝 **Auto-codegen** — `gencow/api.ts` and `gencow/README.md` regenerate on file changes

#### Dev Modes

```bash
## Default: Cloud development (connects to Gencow Cloud DB)
gencow dev

## Local-only: Uses PGlite embedded database
gencow dev --local

## Verbose: Show all HTTP logs (including admin/ws)
gencow dev --verbose
```

### Using with Existing Projects

If you already have a Next.js, Vite, or other frontend project:

```bash
## Navigate to your project root
cd my-existing-project

## Initialize Gencow in the current directory
npx gencow init . --force

## Install dependencies
bun install   # or npm install

## Start Gencow backend
gencow dev
```

The `--force` flag:
- Preserves all existing files
- Merges Gencow dependencies into your existing `package.json`
- Creates `gencow/` folder alongside your existing `src/`
- Skips `.env` and `tsconfig.json` if they already exist

### Next Steps

- [Quickstart](/docs/getting-started/quickstart) — Build a Todo app in 5 minutes
- [Project Structure](/docs/getting-started/project-structure) — Understand every file
- [Schema Guide](/docs/guides/schema) — Learn about schema patterns

---

## Quickstart

> Build a fullstack Todo app in 5 minutes

Let's build a **Todo app** with authentication, CRUD operations, and realtime updates — from scratch in 5 minutes.

### 1. Create the Project

```bash
npx gencow init my-todo --template task-app
cd my-todo && bun install
```

### 2. Explore the Schema

Open `gencow/schema.ts` — the template already includes a tasks table:

```typescript
import { pgTable, serial, text, boolean, timestamp } from "drizzle-orm/pg-core";
import { user } from "./auth-schema";

export const tasks = pgTable("tasks", {
    id: serial("id").primaryKey(),
    title: text("title").notNull(),
    done: boolean("done").default(false).notNull(),
    userId: text("user_id")
        .notNull()
        .references(() => user.id, { onDelete: "cascade" }),
    createdAt: timestamp("created_at").defaultNow().notNull(),
});
```

> **Security:** The `userId` column with `.references()` ensures every task belongs to a user. This is critical for data isolation — Gencow enforces this pattern.

### 3. Understand Queries & Mutations

Open `gencow/tasks.ts` — the template provides full CRUD:

```typescript
import { query, mutation, v } from "@gencow/core";
import { eq, and, desc } from "drizzle-orm";
import { tasks } from "./schema";

// List all tasks for the current user (newest first)
export const list = query("tasks.list", {
    args: {},
    handler: async (ctx) => {
        const session = ctx.auth.requireAuth();
        return ctx.db
            .select()
            .from(tasks)
            .where(eq(tasks.userId, session.user.id))
            .orderBy(desc(tasks.createdAt));
    },
});

// Create a new task
export const create = mutation("tasks.create", {
    args: { title: v.string() },
    handler: async (ctx, { title }) => {
        const session = ctx.auth.requireAuth();
        const [task] = await ctx.db
            .insert(tasks)
            .values({ title, userId: session.user.id })
            .returning();
        return task;
    },
});

// Toggle done status
export const toggle = mutation("tasks.toggle", {
    args: { id: v.number() },
    handler: async (ctx, { id }) => {
        const session = ctx.auth.requireAuth();
        const [task] = await ctx.db
            .select()
            .from(tasks)
            .where(and(eq(tasks.id, id), eq(tasks.userId, session.user.id)));
        if (!task) throw new Error("Task not found");

        await ctx.db
            .update(tasks)
            .set({ done: !task.done })
            .where(eq(tasks.id, id));
    },
});

// Delete a task (with ownership check)
export const _delete = mutation("tasks.delete", {
    args: { id: v.number() },
    handler: async (ctx, { id }) => {
        const session = ctx.auth.requireAuth();
        await ctx.db
            .delete(tasks)
            .where(and(eq(tasks.id, id), eq(tasks.userId, session.user.id)));
    },
});
```

### 4. Register Modules

Open `gencow/index.ts` — re-export all modules:

```typescript
export * as tasks from "./tasks";
// export * as files from "./files";  // uncomment when needed
```

> **Important pattern:** Always use `export * as moduleName` — don't add suffixes like `Module` or `Mod`.

### 5. Start the Dev Server

```bash
gencow dev
```

You'll see:
```
  Gencow Dev (local)

  ▸ Functions: ./gencow
  ▸ Storage:   ./.gencow/uploads
  ▸ DB:        ./.gencow/data

  ✓ Schema → migrations synced
  ✓ Generated gencow/api.ts
  ✓ Generated gencow/README.md (AI vibe-coding guide)

  Starting server with hot-reload...

  ✓ Server running at http://localhost:5456
  ✓ Dashboard: http://localhost:5456/_admin
```

#### Verify the API

Open the admin dashboard at `http://localhost:5456/_admin` to:
- Browse your database tables
- View registered queries and mutations
- Test API endpoints

### 6. Connect a React Frontend

Install the React SDK:

```bash
npm install @gencow/react
```

#### Set Up Auth

```typescript
// src/lib/auth.ts
import { gencowAuth } from "@gencow/react";
export const { signIn, signUp, signOut, useAuth } = gencowAuth();
```

#### Set Up the Provider

```tsx
// src/main.tsx (or layout.tsx)
import { GencowProvider } from "@gencow/react";
import { useAuth } from "./lib/auth";

function AppWrapper({ children }) {
    const { token } = useAuth();
    const baseUrl = import.meta.env.VITE_API_URL ?? "http://localhost:5456";

    return (
        <GencowProvider baseUrl={baseUrl} token={token}>
            {children}
        </GencowProvider>
    );
}
```

#### Build the Todo UI

```tsx
import { useQuery, useMutation } from "@gencow/react";
import { api } from "../gencow/api";  // auto-generated

function TodoApp() {
    const tasks = useQuery(api.tasks.list);
    const [createTask, isCreating] = useMutation(api.tasks.create);
    const [toggleTask] = useMutation(api.tasks.toggle);
    const [deleteTask] = useMutation(api.tasks.delete);

    if (tasks === undefined) return <div>Loading...</div>;

    return (
        <div>
            <h1>My Todos</h1>

            {/* Create form */}
            <form onSubmit={(e) => {
                e.preventDefault();
                const title = new FormData(e.currentTarget).get("title") as string;
                createTask({ title });
                e.currentTarget.reset();
            }}>
                <input name="title" placeholder="New task..." required />
                <button disabled={isCreating}>
                    {isCreating ? "Adding..." : "Add"}
                </button>
            </form>

            {/* Task list */}
            <ul>
                {tasks.map((t) => (
                    <li key={t.id}>
                        <span
                            onClick={() => toggleTask({ id: t.id })}
                            style={{ cursor: "pointer" }}
                        >
                            {t.done ? "✅" : "⬜"} {t.title}
                        </span>
                        <button onClick={() => deleteTask({ id: t.id })}>🗑️</button>
                    </li>
                ))}
            </ul>
        </div>
    );
}
```

> **Realtime magic:** When you call `createTask()`, the server automatically pushes the updated data via WebSocket. All `useQuery(api.tasks.list)` hooks refresh instantly — no manual refetching needed!

### 7. Add Seed Data (Optional)

Create `gencow/seed.ts` to populate the database with test data:

```typescript
export default async function seed(ctx) {
    // Create a test user first (auth is handled separately)
    // Then seed tasks
    await ctx.db.insert(tasks).values([
        { title: "Learn Gencow", userId: "test-user-id" },
        { title: "Build an awesome app", userId: "test-user-id" },
        { title: "Deploy to cloud", userId: "test-user-id" },
    ]);
}
```

```bash
## Run seed (server must be running)
gencow db:seed
```

### 8. Deploy

```bash
## Login (first time only)
gencow login

## Deploy backend
gencow deploy

## Deploy frontend (if you have one)
VITE_API_URL=https://<app-id>.gencow.app npm run build
gencow deploy --static dist/
```

That's it! Your app is live on `https://<app-id>.gencow.app`. 🎉

### Next Steps

- [Project Structure](/docs/getting-started/project-structure) — Understand every config file
- [Schema Guide](/docs/guides/schema) — Advanced schema patterns
- [Authentication](/docs/guides/authentication) — Auth setup in detail
- [AI Engine](/docs/ai/ai-engine) — Add AI to your app
- [Deployment](/docs/guides/deployment) — Cloud deployment details

---

## Project Structure

> Understand every file and folder in a Gencow project

### Overview

A Gencow project follows a simple convention: your backend lives in `gencow/`, and everything else (frontend, configs) lives alongside it.

```
my-app/
├── gencow/                  ← Backend code
│   ├── schema.ts            ← Database tables (Drizzle ORM)
│   ├── auth-schema.ts       ← Auth tables (auto-generated by init)
│   ├── auth.ts              ← Auth configuration (defineAuth)
│   ├── index.ts             ← Re-exports all modules
│   ├── tasks.ts             ← Your queries & mutations
│   ├── crons.ts             ← Scheduled jobs
│   ├── seed.ts              ← Seed data (optional)
│   ├── api.ts               ← ⚡ Auto-generated (do not edit)
│   ├── README.md            ← ⚡ Auto-generated AI guide
│   └── SECURITY.md          ← Security checklist
├── .gencow/                 ← Runtime data (gitignored)
│   ├── data/                ← PGlite database files
│   ├── uploads/             ← File storage
│   ├── backups/             ← Auto-backups before dev restart
│   ├── server.js            ← Bundled server copy
│   └── dashboard/           ← Admin dashboard assets
├── migrations/              ← SQL migration files
├── gencow.config.ts         ← Project configuration
├── gencow.json              ← Cloud app ID (created on deploy)
├── drizzle.config.ts        ← Database config
├── package.json
├── tsconfig.json
├── .env                     ← Environment variables (local only)
└── .gitignore
```

### Configuration Files

#### `gencow.config.ts`

The main project configuration file:

```typescript
export default {
    // Path to your backend functions directory
    functionsDir: "./gencow",

    // Path to your Drizzle schema file
    schema: "./gencow/schema.ts",

    // File storage directory
    storage: "./.gencow/uploads",

    // Local database configuration
    db: { url: "./.gencow/data" },

    // API server port
    port: 5456,
};
```

| Option | Default | Description |
|---|---|---|
| `functionsDir` | `"./gencow"` | Directory containing your backend code |
| `schema` | `"./gencow/schema.ts"` | Path to Drizzle schema file |
| `storage` | `"./.gencow/uploads"` | File storage directory |
| `db.url` | `"./.gencow/data"` | PGlite data directory (local) |
| `port` | `5456` | Dev server port |

#### `gencow.json`

Auto-created when you run `gencow deploy`. Contains your cloud app identity:

```json
{
  "appId": "null-mint-9625",
  "displayName": "my-app",
  "platformUrl": "https://gencow.app"
}
```

> **Do not edit `appId`** — it's a unique identifier assigned by the platform. Changing it will create a new app on next deploy.

#### `drizzle.config.ts`

Database configuration for Drizzle Kit (migrations):

```typescript
import { defineConfig } from "drizzle-kit";

export default defineConfig({
    dialect: "postgresql",
    schema: ["./gencow/schema.ts", "./gencow/auth-schema.ts"],
    out: "./migrations",
    // Auto-detects: DATABASE_URL → PostgreSQL, otherwise → PGlite
    ...(process.env.DATABASE_URL
        ? { dbCredentials: { url: process.env.DATABASE_URL } }
        : { driver: "pglite", dbCredentials: { url: "./.gencow/data" } }),
});
```

### The `gencow/` Folder

#### `schema.ts` — Database Tables

Define your tables using Drizzle ORM's `pgTable`:

```typescript
import { pgTable, serial, text, boolean, timestamp } from "drizzle-orm/pg-core";
import { user } from "./auth-schema";

export const tasks = pgTable("tasks", {
    id: serial("id").primaryKey(),
    title: text("title").notNull(),
    done: boolean("done").default(false).notNull(),
    userId: text("user_id")
        .notNull()
        .references(() => user.id, { onDelete: "cascade" }),
    createdAt: timestamp("created_at").defaultNow().notNull(),
});
```

#### `auth-schema.ts` — Auth Tables

Auto-generated by `gencow init`. Contains `user`, `session`, and `account` tables required by better-auth. **Do not remove or modify** unless you know what you're doing.

#### `auth.ts` — Auth Configuration

Customize authentication behavior:

```typescript
import { defineAuth } from "@gencow/core";

export default defineAuth({
    emailAndPassword: { enabled: true },
    // emailVerification: { sendVerificationEmail: async ({ email, url }) => { ... } },
});
```

#### `index.ts` — Module Re-exports

**Critical file** — tells the server which modules to register:

```typescript
export * as tasks from "./tasks";
export * as files from "./files";
// export * as chat from "./chat";
```

> **Pattern:** Always use `export * as moduleName` (not `export * as tasksModule` or `export * as TasksMod`).

#### `crons.ts` — Cron Jobs

Define scheduled tasks:

```typescript
import { cronJobs } from "@gencow/core";

const crons = cronJobs();

crons.interval("syncData", { minutes: 30 }, "data.sync");
crons.daily("report", { hour: 9 }, "reports.generate");

export default crons;  // ← Required!
```

#### `seed.ts` — Seed Data (Optional)

Populate the database with test data:

```typescript
import { tasks } from "./schema";

export default async function seed(ctx) {
    await ctx.db.insert(tasks).values([
        { title: "First task", userId: "test-user" },
    ]);
}
```

Run with `gencow db:seed`.

#### `api.ts` — Auto-Generated (⚡ Do Not Edit)

Generated by `gencow dev` on every file change. Provides type-safe API references for your React frontend:

```typescript
// Generated by Gencow — do not edit manually.
import { defineQuery, defineMutation } from "@gencow/react";
import type * as tasks from "./tasks.ts";

export const api = {
    tasks: {
        list: defineQuery<typeof tasks.list>("tasks.list"),
        create: defineMutation<typeof tasks.create>("tasks.create"),
        toggle: defineMutation<typeof tasks.toggle>("tasks.toggle"),
        delete: defineMutation<typeof tasks._delete>("tasks.delete"),
    },
} as const;
```

#### `README.md` — Auto-Generated AI Guide (⚡ Do Not Edit)

Generated alongside `api.ts`. Contains a comprehensive vibe-coding guide that you can paste into AI assistants. Includes API reference, React hook usage, auth setup, cron patterns, and deployment commands.

### The `.gencow/` Folder (Gitignored)

| Path | Purpose |
|---|---|
| `.gencow/data/` | PGlite database files (local dev) |
| `.gencow/uploads/` | Uploaded files (via `ctx.storage.store()`) |
| `.gencow/backups/` | Auto-backups (kept last 3, created on `gencow dev`) |
| `.gencow/server.js` | Bundled server copy (for standalone projects) |
| `.gencow/dashboard/` | Admin dashboard static assets |

### Environment Variables

#### `.env` (Local Development Only)

```bash
## Gencow auto-populates this after deploy:
VITE_API_URL=https://my-app-id.gencow.app

## Your secrets (local only):
OPENAI_API_KEY=sk-your-key-here
DATABASE_URL=postgres://user:pass@host/db
```

#### Production Environment

Manage via CLI:

```bash
gencow env set OPENAI_API_KEY=sk-...
gencow env set DATABASE_URL=postgres://...
gencow env list
gencow env push   # Push all .env vars to cloud
```

> **Security:** `.env` is gitignored. Production environment variables are encrypted at rest. Never expose secrets in frontend code.

### Next Steps

- [Schema Guide](/docs/guides/schema) — Advanced table patterns
- [Queries & Mutations](/docs/guides/queries) — Read and write data
- [Authentication](/docs/guides/authentication) — Auth setup in detail

---

## Schema

> Define your database schema with Drizzle ORM

Gencow uses **Drizzle ORM** for schema definition. Your schema lives in `gencow/schema.ts` and uses PostgreSQL column types.

### Defining Tables

```typescript
import { pgTable, serial, text, boolean, timestamp, integer, jsonb, uuid } from "drizzle-orm/pg-core";
import { user } from "./auth-schema";

export const posts = pgTable("posts", {
    id: serial("id").primaryKey(),
    title: text("title").notNull(),
    content: text("content"),
    published: boolean("published").default(false).notNull(),
    views: integer("views").default(0).notNull(),
    metadata: jsonb("metadata"),
    userId: text("user_id")
        .notNull()
        .references(() => user.id, { onDelete: "cascade" }),
    createdAt: timestamp("created_at").defaultNow().notNull(),
    updatedAt: timestamp("updated_at").defaultNow().notNull(),
});
```

### Column Types

| Type | Drizzle | PostgreSQL | Example |
|---|---|---|---|
| Auto-increment | `serial("id")` | `SERIAL` | Primary keys |
| Text | `text("name")` | `TEXT` | Strings of any length |
| Integer | `integer("count")` | `INTEGER` | Numbers, counts |
| Boolean | `boolean("active")` | `BOOLEAN` | Flags, toggles |
| Timestamp | `timestamp("created_at")` | `TIMESTAMP` | Dates, times |
| JSON | `jsonb("metadata")` | `JSONB` | Structured data, settings |
| UUID | `uuid("id")` | `UUID` | Unique identifiers |
| Enum | `text("status")` | `TEXT` | Use text with validation |
| Real | `real("score")` | `REAL` | Floating point |
| Decimal | `numeric("price", { precision: 10, scale: 2 })` | `NUMERIC` | Money, precise values |

### Column Modifiers

```typescript
// Required field
text("title").notNull()

// Default value
boolean("done").default(false).notNull()

// Auto-timestamp
timestamp("created_at").defaultNow().notNull()

// Primary key
serial("id").primaryKey()

// UUID primary key (alternative)
uuid("id").defaultRandom().primaryKey()

// Unique constraint
text("email").notNull().unique()
```

### Relationships

#### Foreign Keys (User Ownership)

**Always** use `userId` with `.references()` for data that belongs to a user:

```typescript
userId: text("user_id")
    .notNull()
    .references(() => user.id, { onDelete: "cascade" }),
```

The `onDelete: "cascade"` ensures that when a user is deleted, all their data is automatically cleaned up.

#### One-to-Many

A post has many comments:

```typescript
export const comments = pgTable("comments", {
    id: serial("id").primaryKey(),
    content: text("content").notNull(),
    postId: integer("post_id")
        .notNull()
        .references(() => posts.id, { onDelete: "cascade" }),
    userId: text("user_id")
        .notNull()
        .references(() => user.id, { onDelete: "cascade" }),
    createdAt: timestamp("created_at").defaultNow().notNull(),
});
```

#### Many-to-Many (Join Table)

Users can belong to multiple teams:

```typescript
export const teams = pgTable("teams", {
    id: serial("id").primaryKey(),
    name: text("name").notNull(),
    createdAt: timestamp("created_at").defaultNow().notNull(),
});

export const teamMembers = pgTable("team_members", {
    id: serial("id").primaryKey(),
    teamId: integer("team_id")
        .notNull()
        .references(() => teams.id, { onDelete: "cascade" }),
    userId: text("user_id")
        .notNull()
        .references(() => user.id, { onDelete: "cascade" }),
    role: text("role").default("member").notNull(), // "admin" | "member"
    joinedAt: timestamp("joined_at").defaultNow().notNull(),
});
```

#### Self-Referencing

Categories with parent-child hierarchy:

```typescript
export const categories = pgTable("categories", {
    id: serial("id").primaryKey(),
    name: text("name").notNull(),
    parentId: integer("parent_id")
        .references(() => categories.id, { onDelete: "set null" }),
});
```

### JSONB for Flexible Data

Use `jsonb` for settings, metadata, or any semi-structured data:

```typescript
export const userSettings = pgTable("user_settings", {
    id: serial("id").primaryKey(),
    userId: text("user_id")
        .notNull()
        .unique()
        .references(() => user.id, { onDelete: "cascade" }),
    preferences: jsonb("preferences").$type<{
        theme: "light" | "dark";
        language: string;
        notifications: boolean;
    }>().default({ theme: "light", language: "en", notifications: true }),
});
```

### Applying Schema Changes

#### Quick Sync (Development)

Push changes instantly without migration files:

```bash
gencow db:push
```

This applies changes **instantly** — like Convex's automatic schema sync. Best for rapid prototyping.

#### Migration Files (Production)

For production deployments with controlled migrations:

```bash
## 1. Generate SQL migration files from schema changes
gencow db:generate

## 2. Apply pending migrations
gencow db:migrate
```

Migration files are saved in `migrations/` and are version-controlled.

#### Comparison

| | `db:push` | `db:generate` + `db:migrate` |
|---|---|---|
| Speed | Instant | Two-step |
| Migration files | No | Yes (SQL files in `migrations/`) |
| Rollback | No | Manual via SQL |
| Best for | Development | Production |
| Auto-detects | Cloud/Local | Cloud/Local |

> **Note:** `gencow dev` automatically runs `db:generate` on startup, so migration files are always up to date when developing.

### Database Commands Reference

| Command | Description |
|---|---|
| `gencow db:push` | Sync schema → DB instantly (no migration files) |
| `gencow db:generate` | Generate SQL migration files |
| `gencow db:migrate` | Apply pending migrations |
| `gencow db:seed` | Run `gencow/seed.ts` (insert test data) |
| `gencow db:reset` | TRUNCATE all data + re-run seed.ts |
| `gencow db:restore` | Restore from backup |
| `gencow db:studio` | Open Drizzle Studio (visual DB browser) |

### Next Steps

- [Queries](/docs/guides/queries) — Read data with `defineQuery`
- [Mutations](/docs/guides/mutations) — Write data with `defineMutation`

---

## Queries

> Read data with type-safe queries

Queries are **read-only** functions that fetch data from the database. They're defined with `query()` from `@gencow/core`.

### Defining Queries

```typescript
import { query, v } from "@gencow/core";
import { eq, desc } from "drizzle-orm";
import { posts } from "./schema";

export const list = query("posts.list", {
    args: {},
    handler: async (ctx) => {
        const session = ctx.auth.requireAuth();
        return ctx.db
            .select()
            .from(posts)
            .where(eq(posts.userId, session.user.id))
            .orderBy(desc(posts.createdAt));
    },
});
```

#### Key Parts

| Part | Description |
|---|---|
| `"posts.list"` | Unique name — must match `{module}.{export}` pattern |
| `args` | Input validation schema (using `v` validator or Zod) |
| `handler(ctx, args)` | Async function that reads from `ctx.db` |
| `ctx.auth.requireAuth()` | Enforces authentication, returns session |
| `ctx.db` | Drizzle ORM instance for database queries |

### Query with Arguments

```typescript
export const getById = query("posts.getById", {
    args: { id: v.number() },
    handler: async (ctx, { id }) => {
        const session = ctx.auth.requireAuth();
        const [post] = await ctx.db
            .select()
            .from(posts)
            .where(eq(posts.id, id));
        return post || null;
    },
});
```

### Filtering & Sorting

```typescript
import { eq, and, or, like, between, desc, asc, gt, lt, isNull, isNotNull } from "drizzle-orm";

// Multiple conditions
export const search = query("posts.search", {
    args: { keyword: v.string(), published: v.optional(v.boolean()) },
    handler: async (ctx, { keyword, published }) => {
        const session = ctx.auth.requireAuth();
        const conditions = [eq(posts.userId, session.user.id)];

        if (keyword) {
            conditions.push(like(posts.title, `%${keyword}%`));
        }
        if (published !== undefined) {
            conditions.push(eq(posts.published, published));
        }

        return ctx.db
            .select()
            .from(posts)
            .where(and(...conditions))
            .orderBy(desc(posts.createdAt));
    },
});
```

#### Available Operators

| Operator | Example | Description |
|---|---|---|
| `eq` | `eq(posts.id, 1)` | Equals |
| `and` | `and(eq(...), eq(...))` | Both conditions |
| `or` | `or(eq(...), eq(...))` | Either condition |
| `like` | `like(posts.title, "%search%")` | Pattern match |
| `gt` / `lt` | `gt(posts.views, 100)` | Greater / less than |
| `between` | `between(posts.views, 10, 100)` | Range |
| `isNull` | `isNull(posts.content)` | Is null |
| `isNotNull` | `isNotNull(posts.content)` | Is not null |
| `desc` / `asc` | `desc(posts.createdAt)` | Sorting |

### Pagination

#### Offset-Based

```typescript
export const listPaged = query("posts.listPaged", {
    args: { page: v.optional(v.number()), limit: v.optional(v.number()) },
    handler: async (ctx, { page = 1, limit = 20 }) => {
        const session = ctx.auth.requireAuth();
        const offset = (page - 1) * limit;

        const items = await ctx.db
            .select()
            .from(posts)
            .where(eq(posts.userId, session.user.id))
            .orderBy(desc(posts.createdAt))
            .limit(limit)
            .offset(offset);

        return { items, page, limit };
    },
});
```

#### Cursor-Based

```typescript
export const listCursor = query("posts.listCursor", {
    args: { cursor: v.optional(v.number()), limit: v.optional(v.number()) },
    handler: async (ctx, { cursor, limit = 20 }) => {
        const session = ctx.auth.requireAuth();

        const conditions = [eq(posts.userId, session.user.id)];
        if (cursor) {
            conditions.push(lt(posts.id, cursor));
        }

        const items = await ctx.db
            .select()
            .from(posts)
            .where(and(...conditions))
            .orderBy(desc(posts.id))
            .limit(limit + 1);

        const hasMore = items.length > limit;
        const data = hasMore ? items.slice(0, -1) : items;
        const nextCursor = hasMore ? data[data.length - 1].id : null;

        return { items: data, nextCursor };
    },
});
```

### Public Queries (No Auth Required)

For endpoints that don't require authentication:

```typescript
export const listPublic = query("posts.listPublic", {
    args: {},
    handler: async (ctx) => {
        // No requireAuth() — anyone can access
        return ctx.db
            .select()
            .from(posts)
            .where(eq(posts.published, true))
            .orderBy(desc(posts.createdAt))
            .limit(50);
    },
});
```

> **Warning:** Public queries should only expose non-sensitive data. Never return user private data without authentication.

### Joining Tables

```typescript
import { posts, comments } from "./schema";

export const getWithComments = query("posts.getWithComments", {
    args: { id: v.number() },
    handler: async (ctx, { id }) => {
        const session = ctx.auth.requireAuth();

        const post = await ctx.db
            .select()
            .from(posts)
            .where(and(eq(posts.id, id), eq(posts.userId, session.user.id)))
            .limit(1);

        if (!post[0]) return null;

        const postComments = await ctx.db
            .select()
            .from(comments)
            .where(eq(comments.postId, id))
            .orderBy(desc(comments.createdAt));

        return { ...post[0], comments: postComments };
    },
});
```

### Using from React

```tsx
import { useQuery } from "@gencow/react";
import { api } from "../gencow/api";

function PostList() {
    // Basic query — returns Post[] | undefined
    const posts = useQuery(api.posts.list);

    // With arguments
    const post = useQuery(api.posts.getById, { id: 42 });

    // Conditional query — skip when no ID selected
    const detail = useQuery(
        api.posts.getById,
        selectedId ? { id: selectedId } : "skip"
    );

    // Public query (no auth needed)
    const publicPosts = useQuery(api.posts.listPublic, {}, { public: true });

    if (posts === undefined) return <div>Loading...</div>;

    return (
        <ul>
            {posts.map((p) => (
                <li key={p.id}>{p.title}</li>
            ))}
        </ul>
    );
}
```

> **Realtime:** `useQuery` automatically subscribes to WebSocket updates. When data changes on the server, your component re-renders with fresh data — no manual refetching.

### Argument Validation

Use the `v` validator:

```typescript
args: {
    id: v.number(),
    title: v.string(),
    count: v.optional(v.number()),         // optional
    tags: v.array(v.string()),             // string array
    settings: v.object({                   // nested object
        theme: v.string(),
        count: v.number(),
    }),
}
```

| Validator | Description |
|---|---|
| `v.string()` | String |
| `v.number()` | Number |
| `v.boolean()` | Boolean |
| `v.optional(v.X())` | Optional field |
| `v.array(v.X())` | Array of type |
| `v.object({...})` | Nested object |

### Security Rules

> **Always filter by userId** in queries that return user data. This prevents data leakage between users.

```typescript
// ✅ Correct — filter by userId
ctx.db.select().from(posts).where(eq(posts.userId, session.user.id));

// ❌ Wrong — returns ALL users' data
ctx.db.select().from(posts);
```

### Next Steps

- [Mutations](/docs/guides/mutations) — Write data with `defineMutation`
- [Authentication](/docs/guides/authentication) — Auth setup details
- [Realtime](/docs/guides/realtime) — How WebSocket sync works

---

## Mutations

> Write data with type-safe mutations

Mutations are functions that **create, update, or delete** data. They're defined with `mutation()` from `@gencow/core`.

### Defining Mutations

```typescript
import { mutation, v } from "@gencow/core";
import { eq, and } from "drizzle-orm";
import { posts } from "./schema";

export const create = mutation("posts.create", {
    args: {
        title: v.string(),
        content: v.optional(v.string()),
    },
    handler: async (ctx, { title, content }) => {
        const session = ctx.auth.requireAuth();
        const [post] = await ctx.db
            .insert(posts)
            .values({ title, content, userId: session.user.id })
            .returning();
        return post;
    },
});
```

### CRUD Patterns

#### Create

```typescript
export const create = mutation("posts.create", {
    args: { title: v.string(), content: v.optional(v.string()) },
    handler: async (ctx, { title, content }) => {
        const session = ctx.auth.requireAuth();
        const [post] = await ctx.db
            .insert(posts)
            .values({ title, content, userId: session.user.id })
            .returning();
        return post;
    },
});
```

#### Update (with Ownership Check)

```typescript
export const update = mutation("posts.update", {
    args: {
        id: v.number(),
        title: v.optional(v.string()),
        content: v.optional(v.string()),
        published: v.optional(v.boolean()),
    },
    handler: async (ctx, { id, ...updates }) => {
        const session = ctx.auth.requireAuth();

        // Remove undefined values
        const data = Object.fromEntries(
            Object.entries(updates).filter(([_, v]) => v !== undefined)
        );

        const [updated] = await ctx.db
            .update(posts)
            .set({ ...data, updatedAt: new Date() })
            .where(and(eq(posts.id, id), eq(posts.userId, session.user.id)))
            .returning();

        if (!updated) throw new Error("Post not found");
        return updated;
    },
});
```

#### Delete (with Ownership Check)

```typescript
// Use _delete (underscore prefix) because 'delete' is a reserved word
export const _delete = mutation("posts.delete", {
    args: { id: v.number() },
    handler: async (ctx, { id }) => {
        const session = ctx.auth.requireAuth();
        // Always verify ownership before deletion
        await ctx.db
            .delete(posts)
            .where(and(
                eq(posts.id, id),
                eq(posts.userId, session.user.id)
            ));
    },
});
```

> **Important:** Export name `_delete` maps to API name `posts.delete`. The underscore prefix is automatically handled.

### File Upload with FormData

Mutations can accept `FormData` for file uploads:

```typescript
export const upload = mutation("files.upload", {
    args: {},  // args come from FormData
    handler: async (ctx) => {
        const session = ctx.auth.requireAuth();
        const file = ctx.file;  // File from FormData

        if (!file) throw new Error("No file provided");

        // Store file using ctx.storage
        const storageId = await ctx.storage.store(file);
        const url = ctx.storage.getUrl(storageId);

        return { storageId, url, name: file.name, size: file.size };
    },
});
```

#### React Upload Example

```tsx
const [upload, isPending] = useMutation(api.files.upload);

const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    const formData = new FormData();
    formData.append("file", file);
    await upload(formData);
};
```

### Scheduling Long-Running Tasks

Mutations have a **10-second timeout**. For tasks that take longer (AI calls, external APIs, crawling), split them into steps:

```typescript
export const startProcess = mutation("pipeline.start", {
    args: { url: v.string() },
    handler: async (ctx, { url }) => {
        const session = ctx.auth.requireAuth();

        // Step 1: Quick validation (< 10 sec)
        const isValid = await validateUrl(url);
        if (!isValid) throw new Error("Invalid URL");

        // Schedule the heavy work as a separate step
        await ctx.scheduler.runAfter(0, "pipeline.processStep", {
            url,
            userId: session.user.id,
        });

        return { status: "started" };
    },
});

export const processStep = mutation("pipeline.processStep", {
    args: { url: v.string(), userId: v.string() },
    handler: async (ctx, { url, userId }) => {
        // This runs independently — can take up to 10 sec
        const result = await crawlAndExtract(url);

        // Save results
        await ctx.db.insert(results).values({
            data: result,
            userId,
        });
    },
});
```

> **Pattern:** Break long pipelines into short mutations connected by `ctx.scheduler.runAfter()`.

### Error Handling

```typescript
export const create = mutation("posts.create", {
    args: { title: v.string() },
    handler: async (ctx, { title }) => {
        const session = ctx.auth.requireAuth();

        // Validation errors
        if (title.length > 200) {
            throw new Error("Title too long (max 200 characters)");
        }

        // Database operations may fail
        try {
            const [post] = await ctx.db
                .insert(posts)
                .values({ title, userId: session.user.id })
                .returning();
            return post;
        } catch (e) {
            if (e.message.includes("unique")) {
                throw new Error("A post with this title already exists");
            }
            throw e;
        }
    },
});
```

#### React Error Handling

```tsx
const [create, isPending, error] = useMutation(api.posts.create);

// error is Error | null
{error && <div className="error">{error.message}</div>}
```

### Calling Other Functions Within Mutations

When you need to call another module's function within a mutation, **import it directly** — don't use fetch:

```typescript
import { fetchNews } from "./naverApi";

export const processNews = mutation("pipeline.processNews", {
    args: { keyword: v.string() },
    handler: async (ctx, { keyword }) => {
        // ✅ Direct import — fast, no network overhead
        const result = await fetchNews.handler(ctx, { keyword });

        // ❌ Don't self-fetch
        // const res = await fetch("/api/mutation", { ... });

        return result;
    },
});
```

### Using from React

```tsx
import { useMutation } from "@gencow/react";
import { api } from "../gencow/api";

function CreatePost() {
    const [createPost, isPending, error] = useMutation(api.posts.create);

    const handleSubmit = async (e: React.FormEvent) => {
        e.preventDefault();
        const data = new FormData(e.currentTarget as HTMLFormElement);
        await createPost({
            title: data.get("title") as string,
            content: data.get("content") as string,
        });
    };

    return (
        <form onSubmit={handleSubmit}>
            <input name="title" placeholder="Post title..." required />
            <textarea name="content" placeholder="Content..." />
            <button disabled={isPending}>
                {isPending ? "Creating..." : "Create Post"}
            </button>
            {error && <p className="error">{error.message}</p>}
        </form>
    );
}
```

> **Realtime sync:** After a mutation completes, the server automatically pushes updated data via WebSocket. All `useQuery` hooks that depend on the changed data will re-render immediately.

### Security Rules

```typescript
// ✅ INSERT — always include userId
ctx.db.insert(posts).values({ ...data, userId: session.user.id });

// ✅ UPDATE/DELETE — always verify ownership (double condition)
ctx.db.update(posts).set(data)
    .where(and(eq(posts.id, id), eq(posts.userId, session.user.id)));

// ❌ WRONG — allows updating ANY user's post
ctx.db.update(posts).set(data).where(eq(posts.id, id));
```

### Next Steps

- [Authentication](/docs/guides/authentication) — Auth setup
- [Storage](/docs/guides/storage) — File upload & download
- [Cron Jobs](/docs/guides/cron-jobs) — Scheduled tasks

---

## Authentication

> Built-in auth with better-auth — signup, login, session management

Gencow includes **built-in authentication** powered by better-auth. No external services (Clerk, Auth0) needed.

### Frontend Setup

#### 1. Create Auth Client

```typescript
// src/lib/auth.ts
import { gencowAuth } from "@gencow/react";

export const { signIn, signUp, signOut, useAuth } = gencowAuth();
// Optional: pass explicit URL
// gencowAuth("http://localhost:5456")
// gencowAuth(import.meta.env.VITE_API_URL)
```

#### 2. Wrap with GencowProvider

```tsx
// src/main.tsx
import { GencowProvider } from "@gencow/react";
import { useAuth } from "./lib/auth";

function AppWrapper({ children }: { children: React.ReactNode }) {
    const { token } = useAuth();
    const baseUrl = import.meta.env.VITE_API_URL ?? "http://localhost:5456";

    return (
        <GencowProvider baseUrl={baseUrl} token={token}>
            {children}
        </GencowProvider>
    );
}
```

#### 3. Use in Components

```tsx
import { signIn, signUp, signOut, useAuth } from "./lib/auth";

function AuthComponent() {
    const { user, isAuthenticated } = useAuth();

    if (!isAuthenticated) {
        return <LoginForm />;
    }

    return (
        <div>
            <p>Welcome, {user?.name || user?.email}</p>
            <button onClick={() => signOut()}>Sign Out</button>
        </div>
    );
}
```

### Sign Up

```typescript
try {
    const user = await signUp("user@example.com", "password123", "John Doe");
    // user = { id, email, name }
    // Session is automatically established
} catch (e) {
    console.error(e.message); // "Email already registered" etc.
}
```

### Sign In

```typescript
try {
    const user = await signIn("user@example.com", "password123");
    // user = { id, email, name }
    // JWT + sessionToken automatically stored
} catch (e) {
    console.error(e.message); // "Invalid credentials" etc.
}
```

### Sign Out

```typescript
await signOut();
// JWT + sessionToken cleared from memory and localStorage
```

### useAuth Hook

```typescript
const { token, user, isAuthenticated } = useAuth();
```

| Property | Type | Description |
|---|---|---|
| `token` | `string \| null` | Current JWT access token (auto-refreshed) |
| `user` | `{ id, email, name } \| null` | Current user info |
| `isAuthenticated` | `boolean` | Whether user is logged in |

### How Auth Works

Gencow uses a **token-based auth** pattern (similar to Firebase/Supabase):

```
Sign In →  Server returns { sessionToken, token (JWT), user }
           │
           ├── JWT (5min) → stored in memory only
           ├── sessionToken (7d) → stored in localStorage
           └── user → stored in localStorage (optimistic UI)

Page reload → sessionToken from localStorage
           → POST /api/auth/token → new JWT
           → UI shows user immediately (from localStorage cache)

JWT expires → auto-refresh using sessionToken (no user action needed)
```

> **No cookies, no rewrites needed.** This eliminates cross-origin cookie issues between frontend (port 3000) and backend (port 5456).

### Backend Auth

#### Requiring Authentication

```typescript
import { query, mutation, v } from "@gencow/core";

export const list = query("tasks.list", {
    args: {},
    handler: async (ctx) => {
        // Throws error if not authenticated
        const session = ctx.auth.requireAuth();

        // session.user.id — current user's ID
        // session.user.email — current user's email
        // session.user.name — current user's name

        return ctx.db.select().from(tasks)
            .where(eq(tasks.userId, session.user.id));
    },
});
```

#### Optional Authentication

```typescript
export const listPublic = query("posts.listPublic", {
    args: {},
    handler: async (ctx) => {
        // Don't call requireAuth() — anyone can access
        return ctx.db.select().from(posts)
            .where(eq(posts.published, true));
    },
});
```

#### Auth Configuration

Customize auth in `gencow/auth.ts`:

```typescript
import { defineAuth } from "@gencow/core";

export default defineAuth({
    emailAndPassword: { enabled: true },
    // Add email verification:
    // emailVerification: {
    //     sendVerificationEmail: async ({ email, url }) => {
    //         // Send email using your preferred provider
    //     },
    // },
});
```

### Auth API Endpoints (Reference)

These are handled automatically by `gencowAuth()` — you don't need to call them directly:

| Endpoint | Method | Description |
|---|---|---|
| `/api/auth/sign-up` | POST | Sign up → `{ user, sessionToken, token }` |
| `/api/auth/sign-in` | POST | Sign in → `{ user, sessionToken, token }` |
| `/api/auth/token` | POST | Refresh JWT (Bearer sessionToken) |
| `/api/auth/sign-out` | POST | Sign out (Bearer sessionToken) |

### ❌ Common Mistakes

```typescript
// ❌ Don't create custom auth routes
fetch("/auth/register", { ... })
fetch("/api/users/login", { ... })

// ❌ Don't manage JWT tokens manually
localStorage.setItem("token", jwt)
headers: { Authorization: `Bearer ${myToken}` }

// ❌ Don't use cookies-based auth with credentials: "include"
fetch("/api/auth/sign-in/email", { credentials: "include" })

// ✅ Use gencowAuth() — it handles everything
const { signIn, signUp, signOut, useAuth } = gencowAuth();
await signIn("user@example.com", "password123");
```

### Next Steps

- [Realtime](/docs/guides/realtime) — WebSocket sync
- [Storage](/docs/guides/storage) — File uploads
- [Deployment](/docs/guides/deployment) — Environment variables for auth

---

## Realtime

> WebSocket push model — automatic data synchronization

Gencow includes **built-in realtime** via WebSocket. When data changes on the server, all connected clients receive updates automatically — no manual refetching, no polling.

### How It Works

```
React Component                    Gencow Server
    │                                      │
    ├── useQuery(api.tasks.list) ──────────┤
    │   ◄── WebSocket subscribe ───────────┤
    │   ◄── Initial data (HTTP) ───────────┤
    │                                      │
    │                    [Another client calls mutation]
    │                                      │
    │   ◄── WebSocket push (fresh data) ───┤
    │   └── Component re-renders          │
    │       automatically!                 │
```

1. `useQuery` makes an HTTP request to fetch initial data
2. It also subscribes via WebSocket for updates
3. When any mutation modifies related data, the server pushes fresh data to all subscribers
4. Your component re-renders with the new data — **zero manual refetching**

### useQuery — Reactive Data

```tsx
import { useQuery } from "@gencow/react";
import { api } from "../gencow/api";

function TaskList() {
    // Returns Task[] | undefined
    // undefined = loading (like Convex pattern)
    const tasks = useQuery(api.tasks.list);

    if (tasks === undefined) return <div>Loading...</div>;

    return (
        <ul>
            {tasks.map((t) => (
                <li key={t.id}>{t.title}</li>
            ))}
        </ul>
    );
}
```

#### With Arguments

```tsx
const task = useQuery(api.tasks.getById, { id: 42 });
```

#### Conditional Queries (Skip)

```tsx
// Method A: "skip" token (Convex-style) — recommended
const messages = useQuery(
    api.chat.getMessages,
    conversationId ? { conversationId } : "skip"
);

// Method B: enabled option (TanStack Query-style)
const messages = useQuery(
    api.chat.getMessages,
    { conversationId },
    { enabled: !!conversationId }
);
// → skip state returns undefined (no API call, no WS subscription)
```

#### Public Queries (No Auth)

```tsx
// By default, useQuery skips if no auth token
// Use { public: true } for unauthenticated endpoints
const publicPosts = useQuery(api.posts.listPublic, {}, { public: true });
```

### useMutation — Write + Auto-Refresh

```tsx
import { useMutation } from "@gencow/react";
import { api } from "../gencow/api";

function CreateTask() {
    // Returns [mutate, isPending, error]
    const [create, isPending, error] = useMutation(api.tasks.create);

    const handleSubmit = async () => {
        await create({ title: "New task" });
        // No need to refetch! WebSocket pushes update automatically
    };

    return (
        <button onClick={handleSubmit} disabled={isPending}>
            {isPending ? "Creating..." : "Create"}
        </button>
    );
}
```

> **Key concept:** After `create()` completes, the server broadcasts updated data via WebSocket. All `useQuery(api.tasks.list)` hooks across all connected tabs/clients will re-render with fresh data.

### useStatus — Connection Health

Monitor the WebSocket connection status:

```tsx
import { useStatus } from "@gencow/react";

function ConnectionIndicator() {
    const { isConnected } = useStatus();

    return (
        <span style={{ color: isConnected ? "green" : "red" }}>
            {isConnected ? "● Connected" : "○ Disconnected"}
        </span>
    );
}
```

The WebSocket automatically reconnects with exponential backoff (1s → 1.5s → 2.25s → ... up to 15s).

### ❌ Don't Use fetch() Directly

```tsx
// ❌ WRONG — bypasses realtime, no auto-refresh
fetch("/api/query", {
    method: "POST",
    body: JSON.stringify({ name: "tasks.list", args: {} }),
});

// ❌ WRONG — creating manual wrappers
const apiPost = (name, args) => fetch("/api/mutation", { ... });

// ✅ CORRECT — use hooks for automatic realtime sync
const tasks = useQuery(api.tasks.list);
const [create] = useMutation(api.tasks.create);
```

### Next Steps

- [Storage](/docs/guides/storage) — File upload & download
- [Cron Jobs](/docs/guides/cron-jobs) — Scheduled tasks
- [Deployment](/docs/guides/deployment) — Cloud deployment

---

## Storage

> File upload, download, and management with ctx.storage

Gencow provides a **Convex-compatible file storage** system. Upload files, get public URLs, and manage storage — all through `ctx.storage`.

### Uploading Files

#### From a Mutation (Backend)

```typescript
import { mutation, v } from "@gencow/core";

export const upload = mutation("files.upload", {
    args: {},
    handler: async (ctx) => {
        const session = ctx.auth.requireAuth();
        const file = ctx.file;  // File from FormData

        if (!file) throw new Error("No file provided");

        // Store file → returns a unique storageId
        const storageId = await ctx.storage.store(file);

        // Get a public serving URL
        const url = ctx.storage.getUrl(storageId);
        // → "/api/storage/550e8400-e29b-41d4-a716-446655440000"

        return {
            storageId,
            url,
            name: file.name,
            size: file.size,
            type: file.type,
        };
    },
});
```

#### Store from Buffer

```typescript
// Useful for programmatic file creation (PDFs, exports, etc.)
const csvContent = "name,email\nJohn,john@example.com";
const buffer = Buffer.from(csvContent);

const storageId = await ctx.storage.storeBuffer(
    buffer,
    "export.csv",
    "text/csv"
);

const url = ctx.storage.getUrl(storageId);
```

### Serving Files

`ctx.storage.getUrl()` returns a **public URL** that serves the file directly:

```typescript
const url = ctx.storage.getUrl(storageId);
// → "/api/storage/<uuid>"
// Full URL: "http://localhost:5456/api/storage/<uuid>"
```

Files are served with:
- Correct `Content-Type` header
- `Cache-Control: public, max-age=31536000, immutable`
- UTF-8 filename support

> **Like Convex:** File URLs are public (no auth required). Control access by only returning URLs to authorized users in your queries.

### Deleting Files

```typescript
export const remove = mutation("files.remove", {
    args: { storageId: v.string() },
    handler: async (ctx, { storageId }) => {
        const session = ctx.auth.requireAuth();
        await ctx.storage.delete(storageId);
    },
});
```

### React File Upload

```tsx
import { useMutation } from "@gencow/react";
import { api } from "../gencow/api";

function FileUpload() {
    const [upload, isPending] = useMutation(api.files.upload);

    const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
        const file = e.target.files?.[0];
        if (!file) return;

        const formData = new FormData();
        formData.append("file", file);

        const result = await upload(formData);
        console.log("Uploaded:", result.url);
    };

    return (
        <div>
            <input
                type="file"
                onChange={handleFileChange}
                disabled={isPending}
            />
            {isPending && <span>Uploading...</span>}
        </div>
    );
}
```

### Listing Files

Files are automatically recorded in a `files` table in the database. Query them:

```typescript
export const list = query("files.list", {
    args: {},
    handler: async (ctx) => {
        const session = ctx.auth.requireAuth();
        // Query the auto-created files table
        const rows = await ctx.rawSql(
            `SELECT storage_id, name, size, type, created_at
             FROM files
             ORDER BY created_at DESC`
        );
        return rows.map(r => ({
            ...r,
            url: ctx.storage.getUrl(r.storage_id),
        }));
    },
});
```

### Limits

| Limit | Value |
|---|---|
| Max file size | 50 MB per file |
| Storage quota | 1 GB per app (default) |
| Supported types | Any file type |

> Exceeding the quota throws: `Storage quota exceeded: 950MB used + 100MB new = 1.05GB, quota is 1GB`

### Storage API Reference

| Method | Description |
|---|---|
| `ctx.storage.store(file, filename?)` | Store a File/Blob → returns storageId |
| `ctx.storage.storeBuffer(buffer, filename, type?)` | Store from Buffer → returns storageId |
| `ctx.storage.getUrl(storageId)` | Get public serving URL |
| `ctx.storage.getMeta(storageId)` | Get file metadata (name, size, type) |
| `ctx.storage.delete(storageId)` | Delete a file |

### Next Steps

- [Cron Jobs](/docs/guides/cron-jobs) — Scheduled tasks
- [Deployment](/docs/guides/deployment) — Cloud deployment

---

## Cron Jobs

> Schedule tasks with cronJobs() — interval, daily, weekly, cron

Gencow provides a **built-in scheduler** for cron jobs. Define scheduled tasks in `gencow/crons.ts` and they run automatically.

### Setup

Create `gencow/crons.ts` (auto-generated by `gencow init`):

```typescript
import { cronJobs } from "@gencow/core";

const crons = cronJobs();

// Define your scheduled jobs here

export default crons;  // ← Required!
```

> **Critical:** You must `export default crons` — without it, the scheduler won't register your jobs.

### Scheduling Methods

#### interval — Run Every N Minutes/Hours

```typescript
crons.interval("syncData", { minutes: 30 }, "data.sync");
// Runs data.sync mutation every 30 minutes
```

Options: `{ minutes?: number, hours?: number, seconds?: number }`

#### daily — Run Once Per Day

```typescript
crons.daily("morningReport", { hour: 9, minute: 0 }, "reports.daily");
// Runs reports.daily mutation every day at 09:00
```

Options: `{ hour: number, minute?: number }`

#### weekly — Run Once Per Week

```typescript
crons.weekly("weeklyDigest", { dayOfWeek: 1, hour: 10 }, "reports.weekly");
// Runs reports.weekly mutation every Monday at 10:00
```

Options: `{ dayOfWeek: number (0=Sun, 1=Mon, ..., 6=Sat), hour: number, minute?: number }`

#### cron — Standard Cron Expression

```typescript
crons.cron("customSchedule", "*/15 * * * *", "tasks.cleanup");
// Standard cron: every 15 minutes
```

### Inline Handlers

Instead of referencing a mutation by name, you can pass an inline async function:

```typescript
crons.interval("healthCheck", { minutes: 5 }, async (ctx) => {
    const result = await fetch(`${process.env.GENCOW_INTERNAL_URL}/health`);
    if (!result.ok) {
        console.error("Health check failed!");
    }
});
```

### Complete Example

```typescript
// gencow/crons.ts
import { cronJobs } from "@gencow/core";

const crons = cronJobs();

// Every 30 minutes: sync external data
crons.interval("syncNews", { minutes: 30 }, "news.sync");

// Every day at 9:00 AM: generate daily report
crons.daily("dailyReport", { hour: 9 }, "reports.generateDaily");

// Every Monday at 10:00 AM: weekly summary
crons.weekly("weeklySummary", { dayOfWeek: 1, hour: 10 }, "reports.generateWeekly");

// Every 15 minutes: cleanup expired sessions
crons.cron("cleanup", "*/15 * * * *", "admin.cleanup");

export default crons;
```

#### The Mutation Handler

```typescript
// gencow/news.ts
import { mutation, v } from "@gencow/core";
import { news } from "./schema";

export const sync = mutation("news.sync", {
    args: {},
    handler: async (ctx) => {
        // Fetch external data
        const response = await fetch("https://api.example.com/news");
        const articles = await response.json();

        // Store in database
        for (const article of articles) {
            await ctx.db.insert(news).values({
                title: article.title,
                url: article.url,
                fetchedAt: new Date(),
            }).onConflictDoNothing();
        }

        console.log(`Synced ${articles.length} articles`);
    },
});
```

### Self-Fetch Pattern

When a cron job needs to call its own server's API:

```typescript
crons.interval("healthPing", { minutes: 5 }, async (ctx) => {
    // Use GENCOW_INTERNAL_URL (auto-injected at server boot)
    const url = process.env.GENCOW_INTERNAL_URL;
    const res = await fetch(`${url}/api/health`);
    console.log("Health:", res.status);
});
```

> **Note:** `GENCOW_INTERNAL_URL` is automatically set to `http://localhost:{PORT}` by the server. Don't hardcode ports.

### Register in index.ts

Make sure your cron module's mutations are exported in `gencow/index.ts`:

```typescript
export * as tasks from "./tasks";
export * as news from "./news";       // ← cron handler mutations
export * as reports from "./reports"; // ← cron handler mutations
```

### Viewing Cron Status

- **Dashboard:** Visit `http://localhost:5456/_admin` → Scheduler tab
- **Logs:** Cron execution results appear in `gencow dev` console output

### Important Notes

1. **`export default crons`** is required — without it, no jobs are registered
2. Cron handlers must be mutations (or inline async functions), not queries
3. Mutation string names (e.g., `"news.sync"`) must match exactly: `{module}.{export}`
4. All times are in **server timezone** (UTC in cloud deployments)
5. Cron jobs run even when no users are connected

### Next Steps

- [Deployment](/docs/guides/deployment) — Deploy your app with cron jobs
- [AI Engine](/docs/ai/ai-engine) — Add AI capabilities

---

## Deployment

> Deploy to Gencow Cloud — backend, static, environments, CI/CD

Gencow supports two deployment modes: **backend deployment** (API + DB) and **static deployment** (frontend files).

### Authentication

#### Login

```bash
gencow login
```

This opens your browser for Device Auth:
1. A code is displayed in the terminal
2. Browser opens to `gencow.app/cli-auth`
3. Confirm the code in the browser
4. Token is saved to `~/.gencow/credentials.json`

#### Check Status

```bash
gencow whoami
## → User ID, Token info, Expiry
```

#### Logout

```bash
gencow logout
```

### Backend Deployment

Deploy your `gencow/` backend to the cloud:

```bash
gencow deploy
```

#### What Happens

1. Bundles `gencow/` + `package.json` + lockfiles → `tar.gz`
2. Creates app on platform (if first deploy) → assigns unique `appId`
3. Uploads bundle to platform
4. Platform provisions: PostgreSQL database + isolated container
5. Saves `appId` to `gencow.json`

#### Deploy Output

```
  Gencow Deploy

  ▸ 앱:    신규 (ID 자동 생성)
  ▸ 환경:  dev
  ▸ 포맷:  tar.gz

  ✓ 번들 생성: 42.5 KB
  ✓ 앱 "null-mint-9625" 생성 완료

  ✓ 배포 완료!
  ▸ 앱 ID: null-mint-9625
  ▸ URL:   https://null-mint-9625.gencow.app
  ▸ Hash:  a1b2c3d4
```

#### Production Deploy

```bash
gencow deploy --prod
## → Confirmation prompt before deploying to production
```

### Static Deployment (Frontend)

Deploy a built frontend (Vite, Next.js, etc.):

```bash
## Build your frontend first
VITE_API_URL=https://my-app.gencow.app npm run build

## Deploy the build output
gencow deploy --static dist/
```

#### Auto-Detection

If you don't specify a directory, Gencow auto-detects in this order:
- `dist/` → `out/` → `build/` → `.next/out/`

```bash
gencow deploy --static   # auto-detects dist/
```

#### Guardrails

The CLI automatically warns about common issues:
- **API references in static files:** If your build contains `/api/query` or `/api/mutation`, Gencow warns that static hosting has no API server
- **Backend detected nearby:** If a `gencow/` folder exists in a parent directory, suggests integrated deployment instead

### Fullstack Deployment (Recommended)

For projects with both backend and frontend:

```bash
## 1. Deploy backend
gencow deploy
## → https://null-mint-9625.gencow.app

## 2. Build frontend with the backend URL
VITE_API_URL=https://null-mint-9625.gencow.app npm run build

## 3. Deploy frontend
gencow deploy --static dist/
```

> **CORS:** `*.gencow.app` subdomains are automatically allowed. For custom domains, set `CORS_ORIGINS` environment variable.

### Environment Variables

#### Set Variables

```bash
## Single variable
gencow env set OPENAI_API_KEY=sk-...

## Multiple
gencow env set DATABASE_URL=postgres://... SECRET_KEY=abc123
```

#### List Variables

```bash
gencow env list
## → Lists all remote env vars (values masked)

gencow env list --prod
## → Lists production env vars
```

#### Remove Variables

```bash
gencow env unset OPENAI_API_KEY
```

#### Push Local .env to Remote

```bash
gencow env push
## → Uploads all .env variables to remote
```

> **Security:** Environment variables are encrypted at rest. `.env` is gitignored by default.

### CI/CD Deployment

For automated deployments from GitHub Actions, GitLab CI, etc.:

#### 1. Create a Deploy Token

Go to Dashboard → Settings → Deploy Tokens → Create Token

#### 2. Set as CI Secret

```bash
## GitHub Actions: Settings → Secrets → GENCOW_TOKEN
## GitLab CI: Settings → CI/CD → Variables → GENCOW_TOKEN
```

#### 3. Use in CI Pipeline

```yaml
## .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v1
      - run: bun install
      - run: npx gencow deploy
        env:
          GENCOW_TOKEN: ${{ secrets.GENCOW_TOKEN }}
```

> When `GENCOW_TOKEN` is set, `gencow deploy` uses it instead of interactive login.

### Custom Domains

Connect your own domain to your Gencow app:

```bash
## Set domain
gencow domain set myapp.com

## Check DNS/TLS status
gencow domain status

## Remove domain
gencow domain remove
```

#### DNS Setup

Add a CNAME record pointing to your app:

| Type | Name | Value |
|---|---|---|
| CNAME | `myapp.com` | `null-mint-9625.gencow.app` |

TLS certificates are provisioned automatically via Let's Encrypt.

### Deploy Commands Reference

| Command | Description |
|---|---|
| `gencow login` | Authenticate via browser |
| `gencow logout` | Clear saved credentials |
| `gencow whoami` | Show current user info |
| `gencow deploy` | Deploy backend to dev |
| `gencow deploy --prod` | Deploy backend to production |
| `gencow deploy --static [dir]` | Deploy frontend static files |
| `gencow deploy --name my-app` | Specify app name |
| `gencow deploy stop` | Stop production containers |
| `gencow deploy logs` | Follow production logs |
| `gencow deploy status` | Check container status |
| `gencow env list` | List remote env vars |
| `gencow env set K=V` | Set remote env var |
| `gencow env unset KEY` | Remove remote env var |
| `gencow env push` | Push local .env to remote |
| `gencow domain set` | Connect custom domain |
| `gencow domain status` | Check domain DNS/TLS |
| `gencow domain remove` | Disconnect domain |

### Next Steps

- [AI Engine](/docs/ai/ai-engine) — Add AI capabilities
- [Components](/docs/ai/components) — `gencow add` components
- [CLI Reference](/docs/api-reference/cli) — All CLI commands

---

## AI Engine

> Built-in AI with ctx.ai — chat, stream, embed, structured output

Gencow includes a built-in AI engine powered by the **Vercel AI SDK**. Use `ctx.ai` inside mutations to call LLMs — no API key management in production.

### Quick Setup

```bash
## Add the AI component (installs ai + @ai-sdk/openai)
gencow add AI
```

This creates `gencow/ai.ts` with a pre-configured AI engine.

### Using AI in Mutations

#### Chat (Non-Streaming)

```typescript
import { mutation, v } from "@gencow/core";
import { ai } from "./ai";

export const chat = mutation("chat.send", {
    args: {
        messages: v.array(v.object({
            role: v.string(),
            content: v.string(),
        })),
    },
    handler: async (ctx, { messages }) => {
        ctx.auth.requireAuth();

        const reply = await ai.chat({
            system: "You are a helpful assistant.",
            messages,
            model: "gpt-4o-mini",  // or "gpt-4o"
        });

        return { role: "assistant", content: reply };
    },
});
```

#### Streaming

```typescript
export const streamChat = mutation("chat.stream", {
    args: {
        messages: v.array(v.object({
            role: v.string(),
            content: v.string(),
        })),
    },
    handler: async (ctx, { messages }) => {
        ctx.auth.requireAuth();

        const stream = await ai.stream({
            system: "You are a helpful assistant.",
            messages,
        });

        // stream is an async iterable
        let fullText = "";
        for await (const chunk of stream) {
            fullText += chunk;
        }

        return { role: "assistant", content: fullText };
    },
});
```

#### Structured Output

Get typed JSON responses:

```typescript
export const analyze = mutation("tasks.analyze", {
    args: { text: v.string() },
    handler: async (ctx, { text }) => {
        ctx.auth.requireAuth();

        const result = await ai.chat({
            system: "Analyze the text and extract structured data.",
            messages: [{ role: "user", content: text }],
            responseFormat: {
                type: "json_object",
                schema: {
                    sentiment: "positive | negative | neutral",
                    keywords: "string[]",
                    summary: "string",
                },
            },
        });

        return JSON.parse(result);
    },
});
```

#### Embeddings

```typescript
const embedding = await ai.embed("Hello, world!");
// → number[] (1536 dimensions for text-embedding-3-small)
```

### API Key Setup

#### Local Development

Add your OpenAI API key to `.env`:

```bash
OPENAI_API_KEY=sk-your-key-here
```

#### Production (Gencow Cloud)

**No key needed!** Deployed apps use the Gencow Platform AI proxy automatically. The platform handles:
- API key management
- Usage tracking
- Credit billing

> **Important:** Do not create `OPENAI_API_KEY` placeholders in `.env` for production. The platform proxy injects the key automatically.

### Available Models

| Model | Best For | Speed | Cost |
|---|---|---|---|
| `gpt-4o-mini` | General tasks, fast responses | ⚡ Fast | $ Low |
| `gpt-4o` | Complex reasoning, analysis | 🐢 Slower | $$$ High |

### ❌ Don't Install OpenAI SDK Directly

```bash
## ❌ Don't do this
npm install openai

## ✅ Use gencow add AI instead
gencow add AI
```

The `gencow add AI` command installs the correct dependencies (`ai`, `@ai-sdk/openai`) and creates a pre-configured `ai.ts` wrapper.

### Next Steps

- [Components](/docs/ai/components) — All `gencow add` components
- [RAG & Memory](/docs/ai/rag-memory) — Document search and agent memory

---

## Components

> Add AI capabilities with gencow add — RAG, Memory, Tools, Guardrails, and more

The `gencow add` command installs pre-built AI components into your project. Each component adds files to `gencow/` and installs required dependencies.

### Usage

```bash
## Add a single component
gencow add AI

## Add multiple at once
gencow add AI RAG Reranker

## Dependencies auto-resolve (RAG requires AI → AI is added automatically)
gencow add RAG   # → also installs AI
```

### Available Components

| # | Component | Description | Requires |
|---|---|---|---|
| 1 | **AI** | Vercel AI SDK wrapper (chat, stream, embed) | — |
| 2 | **Tools** | AI Tool Calling with `ctx` integration | AI |
| 3 | **RAG** | Document ingestion + semantic search | AI |
| 4 | **Memory** | Agent memory (episodic/semantic/procedural) | AI |
| 5 | **Reranker** | LLM-powered search result reranking | AI |
| 6 | **Guardrails** | Input/output safety filters (PII, topic blocking) | AI |
| 7 | **Prompts** | Reusable prompt templates | — |
| 8 | **Parsers** | PDF/HTML/CSV file parsing | — |
| 9 | **Analytics** | LLM call tracking | AI *(coming soon)* |

### Component Details

#### AI — Core Engine

```bash
gencow add AI
```

Creates `gencow/ai.ts`. Provides:

```typescript
ai.chat({ system, messages, model })    // Non-streaming response
ai.stream({ system, messages, model })  // Streaming response
ai.embed(text)                          // Generate embeddings
```

**Installed deps:** `ai`, `@ai-sdk/openai`
**Env required:** `OPENAI_API_KEY` (local only — auto in cloud)

#### RAG — Document Search

```bash
gencow add RAG
```

Creates `gencow/rag.ts` + `gencow/schema-rag.ts`. Provides:

```typescript
// Ingest documents
await rag.ingest(ctx, "source-name", "Document text content...");

// Search with semantic similarity
const results = await rag.search(ctx, "What is Gencow?");
// → [{ content, source, score }]
```

> **Important:** Import `schema-rag.ts` in your main `schema.ts` to create the required DB tables.

---

#### Memory — Agent Memory

```bash
gencow add Memory
```

Creates `gencow/memory.ts` + `gencow/schema-memory.ts`. Three memory types:

```typescript
// Build context from memory for AI conversations
const memCtx = await memory.buildContext(ctx, userId, sessionId, query);
// → { episodic, semantic, procedural }

// Extract and store memories from conversation
await memory.extract(ctx, userId, sessionId, messages);
```

| Type | Purpose | Example |
|---|---|---|
| **Episodic** | Conversation history | "Last time we discussed…" |
| **Semantic** | Facts and knowledge | "User prefers dark mode" |
| **Procedural** | Learned procedures | "When user asks X, do Y" |

---

#### Reranker — Result Quality

```bash
gencow add Reranker
```

Creates `gencow/reranker.ts`. Improves search result relevance:

```typescript
// Rerank search results
const reranked = await reranker.rerank(query, searchResults, { topK: 5 });

// Combined RAG pipeline: search + rerank
const results = await reranker.searchAndRerank(ctx, rag, query);
```

---

#### Guardrails — Safety Filters

```bash
gencow add Guardrails
```

Creates `gencow/guardrails.ts`. Input/output validation:

```typescript
// Validate input
const safe = await guardrails.validateInput(userText, {
    maskPII: true,           // Mask phone numbers, emails, etc.
    blockTopics: ["politics"], // Block specific topics
});

// Validate output
const cleanOutput = await guardrails.validateOutput(aiResponse, {
    removePII: true,
});

// Wrap a function with both input and output guards
const result = await guardrails.wrap(
    myFunction, input, inputOptions, outputOptions
);
```

---

#### Prompts — Reusable Templates

```bash
gencow add Prompts
```

Creates `gencow/prompts.ts`. Pre-built prompt templates:

```typescript
import { ragQAPrompt, summarizePrompt, classifyPrompt } from "./prompts";

// RAG Q&A
const prompt = ragQAPrompt({
    question: "What is Gencow?",
    context: "Retrieved context here...",
});

// Summarization
const prompt = summarizePrompt({ text: "Long text to summarize..." });

// Classification
const prompt = classifyPrompt({
    text: "I love this product!",
    categories: ["positive", "negative", "neutral"],
});
```

---

#### Parsers — File Parsing

```bash
gencow add Parsers
```

Creates `gencow/parsers.ts`. Parse various file formats:

```typescript
// PDF
const text = await parsers.pdf(buffer);

// HTML
const text = await parsers.html(htmlString);

// CSV
const rows = await parsers.csv(csvString);

// Auto-detect by filename
const text = await parsers.auto("document.pdf", buffer);

// RAG integration
await rag.ingest(ctx, "manual.pdf", await parsers.pdf(buffer));
```

**Installed deps:** `pdf-parse`

### Dependency Resolution

Components automatically install their dependencies:

```bash
gencow add RAG
## → Also installs AI (because RAG requires AI)
```

```bash
gencow add RAG Reranker Memory
## → Installs AI first, then RAG, Reranker, Memory
```

### After Installation

```bash
## README is auto-updated with new component docs
gencow dev
```

Each component's usage is added to the auto-generated `gencow/README.md`.

### Next Steps

- [RAG & Memory](/docs/ai/rag-memory) — Deep dive into document search and agent memory
- [CLI Reference](/docs/api-reference/cli) — All CLI commands

---

## RAG & Memory

> Document ingestion, semantic search, and agent memory systems

This guide covers the **RAG** (Retrieval-Augmented Generation) and **Memory** components in detail.

### RAG — Document Search Pipeline

RAG enables your AI to answer questions based on your own documents.

#### Setup

```bash
gencow add RAG
```

This creates:
- `gencow/rag.ts` — RAG engine (ingest, search)
- `gencow/schema-rag.ts` — Database tables for document chunks & embeddings

> **Important:** Import `schema-rag.ts` in your schema to create the tables:
> ```typescript
> // gencow/schema.ts
> export * from "./schema-rag";
> ```

#### Ingest Documents

```typescript
import { mutation, v } from "@gencow/core";
import { rag } from "./rag";

export const ingestDoc = mutation("docs.ingest", {
    args: { source: v.string(), content: v.string() },
    handler: async (ctx, { source, content }) => {
        ctx.auth.requireAuth();

        // Automatically chunks, embeds, and stores
        await rag.ingest(ctx, source, content);
        return { status: "ingested", source };
    },
});
```

#### Search Documents

```typescript
import { query, v } from "@gencow/core";
import { rag } from "./rag";

export const search = query("docs.search", {
    args: { question: v.string() },
    handler: async (ctx, { question }) => {
        ctx.auth.requireAuth();

        const results = await rag.search(ctx, question);
        // → [{ content, source, score }, ...]

        return results;
    },
});
```

#### RAG + AI Q&A Pipeline

```typescript
import { mutation, v } from "@gencow/core";
import { ai } from "./ai";
import { rag } from "./rag";

export const ask = mutation("docs.ask", {
    args: { question: v.string() },
    handler: async (ctx, { question }) => {
        ctx.auth.requireAuth();

        // 1. Search relevant documents
        const results = await rag.search(ctx, question);

        // 2. Build context from results
        const context = results
            .map(r => `[${r.source}]: ${r.content}`)
            .join("\n\n");

        // 3. Ask AI with context
        const answer = await ai.chat({
            system: `Answer based on the following context. If the answer is not in the context, say "I don't know."

Context:
${context}`,
            messages: [{ role: "user", content: question }],
        });

        return {
            answer,
            sources: results.map(r => r.source),
        };
    },
});
```

#### With Parsers + Reranker

Full document pipeline:

```typescript
import { parsers } from "./parsers";
import { rag } from "./rag";
import { reranker } from "./reranker";

// Ingest: Parse PDF → chunk → embed → store
export const ingestPdf = mutation("docs.ingestPdf", {
    args: {},
    handler: async (ctx) => {
        ctx.auth.requireAuth();
        const file = ctx.file;
        if (!file) throw new Error("No file");

        const text = await parsers.pdf(Buffer.from(await file.arrayBuffer()));
        await rag.ingest(ctx, file.name, text);
    },
});

// Search: Query → search → rerank → top results
export const smartSearch = query("docs.smartSearch", {
    args: { question: v.string() },
    handler: async (ctx, { question }) => {
        ctx.auth.requireAuth();

        // Search + rerank for better relevance
        const results = await reranker.searchAndRerank(ctx, rag, question);
        return results;
    },
});
```

### Memory — Agent Memory System

Memory gives your AI agents persistent context across conversations.

#### Setup

```bash
gencow add Memory
```

This creates:
- `gencow/memory.ts` — Memory engine
- `gencow/schema-memory.ts` — Database tables for memory storage

> Import in schema: `export * from "./schema-memory";`

#### Three Memory Types

| Type | Purpose | Example |
|---|---|---|
| **Episodic** | Recent conversation history | "5 minutes ago you asked about…" |
| **Semantic** | Facts learned about the user | "User prefers Korean language" |
| **Procedural** | Learned behaviors and rules | "When user says 'report', generate PDF" |

#### Building Context

Before each AI response, build context from memory:

```typescript
export const chat = mutation("agent.chat", {
    args: {
        sessionId: v.string(),
        message: v.string(),
    },
    handler: async (ctx, { sessionId, message }) => {
        const session = ctx.auth.requireAuth();
        const userId = session.user.id;

        // 1. Build memory context
        const memCtx = await memory.buildContext(
            ctx, userId, sessionId, message
        );

        // 2. Include memory in AI prompt
        const reply = await ai.chat({
            system: `You are a helpful assistant.

Memory context:
${memCtx.episodic ? `Recent: ${memCtx.episodic}` : ""}
${memCtx.semantic ? `Known facts: ${memCtx.semantic}` : ""}
${memCtx.procedural ? `Learned rules: ${memCtx.procedural}` : ""}`,
            messages: [{ role: "user", content: message }],
        });

        // 3. Extract and store new memories
        await memory.extract(ctx, userId, sessionId, [
            { role: "user", content: message },
            { role: "assistant", content: reply },
        ]);

        return { role: "assistant", content: reply };
    },
});
```

#### Memory Lifecycle

```
User: "I prefer responses in Korean"
        │
        ├── memory.extract() → stores semantic memory:
        │   "User prefers Korean language responses"
        │
        [Next conversation]
        │
        ├── memory.buildContext() → retrieves:
        │   semantic: "User prefers Korean language responses"
        │
        └── AI responds in Korean ✅
```

### Next Steps

- [CLI Reference](/docs/api-reference/cli) — All CLI commands
- [React Hooks](/docs/api-reference/react) — Frontend API reference
- [Core API](/docs/api-reference/core) — Backend API reference

---

## CLI Reference

> Complete Gencow CLI command reference

### Quick Start

```bash
gencow <command> [options]
```

### Project Commands

#### `gencow init <name>`

Create a new Gencow project.

```bash
gencow init my-app
gencow init .                    # current directory
gencow init my-app -t fullstack  # with template
gencow init . --force            # non-empty directory
```

| Flag | Description |
|---|---|
| `--template, -t` | Template: `default`, `task-app`, `fullstack`, `ai-chat` |
| `--force, -f` | Initialize in non-empty directory (preserves existing files) |

#### `gencow dev`

Start development server with hot-reload.

```bash
gencow dev             # Cloud development (default)
gencow dev --local     # Local PGlite database
gencow dev --verbose   # Show all HTTP logs
```

| Flag | Description |
|---|---|
| `--local` | Use PGlite embedded database instead of cloud |
| `--verbose` | Show admin/ws/auth HTTP logs (normally suppressed) |

**What it does:**
- Starts Hono server at `http://localhost:5456`
- Opens admin dashboard at `http://localhost:5456/_admin`
- Auto-generates `gencow/api.ts` and `gencow/README.md` on file changes
- Hot-reloads on code changes
- Syncs schema with database

#### `gencow dashboard`

Open the admin dashboard in your browser.

```bash
gencow dashboard
## → Opens http://localhost:5456/_admin
```

#### `gencow codegen`

Generate frontend API client without starting the dev server.

```bash
gencow codegen
gencow codegen --outdir src/gencow/
```

| Flag | Description |
|---|---|
| `--outdir, -o` | Output directory (default: `src/gencow/`) |

#### `gencow add <component...>`

Add AI components to your project.

```bash
gencow add AI
gencow add AI RAG Reranker
gencow add Guardrails Prompts
```

**Available components:** AI, Tools, RAG, Reranker, Guardrails, Prompts, Parsers, Memory, Analytics

Dependencies are auto-resolved (e.g., `gencow add RAG` also installs AI).

#### `gencow mcp`

Start MCP (Model Context Protocol) server for AI agent integration.

```bash
gencow mcp
## → Starts stdio-based MCP server
```

### Database Commands

#### `gencow db:push`

Sync `schema.ts` → database instantly (no migration files). Auto-detects cloud/local.

```bash
gencow db:push
```

#### `gencow db:generate`

Generate SQL migration files from `schema.ts` changes.

```bash
gencow db:generate
## → Creates files in migrations/
```

#### `gencow db:migrate`

Apply pending migration files.

```bash
gencow db:migrate
```

#### `gencow db:seed`

Run `gencow/seed.ts` to insert test data (server must be running).

```bash
gencow db:seed
```

#### `gencow db:reset`

Truncate all data and re-run seed.ts.

```bash
gencow db:reset
```

⚠️ **Destructive:** Deletes all data. In offline mode (PGlite), deletes the database file entirely.

#### `gencow db:restore`

Restore database from a backup.

```bash
gencow db:restore
```

#### `gencow db:studio`

Open Drizzle Studio (visual database browser).

```bash
gencow db:studio
```

### BaaS Commands (Login Required)

#### `gencow login`

Authenticate via browser (Device Auth flow).

```bash
gencow login
## → Opens browser for authentication
## → Saves token to ~/.gencow/credentials.json
```

#### `gencow logout`

Clear saved credentials.

```bash
gencow logout
```

#### `gencow whoami`

Show current user info and token status.

```bash
gencow whoami
```

#### `gencow deploy`

Deploy to Gencow Platform.

```bash
gencow deploy                # Deploy backend (dev)
gencow deploy --prod         # Deploy to production
gencow deploy --name my-app  # Specify app name
gencow deploy --static       # Deploy static frontend
gencow deploy --static dist/ # Specify static directory
gencow deploy stop           # Stop production containers
gencow deploy logs           # Follow production logs
gencow deploy status         # Container status
```

| Flag | Description |
|---|---|
| `--prod` | Deploy to production (requires confirmation) |
| `--name, -n` | Specify app name |
| `--static [dir]` | Deploy static files (auto-detects dist/out/build/) |

#### `gencow env`

Manage remote environment variables.

```bash
gencow env list              # List all remote vars
gencow env list --prod       # List production vars
gencow env set KEY=VALUE     # Set a variable
gencow env unset KEY         # Remove a variable
gencow env push              # Push local .env to remote
```

#### `gencow domain`

Manage custom domains.

```bash
gencow domain set myapp.com   # Connect custom domain
gencow domain status          # Check DNS/TLS status
gencow domain remove          # Disconnect domain
```

### Environment Variables

| Variable | Description |
|---|---|
| `GENCOW_TOKEN` | Deploy token for CI/CD (bypasses `gencow login`) |
| `GENCOW_PLATFORM_URL` | Platform URL (default: `https://gencow.app`) |
| `OPENAI_API_KEY` | OpenAI API key (local dev only) |
| `DATABASE_URL` | PostgreSQL connection URL (production) |
| `GENCOW_INTERNAL_URL` | Auto-injected server URL for self-fetch |

### Next Steps

- [React Hooks](/docs/api-reference/react) — Frontend API
- [Core API](/docs/api-reference/core) — Backend API

---

## React Hooks

> @gencow/react — GencowProvider, useQuery, useMutation, gencowAuth

The `@gencow/react` package provides React hooks for Gencow — like `@convex/react` but with built-in auth.

```bash
npm install @gencow/react
```

### GencowProvider

Wrap your app to provide `baseUrl` and auth `token` to all hooks.

```tsx
import { GencowProvider } from "@gencow/react";

<GencowProvider baseUrl="http://localhost:5456" token={token}>
    {children}
</GencowProvider>
```

#### Props

| Prop | Type | Description |
|---|---|---|
| `baseUrl` | `string` | Gencow server URL |
| `token` | `string \| null` | JWT auth token (from `useAuth()`) |
| `children` | `React.ReactNode` | Child components |

#### Recommended Setup

```tsx
import { GencowProvider } from "@gencow/react";
import { useAuth } from "./lib/auth";

function AppProvider({ children }: { children: React.ReactNode }) {
    const { token } = useAuth();
    const baseUrl = import.meta.env.VITE_API_URL ?? "http://localhost:5456";

    return (
        <GencowProvider baseUrl={baseUrl} token={token}>
            {children}
        </GencowProvider>
    );
}
```

### useQuery

Reactive data fetching. Returns `T | undefined` (undefined = loading, like Convex).

#### Signature

```typescript
function useQuery<T>(
    def: QueryDef<T>,
    args?: Args | "skip",
    options?: { enabled?: boolean; public?: boolean }
): T | undefined;
```

#### Parameters

| Parameter | Type | Description |
|---|---|---|
| `def` | `QueryDef<T>` | Query definition from `api.ts` |
| `args` | `object \| "skip"` | Arguments for the query. Pass `"skip"` to disable |
| `options.enabled` | `boolean` | When `false`, query is skipped (default: `true`) |
| `options.public` | `boolean` | When `true`, query runs without auth token (default: `false`) |

#### Return Value

- `undefined` — Query is loading or skipped
- `T` — Query result (auto-updated via WebSocket)

#### Examples

```tsx
import { useQuery } from "@gencow/react";
import { api } from "../gencow/api";

// Basic query
const tasks = useQuery(api.tasks.list);
// → Task[] | undefined

// With arguments
const task = useQuery(api.tasks.getById, { id: 42 });

// Conditional: Convex-style "skip" token
const messages = useQuery(
    api.chat.getMessages,
    conversationId ? { conversationId } : "skip"
);

// Conditional: TanStack Query-style enabled
const messages = useQuery(
    api.chat.getMessages,
    { conversationId },
    { enabled: !!conversationId }
);

// Public query (no auth required)
const publicPosts = useQuery(
    api.posts.listPublic,
    {},
    { public: true }
);
```

#### Auto-Skip Behavior

`useQuery` automatically skips when:
1. `args` is `"skip"`
2. `options.enabled` is `false`
3. No auth `token` available AND `options.public` is not `true`

### useMutation

Execute mutations with pending state and error tracking.

#### Signature

```typescript
function useMutation<T>(
    def: MutationDef<T>
): [
    (args: Args) => Promise<Return>,  // mutate function
    boolean,                           // isPending
    Error | null                       // error
];
```

#### Return Value

| Index | Type | Description |
|---|---|---|
| `[0]` | `(args) => Promise` | Mutation function |
| `[1]` | `boolean` | Whether mutation is in progress |
| `[2]` | `Error \| null` | Last error (or null) |

#### Examples

```tsx
import { useMutation } from "@gencow/react";
import { api } from "../gencow/api";

function CreateTask() {
    const [create, isPending, error] = useMutation(api.tasks.create);

    return (
        <div>
            <button
                onClick={() => create({ title: "New task" })}
                disabled={isPending}
            >
                {isPending ? "Creating..." : "Create"}
            </button>
            {error && <p className="error">{error.message}</p>}
        </div>
    );
}
```

#### File Upload (FormData)

```tsx
const [upload, isPending] = useMutation(api.files.upload);

const handleUpload = async (file: File) => {
    const formData = new FormData();
    formData.append("file", file);
    const result = await upload(formData);
    // result = { storageId, url, name, size }
};
```

### useStatus

Monitor WebSocket connection health.

#### Signature

```typescript
function useStatus(): { isConnected: boolean };
```

#### Example

```tsx
import { useStatus } from "@gencow/react";

function StatusBar() {
    const { isConnected } = useStatus();

    return (
        <div className={isConnected ? "online" : "offline"}>
            {isConnected ? "● Connected" : "○ Reconnecting..."}
        </div>
    );
}
```

### gencowAuth

Create a complete auth client. Returns auth functions and hooks.

#### Signature

```typescript
function gencowAuth(baseUrl?: string): {
    signIn: (email: string, password: string) => Promise<AuthUser>;
    signUp: (email: string, password: string, name?: string) => Promise<AuthUser>;
    signOut: () => Promise<void>;
    useAuth: () => { token: string | null; user: AuthUser | null; isAuthenticated: boolean };
    store: AuthStore;  // Internal store (advanced use)
};
```

#### Setup

```typescript
// src/lib/auth.ts — one file, done
import { gencowAuth } from "@gencow/react";
export const { signIn, signUp, signOut, useAuth } = gencowAuth();
```

#### signIn

```typescript
const user = await signIn("user@example.com", "password123");
// user = { id: "abc123", email: "user@example.com", name: "John" }
// JWT + sessionToken automatically managed
```

#### signUp

```typescript
const user = await signUp("user@example.com", "password123", "John Doe");
// Same return as signIn — session is established immediately
```

#### signOut

```typescript
await signOut();
// Clears JWT, sessionToken, and user from memory + localStorage
```

#### useAuth

```tsx
function Profile() {
    const { user, isAuthenticated, token } = useAuth();

    if (!isAuthenticated) return <LoginPage />;

    return <div>Welcome, {user.name}!</div>;
}
```

#### Token Refresh Flow

```
JWT (5min)  ← memory only, auto-refreshed 10sec before expiry
sessionToken (7d)  ← localStorage, used to refresh JWT
user  ← localStorage, shown immediately on page load
```

### defineQuery / defineMutation

Factory functions to create type-safe query/mutation definitions. Used in auto-generated `api.ts`.

```typescript
import { defineQuery, defineMutation } from "@gencow/react";
import type * as tasks from "./tasks.ts";

// Creates a QueryDef that infers types from the backend function
export const listTasks = defineQuery<typeof tasks.list>("tasks.list");

// Creates a MutationDef with inferred args and return type
export const createTask = defineMutation<typeof tasks.create>("tasks.create");
```

> **Normally you don't call these directly** — `gencow dev` auto-generates `api.ts` with all definitions.

### Type Inference

Types flow end-to-end:

```typescript
// Backend (gencow/tasks.ts)
export const list = query("tasks.list", {
    args: {},
    handler: async (ctx): Promise<Task[]> => { ... }
});

// Auto-generated (gencow/api.ts)
export const api = {
    tasks: {
        list: defineQuery<typeof tasks.list>("tasks.list"),
    },
};

// Frontend (component.tsx)
const tasks = useQuery(api.tasks.list);
//    ^? Task[] | undefined  ← fully typed!
```

### Next Steps

- [Core API](/docs/api-reference/core) — Backend API reference
- [Authentication Guide](/docs/guides/authentication) — Auth setup walkthrough

---

## Core API

> @gencow/core — query, mutation, httpAction, ctx, validator, cronJobs

The `@gencow/core` package provides backend primitives for Gencow — queries, mutations, HTTP actions, validators, and schedulers.

### query()

Define a read-only data endpoint.

```typescript
import { query, v } from "@gencow/core";

export const list = query("module.functionName", {
    args: { /* validation schema */ },
    handler: async (ctx, args) => {
        // Read data from ctx.db
        return result;
    },
});
```

#### Parameters

| Parameter | Type | Description |
|---|---|---|
| `name` | `string` | Unique identifier: `"module.function"` |
| `args` | `object` | Input validation schema using `v` validators |
| `handler` | `(ctx, args) => Promise<T>` | Async function that returns data |

#### Name Convention

The name string must match the module export pattern:
- File: `gencow/tasks.ts`, export: `list` → name: `"tasks.list"`
- File: `gencow/posts.ts`, export: `getById` → name: `"posts.getById"`

### mutation()

Define a data-modification endpoint.

```typescript
import { mutation, v } from "@gencow/core";

export const create = mutation("tasks.create", {
    args: { title: v.string() },
    handler: async (ctx, { title }) => {
        const session = ctx.auth.requireAuth();
        const [task] = await ctx.db
            .insert(tasks)
            .values({ title, userId: session.user.id })
            .returning();
        return task;
    },
});
```

Same signature as `query()`, but intended for write operations. Mutations trigger WebSocket push to all subscribed `useQuery` hooks.

### httpAction()

Define custom HTTP endpoints (REST-style routes).

```typescript
import { httpAction } from "@gencow/core";

// GET /api/health
export const health = httpAction("http.health", {
    method: "GET",
    path: "/health",
    handler: async (req, ctx) => {
        return { status: "ok", uptime: process.uptime() };
    },
});

// POST /api/webhook
export const webhook = httpAction("http.webhook", {
    method: "POST",
    path: "/webhook",
    handler: async (req, ctx) => {
        const body = await req.json();
        // Process webhook payload
        return { received: true };
    },
});
```

#### httpAction Parameters

| Parameter | Type | Description |
|---|---|---|
| `method` | `"GET" \| "POST" \| "PUT" \| "DELETE"` | HTTP method |
| `path` | `string` | URL path (e.g., `/health`) |
| `handler` | `(req, ctx) => Promise<T>` | Handler function |

#### Request Object

| Property | Type | Description |
|---|---|---|
| `req.json()` | `Promise<any>` | Parse JSON body |
| `req.text()` | `Promise<string>` | Get raw body text |
| `req.headers` | `Headers` | HTTP headers |
| `req.query` | `Record<string, string>` | URL query parameters |
| `req.params` | `Record<string, string>` | URL path parameters |

### ctx — The Context Object

Every `query` and `mutation` handler receives `ctx`:

```typescript
handler: async (ctx, args) => {
    // Database
    ctx.db                    // Drizzle ORM instance
    ctx.rawSql(sql, params)   // Raw SQL execution

    // Auth
    ctx.auth.requireAuth()    // Returns session (throws if not authed)
    ctx.auth.getSession()     // Returns session or null

    // Storage
    ctx.storage.store(file)   // Store file → storageId
    ctx.storage.getUrl(id)    // Get serving URL
    ctx.storage.delete(id)    // Delete file

    // Scheduler
    ctx.scheduler.runAfter(delayMs, "mutation.name", args)
    ctx.scheduler.runAt(timestamp, "mutation.name", args)

    // AI (when gencow add AI is installed)
    ctx.ai.chat({ system, messages })
    ctx.ai.stream({ system, messages })
    ctx.ai.embed(text)

    // File (from FormData uploads)
    ctx.file                  // File object from multipart upload
}
```

#### ctx.db — Database

Drizzle ORM instance for type-safe queries:

```typescript
import { eq, and, desc } from "drizzle-orm";
import { tasks } from "./schema";

// SELECT
const rows = await ctx.db.select().from(tasks).where(eq(tasks.id, 1));

// INSERT
const [row] = await ctx.db.insert(tasks).values({ title: "..." }).returning();

// UPDATE
await ctx.db.update(tasks).set({ done: true }).where(eq(tasks.id, 1));

// DELETE
await ctx.db.delete(tasks).where(eq(tasks.id, 1));
```

#### ctx.auth — Authentication

```typescript
// Require authentication (throws 401 if not logged in)
const session = ctx.auth.requireAuth();
// session.user.id    — User ID
// session.user.email — User email
// session.user.name  — User name

// Optional authentication
const session = ctx.auth.getSession();
// null if not authenticated
```

#### ctx.storage — File Storage

```typescript
// Store a file
const storageId = await ctx.storage.store(file, "optional-filename");

// Store from buffer
const storageId = await ctx.storage.storeBuffer(buffer, "name.pdf", "application/pdf");

// Get public URL
const url = ctx.storage.getUrl(storageId);
// → "/api/storage/<uuid>"

// Get metadata
const meta = await ctx.storage.getMeta(storageId);
// → { id, name, size, type, path }

// Delete
await ctx.storage.delete(storageId);
```

#### ctx.scheduler — Delayed Execution

```typescript
// Run after delay (milliseconds)
await ctx.scheduler.runAfter(0, "emails.send", { to: "user@example.com" });
await ctx.scheduler.runAfter(60_000, "tasks.cleanup", {}); // 1 minute later

// Run at specific time
await ctx.scheduler.runAt(new Date("2026-03-27T09:00:00"), "reports.generate", {});
```

### v — Validator

Built-in argument validation (similar to Zod but lighter):

```typescript
import { v } from "@gencow/core";
```

#### Available Validators

| Validator | Description | Example |
|---|---|---|
| `v.string()` | String | `"hello"` |
| `v.number()` | Number | `42` |
| `v.boolean()` | Boolean | `true` |
| `v.optional(v.X())` | Optional field | `undefined` or value |
| `v.array(v.X())` | Array | `[1, 2, 3]` |
| `v.object({...})` | Nested object | `{ key: "value" }` |

#### Usage in Args

```typescript
{
    args: {
        title: v.string(),
        count: v.number(),
        active: v.boolean(),
        tags: v.array(v.string()),
        config: v.optional(v.object({
            theme: v.string(),
            limit: v.number(),
        })),
    },
}
```

### cronJobs()

Define scheduled tasks:

```typescript
import { cronJobs } from "@gencow/core";

const crons = cronJobs();

crons.interval("name", { minutes: 30 }, "module.mutation");
crons.daily("name", { hour: 9 }, "module.mutation");
crons.weekly("name", { dayOfWeek: 1, hour: 10 }, "module.mutation");
crons.cron("name", "*/15 * * * *", "module.mutation");
// Or inline handler:
crons.interval("name", { minutes: 5 }, async (ctx) => { ... });

export default crons;  // Required!
```

### defineAuth()

Configure authentication:

```typescript
import { defineAuth } from "@gencow/core";

export default defineAuth({
    emailAndPassword: { enabled: true },
    // emailVerification: { ... },
});
```

### withRetry()

Retry failed operations with exponential backoff:

```typescript
import { withRetry } from "@gencow/core";

const result = await withRetry(
    () => fetch("https://api.example.com/data"),
    { maxRetries: 3, initialDelay: 1000 }
);
```

#### Options

| Option | Default | Description |
|---|---|---|
| `maxRetries` | `3` | Maximum retry attempts |
| `initialDelay` | `1000` | Initial delay in ms |
| `maxDelay` | `30000` | Maximum delay in ms |
| `backoffMultiplier` | `2` | Delay multiplier per retry |

---