feat: initialize Prisma in packages/database with Docker Postgres

- add docker-compose.yml for Postgres 18 (alpine)
- initialize Prisma ORM in packages/database with pg adapter
- add User placeholder model + first migration
- document module resolution and generator gotchas in SETUP.md

Author: codebyrashel

.env.example

@@ -0,0 +1,4 @@
+POSTGRES_USER=kaeru
+POSTGRES_PASSWORD=kaeru_dev_password
+POSTGRES_DB=kaeru
+POSTGRES_PORT=5432

Makefile

@@ -0,0 +1,10 @@
+.PHONY: db-up db-down db-logs
+
+db-up:
+	docker compose up -d postgres
+
+db-down:
+	docker compose down
+
+db-logs:
+	docker compose logs -f postgres

docker-compose.yml

@@ -0,0 +1,21 @@
+services:
+  postgres:
+    image: postgres:18-alpine
+    container_name: kaeru-postgres
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-kaeru}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-kaeru_dev_password}
+      POSTGRES_DB: ${POSTGRES_DB:-kaeru}
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - postgres_data:/var/lib/postgresql
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-kaeru}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:

docs/SETUP.md

@@ -0,0 +1,19 @@
+## packages/database - gotchas
+
+- **moduleResolution**: set to `"bundler"` in tsconfig.json, not the
+  `tsc --init` default. This package is only ever consumed through
+  Next.js/Turbopack, never run directly with plain `node`, so bundler
+  resolution is correct - it understands package.json `exports` maps
+  (needed for `dotenv/config`, `prisma/config`) without requiring
+  explicit file extensions on every relative import.
+
+- **Prisma client import path**: schema.prisma uses the `prisma-client`
+  generator, which outputs a flat structure - `generated/client/client.ts`
+  is the documented main entry point, there is no `index.ts` barrel.
+  Always import from `./generated/client/client`, not `./generated/client`.
+  This will look wrong at a glance; it isn't.
+
+- **Postgres 18 volume mount**: docker-compose.yml mounts the volume at
+  `/var/lib/postgresql` (not `/var/lib/postgresql/data`). Postgres 18+
+  manages a version-specific subdirectory itself; mounting directly at
+  the old `/data` path causes a crash-loop.

packages/database/.agents/skills/prisma-cli/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: prisma-cli
+description: Prisma ORM CLI commands reference covering init, generate, migrate, db, dev, studio, validate, format, debug, and mcp. Use for ORM/database CLI workflows, not Prisma Compute app deployment. For Prisma Compute, `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, apps, deployments, logs, or domains, use the `prisma-compute` skill instead. Triggers on "prisma init", "prisma generate", "prisma migrate", "prisma db", "prisma studio", "prisma mcp".
+license: MIT
+metadata:
+  author: prisma
+  version: "7.6.0"
+---
+
+# Prisma CLI Reference
+
+Reference for Prisma ORM CLI commands. This skill provides guidance on command usage, options, and best practices for current Prisma ORM releases.
+
+## Boundary: Compute
+
+Do not use this skill for Prisma Compute app deployment. Use `prisma-compute` for `@prisma/cli app deploy`, `compute:deploy`, `create-prisma --deploy`, Compute apps, deployments, logs, domains, and framework deploy readiness.
+
+## When to Apply
+
+Reference this skill when:
+- Setting up a new Prisma project (`prisma init`)
+- Generating Prisma Client (`prisma generate`)
+- Running database migrations (`prisma migrate`)
+- Managing database state (`prisma db push/pull`)
+- Using local development database (`prisma dev`)
+- Debugging Prisma issues (`prisma debug`)
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Setup | HIGH | `init` |
+| 2 | Generation | HIGH | `generate` |
+| 3 | Development | HIGH | `dev` |
+| 4 | Database | HIGH | `db-` |
+| 5 | Migrations | CRITICAL | `migrate-` |
+| 6 | Utility | MEDIUM | `studio`, `validate`, `format`, `debug`, `mcp` |
+
+## Command Categories
+
+| Category | Commands | Purpose |
+|----------|----------|---------|
+| Setup | `init` | Bootstrap new Prisma project |
+| Generation | `generate` | Generate Prisma Client |
+| Validation | `validate`, `format` | Schema validation and formatting |
+| Development | `dev` | Local Prisma Postgres for development |
+| Database | `db pull`, `db push`, `db seed`, `db execute` | Direct database operations |
+| Migrations | `migrate dev`, `migrate deploy`, `migrate reset`, `migrate status`, `migrate diff`, `migrate resolve` | Schema migrations |
+| Utility | `studio`, `mcp`, `version`, `debug` | Development and AI tooling |
+
+## Quick Reference
+
+### Project Setup
+
+```bash
+# Initialize new project (creates prisma/ folder and prisma.config.ts)
+prisma init
+
+# Initialize with specific database
+prisma init --datasource-provider postgresql
+prisma init --datasource-provider mysql
+prisma init --datasource-provider sqlite
+
+# Initialize with Prisma Postgres (cloud)
+prisma init --db
+
+# Initialize with an example model
+prisma init --with-model
+```
+
+### Client Generation
+
+```bash
+# Generate Prisma Client
+prisma generate
+
+# Watch mode for development
+prisma generate --watch
+
+# Generate specific generator only
+prisma generate --generator client
+```
+
+### Bun Runtime
+
+When using Bun, always add the `--bun` flag so Prisma runs with the Bun runtime (otherwise it falls back to Node.js because of the CLI shebang):
+
+```bash
+bunx --bun prisma init
+bunx --bun prisma generate
+```
+
+### Local Development Database
+
+```bash
+# Start local Prisma Postgres
+prisma dev
+
+# Start with specific name
+prisma dev --name myproject
+
+# Start in background (detached)
+prisma dev --detach
+
+# List all local instances
+prisma dev ls
+
+# Stop instance
+prisma dev stop myproject
+
+# Remove instance data
+prisma dev rm myproject
+```
+
+### Database Operations
+
+```bash
+# Pull schema from existing database
+prisma db pull
+
+# Push schema to database (no migrations)
+prisma db push
+
+# Seed database
+prisma db seed
+
+# Execute raw SQL
+prisma db execute --file ./script.sql
+```
+
+### Migrations (Development)
+
+```bash
+# Create and apply migration
+prisma migrate dev
+
+# Create migration with name
+prisma migrate dev --name add_users_table
+
+# Create migration without applying
+prisma migrate dev --create-only
+
+# Reset database and apply all migrations
+prisma migrate reset
+```
+
+### Migrations (Production)
+
+```bash
+# Apply pending migrations (CI/CD)
+prisma migrate deploy
+
+# Check migration status
+prisma migrate status
+
+# Compare schemas and generate diff
+prisma migrate diff --from-config-datasource --to-schema schema.prisma --script
+```
+
+### Utility Commands
+
+```bash
+# Open Prisma Studio (database GUI)
+prisma studio
+
+# Start Prisma's MCP server for AI tools
+prisma mcp
+
+# Show version info
+prisma version
+prisma -v
+
+# Debug information
+prisma debug
+
+# Validate schema
+prisma validate
+
+# Format schema
+prisma format
+```
+
+## Current Prisma CLI Setup
+
+### New Configuration File
+
+Use `prisma.config.ts` for CLI configuration:
+
+```typescript
+import 'dotenv/config'
+import { defineConfig, env } from 'prisma/config'
+
+export default defineConfig({
+  schema: 'prisma/schema.prisma',
+  migrations: {
+    path: 'prisma/migrations',
+    seed: 'tsx prisma/seed.ts',
+  },
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+### Current Command Behavior
+
+- Run `prisma generate` explicitly after `migrate dev`, `db push`, or other schema syncs when you need fresh client output
+- Run `prisma db seed` explicitly after `migrate dev` or `migrate reset` when you need seed data
+- Use `prisma db execute --file ...` for raw SQL scripts
+
+### Environment Variables
+
+Load environment variables explicitly in `prisma.config.ts`, commonly with `dotenv`:
+
+```typescript
+// prisma.config.ts
+import 'dotenv/config'
+```
+
+## Rule Files
+
+See individual rule files for detailed command documentation:
+
+```
+references/init.md           - Project initialization
+references/generate.md       - Client generation
+references/dev.md            - Local development database
+references/db-pull.md        - Database introspection
+references/db-push.md        - Schema push
+references/db-seed.md        - Database seeding
+references/db-execute.md     - Raw SQL execution
+references/migrate-dev.md    - Development migrations
+references/migrate-deploy.md - Production migrations
+references/migrate-reset.md  - Database reset
+references/migrate-status.md - Migration status
+references/migrate-resolve.md - Migration resolution
+references/migrate-diff.md   - Schema diffing
+references/studio.md         - Database GUI
+references/mcp.md            - Prisma MCP server
+references/validate.md       - Schema validation
+references/format.md         - Schema formatting
+references/debug.md          - Debug info
+```
+
+## How to Use
+
+Use the command categories above for navigation, then open the specific command reference file you need.

packages/database/.agents/skills/prisma-cli/references/db-execute.md

@@ -0,0 +1,78 @@
+# prisma db execute
+
+Execute native commands (SQL) to your database.
+
+## Command
+
+```bash
+prisma db execute [options]
+```
+
+## What It Does
+
+- Connects to your database using the configured datasource
+- Executes a script provided via file (`--file`) or stdin (`--stdin`)
+- Useful for running raw SQL, maintenance tasks, or applying diffs from `migrate diff`
+- Not supported on MongoDB
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--file` | Path to a file containing the script to execute |
+| `--stdin` | Use terminal standard input as the script |
+| `--config` | Custom path to your Prisma config file |
+
+## Current Option Surface
+
+`prisma db execute` uses the datasource configured in `prisma.config.ts`. Use `--config` if you need a separate config file for another environment.
+
+## Examples
+
+### Execute from file
+
+```bash
+prisma db execute --file ./script.sql
+```
+
+### Execute from stdin
+
+```bash
+echo "TRUNCATE TABLE User;" | prisma db execute --stdin
+```
+
+### Execute `migrate diff` output
+
+Pipe the output of `migrate diff` directly to the database:
+
+```bash
+prisma migrate diff \
+  --from-empty \
+  --to-schema prisma/schema.prisma \
+  --script \
+| prisma db execute --stdin
+```
+
+## Configuration
+
+Uses `datasource` from `prisma.config.ts`:
+
+```typescript
+export default defineConfig({
+  datasource: {
+    url: env('DATABASE_URL'),
+  },
+})
+```
+
+## Use Cases
+
+- **Manual Migrations**: Applying raw SQL changes
+- **Data Maintenance**: Truncating tables, cleaning up data
+- **Schema Synchronization**: Applying `migrate diff` scripts
+- **Debugging**: Running test queries (though typically not for fetching data)
+
+## Limitations
+
+- **No Data Return**: The command reports success/failure, not query results (rows). Use Prisma Client or `prisma studio` to view data.
+- **SQL Only**: Primarily for SQL databases.