diff --git a/.agents/skills/neon-postgres/SKILL.md b/.agents/skills/neon-postgres/SKILL.md
new file mode 100644
index 00000000..f376db53
--- /dev/null
+++ b/.agents/skills/neon-postgres/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: neon-postgres
+description: Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/auth), PostgREST-style data API (@neondatabase/neon-js), Neon CLI, and Neon's Platform API/SDKs. Use for any Neon-related questions.
+---
+
+# Neon Serverless Postgres
+
+Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres.
+
+## Neon Documentation
+
+The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data.
+
+### Fetching docs as markdown
+
+Any Neon doc page can be fetched as markdown in two ways:
+
+1. **Append `.md` to the URL** (simplest): `https://neon.com/docs/introduction/branching.md`
+2. **Request `text/markdown`** on the standard URL: `curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching`
+
+Both return the same markdown content. Use whichever method your tools support.
+
+### Finding the right page
+
+The docs index lists every available page with its URL and a short description:
+
+```
+https://neon.com/docs/llms.txt
+```
+
+Common doc URLs are listed in the tables below. If you need a page not listed here, search the [docs index](https://neon.com/docs/llms.txt) — don't guess URLs.
+
+### Common Documentation Paths
+
+| Topic | URL |
+| ------------------- | --------------------------------------------------------- |
+| Introduction | https://neon.com/docs/introduction.md |
+| Branching | https://neon.com/docs/introduction/branching.md |
+| Autoscaling | https://neon.com/docs/introduction/autoscaling.md |
+| Scale to Zero | https://neon.com/docs/introduction/scale-to-zero.md |
+| Instant Restore | https://neon.com/docs/introduction/branch-restore.md |
+| Read Replicas | https://neon.com/docs/introduction/read-replicas.md |
+| Connection Pooling | https://neon.com/docs/connect/connection-pooling.md |
+| IP Allow Lists | https://neon.com/docs/introduction/ip-allow.md |
+| Neon Auth | https://neon.com/docs/auth/overview.md |
+| Data API | https://neon.com/docs/data-api/overview.md |
+| Serverless Driver | https://neon.com/docs/serverless/serverless-driver.md |
+| JavaScript SDK | https://neon.com/docs/reference/javascript-sdk.md |
+| API Reference | https://neon.com/docs/reference/api-reference.md |
+| TypeScript SDK | https://neon.com/docs/reference/typescript-sdk.md |
+| Python SDK | https://neon.com/docs/reference/python-sdk.md |
+| Neon CLI | https://neon.com/docs/reference/neon-cli.md |
+| Logical Replication | https://neon.com/docs/guides/logical-replication-guide.md |
+
+### Framework & Language Guides
+
+| Framework/Language | URL |
+| ------------------ | ----------------------------------------- |
+| Next.js | https://neon.com/docs/guides/nextjs.md |
+| Django | https://neon.com/docs/guides/django.md |
+| Drizzle ORM | https://neon.com/docs/guides/drizzle.md |
+| Prisma | https://neon.com/docs/guides/prisma.md |
+| ORMs Guide | https://neon.com/docs/get-started/orms.md |
+
+### Platform API
+
+For managing Neon resources programmatically (projects, branches, endpoints, databases, roles):
+
+| Method | Documentation |
+| --------------- | ------------------------------------------------------------------ |
+| REST API | https://neon.com/docs/reference/api-reference.md |
+| Interactive API | https://api-docs.neon.tech/reference/getting-started-with-neon-api |
+| OpenAPI Spec | https://neon.com/api_spec/release/v2.json |
+| TypeScript SDK | https://neon.com/docs/reference/typescript-sdk.md |
+| Python SDK | https://neon.com/docs/reference/python-sdk.md |
+| CLI | https://neon.com/docs/reference/neon-cli.md |
+
+**Quick cross-reference** (common operations across interfaces):
+
+| Operation | REST API | TypeScript SDK | Python SDK |
+| ------------------ | ------------------------------ | --------------------------- | ---------------------- |
+| List projects | `GET /projects?org_id=...` | `listProjects({ org_id })` | `projects(org_id=...)` |
+| Create project | `POST /projects` | `createProject({...})` | `project_create(...)` |
+| Get connection URI | `GET .../connection_uri` | `getConnectionUri({...})` | `connection_uri(...)` |
+| Create branch | `POST .../branches` | `createProjectBranch(...)` | `branch_create(...)` |
+| Start endpoint | `POST .../endpoints/.../start` | `startProjectEndpoint(...)` | `endpoint_start(...)` |
+
+## Overview of Resources
+
+Reference the appropriate resource file based on the user's needs:
+
+### Core Guides
+
+| Area | Resource | When to Use |
+| ------------------ | ---------------------------------- | -------------------------------------------------------------- |
+| What is Neon | `references/what-is-neon.md` | Understanding Neon concepts, architecture, core resources |
+| Features | `references/features.md` | Branching, autoscaling, scale-to-zero, connection pooling |
+| Getting Started | `references/getting-started.md` | Setting up a project, connection strings, dependencies, schema |
+| Connection Methods | `references/connection-methods.md` | Choosing drivers based on platform and runtime |
+| Developer Tools | `references/devtools.md` | VSCode extension, MCP server, Neon CLI (`neon init`) |
+
+### Database Drivers & ORMs
+
+HTTP/WebSocket queries for serverless/edge functions.
+
+| Area | Resource | When to Use |
+| ----------------- | ------------------------------- | --------------------------------------------------- |
+| Serverless Driver | `references/neon-serverless.md` | `@neondatabase/serverless` - HTTP/WebSocket queries |
+| Drizzle ORM | `references/neon-drizzle.md` | Drizzle ORM integration with Neon |
+
+### Auth & Data API SDKs
+
+Authentication and PostgREST-style data API for Neon.
+
+| Area | Resource | When to Use |
+| ----------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Neon Auth | `references/neon-auth.md` | `@neondatabase/auth` or `@neondatabase/neon-js` - Setup, UI components, auth methods, common mistakes |
+| Neon JS SDK | `references/neon-js.md` | `@neondatabase/neon-js` - Auth + Data API (PostgREST-style queries) |
+
+### Neon Platform API & CLI
+
+Managing Neon resources programmatically via REST API, SDKs, or CLI.
+
+| Area | Resource | When to Use |
+| -------------- | ----------------------------------- | ------------------------------------------------ |
+| REST API | `references/neon-rest-api.md` | Direct HTTP calls - auth, endpoints, rate limits |
+| Neon CLI | `references/neon-cli.md` | Terminal workflows, scripts, CI/CD pipelines |
+| TypeScript SDK | `references/neon-typescript-sdk.md` | `@neondatabase/api-client` |
+| Python SDK | `references/neon-python-sdk.md` | `neon-api` package |
diff --git a/.agents/skills/neon-postgres/references/connection-methods.md b/.agents/skills/neon-postgres/references/connection-methods.md
new file mode 100644
index 00000000..398fa07f
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/connection-methods.md
@@ -0,0 +1,177 @@
+# Connection Methods
+
+Guide to selecting the optimal connection method for your Neon Postgres database based on deployment platform and runtime environment.
+
+See the [official connection guide](https://neon.com/docs/connect/choose-connection.md) for complete details.
+
+## Decision Tree
+
+Follow this flow to determine the right connection approach:
+
+### 1. What Language Are You Using?
+
+**Not TypeScript/JavaScript** → Use **TCP with connection pooling** from a secure server.
+
+For non-TypeScript languages, connect from a secure backend server using your language's native Postgres driver with connection pooling enabled.
+
+| Language/Framework | Documentation |
+| ------------------- | --------------------------------------------- |
+| Django (Python) | https://neon.com/docs/guides/django.md |
+| SQLAlchemy (Python) | https://neon.com/docs/guides/sqlalchemy.md |
+| Elixir Ecto | https://neon.com/docs/guides/elixir-ecto.md |
+| Laravel (PHP) | https://neon.com/docs/guides/laravel.md |
+| Ruby on Rails | https://neon.com/docs/guides/ruby-on-rails.md |
+| Go | https://neon.com/docs/guides/go.md |
+| Rust | https://neon.com/docs/guides/rust.md |
+| Java | https://neon.com/docs/guides/java.md |
+
+**TypeScript/JavaScript** → Continue to step 2.
+
+---
+
+### 2. Client-Side App Without Backend?
+
+**Yes** → Use **Neon Data API** via `@neondatabase/neon-js`
+
+This is the only option for client-side apps since browsers cannot make direct TCP connections to Postgres. See `neon-js.md` for setup and the [JavaScript SDK docs](https://neon.com/docs/reference/javascript-sdk.md) for the full reference.
+
+**No** → Continue to step 3.
+
+---
+
+### 3. Long-Running Server? (Railway, Render, traditional VPS)
+
+**Yes** → Use **TCP with connection pooling** via `node-postgres`, `postgres.js`, or `bun:pg`
+
+Long-running servers maintain persistent connections, so standard TCP drivers with pooling are optimal.
+
+**No** → Continue to step 4.
+
+---
+
+### 4. Edge Environment Without TCP Support?
+
+Some edge runtimes don't support TCP connections. Rarely the case anymore.
+
+**Yes** → Continue to step 5 to check transaction requirements.
+
+**No** → Continue to step 6 to check pooling support.
+
+---
+
+### 5. Does Your App Use SQL Transactions?
+
+**Yes** → Use **WebSocket transport** via `@neondatabase/serverless` with `Pool`
+
+WebSocket maintains connection state needed for transactions. See `neon-serverless.md` for setup.
+
+**No** → Use **HTTP transport** via `@neondatabase/serverless`
+
+HTTP is faster for single queries (~3 roundtrips vs ~8 for TCP). See `neon-serverless.md` for setup and the [serverless driver docs](https://neon.com/docs/serverless/serverless-driver.md) for the full reference.
+
+---
+
+### 6. Serverless Environment With Connection Pooling Support?
+
+**Vercel (Fluid Compute)** → Use **TCP with `@vercel/functions`**
+
+Vercel's Fluid compute supports connection pooling. Use `attachDatabasePool` for optimal connection management. See the [Vercel connection methods guide](https://neon.com/docs/guides/vercel-connection-methods.md) for details.
+
+**Cloudflare (with Hyperdrive)** → Use **TCP via Hyperdrive**
+
+Cloudflare Hyperdrive provides connection pooling for Workers. Use `node-postgres` or any native TCP driver.
+
+See the [Cloudflare Hyperdrive guide](https://neon.com/docs/guides/cloudflare-hyperdrive.md) for connecting with Cloudflare Workers and Hyperdrive.
+
+**No pooling support (Netlify, Deno Deploy)** → Use `@neondatabase/serverless`
+
+Fall back to the decision in step 5 based on transaction requirements.
+
+---
+
+## Quick Reference Table
+
+| Platform | TCP Support | Pooling | Recommended Driver |
+| ----------------------- | ----------- | ------------------- | -------------------------- |
+| Vercel (Fluid) | Yes | `@vercel/functions` | `pg` (node-postgres) |
+| Cloudflare (Hyperdrive) | Yes | Hyperdrive | `pg` (node-postgres) |
+| Cloudflare Workers | No | No | `@neondatabase/serverless` |
+| Netlify Functions | No | No | `@neondatabase/serverless` |
+| Deno Deploy | No | No | `@neondatabase/serverless` |
+| Railway / Render | Yes | Built-in | `pg` (node-postgres) |
+| Client-side (browser) | No | N/A | `@neondatabase/neon-js` |
+
+---
+
+## ORM Support
+
+Popular TypeScript/JavaScript ORMs all work with Neon:
+
+| ORM | Drivers Supported | Documentation |
+| ------- | ----------------------------------------------- | --------------------------------------- |
+| Drizzle | `pg`, `postgres.js`, `@neondatabase/serverless` | https://neon.com/docs/guides/drizzle.md |
+| Kysely | `pg`, `postgres.js`, `@neondatabase/serverless` | https://neon.com/docs/guides/kysely.md |
+| Prisma | `pg`, `@neondatabase/serverless` | https://neon.com/docs/guides/prisma.md |
+| TypeORM | `pg` | https://neon.com/docs/guides/typeorm.md |
+
+All ORMs support both TCP drivers and Neon's serverless driver depending on your platform.
+
+For Drizzle ORM integration with Neon, see `neon-drizzle.md`.
+
+---
+
+## Vercel Fluid + Drizzle Example
+
+Complete database client setup for Vercel with Drizzle ORM and connection pooling. See `neon-drizzle.md` for more examples.
+
+```typescript
+// src/lib/db/client.ts
+import { attachDatabasePool } from "@vercel/functions";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+
+import * as schema from "./schema";
+
+const pool = new Pool({
+ connectionString: process.env.DATABASE_URL,
+});
+attachDatabasePool(pool);
+
+export const db = drizzle({ client: pool, schema });
+```
+
+**Why `attachDatabasePool`?**
+
+- First request establishes the TCP connection (~8 roundtrips)
+- Subsequent requests reuse the connection instantly
+- Ensures idle connections close gracefully before function suspension
+- Prevents connection leaks in serverless environments
+
+---
+
+## Gathering Requirements
+
+When helping a user choose their connection method, gather this information:
+
+1. **Deployment platform**: Where will the app run? (Vercel, Cloudflare, Netlify, Railway, browser, etc.)
+2. **Runtime type**: Serverless functions, edge functions, or long-running server?
+3. **Transaction requirements**: Does the app need SQL transactions?
+4. **ORM preference**: Using Drizzle, Kysely, Prisma, or raw SQL?
+
+Then provide:
+
+- The recommended driver/package
+- A working code example for their setup
+- The correct npm install command
+
+---
+
+## Documentation Resources
+
+| Topic | URL |
+| -------------------------- | --------------------------------------------------------- |
+| Choosing Connection Method | https://neon.com/docs/connect/choose-connection.md |
+| Serverless Driver | https://neon.com/docs/serverless/serverless-driver.md |
+| JavaScript SDK | https://neon.com/docs/reference/javascript-sdk.md |
+| Connection Pooling | https://neon.com/docs/connect/connection-pooling.md |
+| Vercel Connection Methods | https://neon.com/docs/guides/vercel-connection-methods.md |
diff --git a/.agents/skills/neon-postgres/references/devtools.md b/.agents/skills/neon-postgres/references/devtools.md
new file mode 100644
index 00000000..5c029c31
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/devtools.md
@@ -0,0 +1,109 @@
+# Neon Developer Tools
+
+Neon provides developer tools to enhance your local development workflow, including a VSCode extension and MCP server for AI-assisted development.
+
+## Quick Setup with neon init
+
+The fastest way to set up all Neon developer tools:
+
+```bash
+npx neon init
+```
+
+This command:
+
+- Installs the Neon VSCode extension
+- Configures the Neon MCP server for AI assistants
+- Sets up your local environment for Neon development
+
+See the [full CLI init reference](https://neon.com/docs/reference/cli-init.md) for all options.
+
+## VSCode Extension
+
+The Neon VSCode extension provides:
+
+- **Database Explorer**: Browse projects, branches, tables, and data
+- **SQL Editor**: Write and execute queries with IntelliSense
+- **Branch Management**: Create, switch, and manage database branches
+- **Connection String Access**: Quick copy of connection strings
+
+**Install from VSCode:**
+
+1. Open Extensions (Cmd/Ctrl+Shift+X)
+2. Search "Neon"
+3. Install "Neon" by Neon
+
+**Or via command line:**
+
+```bash
+code --install-extension neon.neon-vscode
+```
+
+See the [full VSCode extension docs](https://neon.com/docs/local/vscode-extension.md) for all features.
+
+## Neon MCP Server
+
+The Neon MCP (Model Context Protocol) server enables AI assistants like Claude, Cursor, and GitHub Copilot to interact with your Neon databases directly.
+
+### Capabilities
+
+The MCP server provides AI assistants with:
+
+- **Project Management**: List, create, describe, and delete projects
+- **Branch Operations**: Create branches, compare schemas, reset from parent
+- **SQL Execution**: Run queries and transactions
+- **Schema Operations**: Describe tables, get database structure
+- **Migrations**: Prepare and complete database migrations with safety checks
+- **Query Tuning**: Analyze and optimize slow queries
+- **Neon Auth**: Provision authentication for your branches
+
+### Setup
+
+**Option 1: Via neon init (Recommended)**
+
+```bash
+npx neon init
+```
+
+**Option 2: Manual Configuration**
+
+Add to your AI assistant's MCP configuration:
+
+```json
+{
+ "mcpServers": {
+ "neon": {
+ "command": "npx",
+ "args": ["-y", "@neondatabase/mcp-server-neon"],
+ "env": {
+ "NEON_API_KEY": "your-api-key"
+ }
+ }
+ }
+}
+```
+
+Get your API key from: https://console.neon.tech/app/settings/api-keys
+
+### Common MCP Operations
+
+| Operation | What It Does |
+| ---------------------------- | ----------------------------- |
+| `list_projects` | Show all Neon projects |
+| `create_project` | Create a new project |
+| `run_sql` | Execute SQL queries |
+| `get_connection_string` | Get database connection URL |
+| `create_branch` | Create a database branch |
+| `prepare_database_migration` | Safely prepare schema changes |
+| `provision_neon_auth` | Set up Neon Auth |
+
+See the [full MCP server docs](https://neon.com/docs/ai/neon-mcp-server.md) for all available operations.
+
+## Documentation Resources
+
+| Topic | URL |
+| ------------------ | ----------------------------------------------- |
+| CLI Init Command | https://neon.com/docs/reference/cli-init.md |
+| VSCode Extension | https://neon.com/docs/local/vscode-extension.md |
+| MCP Server | https://neon.com/docs/ai/neon-mcp-server.md |
+| Neon CLI Reference | https://neon.com/docs/reference/neon-cli.md |
diff --git a/.agents/skills/neon-postgres/references/features.md b/.agents/skills/neon-postgres/references/features.md
new file mode 100644
index 00000000..a442acdc
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/features.md
@@ -0,0 +1,64 @@
+# Neon Features
+
+Quick-reference summaries of Neon's key platform features. Fetch the linked docs for full details.
+
+## Branching
+
+Instant, copy-on-write database clones at any point in time. Branches only store changes from parent -- no data duplication.
+
+- Branches are instant (no data copying)
+- Use for: dev environments, staging, preview deployments, testing migrations
+- Each branch can have its own compute endpoint
+- If the Neon MCP server is available, use it to list and create branches. Otherwise, use the CLI or Platform API.
+
+[Branching docs](https://neon.com/docs/introduction/branching.md)
+
+## Autoscaling
+
+Compute scales automatically between configured min and max Compute Units (CUs) based on CPU and memory pressure. No manual intervention required.
+
+[Autoscaling docs](https://neon.com/docs/introduction/autoscaling.md)
+
+## Scale to Zero
+
+Computes suspend after inactivity (default: 5 minutes, configurable). First query after suspend has ~500ms cold start. Storage is always maintained.
+
+[Scale to zero docs](https://neon.com/docs/introduction/scale-to-zero.md)
+
+## Instant Restore
+
+Point-in-time recovery without pre-configured backups. Restore window depends on plan (7-30 days). Can also create branches from any historical point, or use Time Travel queries.
+
+[Instant restore docs](https://neon.com/docs/introduction/branch-restore.md)
+
+## Read Replicas
+
+Read-only compute endpoints that share storage with the primary (no data duplication). Instant creation, independent scaling. Use for analytics, reporting, and read-heavy workloads.
+
+[Read replicas docs](https://neon.com/docs/introduction/read-replicas.md)
+
+## Connection Pooling
+
+Built-in PgBouncer. Enable by adding `-pooler` to the endpoint hostname. Transaction mode by default. Supports up to 10,000 concurrent connections. Essential for serverless environments.
+
+[Connection pooling docs](https://neon.com/docs/connect/connection-pooling.md)
+
+## Neon Auth
+
+Managed authentication that branches with your database. Supports email, social providers (Google, GitHub), session management, and UI components.
+
+For setup, see `neon-auth.md`. For auth + Data API, see `neon-js.md`.
+
+[Neon Auth docs](https://neon.com/docs/auth/overview.md)
+
+## IP Allow Lists
+
+Restrict database access to specific IP addresses or CIDR ranges. Can be scoped to protected branches only.
+
+[IP Allow docs](https://neon.com/docs/introduction/ip-allow.md)
+
+## Logical Replication
+
+Replicate data to/from external Postgres databases using native logical replication.
+
+[Logical replication docs](https://neon.com/docs/guides/logical-replication-guide.md)
diff --git a/.agents/skills/neon-postgres/references/getting-started.md b/.agents/skills/neon-postgres/references/getting-started.md
new file mode 100644
index 00000000..8bf26004
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/getting-started.md
@@ -0,0 +1,111 @@
+# Getting Started with Neon
+
+Interactive guide for setting up a Neon project and connecting it to code.
+
+See the [official getting started guide](https://neon.com/docs/get-started/signing-up.md) for complete details.
+
+## Setup Flow
+
+### 1. Select Organization and Project
+
+- Check existing organizations and projects (via MCP server or CLI)
+- **1 organization**: default to it
+- **Multiple organizations**: list all and ask which to use
+- **No projects**: ask if they want to create a new project
+- **1 project**: ask "Would you like to use '{project_name}' or create a new one?"
+- **Multiple projects (<6)**: list all and let them choose
+- **Many projects (6+)**: list recent projects, offer to create new or specify by name/ID
+
+### 2. Get Connection String
+
+- Use MCP server or CLI to get the connection string
+- Store it in `.env` as `DATABASE_URL`:
+
+```
+DATABASE_URL=postgresql://user:password@host/database
+```
+
+**Before modifying `.env`:**
+
+1. Try to read the `.env` file first
+2. If readable: use search/replace to update or append `DATABASE_URL`
+3. If unreadable (permissions): use append command or show the line to add manually
+4. Never overwrite an existing `.env` — always append or update in place
+
+### 3. Install Driver
+
+Choose based on deployment platform. For detailed guidance, see `connection-methods.md`.
+
+| Environment | Driver | Install |
+| ------------------------ | -------------------------- | -------------------------------------- |
+| Vercel (Edge/Serverless) | `@neondatabase/serverless` | `npm install @neondatabase/serverless` |
+| Cloudflare Workers | `@neondatabase/serverless` | `npm install @neondatabase/serverless` |
+| AWS Lambda | `@neondatabase/serverless` | `npm install @neondatabase/serverless` |
+| Traditional Node.js | `pg` | `npm install pg` |
+| Long-running servers | `pg` with pooling | `npm install pg` |
+
+For serverless driver patterns, see `neon-serverless.md`. For complex scenarios (multiple runtimes, hybrid architectures), see `connection-methods.md`.
+
+### 4. Authentication (if needed)
+
+Skip for CLI tools, scripts, or apps without user accounts.
+
+If the app needs auth: use MCP server `provision_neon_auth` tool, then see `neon-auth.md` for setup. For auth + database queries, see `neon-js.md`.
+
+### 5. ORM Setup (optional)
+
+Check for existing ORM (Prisma, Drizzle, TypeORM). If none, ask if they want one. For Drizzle integration, see `neon-drizzle.md`.
+
+### 6. Schema Setup
+
+- Check for existing migration files or ORM schemas
+- If none: offer to create an example schema or design one together
+
+### 7. Developer Tools
+
+```bash
+npx neon init
+```
+
+Installs the VSCode extension and configures the MCP server. See `devtools.md` for details.
+
+## What's Next
+
+After setup is complete, offer to help with:
+
+- Neon-specific features (branching, autoscaling, scale-to-zero) — see `features.md`
+- Connection pooling for production
+- Writing queries or building API endpoints
+- Database migrations and schema changes
+- Performance optimization
+
+## Resume Support
+
+If the user says "Continue with Neon setup", check what's already configured:
+
+- MCP server connection
+- `.env` file with `DATABASE_URL`
+- Dependencies installed
+- Schema created
+
+Then resume from where they left off.
+
+## Security Reminders
+
+- Never commit connection strings to version control
+- Use environment variables for all credentials
+- Prefer SSL connections (default in Neon)
+- Use least-privilege database roles
+- Rotate API keys and passwords regularly
+
+## Documentation
+
+| Topic | URL |
+| ------------------ | ----------------------------------------------------- |
+| Getting Started | https://neon.com/docs/get-started/signing-up.md |
+| Connecting to Neon | https://neon.com/docs/connect/connect-intro.md |
+| Connection String | https://neon.com/docs/connect/connect-from-any-app.md |
+| Frameworks Guide | https://neon.com/docs/get-started/frameworks.md |
+| ORMs Guide | https://neon.com/docs/get-started/orms.md |
+| VSCode Extension | https://neon.com/docs/local/vscode-extension.md |
+| MCP Server | https://neon.com/docs/ai/neon-mcp-server.md |
diff --git a/.agents/skills/neon-postgres/references/neon-auth.md b/.agents/skills/neon-postgres/references/neon-auth.md
new file mode 100644
index 00000000..579d0b27
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/neon-auth.md
@@ -0,0 +1,413 @@
+# Neon Auth
+
+Neon Auth provides managed authentication that stores users, sessions, and auth configuration directly in your Neon database. When you branch your database, your entire auth state branches with it.
+
+See the [official Neon Auth docs](https://neon.com/docs/auth/overview.md) for complete details.
+
+## Package Selection
+
+| Framework / Use Case | Package | Notes |
+| ----------------------- | ----------------------- | ------------------------------ |
+| Next.js | `@neondatabase/auth` | Server + client SDK |
+| React SPA (Vite, etc) | `@neondatabase/neon-js` | Client SDK + optional Data API |
+| Auth + Database queries | `@neondatabase/neon-js` | Full SDK |
+
+Both packages share auth exports (`@neondatabase/neon-js/auth/*` re-exports `@neondatabase/auth/*`).
+
+```bash
+# Next.js
+npm install @neondatabase/auth@latest
+
+# React SPA / Full SDK
+npm install @neondatabase/neon-js@latest
+```
+
+> **Note:** While these packages are in pre-release (beta), you must use `@latest` with npm. Without it, npm may install an older version. This is not needed with pnpm or yarn.
+
+## Next.js Setup
+
+**1. Server auth instance** (`lib/auth/server.ts`):
+
+```typescript
+import { createNeonAuth } from "@neondatabase/auth/next/server";
+
+export const auth = createNeonAuth({
+ baseUrl: process.env.NEON_AUTH_BASE_URL!,
+ cookies: {
+ secret: process.env.NEON_AUTH_COOKIE_SECRET!,
+ },
+});
+```
+
+**2. API route handler** (`app/api/auth/[...path]/route.ts`):
+
+```typescript
+import { auth } from "@/lib/auth/server";
+export const { GET, POST } = auth.handler();
+```
+
+**3. Middleware** (`middleware.ts`):
+
+```typescript
+import { auth } from "@/lib/auth/server";
+
+export default auth.middleware({
+ loginUrl: "/auth/sign-in",
+});
+
+export const config = {
+ matcher: ["/account/:path*"],
+};
+```
+
+**4. Client** (`lib/auth/client.ts`):
+
+```typescript
+"use client";
+import { createAuthClient } from "@neondatabase/auth/next";
+export const authClient = createAuthClient();
+```
+
+**5. Server component access** (must set `force-dynamic`):
+
+```typescript
+import { auth } from "@/lib/auth/server";
+
+export const dynamic = "force-dynamic";
+
+export default async function DashboardPage() {
+ const { data: session } = await auth.getSession();
+ if (!session?.user) return
Not logged in
;
+ return
Hello {session.user.name}
;
+}
+```
+
+**6. UI setup** — Add the provider, CSS, and page components. See [UI Components](#ui-components) below for `NeonAuthUIProvider`, CSS imports, `AuthView`, and `AccountView` setup.
+
+See the [Next.js quickstart](https://neon.com/docs/auth/quick-start/nextjs.md) and [server SDK reference](https://neon.com/docs/auth/reference/nextjs-server.md) for the full setup.
+
+### Environment Variables (Next.js)
+
+```bash
+NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
+NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
+```
+
+Get your Auth URL from the Neon Console: Project -> Branch -> Auth -> Configuration.
+
+Generate a cookie secret: `openssl rand -base64 32`
+
+## React SPA Setup
+
+**1. Auth client** (`lib/auth.ts`):
+
+```typescript
+import { createAuthClient } from "@neondatabase/neon-js/auth";
+
+export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL);
+```
+
+If you need `useSession()` in custom components, pass an adapter:
+
+```typescript
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+
+const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL, {
+ adapter: BetterAuthReactAdapter(),
+});
+```
+
+UI components (`AuthView`, `SignedIn`, etc.) work without an adapter.
+
+**2. UI setup** — Wrap your app with `NeonAuthUIProvider` and import CSS. See [UI Components](#ui-components) below. In a SPA, the provider and CSS go in your root component (e.g., `App.tsx` or your router layout).
+
+**3. Routing** — Map `AuthView` and `AccountView` to routes in your router (React Router, TanStack Router, etc.). For example, with React Router:
+
+```tsx
+} />
+} />
+```
+
+### Environment Variables (React SPA)
+
+```bash
+VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
+```
+
+See the [React quickstart with UI components](https://neon.com/docs/auth/quick-start/react-router-components.md) and [React API-only quickstart](https://neon.com/docs/auth/quick-start/react.md) for the full setup.
+
+## UI Components
+
+Use pre-built components instead of building custom auth forms.
+
+| Component | Purpose |
+| ------------------------ | ----------------------------------------- |
+| `AuthView` | Sign-in, sign-up, forgot-password pages |
+| `AccountView` | Account settings, security pages |
+| `UserButton` | User avatar with dropdown menu |
+| `SignedIn` / `SignedOut` | Conditional rendering based on auth state |
+| `RedirectToSignIn` | Redirect unauthenticated users |
+| `RedirectToSignUp` | Redirect to sign-up page |
+
+See the [UI components reference](https://neon.com/docs/auth/reference/ui-components.md) for full props and customization.
+
+### CSS (choose one, never both)
+
+The CSS import path depends on which package you installed:
+
+```typescript
+// Next.js (@neondatabase/auth)
+import "@neondatabase/auth/ui/css";
+
+// React SPA (@neondatabase/neon-js)
+import "@neondatabase/neon-js/ui/css";
+```
+
+```css
+/* With Tailwind v4 — Next.js */
+@import "tailwindcss";
+@import "@neondatabase/auth/ui/tailwind";
+
+/* With Tailwind v4 — React SPA */
+@import "tailwindcss";
+@import "@neondatabase/neon-js/ui/tailwind";
+```
+
+### Provider Setup
+
+Wrap your app with `NeonAuthUIProvider`. Only `authClient` is required.
+
+In Next.js, add `suppressHydrationWarning` to the `` tag in your root layout — the provider injects theme attributes (`className="light"`, `color-scheme`) client-side that don't exist in the server render:
+
+```tsx
+// app/layout.tsx
+import { NeonAuthUIProvider, UserButton } from "@neondatabase/auth/react";
+import { authClient } from "@/lib/auth/client";
+
+export default function RootLayout({ children }) {
+ return (
+
+
+
+ {children}
+
+
+
+ );
+}
+```
+
+**Social login** requires TWO configurations: enable in Neon Console AND add `social` prop to provider.
+
+### AuthView (Next.js)
+
+Create `app/auth/[path]/page.tsx`:
+
+```tsx
+import { AuthView } from "@neondatabase/auth/react";
+
+export const dynamicParams = false;
+
+export default async function AuthPage({
+ params,
+}: {
+ params: Promise<{ path: string }>;
+}) {
+ const { path } = await params;
+ return ;
+}
+```
+
+Auth paths: `sign-in`, `sign-up`, `forgot-password`, `reset-password`, `magic-link`, `two-factor`, `callback`, `sign-out`
+
+### AccountView (Next.js)
+
+Create `app/account/[path]/page.tsx`:
+
+```tsx
+import { AccountView } from "@neondatabase/auth/react";
+import { accountViewPaths } from "@neondatabase/auth/react/ui/server";
+
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+ return Object.values(accountViewPaths).map((path) => ({ path }));
+}
+
+export default async function AccountPage({
+ params,
+}: {
+ params: Promise<{ path: string }>;
+}) {
+ const { path } = await params;
+ return ;
+}
+```
+
+Account paths: `settings`, `security`
+
+### Conditional Rendering
+
+```tsx
+import { SignedIn, SignedOut, UserButton } from "@neondatabase/auth/react";
+
+
+ Sign In
+
+
+
+
+```
+
+## Auth Methods Quick Reference
+
+| Method | Usage |
+| ----------------------------------------------- | ---------------------------------------------- |
+| `auth.signUp.email({ email, password, name })` | Create account (server) |
+| `auth.signIn.email({ email, password })` | Sign in (server) |
+| `auth.signIn.social({ provider, callbackURL })` | OAuth sign-in (server) |
+| `auth.signOut()` | Sign out (server) |
+| `auth.getSession()` | Get session (server, requires `force-dynamic`) |
+| `authClient.useSession()` | Session hook (client, needs React adapter) |
+| `authClient.getSession()` | Get session (client, no adapter needed) |
+| `authClient.signIn.email(...)` | Sign in (client) |
+| `authClient.signUp.email(...)` | Create account (client) |
+
+### Session Data
+
+```typescript
+const { data: session } = await auth.getSession();
+// session.user: { id, name, email, image, emailVerified, createdAt, updatedAt }
+// session.session: { id, expiresAt, token, createdAt, updatedAt, userId }
+```
+
+### Error Handling
+
+```typescript
+const { error } = await auth.signIn.email({ email, password });
+if (error) {
+ // error.code: "INVALID_EMAIL_OR_PASSWORD", "EMAIL_NOT_VERIFIED",
+ // "USER_NOT_FOUND", "TOO_MANY_REQUESTS"
+ console.error(error.message);
+}
+```
+
+## Key Imports
+
+```typescript
+// Server (Next.js)
+import { createNeonAuth } from "@neondatabase/auth/next/server";
+
+// Client (Next.js) -- includes React adapter automatically
+import { createAuthClient } from "@neondatabase/auth/next";
+
+// Client (React SPA)
+import { createAuthClient } from "@neondatabase/neon-js/auth";
+
+// React adapter (only needed for useSession() in React SPA)
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+
+// UI components
+import {
+ NeonAuthUIProvider,
+ AuthView,
+ AccountView,
+ SignedIn,
+ SignedOut,
+ UserButton,
+} from "@neondatabase/auth/react";
+import { accountViewPaths } from "@neondatabase/auth/react/ui/server";
+
+// CSS (choose one, never both; path matches your package)
+import "@neondatabase/auth/ui/css"; // Next.js
+import "@neondatabase/neon-js/ui/css"; // React SPA
+// or in CSS: @import "@neondatabase/auth/ui/tailwind"; (Next.js)
+// or in CSS: @import "@neondatabase/neon-js/ui/tailwind"; (React SPA)
+```
+
+## Common Mistakes
+
+### Missing NEON_AUTH_COOKIE_SECRET
+
+Required for Next.js, must be 32+ characters for HMAC-SHA256. Generate with `openssl rand -base64 32`.
+
+### Missing force-dynamic on server components
+
+```typescript
+// WRONG -- will error
+export default async function Page() {
+ const { data: session } = await auth.getSession();
+}
+
+// CORRECT
+export const dynamic = "force-dynamic";
+export default async function Page() {
+ const { data: session } = await auth.getSession();
+}
+```
+
+### Using v0.1 API patterns
+
+Use `createNeonAuth()` + `auth.handler()`, not the old standalone `authApiHandler()`. See the [migration guide](https://neon.com/docs/auth/migrate/from-auth-v0.1.md).
+
+### Using useSession() without adapter in React SPA
+
+`createAuthClient(url)` without an adapter returns a vanilla client with no React hooks. Either pass `BetterAuthReactAdapter()` or use UI components (`SignedIn`, etc.) which don't require an adapter.
+
+### Wrong BetterAuthReactAdapter import
+
+Must use subpath import and call as function:
+
+```typescript
+// WRONG
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js";
+
+// CORRECT
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+const client = createAuthClient(url, { adapter: BetterAuthReactAdapter() });
+```
+
+### CSS import conflicts
+
+Choose ONE: `ui/css` (without Tailwind) or `ui/tailwind` (with Tailwind v4). Never import both -- causes ~94KB of duplicate styles.
+
+### Missing "use client" directive
+
+Required for any component using `useSession()` or other React hooks.
+
+### Wrong createAuthClient signature
+
+URL is the first argument, not a property in an options object:
+
+```typescript
+// WRONG
+createAuthClient({ url: myUrl });
+
+// CORRECT (React SPA)
+createAuthClient(url);
+createAuthClient(url, { adapter: BetterAuthReactAdapter() });
+
+// CORRECT (Next.js) -- no arguments, uses proxy
+createAuthClient();
+```
+
+## Documentation
+
+| Topic | URL |
+| -------------------- | ----------------------------------------------------------------- |
+| Auth Overview | https://neon.com/docs/auth/overview.md |
+| Next.js Quickstart | https://neon.com/docs/auth/quick-start/nextjs.md |
+| Next.js API-only | https://neon.com/docs/auth/quick-start/nextjs-api-only.md |
+| React with UI | https://neon.com/docs/auth/quick-start/react-router-components.md |
+| React API Methods | https://neon.com/docs/auth/quick-start/react.md |
+| TanStack Router | https://neon.com/docs/auth/quick-start/tanstack-router.md |
+| Server SDK Reference | https://neon.com/docs/auth/reference/nextjs-server.md |
+| UI Components Ref | https://neon.com/docs/auth/reference/ui-components.md |
+| Client SDK Reference | https://neon.com/docs/reference/javascript-sdk.md |
+| v0.1 Migration Guide | https://neon.com/docs/auth/migrate/from-auth-v0.1.md |
+| OAuth Setup | https://neon.com/docs/auth/guides/setup-oauth.md |
+| Email Verification | https://neon.com/docs/auth/guides/email-verification.md |
+| Branching Auth | https://neon.com/docs/auth/branching-authentication.md |
diff --git a/.agents/skills/neon-postgres/references/neon-cli.md b/.agents/skills/neon-postgres/references/neon-cli.md
new file mode 100644
index 00000000..6ff7d462
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/neon-cli.md
@@ -0,0 +1,154 @@
+# Neon CLI
+
+The Neon CLI is a command-line interface for managing Neon Serverless Postgres directly from your terminal. It provides the same capabilities as the Neon Platform API and is ideal for scripting, CI/CD pipelines, and developers who prefer terminal workflows.
+
+## Installation
+
+**macOS (Homebrew):**
+
+```bash
+brew install neonctl
+```
+
+**npm (cross-platform):**
+
+```bash
+npm install -g neonctl
+```
+
+## Authentication
+
+Authenticate with your Neon account:
+
+```bash
+neonctl auth
+```
+
+This opens a browser for OAuth authentication and stores credentials locally.
+
+For CI/CD or non-interactive environments, use an API key:
+
+```bash
+export NEON_API_KEY=your-api-key
+```
+
+Get your API key from: https://console.neon.tech/app/settings/api-keys
+
+## Common Commands
+
+### Project Management
+
+```bash
+# List all projects (org-scoped)
+neonctl projects list --org-id
+
+# Create a new project
+neonctl projects create --name my-project --org-id
+
+# Get project details
+neonctl projects get
+
+# Delete a project
+neonctl projects delete
+```
+
+### Branch Operations
+
+```bash
+# List branches
+neonctl branches list --project-id
+
+# Create a branch
+neonctl branches create --project-id --name dev
+
+# Delete a branch
+neonctl branches delete --project-id
+```
+
+### Connection Strings
+
+```bash
+# Get connection string
+neonctl connection-string --project-id
+
+# Get connection string for specific branch
+neonctl connection-string --project-id --branch-id
+
+# Get pooled connection string
+neonctl connection-string --project-id --pooled
+```
+
+### SQL Execution
+
+```bash
+# Run SQL query
+neonctl sql "SELECT * FROM users LIMIT 10" --project-id
+
+# Run SQL from file
+neonctl sql --file schema.sql --project-id
+```
+
+### Database Management
+
+```bash
+# List databases
+neonctl databases list --project-id --branch-id
+
+# Create database
+neonctl databases create --project-id --name mydb
+
+# List roles
+neonctl roles list --project-id --branch-id
+```
+
+## Output Formats
+
+The CLI supports multiple output formats:
+
+```bash
+# JSON output (default for scripting)
+neonctl projects list --output json
+
+# Table output (human-readable)
+neonctl projects list --output table
+
+# YAML output
+neonctl projects list --output yaml
+```
+
+## CI/CD Integration
+
+Example GitHub Actions workflow:
+
+```yaml
+- name: Create preview branch
+ env:
+ NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
+ run: |
+ neonctl branches create \
+ --project-id ${{ vars.NEON_PROJECT_ID }} \
+ --name preview-${{ github.event.pull_request.number }}
+```
+
+## CLI vs MCP Server vs SDKs
+
+| Tool | Best For |
+| -------------- | ------------------------------------------------- |
+| Neon CLI | Terminal workflows, scripts, CI/CD pipelines |
+| MCP Server | AI-assisted development with Claude, Cursor, etc. |
+| TypeScript SDK | Programmatic access in Node.js/TypeScript apps |
+| Python SDK | Programmatic access in Python applications |
+| REST API | Direct HTTP integration in any language |
+
+## Documentation Resources
+
+| Topic | URL |
+| -------------- | -------------------------------------------------------- |
+| CLI Reference | https://neon.com/docs/reference/neon-cli.md |
+| CLI Install | https://neon.com/docs/reference/cli-install.md |
+| CLI Auth | https://neon.com/docs/reference/cli-auth.md |
+| CLI Projects | https://neon.com/docs/reference/cli-projects.md |
+| CLI Branches | https://neon.com/docs/reference/cli-branches.md |
+| CLI Connection | https://neon.com/docs/reference/cli-connection-string.md |
+
+See the [full CLI docs](https://neon.com/docs/reference/neon-cli.md) for the complete command reference.
diff --git a/.agents/skills/neon-postgres/references/neon-drizzle.md b/.agents/skills/neon-postgres/references/neon-drizzle.md
new file mode 100644
index 00000000..c5f3ff25
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/neon-drizzle.md
@@ -0,0 +1,241 @@
+# Neon and Drizzle Integration
+
+Integration patterns, configurations, and optimizations for using **Drizzle ORM** with **Neon** Postgres.
+
+See the [official Drizzle guide](https://neon.com/docs/guides/drizzle.md) for complete details.
+
+## Choosing the Right Driver
+
+Drizzle ORM works with multiple Postgres drivers. See `connection-methods.md` for the full decision tree.
+
+| Platform | TCP Support | Pooling | Recommended Driver |
+| ----------------------- | ----------- | ------------------- | -------------------------- |
+| Vercel (Fluid) | Yes | `@vercel/functions` | `pg` (node-postgres) |
+| Cloudflare (Hyperdrive) | Yes | Hyperdrive | `pg` (node-postgres) |
+| Cloudflare Workers | No | No | `@neondatabase/serverless` |
+| Netlify Functions | No | No | `@neondatabase/serverless` |
+| Deno Deploy | No | No | `@neondatabase/serverless` |
+| Railway / Render | Yes | Built-in | `pg` (node-postgres) |
+
+## Connection Setup
+
+### 1. TCP with node-postgres (Long-Running Servers)
+
+Best for Railway, Render, traditional VPS.
+
+```bash
+npm install drizzle-orm pg
+npm install -D drizzle-kit @types/pg dotenv
+```
+
+```typescript
+// src/db.ts
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+export const db = drizzle({ client: pool });
+```
+
+### 2. Vercel Fluid Compute with Connection Pooling
+
+```bash
+npm install drizzle-orm pg @vercel/functions
+npm install -D drizzle-kit @types/pg
+```
+
+```typescript
+// src/db.ts
+import { attachDatabasePool } from "@vercel/functions";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import * as schema from "./schema";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+attachDatabasePool(pool);
+
+export const db = drizzle({ client: pool, schema });
+```
+
+### 3. HTTP Adapter (Edge Without TCP)
+
+For Cloudflare Workers, Netlify Edge, Deno Deploy. Does NOT support interactive transactions.
+
+```bash
+npm install drizzle-orm @neondatabase/serverless
+npm install -D drizzle-kit dotenv
+```
+
+```typescript
+// src/db.ts
+import { drizzle } from "drizzle-orm/neon-http";
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!);
+export const db = drizzle(sql);
+```
+
+### 4. WebSocket Adapter (Edge with Transactions)
+
+```bash
+npm install drizzle-orm @neondatabase/serverless ws
+npm install -D drizzle-kit dotenv @types/ws
+```
+
+```typescript
+// src/db.ts
+import { drizzle } from "drizzle-orm/neon-serverless";
+import { Pool, neonConfig } from "@neondatabase/serverless";
+import ws from "ws";
+
+neonConfig.webSocketConstructor = ws; // Required for Node.js < v22
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+export const db = drizzle(pool);
+```
+
+## Drizzle Config
+
+```typescript
+// drizzle.config.ts
+import { config } from "dotenv";
+import { defineConfig } from "drizzle-kit";
+
+config({ path: ".env.local" });
+
+export default defineConfig({
+ schema: "./src/schema.ts",
+ out: "./drizzle",
+ dialect: "postgresql",
+ dbCredentials: {
+ url: process.env.DATABASE_URL!,
+ },
+});
+```
+
+## Migrations
+
+```bash
+# Generate migrations
+npx drizzle-kit generate
+
+# Apply migrations
+npx drizzle-kit migrate
+```
+
+## Schema Definition
+
+```typescript
+// src/schema.ts
+import { pgTable, serial, text, integer, timestamp } from "drizzle-orm/pg-core";
+
+export const usersTable = pgTable("users", {
+ id: serial("id").primaryKey(),
+ name: text("name").notNull(),
+ email: text("email").notNull().unique(),
+ role: text("role").default("user").notNull(),
+ createdAt: timestamp("created_at").defaultNow().notNull(),
+});
+
+export type User = typeof usersTable.$inferSelect;
+export type NewUser = typeof usersTable.$inferInsert;
+
+export const postsTable = pgTable("posts", {
+ id: serial("id").primaryKey(),
+ title: text("title").notNull(),
+ content: text("content").notNull(),
+ userId: integer("user_id")
+ .notNull()
+ .references(() => usersTable.id, { onDelete: "cascade" }),
+ createdAt: timestamp("created_at").defaultNow().notNull(),
+});
+
+export type Post = typeof postsTable.$inferSelect;
+export type NewPost = typeof postsTable.$inferInsert;
+```
+
+## Query Patterns
+
+### Batch Inserts
+
+```typescript
+export async function batchInsertUsers(users: NewUser[]) {
+ return db.insert(usersTable).values(users).returning();
+}
+```
+
+### Prepared Statements
+
+```typescript
+import { sql } from "drizzle-orm";
+
+export const getUsersByRolePrepared = db
+ .select()
+ .from(usersTable)
+ .where(sql`${usersTable.role} = ${sql.placeholder('role')}`)
+ .prepare("get_users_by_role");
+
+// Usage: getUsersByRolePrepared.execute({ role: 'admin' })
+```
+
+### Transactions
+
+```typescript
+export async function createUserWithPosts(user: NewUser, posts: NewPost[]) {
+ return await db.transaction(async (tx) => {
+ const [newUser] = await tx.insert(usersTable).values(user).returning();
+
+ if (posts.length > 0) {
+ await tx.insert(postsTable).values(
+ posts.map((post) => ({
+ ...post,
+ userId: newUser.id,
+ })),
+ );
+ }
+
+ return newUser;
+ });
+}
+```
+
+## Working with Neon Branches
+
+```typescript
+import { drizzle } from "drizzle-orm/neon-http";
+import { neon } from "@neondatabase/serverless";
+
+const getBranchUrl = () => {
+ const env = process.env.NODE_ENV;
+ if (env === "development") return process.env.DEV_DATABASE_URL;
+ if (env === "test") return process.env.TEST_DATABASE_URL;
+ return process.env.DATABASE_URL;
+};
+
+const sql = neon(getBranchUrl()!);
+export const db = drizzle({ client: sql });
+```
+
+## Error Handling
+
+```typescript
+export async function safeNeonOperation(
+ operation: () => Promise,
+): Promise {
+ try {
+ return await operation();
+ } catch (error: any) {
+ if (error.message?.includes("connection pool timeout")) {
+ console.error("Neon connection pool timeout");
+ }
+ throw error;
+ }
+}
+```
+
+## Best Practices
+
+1. **Connection Management** - See `connection-methods.md` for platform-specific guidance
+2. **Neon Features** - Utilize branching for development/testing (see `features.md`)
+3. **Query Optimization** - Batch operations, use prepared statements
+4. **Schema Design** - Leverage Postgres-specific features, use appropriate indexes
diff --git a/.agents/skills/neon-postgres/references/neon-js.md b/.agents/skills/neon-postgres/references/neon-js.md
new file mode 100644
index 00000000..6d4d83c4
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/neon-js.md
@@ -0,0 +1,451 @@
+# Neon JS SDK
+
+The `@neondatabase/neon-js` SDK provides a unified client for Neon Auth and Data API. It combines authentication handling with PostgREST-compatible database queries.
+
+**Auth only?** Use `@neondatabase/auth` instead (see `neon-auth.md`) for smaller bundle size.
+
+See the [official JavaScript SDK docs](https://neon.com/docs/reference/javascript-sdk.md) for complete details.
+
+## Package Selection
+
+| Use Case | Package | Notes |
+| --------------- | ---------------------------- | ------------------- |
+| Auth + Data API | `@neondatabase/neon-js` | Full SDK |
+| Auth only | `@neondatabase/auth` | Smaller bundle |
+| Data API only | `@neondatabase/postgrest-js` | Bring your own auth |
+
+## Installation
+
+```bash
+npm install @neondatabase/neon-js@latest
+```
+
+> **Note:** While this package is in pre-release (beta), you must use `@latest` with npm. Without it, npm may install an older version. This is not needed with pnpm or yarn.
+
+## Quick Setup Patterns
+
+### Next.js
+
+**1. Server Auth Instance:**
+
+```typescript
+// lib/auth/server.ts
+import { createNeonAuth } from "@neondatabase/neon-js/auth/next/server";
+
+export const auth = createNeonAuth({
+ baseUrl: process.env.NEON_AUTH_BASE_URL!,
+ cookies: {
+ secret: process.env.NEON_AUTH_COOKIE_SECRET!,
+ },
+});
+```
+
+**2. API Route Handler:**
+
+```typescript
+// app/api/auth/[...path]/route.ts
+import { auth } from "@/lib/auth/server";
+export const { GET, POST } = auth.handler();
+```
+
+**3. Auth Client:**
+
+```typescript
+// lib/auth/client.ts
+"use client";
+import { createAuthClient } from "@neondatabase/neon-js/auth/next";
+export const authClient = createAuthClient();
+```
+
+**4. Database Client:**
+
+```typescript
+// lib/db/client.ts
+import { createClient } from "@neondatabase/neon-js";
+import type { Database } from "./database.types";
+
+export const dbClient = createClient({
+ auth: { url: process.env.NEON_AUTH_BASE_URL! },
+ dataApi: { url: process.env.NEON_DATA_API_URL! },
+});
+```
+
+**5. Middleware + UI setup** — See [Neon Auth reference](neon-auth.md) for middleware configuration, `NeonAuthUIProvider`, CSS imports, and `AuthView`/`AccountView` page components.
+
+### React SPA
+
+```typescript
+import { createAuthClient } from "@neondatabase/neon-js/auth";
+
+const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL);
+```
+
+> **Note:** If you need React hooks like `useSession()` in custom components, pass an adapter:
+> `createAuthClient(url, { adapter: BetterAuthReactAdapter() })`.
+> UI components (`AuthView`, `SignedIn`, etc.) do not require an adapter.
+
+### React SPA with Data API
+
+```typescript
+import { createClient } from "@neondatabase/neon-js";
+
+const client = createClient({
+ auth: { url: import.meta.env.VITE_NEON_AUTH_URL },
+ dataApi: { url: import.meta.env.VITE_NEON_DATA_API_URL },
+});
+
+export const authClient = client.auth;
+```
+
+## Environment Variables
+
+```bash
+# Next.js (.env)
+NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
+NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
+NEON_DATA_API_URL=https://ep-xxx.apirest.us-east-1.aws.neon.tech/neondb/rest/v1
+
+# Vite/React (.env)
+VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
+VITE_NEON_DATA_API_URL=https://ep-xxx.apirest.us-east-1.aws.neon.tech/neondb/rest/v1
+```
+
+Get your Auth URL from the Neon Console: Project -> Branch -> Auth -> Configuration.
+
+Generate a cookie secret: `openssl rand -base64 32`
+
+## Database Queries (PostgREST / Data API)
+
+> **Prerequisite:** The Data API must be enabled per branch before making queries. Enable it via the Neon Console (Project → Data API), the MCP server's `provision_neon_data_api` tool, or the [REST API](https://api-docs.neon.tech/reference/createprojectbranchdataapi) (`POST /projects/{project_id}/branches/{branch_id}/data-api/{database_name}`). Without it, requests will return 404.
+
+All query methods follow PostgREST syntax (same as Supabase).
+
+```typescript
+// Select with filters
+const { data } = await client
+ .from("items")
+ .select("id, name, status")
+ .eq("status", "active")
+ .order("created_at", { ascending: false })
+ .limit(10);
+
+// Select single row
+const { data, error } = await client
+ .from("items")
+ .select("*")
+ .eq("id", 1)
+ .single();
+
+// Insert (returns inserted row)
+const { data, error } = await client
+ .from("items")
+ .insert({ name: "New Item", status: "pending" })
+ .select()
+ .single();
+
+// Insert multiple
+const { data } = await client
+ .from("items")
+ .insert([{ name: "A" }, { name: "B" }])
+ .select();
+
+// Update
+await client.from("items").update({ status: "completed" }).eq("id", 1);
+
+// Update and return updated row
+const { data } = await client
+ .from("items")
+ .update({ status: "completed" })
+ .eq("id", 1)
+ .select()
+ .single();
+
+// Delete
+await client.from("items").delete().eq("id", 1);
+
+// Delete and return deleted row
+const { data } = await client
+ .from("items")
+ .delete()
+ .eq("id", 1)
+ .select()
+ .single();
+
+// Upsert
+await client.from("items").upsert({ id: 1, name: "Updated", status: "active" });
+```
+
+### Filter Operators
+
+| Operator | Example |
+| ------------- | -------------------------------------------- |
+| `.eq()` | `.eq("status", "active")` |
+| `.neq()` | `.neq("status", "archived")` |
+| `.gt()` | `.gt("price", 100)` |
+| `.gte()` | `.gte("price", 100)` |
+| `.lt()` | `.lt("price", 100)` |
+| `.lte()` | `.lte("price", 100)` |
+| `.like()` | `.like("name", "%item%")` |
+| `.ilike()` | `.ilike("name", "%item%")` |
+| `.is()` | `.is("deleted_at", null)` |
+| `.in()` | `.in("status", ["active", "pending"])` |
+| `.contains()` | `.contains("tags", ["important"])` |
+| `.or()` | `.or("status.eq.active,price.gt.100")` |
+| `.not()` | `.not("status", "eq", "archived")` |
+| `.order()` | `.order("created_at", { ascending: false })` |
+| `.limit()` | `.limit(10)` |
+| `.range()` | `.range(0, 9)` (first 10 items) |
+
+**Pagination formula**: `.range((page - 1) * pageSize, page * pageSize - 1)`
+
+### Relationships
+
+```typescript
+// One-to-many
+const { data } = await client
+ .from("posts")
+ .select("id, title, author:users(name, email)");
+
+// Many-to-many
+const { data } = await client
+ .from("posts")
+ .select("id, title, tags:post_tags(tag:tags(name))");
+
+// Nested
+const { data } = await client.from("posts").select(`
+ id, title,
+ author:users(id, name, profile:profiles(bio, avatar))
+ `);
+```
+
+### Error Handling
+
+```typescript
+const { data, error } = await client.from("items").select();
+if (error) {
+ console.error(error.message, error.code, error.details);
+ return;
+}
+```
+
+Common error codes: `PGRST116` (no rows with `.single()`), `23505` (unique violation), `23503` (FK violation), `42P01` (table not found).
+
+### Next.js Usage Examples
+
+**Server Component:**
+
+```typescript
+// app/posts/page.tsx
+import { dbClient } from "@/lib/db/client";
+
+export default async function PostsPage() {
+ const { data: posts, error } = await dbClient
+ .from("posts")
+ .select("id, title, created_at, author:users(name)")
+ .order("created_at", { ascending: false })
+ .limit(10);
+
+ if (error) return
Error loading posts
;
+
+ return (
+
+ {posts?.map((post) => (
+
+
{post.title}
+
By {post.author?.name}
+
+ ))}
+
+ );
+}
+```
+
+**API Route:**
+
+```typescript
+// app/api/posts/route.ts
+import { dbClient } from "@/lib/db/client";
+import { NextResponse } from "next/server";
+
+export async function GET() {
+ const { data, error } = await dbClient.from("posts").select();
+ if (error)
+ return NextResponse.json({ error: error.message }, { status: 500 });
+ return NextResponse.json(data);
+}
+
+export async function POST(request: Request) {
+ const body = await request.json();
+ const { data, error } = await dbClient
+ .from("posts")
+ .insert(body)
+ .select()
+ .single();
+ if (error)
+ return NextResponse.json({ error: error.message }, { status: 400 });
+ return NextResponse.json(data, { status: 201 });
+}
+```
+
+## Auth Methods
+
+### BetterAuth API (Default)
+
+```typescript
+await client.auth.signIn.email({ email, password });
+await client.auth.signUp.email({ email, password, name });
+await client.auth.signOut();
+const { data: session } = await client.auth.getSession();
+await client.auth.signIn.social({
+ provider: "google",
+ callbackURL: "/dashboard",
+});
+```
+
+### Supabase-Compatible API
+
+```typescript
+import { createClient, SupabaseAuthAdapter } from "@neondatabase/neon-js";
+
+const client = createClient({
+ auth: { adapter: SupabaseAuthAdapter(), url },
+ dataApi: { url },
+});
+
+await client.auth.signInWithPassword({ email, password });
+await client.auth.signUp({ email, password });
+const {
+ data: { session },
+} = await client.auth.getSession();
+```
+
+## Key Imports
+
+```typescript
+// Main client
+import {
+ createClient,
+ SupabaseAuthAdapter,
+ BetterAuthVanillaAdapter,
+} from "@neondatabase/neon-js";
+
+// Server auth (Next.js) -- unified instance
+import { createNeonAuth } from "@neondatabase/neon-js/auth/next/server";
+
+// Client auth (Next.js) -- auto-includes React adapter
+import { createAuthClient } from "@neondatabase/neon-js/auth/next";
+
+// Client auth (React SPA / vanilla)
+import { createAuthClient } from "@neondatabase/neon-js/auth";
+
+// React adapter (only needed for useSession() in custom components)
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+
+// UI components (use /auth/react -- superset of /auth/react/ui and /auth/react/adapters)
+import {
+ NeonAuthUIProvider,
+ AuthView,
+ AccountView,
+ SignedIn,
+ SignedOut,
+ UserButton,
+} from "@neondatabase/neon-js/auth/react";
+import { accountViewPaths } from "@neondatabase/neon-js/auth/react/ui/server";
+
+// CSS (choose one, never both)
+import "@neondatabase/neon-js/ui/css"; // Without Tailwind
+// @import '@neondatabase/neon-js/ui/tailwind'; // With Tailwind v4 (in CSS file)
+```
+
+## Generate Types
+
+```bash
+npx neon-js gen-types --db-url "$DATABASE_URL" --output src/types/database.ts
+```
+
+Use types in the client for autocomplete and compile-time checking:
+
+```typescript
+import type { Database } from "./database.types";
+const client = createClient({ ... });
+```
+
+## Supabase Migration
+
+The Neon JS SDK uses the same PostgREST API as Supabase. Query syntax is identical:
+
+```typescript
+// Before (Supabase)
+import { createClient } from "@supabase/supabase-js";
+const client = createClient(SUPABASE_URL, SUPABASE_KEY);
+
+// After (Neon)
+import { createClient, SupabaseAuthAdapter } from "@neondatabase/neon-js";
+const client = createClient({
+ auth: { adapter: SupabaseAuthAdapter(), url: NEON_AUTH_URL },
+ dataApi: { url: NEON_DATA_API_URL },
+});
+
+// Queries work the same
+const { data } = await client.from("items").select();
+```
+
+## Common Mistakes
+
+### Using old v0.1 server APIs
+
+Use `createNeonAuth()` + `auth.handler()`, not standalone `authApiHandler()`. See `neon-auth.md` for the v0.2 pattern.
+
+### Missing NEON_AUTH_COOKIE_SECRET
+
+Required for Next.js, must be 32+ characters. Generate with `openssl rand -base64 32`.
+
+### Missing force-dynamic on server components
+
+Server components using `auth.getSession()` need `export const dynamic = 'force-dynamic'`.
+
+### Wrong adapter import path
+
+`BetterAuthReactAdapter` must be imported from a subpath and called as a function:
+
+```typescript
+// WRONG
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js";
+
+// CORRECT
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+auth: {
+ adapter: BetterAuthReactAdapter();
+} // Don't forget ()
+```
+
+### CSS import conflicts
+
+Choose ONE method. Never import both -- causes duplicate styles:
+
+```css
+/* With Tailwind v4 */
+@import "tailwindcss";
+@import "@neondatabase/neon-js/ui/tailwind";
+```
+
+```typescript
+/* Without Tailwind */
+import "@neondatabase/neon-js/ui/css";
+```
+
+### Missing "use client" directive
+
+Required for any component using `useSession()` or other React hooks:
+
+```typescript
+"use client"; // Required!
+import { authClient } from "@/lib/auth/client";
+```
+
+### Wrong API for adapter type
+
+| Adapter | Sign In | Sign Up |
+| ---------------------- | ----------------------------------------- | ----------------------------------- |
+| BetterAuthReactAdapter | `signIn.email({ email, password })` | `signUp.email({ email, password })` |
+| SupabaseAuthAdapter | `signInWithPassword({ email, password })` | `signUp({ email, password })` |
diff --git a/.agents/skills/neon-postgres/references/neon-python-sdk.md b/.agents/skills/neon-postgres/references/neon-python-sdk.md
new file mode 100644
index 00000000..76a2c613
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/neon-python-sdk.md
@@ -0,0 +1,101 @@
+# Neon Python SDK
+
+The `neon-api` Python SDK is a Pythonic wrapper around the Neon REST API for managing Neon resources programmatically.
+
+For core concepts (Organization, Project, Branch, Endpoint, etc.), see `what-is-neon.md`.
+
+See the [official Python SDK docs](https://neon.com/docs/reference/python-sdk.md) for complete details.
+
+## Installation
+
+```bash
+pip install neon-api
+```
+
+## Authentication
+
+```python
+import os
+from neon_api import NeonAPI
+
+neon = NeonAPI(api_key=os.environ["NEON_API_KEY"])
+```
+
+## Org-Aware Workflow
+
+All Neon accounts are organization-based. Discover the user's org first, then pass `org_id` to project operations:
+
+```python
+# 1. Get the user's organizations
+orgs = neon.current_user_organizations()
+org_id = orgs[0].id
+
+# 2. List projects within the org
+projects = neon.projects(org_id=org_id)
+```
+
+## Method Quick Reference
+
+### Projects
+
+| Operation | Method |
+| ------------------ | ------------------------------------------------------------------------------- |
+| List projects | `neon.projects(org_id=...)` |
+| Create project | `neon.project_create(project={ 'name': ..., 'pg_version': 17, 'org_id': ... })` |
+| Get project | `neon.project(project_id=...)` |
+| Update project | `neon.project_update(project_id=..., project={...})` |
+| Delete project | `neon.project_delete(project_id=...)` |
+| Get connection URI | `neon.connection_uri(project_id=..., database_name=..., role_name=...)` |
+
+### Branches
+
+| Operation | Method |
+| ------------- | ------------------------------------------------------------------- |
+| Create branch | `neon.branch_create(project_id=..., branch={...}, endpoints=[...])` |
+| List branches | `neon.branches(project_id=...)` |
+| Get branch | `neon.branch(project_id=..., branch_id=...)` |
+| Update branch | `neon.branch_update(project_id=..., branch_id=..., branch={...})` |
+| Delete branch | `neon.branch_delete(project_id=..., branch_id=...)` |
+
+### Databases
+
+| Operation | Method |
+| --------------- | ---------------------------------------------------------------------- |
+| Create database | `neon.database_create(project_id=..., branch_id=..., database={...})` |
+| List databases | `neon.databases(project_id=..., branch_id=...)` |
+| Delete database | `neon.database_delete(project_id=..., branch_id=..., database_id=...)` |
+
+### Roles
+
+| Operation | Method |
+| ----------- | ---------------------------------------------------------------- |
+| Create role | `neon.role_create(project_id=..., branch_id=..., role_name=...)` |
+| List roles | `neon.roles(project_id=..., branch_id=...)` |
+| Delete role | `neon.role_delete(project_id=..., branch_id=..., role_name=...)` |
+
+### Endpoints
+
+| Operation | Method |
+| ---------------- | ----------------------------------------------------------------------- |
+| Create endpoint | `neon.endpoint_create(project_id=..., endpoint={...})` |
+| Start endpoint | `neon.endpoint_start(project_id=..., endpoint_id=...)` |
+| Suspend endpoint | `neon.endpoint_suspend(project_id=..., endpoint_id=...)` |
+| Update endpoint | `neon.endpoint_update(project_id=..., endpoint_id=..., endpoint={...})` |
+| Delete endpoint | `neon.endpoint_delete(project_id=..., endpoint_id=...)` |
+
+### Organizations
+
+| Operation | Method |
+| -------------- | ----------------------------------- |
+| List user orgs | `neon.current_user_organizations()` |
+| Get org | `neon.organization(org_id=...)` |
+
+### API Keys & Operations
+
+| Operation | Method |
+| --------------- | -------------------------------------------------- |
+| List API keys | `neon.api_keys()` |
+| Create API key | `neon.api_key_create(key_name=...)` |
+| Revoke API key | `neon.api_key_revoke(key_id)` |
+| List operations | `neon.operations(project_id=...)` |
+| Get operation | `neon.operation(project_id=..., operation_id=...)` |
diff --git a/.agents/skills/neon-postgres/references/neon-rest-api.md b/.agents/skills/neon-postgres/references/neon-rest-api.md
new file mode 100644
index 00000000..4a33f97d
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/neon-rest-api.md
@@ -0,0 +1,73 @@
+# Neon REST API
+
+Essentials for making direct HTTP requests to the Neon Platform API.
+
+See the [official API reference](https://neon.com/docs/reference/api-reference.md) and [interactive explorer](https://api-docs.neon.tech/reference/getting-started-with-neon-api) for complete details. The full [OpenAPI spec](https://neon.com/api_spec/release/v2.json) is available for programmatic lookup of exact endpoints, request/response schemas, and required fields.
+
+## Base URL
+
+```
+https://console.neon.tech/api/v2/
+```
+
+## Authentication
+
+Include a Neon API key in every request:
+
+```
+Authorization: Bearer $NEON_API_KEY
+```
+
+### API Key Types
+
+| Type | Scope | Best For |
+| -------------- | ------------------------------- | ----------------------------- |
+| Personal | All projects user has access to | Individual use, scripting |
+| Organization | Entire organization | CI/CD, org-wide automation |
+| Project-scoped | Single project only | Project-specific integrations |
+
+## Rate Limits
+
+- 700 requests/minute (~11/second)
+- Bursts up to 40 requests/second per route
+- Handle `429 Too Many Requests` with retry + backoff
+
+## Common Endpoints
+
+| Operation | Method | Path |
+| ------------------ | -------- | -------------------------------------------------------- |
+| List projects | `GET` | `/projects?org_id={org_id}` |
+| List user orgs | `GET` | `/users/me/organizations` |
+| Create project | `POST` | `/projects` (include `org_id` in body) |
+| Get connection URI | `GET` | `/projects/{project_id}/connection_uri` |
+| Create branch | `POST` | `/projects/{project_id}/branches` |
+| List branches | `GET` | `/projects/{project_id}/branches` |
+| Delete branch | `DELETE` | `/projects/{project_id}/branches/{branch_id}` |
+| Start endpoint | `POST` | `/projects/{project_id}/endpoints/{endpoint_id}/start` |
+| Suspend endpoint | `POST` | `/projects/{project_id}/endpoints/{endpoint_id}/suspend` |
+| List databases | `GET` | `/projects/{project_id}/branches/{branch_id}/databases` |
+| Create database | `POST` | `/projects/{project_id}/branches/{branch_id}/databases` |
+| List roles | `GET` | `/projects/{project_id}/branches/{branch_id}/roles` |
+| List API keys | `GET` | `/api_keys` |
+| List operations | `GET` | `/projects/{project_id}/operations` |
+
+## Important Constraints
+
+- You **cannot delete** a project's root or default branch
+- You **cannot delete** a branch that has child branches — delete all children first
+- Creating a new role may **drop existing connections** to the active compute endpoint
+- A branch can have only one `read_write` endpoint but multiple `read_only` endpoints
+- Operations are async — poll operation status before starting dependent operations
+- Operations older than 6 months may be deleted from Neon's systems
+- The first API key must be created from the [Neon Console](https://console.neon.tech/app/settings/api-keys); subsequent keys can be created via the API
+
+## Error Codes
+
+| Status | Meaning | Action |
+| ------ | ------------ | ------------------------ |
+| 401 | Unauthorized | Check API key |
+| 404 | Not Found | Verify resource ID |
+| 429 | Rate Limited | Retry with backoff |
+| 500 | Server Error | Retry or contact support |
+
+For TypeScript SDK usage, see `neon-typescript-sdk.md`. For Python SDK, see `neon-python-sdk.md`.
diff --git a/.agents/skills/neon-postgres/references/neon-serverless.md b/.agents/skills/neon-postgres/references/neon-serverless.md
new file mode 100644
index 00000000..e9897d76
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/neon-serverless.md
@@ -0,0 +1,250 @@
+# Neon Serverless Driver
+
+Patterns and best practices for connecting to Neon databases in serverless environments using the `@neondatabase/serverless` driver. The driver connects over **HTTP** for fast, single queries or **WebSockets** for `node-postgres` compatibility and interactive transactions.
+
+See the [official serverless driver docs](https://neon.com/docs/serverless/serverless-driver.md) for complete details.
+
+## Installation
+
+```bash
+# Using npm
+npm install @neondatabase/serverless
+
+# Using JSR
+bunx jsr add @neon/serverless
+```
+
+**Note:** Version 1.0.0+ requires **Node.js v19 or later**.
+
+For projects that depend on `pg` but want to use Neon's WebSocket-based connection pool:
+
+```json
+"dependencies": {
+ "pg": "npm:@neondatabase/serverless@^0.10.4"
+},
+"overrides": {
+ "pg": "npm:@neondatabase/serverless@^0.10.4"
+}
+```
+
+## Connection String
+
+Always use environment variables:
+
+```typescript
+// For HTTP queries
+import { neon } from "@neondatabase/serverless";
+const sql = neon(process.env.DATABASE_URL!);
+
+// For WebSocket connections
+import { Pool } from "@neondatabase/serverless";
+const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+```
+
+**Never hardcode credentials:**
+
+```typescript
+// AVOID
+const sql = neon("postgres://username:password@host.neon.tech/neondb");
+```
+
+## HTTP Queries with `neon` function
+
+Ideal for simple, "one-shot" queries in serverless/edge environments. Uses HTTP `fetch` - fastest method for single queries.
+
+### Parameterized Queries
+
+Use tagged template literals for safe parameter interpolation:
+
+```typescript
+const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
+```
+
+For manually constructed queries:
+
+```typescript
+const [post] = await sql.query("SELECT * FROM posts WHERE id = $1", [postId]);
+```
+
+**Never concatenate user input:**
+
+```typescript
+// AVOID: SQL Injection Risk
+const [post] = await sql("SELECT * FROM posts WHERE id = " + postId);
+```
+
+### Configuration Options
+
+```typescript
+// Return rows as arrays instead of objects
+const sqlArrayMode = neon(process.env.DATABASE_URL!, { arrayMode: true });
+const rows = await sqlArrayMode`SELECT id, title FROM posts`;
+// rows -> [[1, "First Post"], [2, "Second Post"]]
+
+// Get full results including row count and field metadata
+const sqlFull = neon(process.env.DATABASE_URL!, { fullResults: true });
+const result = await sqlFull`SELECT * FROM posts LIMIT 1`;
+// result -> { rows: [...], fields: [...], rowCount: 1, ... }
+```
+
+## WebSocket Connections with `Pool` and `Client`
+
+Use for `node-postgres` compatibility, interactive transactions, or session support.
+
+### WebSocket Configuration
+
+For Node.js v21 and earlier:
+
+```typescript
+import { Pool, neonConfig } from "@neondatabase/serverless";
+import ws from "ws";
+
+// Required for Node.js < v22
+neonConfig.webSocketConstructor = ws;
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+```
+
+### Serverless Lifecycle Management
+
+Create, use, and close the pool within the same invocation:
+
+```typescript
+// Vercel Edge Functions example
+export default async (req: Request, ctx: ExecutionContext) => {
+ const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+
+ try {
+ const { rows } = await pool.query("SELECT * FROM users");
+ return new Response(JSON.stringify(rows));
+ } catch (err) {
+ console.error(err);
+ return new Response("Database error", { status: 500 });
+ } finally {
+ ctx.waitUntil(pool.end());
+ }
+};
+```
+
+**Avoid** creating a global `Pool` instance outside the handler.
+
+## Transactions
+
+### HTTP Transactions
+
+For running multiple queries in a single, non-interactive transaction:
+
+```typescript
+const [newUser, newProfile] = await sql.transaction(
+ [
+ sql`INSERT INTO users(name) VALUES(${name}) RETURNING id`,
+ sql`INSERT INTO profiles(user_id, bio) VALUES(${userId}, ${bio})`,
+ ],
+ {
+ isolationLevel: "ReadCommitted",
+ readOnly: false,
+ },
+);
+```
+
+### Interactive Transactions
+
+For complex transactions with conditional logic:
+
+```typescript
+const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+const client = await pool.connect();
+try {
+ await client.query("BEGIN");
+ const {
+ rows: [{ id }],
+ } = await client.query("INSERT INTO users(name) VALUES($1) RETURNING id", [
+ name,
+ ]);
+ await client.query("INSERT INTO profiles(user_id, bio) VALUES($1, $2)", [
+ id,
+ bio,
+ ]);
+ await client.query("COMMIT");
+} catch (err) {
+ await client.query("ROLLBACK");
+ throw err;
+} finally {
+ client.release();
+ await pool.end();
+}
+```
+
+## Environment-Specific Optimizations
+
+```javascript
+// For Vercel Edge Functions, specify nearest region
+export const config = {
+ runtime: "edge",
+ regions: ["iad1"], // Region nearest to your Neon DB
+};
+
+// For Cloudflare Workers, consider using Hyperdrive
+// https://neon.com/blog/hyperdrive-neon-faq
+```
+
+## ORM Integration
+
+For Drizzle ORM integration with the serverless driver, see `neon-drizzle.md`.
+
+### Prisma
+
+```typescript
+import { neonConfig } from "@neondatabase/serverless";
+import { PrismaNeon, PrismaNeonHTTP } from "@prisma/adapter-neon";
+import { PrismaClient } from "@prisma/client";
+import ws from "ws";
+
+const connectionString = process.env.DATABASE_URL;
+neonConfig.webSocketConstructor = ws;
+
+// HTTP adapter
+const adapterHttp = new PrismaNeonHTTP(connectionString!, {});
+export const prismaClientHttp = new PrismaClient({ adapter: adapterHttp });
+
+// WebSocket adapter
+const adapterWs = new PrismaNeon({ connectionString });
+export const prismaClientWs = new PrismaClient({ adapter: adapterWs });
+```
+
+### Kysely
+
+```typescript
+import { Pool } from "@neondatabase/serverless";
+import { Kysely, PostgresDialect } from "kysely";
+
+const dialect = new PostgresDialect({
+ pool: new Pool({ connectionString: process.env.DATABASE_URL }),
+});
+
+const db = new Kysely({ dialect });
+```
+
+**NOTE:** Do not pass the `neon()` function to ORMs that expect a `node-postgres` compatible `Pool`.
+
+## Error Handling
+
+```javascript
+// Pool error handling
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+pool.on("error", (err) => {
+ console.error("Unexpected error on idle client", err);
+ process.exit(-1);
+});
+
+// Query error handling
+try {
+ const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
+ if (!post) {
+ return new Response("Not found", { status: 404 });
+ }
+} catch (err) {
+ console.error("Database query failed:", err);
+ return new Response("Server error", { status: 500 });
+}
+```
diff --git a/.agents/skills/neon-postgres/references/neon-typescript-sdk.md b/.agents/skills/neon-postgres/references/neon-typescript-sdk.md
new file mode 100644
index 00000000..8dbdb8ec
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/neon-typescript-sdk.md
@@ -0,0 +1,135 @@
+# Neon TypeScript SDK
+
+The `@neondatabase/api-client` TypeScript SDK is a typed wrapper around the Neon REST API for managing Neon resources programmatically.
+
+For core concepts (Organization, Project, Branch, Endpoint, etc.), see `what-is-neon.md`.
+
+See the [official TypeScript SDK docs](https://neon.com/docs/reference/typescript-sdk.md) for complete details.
+
+## Installation
+
+```bash
+npm install @neondatabase/api-client
+```
+
+## Authentication
+
+```typescript
+import { createApiClient } from "@neondatabase/api-client";
+
+const apiClient = createApiClient({ apiKey: process.env.NEON_API_KEY! });
+```
+
+## Org-Aware Workflow
+
+All Neon accounts are organization-based. You must discover the user's org first, then pass `org_id` to project operations:
+
+```typescript
+// 1. Get the user's organizations
+const { data: orgs } = await apiClient.getCurrentUserOrganizations();
+const orgId = orgs.organizations[0].id;
+
+// 2. List projects within the org
+const { data: projects } = await apiClient.listProjects({ org_id: orgId });
+```
+
+## Method Quick Reference
+
+### Projects
+
+| Operation | Method |
+| ------------------ | ------------------------------------------------------------------------------- |
+| List projects | `apiClient.listProjects({ org_id })` |
+| Create project | `apiClient.createProject({ project: { name, pg_version, region_id, org_id } })` |
+| Get project | `apiClient.getProject(projectId)` |
+| Update project | `apiClient.updateProject(projectId, { project: { name } })` |
+| Delete project | `apiClient.deleteProject(projectId)` |
+| Get connection URI | `apiClient.getConnectionUri({ projectId, database_name, role_name, pooled })` |
+
+### Branches
+
+| Operation | Method |
+| ------------- | --------------------------------------------------------------------------------------- |
+| Create branch | `apiClient.createProjectBranch(projectId, { branch: { name }, endpoints: [{ type }] })` |
+| List branches | `apiClient.listProjectBranches({ projectId })` |
+| Get branch | `apiClient.getProjectBranch(projectId, branchId)` |
+| Update branch | `apiClient.updateProjectBranch(projectId, branchId, { branch: { name } })` |
+| Delete branch | `apiClient.deleteProjectBranch(projectId, branchId)` |
+
+### Databases
+
+| Operation | Method |
+| --------------- | ------------------------------------------------------------------------------------------------ |
+| Create database | `apiClient.createProjectBranchDatabase(projectId, branchId, { database: { name, owner_name } })` |
+| List databases | `apiClient.listProjectBranchDatabases(projectId, branchId)` |
+| Delete database | `apiClient.deleteProjectBranchDatabase(projectId, branchId, databaseName)` |
+
+### Roles
+
+| Operation | Method |
+| ----------- | ---------------------------------------------------------------------------- |
+| Create role | `apiClient.createProjectBranchRole(projectId, branchId, { role: { name } })` |
+| List roles | `apiClient.listProjectBranchRoles(projectId, branchId)` |
+| Delete role | `apiClient.deleteProjectBranchRole(projectId, branchId, roleName)` |
+
+### Endpoints
+
+| Operation | Method |
+| ---------------- | ------------------------------------------------------------------------------- |
+| Create endpoint | `apiClient.createProjectEndpoint(projectId, { endpoint: { branch_id, type } })` |
+| List endpoints | `apiClient.listProjectEndpoints(projectId)` |
+| Start endpoint | `apiClient.startProjectEndpoint(projectId, endpointId)` |
+| Suspend endpoint | `apiClient.suspendProjectEndpoint(projectId, endpointId)` |
+| Restart endpoint | `apiClient.restartProjectEndpoint(projectId, endpointId)` |
+| Update endpoint | `apiClient.updateProjectEndpoint(projectId, endpointId, { endpoint: {...} })` |
+| Delete endpoint | `apiClient.deleteProjectEndpoint(projectId, endpointId)` |
+
+### API Keys
+
+| Operation | Method |
+| ---------- | -------------------------------------- |
+| List keys | `apiClient.listApiKeys()` |
+| Create key | `apiClient.createApiKey({ key_name })` |
+| Revoke key | `apiClient.revokeApiKey(keyId)` |
+
+### Operations
+
+| Operation | Method |
+| --------------- | ------------------------------------------------------- |
+| List operations | `apiClient.listProjectOperations({ projectId })` |
+| Get operation | `apiClient.getProjectOperation(projectId, operationId)` |
+
+### Organizations
+
+| Operation | Method |
+| -------------- | ------------------------------------------------------------------------ |
+| List user orgs | `apiClient.getCurrentUserOrganizations()` |
+| Get org | `apiClient.getOrganization(orgId)` |
+| List members | `apiClient.getOrganizationMembers(orgId)` |
+| Create org key | `apiClient.createOrgApiKey(orgId, { key_name, project_id? })` |
+| Invite member | `apiClient.createOrganizationInvitations(orgId, { invitations: [...] })` |
+
+## Error Handling
+
+```typescript
+try {
+ const response = await apiClient.getProject(projectId);
+ return response.data;
+} catch (error: any) {
+ if (error.isAxiosError) {
+ const status = error.response?.status;
+ // 401 = bad API key, 404 = not found, 429 = rate limited
+ console.error("API error:", status, error.response?.data?.message);
+ }
+ return null;
+}
+```
+
+## Key Types
+
+```typescript
+import { EndpointType, MemberRole } from "@neondatabase/api-client";
+
+// EndpointType.ReadWrite, EndpointType.ReadOnly
+// MemberRole.Admin, MemberRole.Member
+```
diff --git a/.agents/skills/neon-postgres/references/what-is-neon.md b/.agents/skills/neon-postgres/references/what-is-neon.md
new file mode 100644
index 00000000..b2d8ba7c
--- /dev/null
+++ b/.agents/skills/neon-postgres/references/what-is-neon.md
@@ -0,0 +1,40 @@
+# What is Neon
+
+Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero.
+
+See the [official introduction](https://neon.com/docs/introduction.md) for complete details.
+
+## Core Concepts
+
+| Concept | Description | Key Relationship |
+| ---------------- | --------------------------------------------------------------------- | ------------------------- |
+| Organization | Highest-level container for billing, users, and projects | Contains Projects |
+| Project | Primary container for all database resources for an application | Contains Branches |
+| Branch | Lightweight, copy-on-write clone of database state | Contains Databases, Roles |
+| Compute Endpoint | Running PostgreSQL instance (CPU/RAM for queries) | Attached to a Branch |
+| Database | Logical container for data (tables, schemas, views) | Exists within a Branch |
+| Role | PostgreSQL role for authentication and authorization | Belongs to a Branch |
+| Operation | Async action by the control plane (creating branch, starting compute) | Associated with Project |
+
+## Key Differentiators
+
+1. **Serverless Architecture**: Compute scales automatically and can suspend when idle
+2. **Branching**: Create instant database copies without duplicating storage
+3. **Separation of Compute and Storage**: Pay for compute only when active
+4. **Postgres Compatible**: Works with any Postgres driver, ORM, or tool
+
+## When to Use Neon
+
+- **Serverless applications**: Functions that need database access without managing connections
+- **Development workflows**: Branch databases like code for isolated testing
+- **Variable workloads**: Auto-scale during traffic spikes, scale to zero when idle
+- **Cost optimization**: Pay only for active compute time and storage used
+
+## Further Reading
+
+| Topic | URL |
+| ---------------------- | ----------------------------------------------------------- |
+| Architecture | https://neon.com/docs/introduction/architecture-overview.md |
+| Plans & Billing | https://neon.com/docs/introduction/about-billing.md |
+| Regions | https://neon.com/docs/introduction/regions.md |
+| Postgres Compatibility | https://neon.com/docs/reference/compatibility.md |
diff --git a/.agents/skills/plugin-manager/SKILL.md b/.agents/skills/plugin-manager/SKILL.md
new file mode 100644
index 00000000..2e55aa64
--- /dev/null
+++ b/.agents/skills/plugin-manager/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: plugin-manager
+description: Manage plugin structure and configuration for this repository across both Cursor and Claude Code. Use when creating, updating, or reviewing plugin folders under plugins/, wiring marketplace manifests, setting up skill symlinks, assigning per-plugin mcp.json files, or adding additional plugins while preserving repo conventions.
+---
+
+# Plugin Manager
+
+Maintain plugin packaging for both ecosystems in a single repository, using a shared `plugins/` directory and a shared top-level `skills/` source of truth.
+
+## Working Rules
+
+- Keep each plugin self-contained in `plugins//`.
+- Keep shared reusable skill content in top-level `skills/`.
+- Expose shared skills per plugin via symlinks in `plugins//skills/`.
+- Keep MCP config plugin-local at `plugins//mcp.json`.
+- Keep both marketplace manifests at repo root:
+ - `.claude-plugin/marketplace.json`
+ - `.cursor-plugin/marketplace.json`
+
+## Required Plugin Layout
+
+For every plugin, ensure this layout exists:
+
+```text
+plugins//
+ .claude-plugin/plugin.json
+ .cursor-plugin/plugin.json
+ skills/
+ -> ../../../skills/ # symlink
+ mcp.json
+ assets/
+```
+
+## Create or Update a Plugin
+
+1. Create `plugins//`.
+2. Add both manifests:
+ - `plugins//.claude-plugin/plugin.json`
+ - `plugins//.cursor-plugin/plugin.json`
+3. Add or update `plugins//mcp.json` for plugin-specific MCP servers.
+4. Symlink required top-level skills into `plugins//skills/`.
+5. Add `plugins//assets/logo.svg` for Cursor.
+6. Register plugin in both marketplaces using `source: "./plugins/"`.
+7. Validate JSON and path references before finishing.
+
+## Manifest Guidelines
+
+- **Claude plugin manifest**
+ - Path: `plugins//.claude-plugin/plugin.json`
+ - Prefer plugin-local relative paths, for example:
+ - `"skills": "./skills/"`
+ - `"mcpServers": "./mcp.json"`
+- **Cursor plugin manifest**
+ - Path: `plugins//.cursor-plugin/plugin.json`
+ - Prefer plugin-local relative paths, for example:
+ - `"skills": "./skills/"`
+ - `"mcpServers": "./mcp.json"`
+ - `"logo": "assets/logo.svg"`
+- **Marketplace manifests**
+ - `.claude-plugin/marketplace.json` uses `source: "./plugins/"`.
+ - `.cursor-plugin/marketplace.json` uses `metadata.pluginRoot: "plugins"` and plugin entries with `source: ""`.
+
+## References
+
+- For detailed examples and checklists, read `references/plugin-guidelines.md`.
diff --git a/.agents/skills/plugin-manager/references/plugin-guidelines.md b/.agents/skills/plugin-manager/references/plugin-guidelines.md
new file mode 100644
index 00000000..f18bd6a6
--- /dev/null
+++ b/.agents/skills/plugin-manager/references/plugin-guidelines.md
@@ -0,0 +1,57 @@
+# Plugin Guidelines
+
+## Current Repository Structure
+
+```text
+.agents/skills/
+ plugin-manager/
+ skill-creator/
+
+skills/
+ neon-postgres/
+
+plugins/
+ neon-postgres/
+ .claude-plugin/plugin.json
+ .cursor-plugin/plugin.json
+ skills/
+ neon-postgres -> ../../../skills/neon-postgres
+ mcp.json
+ assets/logo.svg
+
+.claude-plugin/marketplace.json
+.cursor-plugin/marketplace.json
+```
+
+## Why This Structure
+
+- Plugin files are co-located per plugin, making ownership and boundaries clear.
+- Reusable skill content stays top-level in `skills/` and is reused via symlink.
+- Each plugin can own its own MCP configuration in `plugins//mcp.json`.
+- Marketplace manifests remain centralized at repo root.
+
+## Create an Additional Plugin
+
+1. Create `plugins//` with:
+ - `.claude-plugin/plugin.json`
+ - `.cursor-plugin/plugin.json`
+ - `skills/` directory
+ - optional `assets/` directory
+2. Add plugin-local MCP config:
+ - `plugins//mcp.json`
+3. Symlink required skills:
+ - `plugins//skills/ -> ../../../skills/`
+4. Add plugin to both marketplaces:
+ - `.claude-plugin/marketplace.json`: `source: "./plugins/"`
+ - `.cursor-plugin/marketplace.json`: with `pluginRoot: "plugins"`, use `source: ""`
+5. Verify paths in both plugin manifests are plugin-local and relative:
+ - `skills: "./skills/"`
+ - `mcpServers: "./mcp.json"`
+ - Cursor logo path, if used: `assets/logo.svg`
+
+## Guardrails
+
+- Do not duplicate shared skills into plugin folders; always symlink.
+- Do not reference paths outside plugin roots in manifest fields.
+- Keep plugin names kebab-case and consistent between marketplace and plugin manifests.
+- Keep Cursor marketplace `pluginRoot` and `source` consistent to avoid double-prefix path resolution errors.
diff --git a/.agents/skills/skill-creator/LICENSE.txt b/.agents/skills/skill-creator/LICENSE.txt
new file mode 100644
index 00000000..7a4a3ea2
--- /dev/null
+++ b/.agents/skills/skill-creator/LICENSE.txt
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
\ No newline at end of file
diff --git a/.agents/skills/skill-creator/SKILL.md b/.agents/skills/skill-creator/SKILL.md
new file mode 100644
index 00000000..913b0ea4
--- /dev/null
+++ b/.agents/skills/skill-creator/SKILL.md
@@ -0,0 +1,356 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+license: Complete terms in LICENSE.txt
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend Claude's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│ ├── YAML frontmatter metadata (required)
+│ │ ├── name: (required)
+│ │ ├── description: (required)
+│ │ └── compatibility: (optional, rarely needed)
+│ └── Markdown instructions (required)
+└── Bundled Resources (optional)
+ ├── scripts/ - Executable code (Python/Bash/etc.)
+ ├── references/ - Documentation intended to be loaded into context as needed
+ └── assets/ - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields (required), plus optional fields like `license`, `metadata`, and `compatibility`. Only `name` and `description` are read by Claude to determine when the skill triggers, so be clear and comprehensive about what the skill is and when it should be used. The `compatibility` field is for noting environment requirements (target product, system packages, etc.) but most skills don't need it.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
+
+- **When to include**: For documentation that Claude should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- etc.
+
+The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+
+**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
+```
+
+Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+ ├── finance.md (revenue, billing metrics)
+ ├── sales.md (opportunities, pipeline)
+ ├── product.md (API usage, features)
+ └── marketing.md (campaigns, attribution)
+```
+
+When a user asks about sales metrics, Claude only reads sales.md.
+
+Similarly, for skills supporting multiple frameworks or variants, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + provider selection)
+└── references/
+ ├── aws.md (AWS deployment patterns)
+ ├── gcp.md (GCP deployment patterns)
+ └── azure.md (Azure deployment patterns)
+```
+
+When the user chooses AWS, Claude only reads aws.md.
+
+**Pattern 3: Conditional details**
+
+Show basic content, link to advanced content:
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+Claude reads REDLINING.md or OOXML.md only when the user needs those features.
+
+**Important guidelines:**
+
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run package_skill.py)
+6. Iterate based on real usage
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+scripts/init_skill.py --path
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Creates example resource directories: `scripts/`, `references/`, and `assets/`
+- Adds example files in each directory that can be customized or deleted
+
+After initialization, customize or remove the generated SKILL.md and example files as needed.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
+
+#### Learn Proven Design Patterns
+
+Consult these helpful guides based on your skill's needs:
+
+- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
+- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
+
+These files contain established best practices for effective skill design.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
+
+Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.
+
+#### Update SKILL.md
+
+**Writing Guidelines:** Always use imperative/infinitive form.
+
+##### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name
+- `description`: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.
+ - Include both what the Skill does and specific triggers/contexts for when to use it.
+ - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
+ - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+
+Do not include any other fields in YAML frontmatter.
+
+##### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Packaging a Skill
+
+Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+scripts/package_skill.py
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+ - YAML frontmatter format and required fields
+ - Skill naming conventions and directory structure
+ - Description completeness and quality
+ - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again
diff --git a/.agents/skills/skill-creator/references/output-patterns.md b/.agents/skills/skill-creator/references/output-patterns.md
new file mode 100644
index 00000000..219c64c2
--- /dev/null
+++ b/.agents/skills/skill-creator/references/output-patterns.md
@@ -0,0 +1,92 @@
+# Output Patterns
+
+Use these patterns when skills need to produce consistent, high-quality output.
+
+## Template Pattern
+
+Provide templates for output format. Match the level of strictness to your needs.
+
+**For strict requirements (like API responses or data formats):**
+
+```markdown
+## Report structure
+
+ALWAYS use this exact template structure:
+
+# [Analysis Title]
+
+## Executive summary
+
+[One-paragraph overview of key findings]
+
+## Key findings
+
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+- Finding 3 with supporting data
+
+## Recommendations
+
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+
+**For flexible guidance (when adaptation is useful):**
+
+```markdown
+## Report structure
+
+Here is a sensible default format, but use your best judgment:
+
+# [Analysis Title]
+
+## Executive summary
+
+[Overview]
+
+## Key findings
+
+[Adapt sections based on what you discover]
+
+## Recommendations
+
+[Tailor to the specific context]
+
+Adjust sections as needed for the specific analysis type.
+```
+
+## Examples Pattern
+
+For skills where output quality depends on seeing examples, provide input/output pairs:
+
+```markdown
+## Commit message format
+
+Generate commit messages following these examples:
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+```
+
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+
+```
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly in reports
+Output:
+```
+
+fix(reports): correct date formatting in timezone conversion
+
+Use UTC timestamps consistently across report generation
+
+```
+
+Follow this style: type(scope): brief description, then detailed explanation.
+```
+
+Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
diff --git a/.agents/skills/skill-creator/references/workflows.md b/.agents/skills/skill-creator/references/workflows.md
new file mode 100644
index 00000000..54b01740
--- /dev/null
+++ b/.agents/skills/skill-creator/references/workflows.md
@@ -0,0 +1,28 @@
+# Workflow Patterns
+
+## Sequential Workflows
+
+For complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md:
+
+```markdown
+Filling a PDF form involves these steps:
+
+1. Analyze the form (run analyze_form.py)
+2. Create field mapping (edit fields.json)
+3. Validate mapping (run validate_fields.py)
+4. Fill the form (run fill_form.py)
+5. Verify output (run verify_output.py)
+```
+
+## Conditional Workflows
+
+For tasks with branching logic, guide Claude through decision points:
+
+```markdown
+1. Determine the modification type:
+ **Creating new content?** → Follow "Creation workflow" below
+ **Editing existing content?** → Follow "Editing workflow" below
+
+2. Creation workflow: [steps]
+3. Editing workflow: [steps]
+```
diff --git a/.agents/skills/skill-creator/scripts/init_skill.py b/.agents/skills/skill-creator/scripts/init_skill.py
new file mode 100644
index 00000000..da1cbfb7
--- /dev/null
+++ b/.agents/skills/skill-creator/scripts/init_skill.py
@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+ init_skill.py --path
+
+Examples:
+ init_skill.py my-new-skill --path skills/public
+ init_skill.py my-api-helper --path skills/private
+ init_skill.py custom-skill --path /custom/location
+"""
+
+import sys
+from pathlib import Path
+
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
+- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
+- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
+- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" → numbered capability list
+- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources
+
+This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
+
+**Examples from other skills:**
+- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
+- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
+
+**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
+
+**Examples from other skills:**
+- Product management: `communication.md`, `context_building.md` - detailed workflow guides
+- BigQuery: API reference documentation and query examples
+- Finance: Schema documentation, company policies
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+**Examples from other skills:**
+- Brand styling: PowerPoint template files (.pptx), logo files
+- Frontend builder: HTML/React boilerplate project directories
+- Typography: Font files (.ttf, .woff2)
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+This is a placeholder script that can be executed directly.
+Replace with actual implementation or delete if not needed.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+ print("This is an example script for {skill_name}")
+ # TODO: Add actual script logic here
+ # This could be data processing, file conversion, API calls, etc.
+
+if __name__ == "__main__":
+ main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Claude produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+def title_case_skill_name(skill_name):
+ """Convert hyphenated skill name to Title Case for display."""
+ return ' '.join(word.capitalize() for word in skill_name.split('-'))
+
+
+def init_skill(skill_name, path):
+ """
+ Initialize a new skill directory with template SKILL.md.
+
+ Args:
+ skill_name: Name of the skill
+ path: Path where the skill directory should be created
+
+ Returns:
+ Path to created skill directory, or None if error
+ """
+ import re
+
+ # Validate skill_name before using it in path operations
+ if not skill_name or not isinstance(skill_name, str):
+ print("❌ Error: Skill name must be a non-empty string")
+ return None
+
+ skill_name = skill_name.strip()
+
+ if not skill_name:
+ print("❌ Error: Skill name cannot be empty or whitespace")
+ return None
+
+ if len(skill_name) > 64:
+ print(f"❌ Error: Skill name too long ({len(skill_name)} chars). Maximum is 64.")
+ return None
+
+ if not re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', skill_name):
+ print(f"❌ Error: Skill name '{skill_name}' must be kebab-case")
+ print(" (lowercase letters, digits, hyphens; no leading/trailing/consecutive hyphens)")
+ return None
+
+ # Determine skill directory path
+ skill_dir = Path(path).resolve() / skill_name
+
+ # Ensure skill_dir is a subpath of the intended base path (prevent path traversal)
+ base_path = Path(path).resolve()
+ try:
+ skill_dir.relative_to(base_path)
+ except ValueError:
+ print(f"❌ Error: Invalid skill name causes path traversal: {skill_name}")
+ return None
+
+ # Check if directory already exists
+ if skill_dir.exists():
+ print(f"❌ Error: Skill directory already exists: {skill_dir}")
+ return None
+
+ # Create skill directory
+ try:
+ skill_dir.mkdir(parents=True, exist_ok=False)
+ print(f"✅ Created skill directory: {skill_dir}")
+ except Exception as e:
+ print(f"❌ Error creating directory: {e}")
+ return None
+
+ # Create SKILL.md from template
+ skill_title = title_case_skill_name(skill_name)
+ skill_content = SKILL_TEMPLATE.format(
+ skill_name=skill_name,
+ skill_title=skill_title
+ )
+
+ skill_md_path = skill_dir / 'SKILL.md'
+ try:
+ skill_md_path.write_text(skill_content)
+ print("✅ Created SKILL.md")
+ except Exception as e:
+ print(f"❌ Error creating SKILL.md: {e}")
+ return None
+
+ # Create resource directories with example files
+ try:
+ # Create scripts/ directory with example script
+ scripts_dir = skill_dir / 'scripts'
+ scripts_dir.mkdir(exist_ok=True)
+ example_script = scripts_dir / 'example.py'
+ example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+ example_script.chmod(0o755)
+ print("✅ Created scripts/example.py")
+
+ # Create references/ directory with example reference doc
+ references_dir = skill_dir / 'references'
+ references_dir.mkdir(exist_ok=True)
+ example_reference = references_dir / 'api_reference.md'
+ example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
+ print("✅ Created references/api_reference.md")
+
+ # Create assets/ directory with example asset placeholder
+ assets_dir = skill_dir / 'assets'
+ assets_dir.mkdir(exist_ok=True)
+ example_asset = assets_dir / 'example_asset.txt'
+ example_asset.write_text(EXAMPLE_ASSET)
+ print("✅ Created assets/example_asset.txt")
+ except Exception as e:
+ print(f"❌ Error creating resource directories: {e}")
+ return None
+
+ # Print next steps
+ print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
+ print("\nNext steps:")
+ print("1. Edit SKILL.md to complete the TODO items and update the description")
+ print("2. Customize or delete the example files in scripts/, references/, and assets/")
+ print("3. Run the validator when ready to check the skill structure")
+
+ return skill_dir
+
+
+def main():
+ if len(sys.argv) < 4 or sys.argv[2] != '--path':
+ print("Usage: init_skill.py --path ")
+ print("\nSkill name requirements:")
+ print(" - Kebab-case identifier (e.g., 'my-data-analyzer')")
+ print(" - Lowercase letters, digits, and hyphens only")
+ print(" - Max 64 characters")
+ print(" - Must match directory name exactly")
+ print("\nExamples:")
+ print(" init_skill.py my-new-skill --path skills/public")
+ print(" init_skill.py my-api-helper --path skills/private")
+ print(" init_skill.py custom-skill --path /custom/location")
+ sys.exit(1)
+
+ skill_name = sys.argv[1]
+ path = sys.argv[3]
+
+ print(f"🚀 Initializing skill: {skill_name}")
+ print(f" Location: {path}")
+ print()
+
+ result = init_skill(skill_name, path)
+
+ if result:
+ sys.exit(0)
+ else:
+ sys.exit(1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.agents/skills/skill-creator/scripts/package_skill.py b/.agents/skills/skill-creator/scripts/package_skill.py
new file mode 100644
index 00000000..531788db
--- /dev/null
+++ b/.agents/skills/skill-creator/scripts/package_skill.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+ python utils/package_skill.py [output-directory]
+
+Example:
+ python utils/package_skill.py skills/public/my-skill
+ python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+
+# Ensure sibling scripts are importable regardless of CWD
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from quick_validate import validate_skill # noqa: E402
+
+
+def package_skill(skill_path, output_dir=None):
+ """
+ Package a skill folder into a .skill file.
+
+ Args:
+ skill_path: Path to the skill folder
+ output_dir: Optional output directory for the .skill file (defaults to current directory)
+
+ Returns:
+ Path to the created .skill file, or None if error
+ """
+ skill_path = Path(skill_path).resolve()
+
+ # Validate skill folder exists
+ if not skill_path.exists():
+ print(f"❌ Error: Skill folder not found: {skill_path}")
+ return None
+
+ if not skill_path.is_dir():
+ print(f"❌ Error: Path is not a directory: {skill_path}")
+ return None
+
+ # Validate SKILL.md exists
+ skill_md = skill_path / "SKILL.md"
+ if not skill_md.exists():
+ print(f"❌ Error: SKILL.md not found in {skill_path}")
+ return None
+
+ # Run validation before packaging
+ print("🔍 Validating skill...")
+ valid, message = validate_skill(skill_path)
+ if not valid:
+ print(f"❌ Validation failed: {message}")
+ print(" Please fix the validation errors before packaging.")
+ return None
+ print(f"✅ {message}\n")
+
+ # Determine output location
+ skill_name = skill_path.name
+ if output_dir:
+ output_path = Path(output_dir).resolve()
+ output_path.mkdir(parents=True, exist_ok=True)
+ else:
+ output_path = Path.cwd()
+
+ skill_filename = output_path / f"{skill_name}.skill"
+
+ # Create the .skill file (zip format)
+ try:
+ with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+ # Walk through the skill directory
+ for file_path in skill_path.rglob('*'):
+ if file_path.is_file():
+ # Calculate the relative path within the zip
+ arcname = file_path.relative_to(skill_path.parent)
+ zipf.write(file_path, arcname)
+ print(f" Added: {arcname}")
+
+ print(f"\n✅ Successfully packaged skill to: {skill_filename}")
+ return skill_filename
+
+ except Exception as e:
+ print(f"❌ Error creating .skill file: {e}")
+ return None
+
+
+def main():
+ if len(sys.argv) < 2:
+ print("Usage: python utils/package_skill.py [output-directory]")
+ print("\nExample:")
+ print(" python utils/package_skill.py skills/public/my-skill")
+ print(" python utils/package_skill.py skills/public/my-skill ./dist")
+ sys.exit(1)
+
+ skill_path = sys.argv[1]
+ output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+ print(f"📦 Packaging skill: {skill_path}")
+ if output_dir:
+ print(f" Output directory: {output_dir}")
+ print()
+
+ result = package_skill(skill_path, output_dir)
+
+ if result:
+ sys.exit(0)
+ else:
+ sys.exit(1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.agents/skills/skill-creator/scripts/quick_validate.py b/.agents/skills/skill-creator/scripts/quick_validate.py
new file mode 100644
index 00000000..0e499646
--- /dev/null
+++ b/.agents/skills/skill-creator/scripts/quick_validate.py
@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import sys
+import os
+import re
+import yaml
+from pathlib import Path
+
+def validate_skill(skill_path):
+ """Basic validation of a skill"""
+ skill_path = Path(skill_path)
+
+ # Check SKILL.md exists
+ skill_md = skill_path / 'SKILL.md'
+ if not skill_md.exists():
+ return False, "SKILL.md not found"
+
+ # Read and validate frontmatter
+ content = skill_md.read_text()
+ if not content.startswith('---'):
+ return False, "No YAML frontmatter found"
+
+ # Extract frontmatter
+ match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+ if not match:
+ return False, "Invalid frontmatter format"
+
+ frontmatter_text = match.group(1)
+
+ # Parse YAML frontmatter
+ try:
+ frontmatter = yaml.safe_load(frontmatter_text)
+ if not isinstance(frontmatter, dict):
+ return False, "Frontmatter must be a YAML dictionary"
+ except yaml.YAMLError as e:
+ return False, f"Invalid YAML in frontmatter: {e}"
+
+ # Define allowed properties
+ ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}
+
+ # Check for unexpected properties (excluding nested keys under metadata)
+ unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
+ if unexpected_keys:
+ return False, (
+ f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
+ f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
+ )
+
+ # Check required fields
+ if 'name' not in frontmatter:
+ return False, "Missing 'name' in frontmatter"
+ if 'description' not in frontmatter:
+ return False, "Missing 'description' in frontmatter"
+
+ # Extract name for validation
+ name = frontmatter.get('name', '')
+ if not isinstance(name, str):
+ return False, f"Name must be a string, got {type(name).__name__}"
+ name = name.strip()
+ if not name:
+ return False, "Name cannot be empty or whitespace"
+
+ # Check naming convention (kebab-case: lowercase with hyphens)
+ if not re.match(r'^[a-z0-9-]+$', name):
+ return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
+ if name.startswith('-') or name.endswith('-') or '--' in name:
+ return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+ # Check name length (max 64 characters per spec)
+ if len(name) > 64:
+ return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
+
+ # Extract and validate description
+ description = frontmatter.get('description', '')
+ if not isinstance(description, str):
+ return False, f"Description must be a string, got {type(description).__name__}"
+ description = description.strip()
+ if not description:
+ return False, "Description cannot be empty or whitespace"
+
+ # Check for angle brackets
+ if '<' in description or '>' in description:
+ return False, "Description cannot contain angle brackets (< or >)"
+ # Check description length (max 1024 characters per spec)
+ if len(description) > 1024:
+ return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
+
+ # Validate compatibility field if present (optional)
+ compatibility = frontmatter.get('compatibility', '')
+ if compatibility:
+ if not isinstance(compatibility, str):
+ return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
+ if len(compatibility) > 500:
+ return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."
+
+ return True, "Skill is valid!"
+
+if __name__ == "__main__":
+ if len(sys.argv) != 2:
+ print("Usage: python quick_validate.py ")
+ sys.exit(1)
+
+ valid, message = validate_skill(sys.argv[1])
+ print(message)
+ sys.exit(0 if valid else 1)
\ No newline at end of file
diff --git a/.cursor/skills/neon-postgres/SKILL.md b/.cursor/skills/neon-postgres/SKILL.md
new file mode 100644
index 00000000..f376db53
--- /dev/null
+++ b/.cursor/skills/neon-postgres/SKILL.md
@@ -0,0 +1,129 @@
+---
+name: neon-postgres
+description: Guides and best practices for working with Neon Serverless Postgres. Covers getting started, local development with Neon, choosing a connection method, Neon features, authentication (@neondatabase/auth), PostgREST-style data API (@neondatabase/neon-js), Neon CLI, and Neon's Platform API/SDKs. Use for any Neon-related questions.
+---
+
+# Neon Serverless Postgres
+
+Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero. It's fully compatible with Postgres and works with any language, framework, or ORM that supports Postgres.
+
+## Neon Documentation
+
+The Neon documentation is the source of truth for all Neon-related information. Always verify claims against the official docs before responding. Neon features and APIs evolve, so prefer fetching current docs over relying on training data.
+
+### Fetching docs as markdown
+
+Any Neon doc page can be fetched as markdown in two ways:
+
+1. **Append `.md` to the URL** (simplest): `https://neon.com/docs/introduction/branching.md`
+2. **Request `text/markdown`** on the standard URL: `curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching`
+
+Both return the same markdown content. Use whichever method your tools support.
+
+### Finding the right page
+
+The docs index lists every available page with its URL and a short description:
+
+```
+https://neon.com/docs/llms.txt
+```
+
+Common doc URLs are listed in the tables below. If you need a page not listed here, search the [docs index](https://neon.com/docs/llms.txt) — don't guess URLs.
+
+### Common Documentation Paths
+
+| Topic | URL |
+| ------------------- | --------------------------------------------------------- |
+| Introduction | https://neon.com/docs/introduction.md |
+| Branching | https://neon.com/docs/introduction/branching.md |
+| Autoscaling | https://neon.com/docs/introduction/autoscaling.md |
+| Scale to Zero | https://neon.com/docs/introduction/scale-to-zero.md |
+| Instant Restore | https://neon.com/docs/introduction/branch-restore.md |
+| Read Replicas | https://neon.com/docs/introduction/read-replicas.md |
+| Connection Pooling | https://neon.com/docs/connect/connection-pooling.md |
+| IP Allow Lists | https://neon.com/docs/introduction/ip-allow.md |
+| Neon Auth | https://neon.com/docs/auth/overview.md |
+| Data API | https://neon.com/docs/data-api/overview.md |
+| Serverless Driver | https://neon.com/docs/serverless/serverless-driver.md |
+| JavaScript SDK | https://neon.com/docs/reference/javascript-sdk.md |
+| API Reference | https://neon.com/docs/reference/api-reference.md |
+| TypeScript SDK | https://neon.com/docs/reference/typescript-sdk.md |
+| Python SDK | https://neon.com/docs/reference/python-sdk.md |
+| Neon CLI | https://neon.com/docs/reference/neon-cli.md |
+| Logical Replication | https://neon.com/docs/guides/logical-replication-guide.md |
+
+### Framework & Language Guides
+
+| Framework/Language | URL |
+| ------------------ | ----------------------------------------- |
+| Next.js | https://neon.com/docs/guides/nextjs.md |
+| Django | https://neon.com/docs/guides/django.md |
+| Drizzle ORM | https://neon.com/docs/guides/drizzle.md |
+| Prisma | https://neon.com/docs/guides/prisma.md |
+| ORMs Guide | https://neon.com/docs/get-started/orms.md |
+
+### Platform API
+
+For managing Neon resources programmatically (projects, branches, endpoints, databases, roles):
+
+| Method | Documentation |
+| --------------- | ------------------------------------------------------------------ |
+| REST API | https://neon.com/docs/reference/api-reference.md |
+| Interactive API | https://api-docs.neon.tech/reference/getting-started-with-neon-api |
+| OpenAPI Spec | https://neon.com/api_spec/release/v2.json |
+| TypeScript SDK | https://neon.com/docs/reference/typescript-sdk.md |
+| Python SDK | https://neon.com/docs/reference/python-sdk.md |
+| CLI | https://neon.com/docs/reference/neon-cli.md |
+
+**Quick cross-reference** (common operations across interfaces):
+
+| Operation | REST API | TypeScript SDK | Python SDK |
+| ------------------ | ------------------------------ | --------------------------- | ---------------------- |
+| List projects | `GET /projects?org_id=...` | `listProjects({ org_id })` | `projects(org_id=...)` |
+| Create project | `POST /projects` | `createProject({...})` | `project_create(...)` |
+| Get connection URI | `GET .../connection_uri` | `getConnectionUri({...})` | `connection_uri(...)` |
+| Create branch | `POST .../branches` | `createProjectBranch(...)` | `branch_create(...)` |
+| Start endpoint | `POST .../endpoints/.../start` | `startProjectEndpoint(...)` | `endpoint_start(...)` |
+
+## Overview of Resources
+
+Reference the appropriate resource file based on the user's needs:
+
+### Core Guides
+
+| Area | Resource | When to Use |
+| ------------------ | ---------------------------------- | -------------------------------------------------------------- |
+| What is Neon | `references/what-is-neon.md` | Understanding Neon concepts, architecture, core resources |
+| Features | `references/features.md` | Branching, autoscaling, scale-to-zero, connection pooling |
+| Getting Started | `references/getting-started.md` | Setting up a project, connection strings, dependencies, schema |
+| Connection Methods | `references/connection-methods.md` | Choosing drivers based on platform and runtime |
+| Developer Tools | `references/devtools.md` | VSCode extension, MCP server, Neon CLI (`neon init`) |
+
+### Database Drivers & ORMs
+
+HTTP/WebSocket queries for serverless/edge functions.
+
+| Area | Resource | When to Use |
+| ----------------- | ------------------------------- | --------------------------------------------------- |
+| Serverless Driver | `references/neon-serverless.md` | `@neondatabase/serverless` - HTTP/WebSocket queries |
+| Drizzle ORM | `references/neon-drizzle.md` | Drizzle ORM integration with Neon |
+
+### Auth & Data API SDKs
+
+Authentication and PostgREST-style data API for Neon.
+
+| Area | Resource | When to Use |
+| ----------- | ------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Neon Auth | `references/neon-auth.md` | `@neondatabase/auth` or `@neondatabase/neon-js` - Setup, UI components, auth methods, common mistakes |
+| Neon JS SDK | `references/neon-js.md` | `@neondatabase/neon-js` - Auth + Data API (PostgREST-style queries) |
+
+### Neon Platform API & CLI
+
+Managing Neon resources programmatically via REST API, SDKs, or CLI.
+
+| Area | Resource | When to Use |
+| -------------- | ----------------------------------- | ------------------------------------------------ |
+| REST API | `references/neon-rest-api.md` | Direct HTTP calls - auth, endpoints, rate limits |
+| Neon CLI | `references/neon-cli.md` | Terminal workflows, scripts, CI/CD pipelines |
+| TypeScript SDK | `references/neon-typescript-sdk.md` | `@neondatabase/api-client` |
+| Python SDK | `references/neon-python-sdk.md` | `neon-api` package |
diff --git a/.cursor/skills/neon-postgres/references/connection-methods.md b/.cursor/skills/neon-postgres/references/connection-methods.md
new file mode 100644
index 00000000..398fa07f
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/connection-methods.md
@@ -0,0 +1,177 @@
+# Connection Methods
+
+Guide to selecting the optimal connection method for your Neon Postgres database based on deployment platform and runtime environment.
+
+See the [official connection guide](https://neon.com/docs/connect/choose-connection.md) for complete details.
+
+## Decision Tree
+
+Follow this flow to determine the right connection approach:
+
+### 1. What Language Are You Using?
+
+**Not TypeScript/JavaScript** → Use **TCP with connection pooling** from a secure server.
+
+For non-TypeScript languages, connect from a secure backend server using your language's native Postgres driver with connection pooling enabled.
+
+| Language/Framework | Documentation |
+| ------------------- | --------------------------------------------- |
+| Django (Python) | https://neon.com/docs/guides/django.md |
+| SQLAlchemy (Python) | https://neon.com/docs/guides/sqlalchemy.md |
+| Elixir Ecto | https://neon.com/docs/guides/elixir-ecto.md |
+| Laravel (PHP) | https://neon.com/docs/guides/laravel.md |
+| Ruby on Rails | https://neon.com/docs/guides/ruby-on-rails.md |
+| Go | https://neon.com/docs/guides/go.md |
+| Rust | https://neon.com/docs/guides/rust.md |
+| Java | https://neon.com/docs/guides/java.md |
+
+**TypeScript/JavaScript** → Continue to step 2.
+
+---
+
+### 2. Client-Side App Without Backend?
+
+**Yes** → Use **Neon Data API** via `@neondatabase/neon-js`
+
+This is the only option for client-side apps since browsers cannot make direct TCP connections to Postgres. See `neon-js.md` for setup and the [JavaScript SDK docs](https://neon.com/docs/reference/javascript-sdk.md) for the full reference.
+
+**No** → Continue to step 3.
+
+---
+
+### 3. Long-Running Server? (Railway, Render, traditional VPS)
+
+**Yes** → Use **TCP with connection pooling** via `node-postgres`, `postgres.js`, or `bun:pg`
+
+Long-running servers maintain persistent connections, so standard TCP drivers with pooling are optimal.
+
+**No** → Continue to step 4.
+
+---
+
+### 4. Edge Environment Without TCP Support?
+
+Some edge runtimes don't support TCP connections. Rarely the case anymore.
+
+**Yes** → Continue to step 5 to check transaction requirements.
+
+**No** → Continue to step 6 to check pooling support.
+
+---
+
+### 5. Does Your App Use SQL Transactions?
+
+**Yes** → Use **WebSocket transport** via `@neondatabase/serverless` with `Pool`
+
+WebSocket maintains connection state needed for transactions. See `neon-serverless.md` for setup.
+
+**No** → Use **HTTP transport** via `@neondatabase/serverless`
+
+HTTP is faster for single queries (~3 roundtrips vs ~8 for TCP). See `neon-serverless.md` for setup and the [serverless driver docs](https://neon.com/docs/serverless/serverless-driver.md) for the full reference.
+
+---
+
+### 6. Serverless Environment With Connection Pooling Support?
+
+**Vercel (Fluid Compute)** → Use **TCP with `@vercel/functions`**
+
+Vercel's Fluid compute supports connection pooling. Use `attachDatabasePool` for optimal connection management. See the [Vercel connection methods guide](https://neon.com/docs/guides/vercel-connection-methods.md) for details.
+
+**Cloudflare (with Hyperdrive)** → Use **TCP via Hyperdrive**
+
+Cloudflare Hyperdrive provides connection pooling for Workers. Use `node-postgres` or any native TCP driver.
+
+See the [Cloudflare Hyperdrive guide](https://neon.com/docs/guides/cloudflare-hyperdrive.md) for connecting with Cloudflare Workers and Hyperdrive.
+
+**No pooling support (Netlify, Deno Deploy)** → Use `@neondatabase/serverless`
+
+Fall back to the decision in step 5 based on transaction requirements.
+
+---
+
+## Quick Reference Table
+
+| Platform | TCP Support | Pooling | Recommended Driver |
+| ----------------------- | ----------- | ------------------- | -------------------------- |
+| Vercel (Fluid) | Yes | `@vercel/functions` | `pg` (node-postgres) |
+| Cloudflare (Hyperdrive) | Yes | Hyperdrive | `pg` (node-postgres) |
+| Cloudflare Workers | No | No | `@neondatabase/serverless` |
+| Netlify Functions | No | No | `@neondatabase/serverless` |
+| Deno Deploy | No | No | `@neondatabase/serverless` |
+| Railway / Render | Yes | Built-in | `pg` (node-postgres) |
+| Client-side (browser) | No | N/A | `@neondatabase/neon-js` |
+
+---
+
+## ORM Support
+
+Popular TypeScript/JavaScript ORMs all work with Neon:
+
+| ORM | Drivers Supported | Documentation |
+| ------- | ----------------------------------------------- | --------------------------------------- |
+| Drizzle | `pg`, `postgres.js`, `@neondatabase/serverless` | https://neon.com/docs/guides/drizzle.md |
+| Kysely | `pg`, `postgres.js`, `@neondatabase/serverless` | https://neon.com/docs/guides/kysely.md |
+| Prisma | `pg`, `@neondatabase/serverless` | https://neon.com/docs/guides/prisma.md |
+| TypeORM | `pg` | https://neon.com/docs/guides/typeorm.md |
+
+All ORMs support both TCP drivers and Neon's serverless driver depending on your platform.
+
+For Drizzle ORM integration with Neon, see `neon-drizzle.md`.
+
+---
+
+## Vercel Fluid + Drizzle Example
+
+Complete database client setup for Vercel with Drizzle ORM and connection pooling. See `neon-drizzle.md` for more examples.
+
+```typescript
+// src/lib/db/client.ts
+import { attachDatabasePool } from "@vercel/functions";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+
+import * as schema from "./schema";
+
+const pool = new Pool({
+ connectionString: process.env.DATABASE_URL,
+});
+attachDatabasePool(pool);
+
+export const db = drizzle({ client: pool, schema });
+```
+
+**Why `attachDatabasePool`?**
+
+- First request establishes the TCP connection (~8 roundtrips)
+- Subsequent requests reuse the connection instantly
+- Ensures idle connections close gracefully before function suspension
+- Prevents connection leaks in serverless environments
+
+---
+
+## Gathering Requirements
+
+When helping a user choose their connection method, gather this information:
+
+1. **Deployment platform**: Where will the app run? (Vercel, Cloudflare, Netlify, Railway, browser, etc.)
+2. **Runtime type**: Serverless functions, edge functions, or long-running server?
+3. **Transaction requirements**: Does the app need SQL transactions?
+4. **ORM preference**: Using Drizzle, Kysely, Prisma, or raw SQL?
+
+Then provide:
+
+- The recommended driver/package
+- A working code example for their setup
+- The correct npm install command
+
+---
+
+## Documentation Resources
+
+| Topic | URL |
+| -------------------------- | --------------------------------------------------------- |
+| Choosing Connection Method | https://neon.com/docs/connect/choose-connection.md |
+| Serverless Driver | https://neon.com/docs/serverless/serverless-driver.md |
+| JavaScript SDK | https://neon.com/docs/reference/javascript-sdk.md |
+| Connection Pooling | https://neon.com/docs/connect/connection-pooling.md |
+| Vercel Connection Methods | https://neon.com/docs/guides/vercel-connection-methods.md |
diff --git a/.cursor/skills/neon-postgres/references/devtools.md b/.cursor/skills/neon-postgres/references/devtools.md
new file mode 100644
index 00000000..5c029c31
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/devtools.md
@@ -0,0 +1,109 @@
+# Neon Developer Tools
+
+Neon provides developer tools to enhance your local development workflow, including a VSCode extension and MCP server for AI-assisted development.
+
+## Quick Setup with neon init
+
+The fastest way to set up all Neon developer tools:
+
+```bash
+npx neon init
+```
+
+This command:
+
+- Installs the Neon VSCode extension
+- Configures the Neon MCP server for AI assistants
+- Sets up your local environment for Neon development
+
+See the [full CLI init reference](https://neon.com/docs/reference/cli-init.md) for all options.
+
+## VSCode Extension
+
+The Neon VSCode extension provides:
+
+- **Database Explorer**: Browse projects, branches, tables, and data
+- **SQL Editor**: Write and execute queries with IntelliSense
+- **Branch Management**: Create, switch, and manage database branches
+- **Connection String Access**: Quick copy of connection strings
+
+**Install from VSCode:**
+
+1. Open Extensions (Cmd/Ctrl+Shift+X)
+2. Search "Neon"
+3. Install "Neon" by Neon
+
+**Or via command line:**
+
+```bash
+code --install-extension neon.neon-vscode
+```
+
+See the [full VSCode extension docs](https://neon.com/docs/local/vscode-extension.md) for all features.
+
+## Neon MCP Server
+
+The Neon MCP (Model Context Protocol) server enables AI assistants like Claude, Cursor, and GitHub Copilot to interact with your Neon databases directly.
+
+### Capabilities
+
+The MCP server provides AI assistants with:
+
+- **Project Management**: List, create, describe, and delete projects
+- **Branch Operations**: Create branches, compare schemas, reset from parent
+- **SQL Execution**: Run queries and transactions
+- **Schema Operations**: Describe tables, get database structure
+- **Migrations**: Prepare and complete database migrations with safety checks
+- **Query Tuning**: Analyze and optimize slow queries
+- **Neon Auth**: Provision authentication for your branches
+
+### Setup
+
+**Option 1: Via neon init (Recommended)**
+
+```bash
+npx neon init
+```
+
+**Option 2: Manual Configuration**
+
+Add to your AI assistant's MCP configuration:
+
+```json
+{
+ "mcpServers": {
+ "neon": {
+ "command": "npx",
+ "args": ["-y", "@neondatabase/mcp-server-neon"],
+ "env": {
+ "NEON_API_KEY": "your-api-key"
+ }
+ }
+ }
+}
+```
+
+Get your API key from: https://console.neon.tech/app/settings/api-keys
+
+### Common MCP Operations
+
+| Operation | What It Does |
+| ---------------------------- | ----------------------------- |
+| `list_projects` | Show all Neon projects |
+| `create_project` | Create a new project |
+| `run_sql` | Execute SQL queries |
+| `get_connection_string` | Get database connection URL |
+| `create_branch` | Create a database branch |
+| `prepare_database_migration` | Safely prepare schema changes |
+| `provision_neon_auth` | Set up Neon Auth |
+
+See the [full MCP server docs](https://neon.com/docs/ai/neon-mcp-server.md) for all available operations.
+
+## Documentation Resources
+
+| Topic | URL |
+| ------------------ | ----------------------------------------------- |
+| CLI Init Command | https://neon.com/docs/reference/cli-init.md |
+| VSCode Extension | https://neon.com/docs/local/vscode-extension.md |
+| MCP Server | https://neon.com/docs/ai/neon-mcp-server.md |
+| Neon CLI Reference | https://neon.com/docs/reference/neon-cli.md |
diff --git a/.cursor/skills/neon-postgres/references/features.md b/.cursor/skills/neon-postgres/references/features.md
new file mode 100644
index 00000000..a442acdc
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/features.md
@@ -0,0 +1,64 @@
+# Neon Features
+
+Quick-reference summaries of Neon's key platform features. Fetch the linked docs for full details.
+
+## Branching
+
+Instant, copy-on-write database clones at any point in time. Branches only store changes from parent -- no data duplication.
+
+- Branches are instant (no data copying)
+- Use for: dev environments, staging, preview deployments, testing migrations
+- Each branch can have its own compute endpoint
+- If the Neon MCP server is available, use it to list and create branches. Otherwise, use the CLI or Platform API.
+
+[Branching docs](https://neon.com/docs/introduction/branching.md)
+
+## Autoscaling
+
+Compute scales automatically between configured min and max Compute Units (CUs) based on CPU and memory pressure. No manual intervention required.
+
+[Autoscaling docs](https://neon.com/docs/introduction/autoscaling.md)
+
+## Scale to Zero
+
+Computes suspend after inactivity (default: 5 minutes, configurable). First query after suspend has ~500ms cold start. Storage is always maintained.
+
+[Scale to zero docs](https://neon.com/docs/introduction/scale-to-zero.md)
+
+## Instant Restore
+
+Point-in-time recovery without pre-configured backups. Restore window depends on plan (7-30 days). Can also create branches from any historical point, or use Time Travel queries.
+
+[Instant restore docs](https://neon.com/docs/introduction/branch-restore.md)
+
+## Read Replicas
+
+Read-only compute endpoints that share storage with the primary (no data duplication). Instant creation, independent scaling. Use for analytics, reporting, and read-heavy workloads.
+
+[Read replicas docs](https://neon.com/docs/introduction/read-replicas.md)
+
+## Connection Pooling
+
+Built-in PgBouncer. Enable by adding `-pooler` to the endpoint hostname. Transaction mode by default. Supports up to 10,000 concurrent connections. Essential for serverless environments.
+
+[Connection pooling docs](https://neon.com/docs/connect/connection-pooling.md)
+
+## Neon Auth
+
+Managed authentication that branches with your database. Supports email, social providers (Google, GitHub), session management, and UI components.
+
+For setup, see `neon-auth.md`. For auth + Data API, see `neon-js.md`.
+
+[Neon Auth docs](https://neon.com/docs/auth/overview.md)
+
+## IP Allow Lists
+
+Restrict database access to specific IP addresses or CIDR ranges. Can be scoped to protected branches only.
+
+[IP Allow docs](https://neon.com/docs/introduction/ip-allow.md)
+
+## Logical Replication
+
+Replicate data to/from external Postgres databases using native logical replication.
+
+[Logical replication docs](https://neon.com/docs/guides/logical-replication-guide.md)
diff --git a/.cursor/skills/neon-postgres/references/getting-started.md b/.cursor/skills/neon-postgres/references/getting-started.md
new file mode 100644
index 00000000..8bf26004
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/getting-started.md
@@ -0,0 +1,111 @@
+# Getting Started with Neon
+
+Interactive guide for setting up a Neon project and connecting it to code.
+
+See the [official getting started guide](https://neon.com/docs/get-started/signing-up.md) for complete details.
+
+## Setup Flow
+
+### 1. Select Organization and Project
+
+- Check existing organizations and projects (via MCP server or CLI)
+- **1 organization**: default to it
+- **Multiple organizations**: list all and ask which to use
+- **No projects**: ask if they want to create a new project
+- **1 project**: ask "Would you like to use '{project_name}' or create a new one?"
+- **Multiple projects (<6)**: list all and let them choose
+- **Many projects (6+)**: list recent projects, offer to create new or specify by name/ID
+
+### 2. Get Connection String
+
+- Use MCP server or CLI to get the connection string
+- Store it in `.env` as `DATABASE_URL`:
+
+```
+DATABASE_URL=postgresql://user:password@host/database
+```
+
+**Before modifying `.env`:**
+
+1. Try to read the `.env` file first
+2. If readable: use search/replace to update or append `DATABASE_URL`
+3. If unreadable (permissions): use append command or show the line to add manually
+4. Never overwrite an existing `.env` — always append or update in place
+
+### 3. Install Driver
+
+Choose based on deployment platform. For detailed guidance, see `connection-methods.md`.
+
+| Environment | Driver | Install |
+| ------------------------ | -------------------------- | -------------------------------------- |
+| Vercel (Edge/Serverless) | `@neondatabase/serverless` | `npm install @neondatabase/serverless` |
+| Cloudflare Workers | `@neondatabase/serverless` | `npm install @neondatabase/serverless` |
+| AWS Lambda | `@neondatabase/serverless` | `npm install @neondatabase/serverless` |
+| Traditional Node.js | `pg` | `npm install pg` |
+| Long-running servers | `pg` with pooling | `npm install pg` |
+
+For serverless driver patterns, see `neon-serverless.md`. For complex scenarios (multiple runtimes, hybrid architectures), see `connection-methods.md`.
+
+### 4. Authentication (if needed)
+
+Skip for CLI tools, scripts, or apps without user accounts.
+
+If the app needs auth: use MCP server `provision_neon_auth` tool, then see `neon-auth.md` for setup. For auth + database queries, see `neon-js.md`.
+
+### 5. ORM Setup (optional)
+
+Check for existing ORM (Prisma, Drizzle, TypeORM). If none, ask if they want one. For Drizzle integration, see `neon-drizzle.md`.
+
+### 6. Schema Setup
+
+- Check for existing migration files or ORM schemas
+- If none: offer to create an example schema or design one together
+
+### 7. Developer Tools
+
+```bash
+npx neon init
+```
+
+Installs the VSCode extension and configures the MCP server. See `devtools.md` for details.
+
+## What's Next
+
+After setup is complete, offer to help with:
+
+- Neon-specific features (branching, autoscaling, scale-to-zero) — see `features.md`
+- Connection pooling for production
+- Writing queries or building API endpoints
+- Database migrations and schema changes
+- Performance optimization
+
+## Resume Support
+
+If the user says "Continue with Neon setup", check what's already configured:
+
+- MCP server connection
+- `.env` file with `DATABASE_URL`
+- Dependencies installed
+- Schema created
+
+Then resume from where they left off.
+
+## Security Reminders
+
+- Never commit connection strings to version control
+- Use environment variables for all credentials
+- Prefer SSL connections (default in Neon)
+- Use least-privilege database roles
+- Rotate API keys and passwords regularly
+
+## Documentation
+
+| Topic | URL |
+| ------------------ | ----------------------------------------------------- |
+| Getting Started | https://neon.com/docs/get-started/signing-up.md |
+| Connecting to Neon | https://neon.com/docs/connect/connect-intro.md |
+| Connection String | https://neon.com/docs/connect/connect-from-any-app.md |
+| Frameworks Guide | https://neon.com/docs/get-started/frameworks.md |
+| ORMs Guide | https://neon.com/docs/get-started/orms.md |
+| VSCode Extension | https://neon.com/docs/local/vscode-extension.md |
+| MCP Server | https://neon.com/docs/ai/neon-mcp-server.md |
diff --git a/.cursor/skills/neon-postgres/references/neon-auth.md b/.cursor/skills/neon-postgres/references/neon-auth.md
new file mode 100644
index 00000000..579d0b27
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/neon-auth.md
@@ -0,0 +1,413 @@
+# Neon Auth
+
+Neon Auth provides managed authentication that stores users, sessions, and auth configuration directly in your Neon database. When you branch your database, your entire auth state branches with it.
+
+See the [official Neon Auth docs](https://neon.com/docs/auth/overview.md) for complete details.
+
+## Package Selection
+
+| Framework / Use Case | Package | Notes |
+| ----------------------- | ----------------------- | ------------------------------ |
+| Next.js | `@neondatabase/auth` | Server + client SDK |
+| React SPA (Vite, etc) | `@neondatabase/neon-js` | Client SDK + optional Data API |
+| Auth + Database queries | `@neondatabase/neon-js` | Full SDK |
+
+Both packages share auth exports (`@neondatabase/neon-js/auth/*` re-exports `@neondatabase/auth/*`).
+
+```bash
+# Next.js
+npm install @neondatabase/auth@latest
+
+# React SPA / Full SDK
+npm install @neondatabase/neon-js@latest
+```
+
+> **Note:** While these packages are in pre-release (beta), you must use `@latest` with npm. Without it, npm may install an older version. This is not needed with pnpm or yarn.
+
+## Next.js Setup
+
+**1. Server auth instance** (`lib/auth/server.ts`):
+
+```typescript
+import { createNeonAuth } from "@neondatabase/auth/next/server";
+
+export const auth = createNeonAuth({
+ baseUrl: process.env.NEON_AUTH_BASE_URL!,
+ cookies: {
+ secret: process.env.NEON_AUTH_COOKIE_SECRET!,
+ },
+});
+```
+
+**2. API route handler** (`app/api/auth/[...path]/route.ts`):
+
+```typescript
+import { auth } from "@/lib/auth/server";
+export const { GET, POST } = auth.handler();
+```
+
+**3. Middleware** (`middleware.ts`):
+
+```typescript
+import { auth } from "@/lib/auth/server";
+
+export default auth.middleware({
+ loginUrl: "/auth/sign-in",
+});
+
+export const config = {
+ matcher: ["/account/:path*"],
+};
+```
+
+**4. Client** (`lib/auth/client.ts`):
+
+```typescript
+"use client";
+import { createAuthClient } from "@neondatabase/auth/next";
+export const authClient = createAuthClient();
+```
+
+**5. Server component access** (must set `force-dynamic`):
+
+```typescript
+import { auth } from "@/lib/auth/server";
+
+export const dynamic = "force-dynamic";
+
+export default async function DashboardPage() {
+ const { data: session } = await auth.getSession();
+ if (!session?.user) return
Not logged in
;
+ return
Hello {session.user.name}
;
+}
+```
+
+**6. UI setup** — Add the provider, CSS, and page components. See [UI Components](#ui-components) below for `NeonAuthUIProvider`, CSS imports, `AuthView`, and `AccountView` setup.
+
+See the [Next.js quickstart](https://neon.com/docs/auth/quick-start/nextjs.md) and [server SDK reference](https://neon.com/docs/auth/reference/nextjs-server.md) for the full setup.
+
+### Environment Variables (Next.js)
+
+```bash
+NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
+NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
+```
+
+Get your Auth URL from the Neon Console: Project -> Branch -> Auth -> Configuration.
+
+Generate a cookie secret: `openssl rand -base64 32`
+
+## React SPA Setup
+
+**1. Auth client** (`lib/auth.ts`):
+
+```typescript
+import { createAuthClient } from "@neondatabase/neon-js/auth";
+
+export const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL);
+```
+
+If you need `useSession()` in custom components, pass an adapter:
+
+```typescript
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+
+const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL, {
+ adapter: BetterAuthReactAdapter(),
+});
+```
+
+UI components (`AuthView`, `SignedIn`, etc.) work without an adapter.
+
+**2. UI setup** — Wrap your app with `NeonAuthUIProvider` and import CSS. See [UI Components](#ui-components) below. In a SPA, the provider and CSS go in your root component (e.g., `App.tsx` or your router layout).
+
+**3. Routing** — Map `AuthView` and `AccountView` to routes in your router (React Router, TanStack Router, etc.). For example, with React Router:
+
+```tsx
+} />
+} />
+```
+
+### Environment Variables (React SPA)
+
+```bash
+VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
+```
+
+See the [React quickstart with UI components](https://neon.com/docs/auth/quick-start/react-router-components.md) and [React API-only quickstart](https://neon.com/docs/auth/quick-start/react.md) for the full setup.
+
+## UI Components
+
+Use pre-built components instead of building custom auth forms.
+
+| Component | Purpose |
+| ------------------------ | ----------------------------------------- |
+| `AuthView` | Sign-in, sign-up, forgot-password pages |
+| `AccountView` | Account settings, security pages |
+| `UserButton` | User avatar with dropdown menu |
+| `SignedIn` / `SignedOut` | Conditional rendering based on auth state |
+| `RedirectToSignIn` | Redirect unauthenticated users |
+| `RedirectToSignUp` | Redirect to sign-up page |
+
+See the [UI components reference](https://neon.com/docs/auth/reference/ui-components.md) for full props and customization.
+
+### CSS (choose one, never both)
+
+The CSS import path depends on which package you installed:
+
+```typescript
+// Next.js (@neondatabase/auth)
+import "@neondatabase/auth/ui/css";
+
+// React SPA (@neondatabase/neon-js)
+import "@neondatabase/neon-js/ui/css";
+```
+
+```css
+/* With Tailwind v4 — Next.js */
+@import "tailwindcss";
+@import "@neondatabase/auth/ui/tailwind";
+
+/* With Tailwind v4 — React SPA */
+@import "tailwindcss";
+@import "@neondatabase/neon-js/ui/tailwind";
+```
+
+### Provider Setup
+
+Wrap your app with `NeonAuthUIProvider`. Only `authClient` is required.
+
+In Next.js, add `suppressHydrationWarning` to the `` tag in your root layout — the provider injects theme attributes (`className="light"`, `color-scheme`) client-side that don't exist in the server render:
+
+```tsx
+// app/layout.tsx
+import { NeonAuthUIProvider, UserButton } from "@neondatabase/auth/react";
+import { authClient } from "@/lib/auth/client";
+
+export default function RootLayout({ children }) {
+ return (
+
+
+
+ {children}
+
+
+
+ );
+}
+```
+
+**Social login** requires TWO configurations: enable in Neon Console AND add `social` prop to provider.
+
+### AuthView (Next.js)
+
+Create `app/auth/[path]/page.tsx`:
+
+```tsx
+import { AuthView } from "@neondatabase/auth/react";
+
+export const dynamicParams = false;
+
+export default async function AuthPage({
+ params,
+}: {
+ params: Promise<{ path: string }>;
+}) {
+ const { path } = await params;
+ return ;
+}
+```
+
+Auth paths: `sign-in`, `sign-up`, `forgot-password`, `reset-password`, `magic-link`, `two-factor`, `callback`, `sign-out`
+
+### AccountView (Next.js)
+
+Create `app/account/[path]/page.tsx`:
+
+```tsx
+import { AccountView } from "@neondatabase/auth/react";
+import { accountViewPaths } from "@neondatabase/auth/react/ui/server";
+
+export const dynamicParams = false;
+
+export function generateStaticParams() {
+ return Object.values(accountViewPaths).map((path) => ({ path }));
+}
+
+export default async function AccountPage({
+ params,
+}: {
+ params: Promise<{ path: string }>;
+}) {
+ const { path } = await params;
+ return ;
+}
+```
+
+Account paths: `settings`, `security`
+
+### Conditional Rendering
+
+```tsx
+import { SignedIn, SignedOut, UserButton } from "@neondatabase/auth/react";
+
+
+ Sign In
+
+
+
+
+```
+
+## Auth Methods Quick Reference
+
+| Method | Usage |
+| ----------------------------------------------- | ---------------------------------------------- |
+| `auth.signUp.email({ email, password, name })` | Create account (server) |
+| `auth.signIn.email({ email, password })` | Sign in (server) |
+| `auth.signIn.social({ provider, callbackURL })` | OAuth sign-in (server) |
+| `auth.signOut()` | Sign out (server) |
+| `auth.getSession()` | Get session (server, requires `force-dynamic`) |
+| `authClient.useSession()` | Session hook (client, needs React adapter) |
+| `authClient.getSession()` | Get session (client, no adapter needed) |
+| `authClient.signIn.email(...)` | Sign in (client) |
+| `authClient.signUp.email(...)` | Create account (client) |
+
+### Session Data
+
+```typescript
+const { data: session } = await auth.getSession();
+// session.user: { id, name, email, image, emailVerified, createdAt, updatedAt }
+// session.session: { id, expiresAt, token, createdAt, updatedAt, userId }
+```
+
+### Error Handling
+
+```typescript
+const { error } = await auth.signIn.email({ email, password });
+if (error) {
+ // error.code: "INVALID_EMAIL_OR_PASSWORD", "EMAIL_NOT_VERIFIED",
+ // "USER_NOT_FOUND", "TOO_MANY_REQUESTS"
+ console.error(error.message);
+}
+```
+
+## Key Imports
+
+```typescript
+// Server (Next.js)
+import { createNeonAuth } from "@neondatabase/auth/next/server";
+
+// Client (Next.js) -- includes React adapter automatically
+import { createAuthClient } from "@neondatabase/auth/next";
+
+// Client (React SPA)
+import { createAuthClient } from "@neondatabase/neon-js/auth";
+
+// React adapter (only needed for useSession() in React SPA)
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+
+// UI components
+import {
+ NeonAuthUIProvider,
+ AuthView,
+ AccountView,
+ SignedIn,
+ SignedOut,
+ UserButton,
+} from "@neondatabase/auth/react";
+import { accountViewPaths } from "@neondatabase/auth/react/ui/server";
+
+// CSS (choose one, never both; path matches your package)
+import "@neondatabase/auth/ui/css"; // Next.js
+import "@neondatabase/neon-js/ui/css"; // React SPA
+// or in CSS: @import "@neondatabase/auth/ui/tailwind"; (Next.js)
+// or in CSS: @import "@neondatabase/neon-js/ui/tailwind"; (React SPA)
+```
+
+## Common Mistakes
+
+### Missing NEON_AUTH_COOKIE_SECRET
+
+Required for Next.js, must be 32+ characters for HMAC-SHA256. Generate with `openssl rand -base64 32`.
+
+### Missing force-dynamic on server components
+
+```typescript
+// WRONG -- will error
+export default async function Page() {
+ const { data: session } = await auth.getSession();
+}
+
+// CORRECT
+export const dynamic = "force-dynamic";
+export default async function Page() {
+ const { data: session } = await auth.getSession();
+}
+```
+
+### Using v0.1 API patterns
+
+Use `createNeonAuth()` + `auth.handler()`, not the old standalone `authApiHandler()`. See the [migration guide](https://neon.com/docs/auth/migrate/from-auth-v0.1.md).
+
+### Using useSession() without adapter in React SPA
+
+`createAuthClient(url)` without an adapter returns a vanilla client with no React hooks. Either pass `BetterAuthReactAdapter()` or use UI components (`SignedIn`, etc.) which don't require an adapter.
+
+### Wrong BetterAuthReactAdapter import
+
+Must use subpath import and call as function:
+
+```typescript
+// WRONG
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js";
+
+// CORRECT
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+const client = createAuthClient(url, { adapter: BetterAuthReactAdapter() });
+```
+
+### CSS import conflicts
+
+Choose ONE: `ui/css` (without Tailwind) or `ui/tailwind` (with Tailwind v4). Never import both -- causes ~94KB of duplicate styles.
+
+### Missing "use client" directive
+
+Required for any component using `useSession()` or other React hooks.
+
+### Wrong createAuthClient signature
+
+URL is the first argument, not a property in an options object:
+
+```typescript
+// WRONG
+createAuthClient({ url: myUrl });
+
+// CORRECT (React SPA)
+createAuthClient(url);
+createAuthClient(url, { adapter: BetterAuthReactAdapter() });
+
+// CORRECT (Next.js) -- no arguments, uses proxy
+createAuthClient();
+```
+
+## Documentation
+
+| Topic | URL |
+| -------------------- | ----------------------------------------------------------------- |
+| Auth Overview | https://neon.com/docs/auth/overview.md |
+| Next.js Quickstart | https://neon.com/docs/auth/quick-start/nextjs.md |
+| Next.js API-only | https://neon.com/docs/auth/quick-start/nextjs-api-only.md |
+| React with UI | https://neon.com/docs/auth/quick-start/react-router-components.md |
+| React API Methods | https://neon.com/docs/auth/quick-start/react.md |
+| TanStack Router | https://neon.com/docs/auth/quick-start/tanstack-router.md |
+| Server SDK Reference | https://neon.com/docs/auth/reference/nextjs-server.md |
+| UI Components Ref | https://neon.com/docs/auth/reference/ui-components.md |
+| Client SDK Reference | https://neon.com/docs/reference/javascript-sdk.md |
+| v0.1 Migration Guide | https://neon.com/docs/auth/migrate/from-auth-v0.1.md |
+| OAuth Setup | https://neon.com/docs/auth/guides/setup-oauth.md |
+| Email Verification | https://neon.com/docs/auth/guides/email-verification.md |
+| Branching Auth | https://neon.com/docs/auth/branching-authentication.md |
diff --git a/.cursor/skills/neon-postgres/references/neon-cli.md b/.cursor/skills/neon-postgres/references/neon-cli.md
new file mode 100644
index 00000000..6ff7d462
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/neon-cli.md
@@ -0,0 +1,154 @@
+# Neon CLI
+
+The Neon CLI is a command-line interface for managing Neon Serverless Postgres directly from your terminal. It provides the same capabilities as the Neon Platform API and is ideal for scripting, CI/CD pipelines, and developers who prefer terminal workflows.
+
+## Installation
+
+**macOS (Homebrew):**
+
+```bash
+brew install neonctl
+```
+
+**npm (cross-platform):**
+
+```bash
+npm install -g neonctl
+```
+
+## Authentication
+
+Authenticate with your Neon account:
+
+```bash
+neonctl auth
+```
+
+This opens a browser for OAuth authentication and stores credentials locally.
+
+For CI/CD or non-interactive environments, use an API key:
+
+```bash
+export NEON_API_KEY=your-api-key
+```
+
+Get your API key from: https://console.neon.tech/app/settings/api-keys
+
+## Common Commands
+
+### Project Management
+
+```bash
+# List all projects (org-scoped)
+neonctl projects list --org-id
+
+# Create a new project
+neonctl projects create --name my-project --org-id
+
+# Get project details
+neonctl projects get
+
+# Delete a project
+neonctl projects delete
+```
+
+### Branch Operations
+
+```bash
+# List branches
+neonctl branches list --project-id
+
+# Create a branch
+neonctl branches create --project-id --name dev
+
+# Delete a branch
+neonctl branches delete --project-id
+```
+
+### Connection Strings
+
+```bash
+# Get connection string
+neonctl connection-string --project-id
+
+# Get connection string for specific branch
+neonctl connection-string --project-id --branch-id
+
+# Get pooled connection string
+neonctl connection-string --project-id --pooled
+```
+
+### SQL Execution
+
+```bash
+# Run SQL query
+neonctl sql "SELECT * FROM users LIMIT 10" --project-id
+
+# Run SQL from file
+neonctl sql --file schema.sql --project-id
+```
+
+### Database Management
+
+```bash
+# List databases
+neonctl databases list --project-id --branch-id
+
+# Create database
+neonctl databases create --project-id --name mydb
+
+# List roles
+neonctl roles list --project-id --branch-id
+```
+
+## Output Formats
+
+The CLI supports multiple output formats:
+
+```bash
+# JSON output (default for scripting)
+neonctl projects list --output json
+
+# Table output (human-readable)
+neonctl projects list --output table
+
+# YAML output
+neonctl projects list --output yaml
+```
+
+## CI/CD Integration
+
+Example GitHub Actions workflow:
+
+```yaml
+- name: Create preview branch
+ env:
+ NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
+ run: |
+ neonctl branches create \
+ --project-id ${{ vars.NEON_PROJECT_ID }} \
+ --name preview-${{ github.event.pull_request.number }}
+```
+
+## CLI vs MCP Server vs SDKs
+
+| Tool | Best For |
+| -------------- | ------------------------------------------------- |
+| Neon CLI | Terminal workflows, scripts, CI/CD pipelines |
+| MCP Server | AI-assisted development with Claude, Cursor, etc. |
+| TypeScript SDK | Programmatic access in Node.js/TypeScript apps |
+| Python SDK | Programmatic access in Python applications |
+| REST API | Direct HTTP integration in any language |
+
+## Documentation Resources
+
+| Topic | URL |
+| -------------- | -------------------------------------------------------- |
+| CLI Reference | https://neon.com/docs/reference/neon-cli.md |
+| CLI Install | https://neon.com/docs/reference/cli-install.md |
+| CLI Auth | https://neon.com/docs/reference/cli-auth.md |
+| CLI Projects | https://neon.com/docs/reference/cli-projects.md |
+| CLI Branches | https://neon.com/docs/reference/cli-branches.md |
+| CLI Connection | https://neon.com/docs/reference/cli-connection-string.md |
+
+See the [full CLI docs](https://neon.com/docs/reference/neon-cli.md) for the complete command reference.
diff --git a/.cursor/skills/neon-postgres/references/neon-drizzle.md b/.cursor/skills/neon-postgres/references/neon-drizzle.md
new file mode 100644
index 00000000..c5f3ff25
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/neon-drizzle.md
@@ -0,0 +1,241 @@
+# Neon and Drizzle Integration
+
+Integration patterns, configurations, and optimizations for using **Drizzle ORM** with **Neon** Postgres.
+
+See the [official Drizzle guide](https://neon.com/docs/guides/drizzle.md) for complete details.
+
+## Choosing the Right Driver
+
+Drizzle ORM works with multiple Postgres drivers. See `connection-methods.md` for the full decision tree.
+
+| Platform | TCP Support | Pooling | Recommended Driver |
+| ----------------------- | ----------- | ------------------- | -------------------------- |
+| Vercel (Fluid) | Yes | `@vercel/functions` | `pg` (node-postgres) |
+| Cloudflare (Hyperdrive) | Yes | Hyperdrive | `pg` (node-postgres) |
+| Cloudflare Workers | No | No | `@neondatabase/serverless` |
+| Netlify Functions | No | No | `@neondatabase/serverless` |
+| Deno Deploy | No | No | `@neondatabase/serverless` |
+| Railway / Render | Yes | Built-in | `pg` (node-postgres) |
+
+## Connection Setup
+
+### 1. TCP with node-postgres (Long-Running Servers)
+
+Best for Railway, Render, traditional VPS.
+
+```bash
+npm install drizzle-orm pg
+npm install -D drizzle-kit @types/pg dotenv
+```
+
+```typescript
+// src/db.ts
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+export const db = drizzle({ client: pool });
+```
+
+### 2. Vercel Fluid Compute with Connection Pooling
+
+```bash
+npm install drizzle-orm pg @vercel/functions
+npm install -D drizzle-kit @types/pg
+```
+
+```typescript
+// src/db.ts
+import { attachDatabasePool } from "@vercel/functions";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import * as schema from "./schema";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+attachDatabasePool(pool);
+
+export const db = drizzle({ client: pool, schema });
+```
+
+### 3. HTTP Adapter (Edge Without TCP)
+
+For Cloudflare Workers, Netlify Edge, Deno Deploy. Does NOT support interactive transactions.
+
+```bash
+npm install drizzle-orm @neondatabase/serverless
+npm install -D drizzle-kit dotenv
+```
+
+```typescript
+// src/db.ts
+import { drizzle } from "drizzle-orm/neon-http";
+import { neon } from "@neondatabase/serverless";
+
+const sql = neon(process.env.DATABASE_URL!);
+export const db = drizzle(sql);
+```
+
+### 4. WebSocket Adapter (Edge with Transactions)
+
+```bash
+npm install drizzle-orm @neondatabase/serverless ws
+npm install -D drizzle-kit dotenv @types/ws
+```
+
+```typescript
+// src/db.ts
+import { drizzle } from "drizzle-orm/neon-serverless";
+import { Pool, neonConfig } from "@neondatabase/serverless";
+import ws from "ws";
+
+neonConfig.webSocketConstructor = ws; // Required for Node.js < v22
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+export const db = drizzle(pool);
+```
+
+## Drizzle Config
+
+```typescript
+// drizzle.config.ts
+import { config } from "dotenv";
+import { defineConfig } from "drizzle-kit";
+
+config({ path: ".env.local" });
+
+export default defineConfig({
+ schema: "./src/schema.ts",
+ out: "./drizzle",
+ dialect: "postgresql",
+ dbCredentials: {
+ url: process.env.DATABASE_URL!,
+ },
+});
+```
+
+## Migrations
+
+```bash
+# Generate migrations
+npx drizzle-kit generate
+
+# Apply migrations
+npx drizzle-kit migrate
+```
+
+## Schema Definition
+
+```typescript
+// src/schema.ts
+import { pgTable, serial, text, integer, timestamp } from "drizzle-orm/pg-core";
+
+export const usersTable = pgTable("users", {
+ id: serial("id").primaryKey(),
+ name: text("name").notNull(),
+ email: text("email").notNull().unique(),
+ role: text("role").default("user").notNull(),
+ createdAt: timestamp("created_at").defaultNow().notNull(),
+});
+
+export type User = typeof usersTable.$inferSelect;
+export type NewUser = typeof usersTable.$inferInsert;
+
+export const postsTable = pgTable("posts", {
+ id: serial("id").primaryKey(),
+ title: text("title").notNull(),
+ content: text("content").notNull(),
+ userId: integer("user_id")
+ .notNull()
+ .references(() => usersTable.id, { onDelete: "cascade" }),
+ createdAt: timestamp("created_at").defaultNow().notNull(),
+});
+
+export type Post = typeof postsTable.$inferSelect;
+export type NewPost = typeof postsTable.$inferInsert;
+```
+
+## Query Patterns
+
+### Batch Inserts
+
+```typescript
+export async function batchInsertUsers(users: NewUser[]) {
+ return db.insert(usersTable).values(users).returning();
+}
+```
+
+### Prepared Statements
+
+```typescript
+import { sql } from "drizzle-orm";
+
+export const getUsersByRolePrepared = db
+ .select()
+ .from(usersTable)
+ .where(sql`${usersTable.role} = ${sql.placeholder('role')}`)
+ .prepare("get_users_by_role");
+
+// Usage: getUsersByRolePrepared.execute({ role: 'admin' })
+```
+
+### Transactions
+
+```typescript
+export async function createUserWithPosts(user: NewUser, posts: NewPost[]) {
+ return await db.transaction(async (tx) => {
+ const [newUser] = await tx.insert(usersTable).values(user).returning();
+
+ if (posts.length > 0) {
+ await tx.insert(postsTable).values(
+ posts.map((post) => ({
+ ...post,
+ userId: newUser.id,
+ })),
+ );
+ }
+
+ return newUser;
+ });
+}
+```
+
+## Working with Neon Branches
+
+```typescript
+import { drizzle } from "drizzle-orm/neon-http";
+import { neon } from "@neondatabase/serverless";
+
+const getBranchUrl = () => {
+ const env = process.env.NODE_ENV;
+ if (env === "development") return process.env.DEV_DATABASE_URL;
+ if (env === "test") return process.env.TEST_DATABASE_URL;
+ return process.env.DATABASE_URL;
+};
+
+const sql = neon(getBranchUrl()!);
+export const db = drizzle({ client: sql });
+```
+
+## Error Handling
+
+```typescript
+export async function safeNeonOperation(
+ operation: () => Promise,
+): Promise {
+ try {
+ return await operation();
+ } catch (error: any) {
+ if (error.message?.includes("connection pool timeout")) {
+ console.error("Neon connection pool timeout");
+ }
+ throw error;
+ }
+}
+```
+
+## Best Practices
+
+1. **Connection Management** - See `connection-methods.md` for platform-specific guidance
+2. **Neon Features** - Utilize branching for development/testing (see `features.md`)
+3. **Query Optimization** - Batch operations, use prepared statements
+4. **Schema Design** - Leverage Postgres-specific features, use appropriate indexes
diff --git a/.cursor/skills/neon-postgres/references/neon-js.md b/.cursor/skills/neon-postgres/references/neon-js.md
new file mode 100644
index 00000000..6d4d83c4
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/neon-js.md
@@ -0,0 +1,451 @@
+# Neon JS SDK
+
+The `@neondatabase/neon-js` SDK provides a unified client for Neon Auth and Data API. It combines authentication handling with PostgREST-compatible database queries.
+
+**Auth only?** Use `@neondatabase/auth` instead (see `neon-auth.md`) for smaller bundle size.
+
+See the [official JavaScript SDK docs](https://neon.com/docs/reference/javascript-sdk.md) for complete details.
+
+## Package Selection
+
+| Use Case | Package | Notes |
+| --------------- | ---------------------------- | ------------------- |
+| Auth + Data API | `@neondatabase/neon-js` | Full SDK |
+| Auth only | `@neondatabase/auth` | Smaller bundle |
+| Data API only | `@neondatabase/postgrest-js` | Bring your own auth |
+
+## Installation
+
+```bash
+npm install @neondatabase/neon-js@latest
+```
+
+> **Note:** While this package is in pre-release (beta), you must use `@latest` with npm. Without it, npm may install an older version. This is not needed with pnpm or yarn.
+
+## Quick Setup Patterns
+
+### Next.js
+
+**1. Server Auth Instance:**
+
+```typescript
+// lib/auth/server.ts
+import { createNeonAuth } from "@neondatabase/neon-js/auth/next/server";
+
+export const auth = createNeonAuth({
+ baseUrl: process.env.NEON_AUTH_BASE_URL!,
+ cookies: {
+ secret: process.env.NEON_AUTH_COOKIE_SECRET!,
+ },
+});
+```
+
+**2. API Route Handler:**
+
+```typescript
+// app/api/auth/[...path]/route.ts
+import { auth } from "@/lib/auth/server";
+export const { GET, POST } = auth.handler();
+```
+
+**3. Auth Client:**
+
+```typescript
+// lib/auth/client.ts
+"use client";
+import { createAuthClient } from "@neondatabase/neon-js/auth/next";
+export const authClient = createAuthClient();
+```
+
+**4. Database Client:**
+
+```typescript
+// lib/db/client.ts
+import { createClient } from "@neondatabase/neon-js";
+import type { Database } from "./database.types";
+
+export const dbClient = createClient({
+ auth: { url: process.env.NEON_AUTH_BASE_URL! },
+ dataApi: { url: process.env.NEON_DATA_API_URL! },
+});
+```
+
+**5. Middleware + UI setup** — See [Neon Auth reference](neon-auth.md) for middleware configuration, `NeonAuthUIProvider`, CSS imports, and `AuthView`/`AccountView` page components.
+
+### React SPA
+
+```typescript
+import { createAuthClient } from "@neondatabase/neon-js/auth";
+
+const authClient = createAuthClient(import.meta.env.VITE_NEON_AUTH_URL);
+```
+
+> **Note:** If you need React hooks like `useSession()` in custom components, pass an adapter:
+> `createAuthClient(url, { adapter: BetterAuthReactAdapter() })`.
+> UI components (`AuthView`, `SignedIn`, etc.) do not require an adapter.
+
+### React SPA with Data API
+
+```typescript
+import { createClient } from "@neondatabase/neon-js";
+
+const client = createClient({
+ auth: { url: import.meta.env.VITE_NEON_AUTH_URL },
+ dataApi: { url: import.meta.env.VITE_NEON_DATA_API_URL },
+});
+
+export const authClient = client.auth;
+```
+
+## Environment Variables
+
+```bash
+# Next.js (.env)
+NEON_AUTH_BASE_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
+NEON_AUTH_COOKIE_SECRET=your-secret-at-least-32-characters-long
+NEON_DATA_API_URL=https://ep-xxx.apirest.us-east-1.aws.neon.tech/neondb/rest/v1
+
+# Vite/React (.env)
+VITE_NEON_AUTH_URL=https://ep-xxx.neonauth.us-east-1.aws.neon.tech/neondb/auth
+VITE_NEON_DATA_API_URL=https://ep-xxx.apirest.us-east-1.aws.neon.tech/neondb/rest/v1
+```
+
+Get your Auth URL from the Neon Console: Project -> Branch -> Auth -> Configuration.
+
+Generate a cookie secret: `openssl rand -base64 32`
+
+## Database Queries (PostgREST / Data API)
+
+> **Prerequisite:** The Data API must be enabled per branch before making queries. Enable it via the Neon Console (Project → Data API), the MCP server's `provision_neon_data_api` tool, or the [REST API](https://api-docs.neon.tech/reference/createprojectbranchdataapi) (`POST /projects/{project_id}/branches/{branch_id}/data-api/{database_name}`). Without it, requests will return 404.
+
+All query methods follow PostgREST syntax (same as Supabase).
+
+```typescript
+// Select with filters
+const { data } = await client
+ .from("items")
+ .select("id, name, status")
+ .eq("status", "active")
+ .order("created_at", { ascending: false })
+ .limit(10);
+
+// Select single row
+const { data, error } = await client
+ .from("items")
+ .select("*")
+ .eq("id", 1)
+ .single();
+
+// Insert (returns inserted row)
+const { data, error } = await client
+ .from("items")
+ .insert({ name: "New Item", status: "pending" })
+ .select()
+ .single();
+
+// Insert multiple
+const { data } = await client
+ .from("items")
+ .insert([{ name: "A" }, { name: "B" }])
+ .select();
+
+// Update
+await client.from("items").update({ status: "completed" }).eq("id", 1);
+
+// Update and return updated row
+const { data } = await client
+ .from("items")
+ .update({ status: "completed" })
+ .eq("id", 1)
+ .select()
+ .single();
+
+// Delete
+await client.from("items").delete().eq("id", 1);
+
+// Delete and return deleted row
+const { data } = await client
+ .from("items")
+ .delete()
+ .eq("id", 1)
+ .select()
+ .single();
+
+// Upsert
+await client.from("items").upsert({ id: 1, name: "Updated", status: "active" });
+```
+
+### Filter Operators
+
+| Operator | Example |
+| ------------- | -------------------------------------------- |
+| `.eq()` | `.eq("status", "active")` |
+| `.neq()` | `.neq("status", "archived")` |
+| `.gt()` | `.gt("price", 100)` |
+| `.gte()` | `.gte("price", 100)` |
+| `.lt()` | `.lt("price", 100)` |
+| `.lte()` | `.lte("price", 100)` |
+| `.like()` | `.like("name", "%item%")` |
+| `.ilike()` | `.ilike("name", "%item%")` |
+| `.is()` | `.is("deleted_at", null)` |
+| `.in()` | `.in("status", ["active", "pending"])` |
+| `.contains()` | `.contains("tags", ["important"])` |
+| `.or()` | `.or("status.eq.active,price.gt.100")` |
+| `.not()` | `.not("status", "eq", "archived")` |
+| `.order()` | `.order("created_at", { ascending: false })` |
+| `.limit()` | `.limit(10)` |
+| `.range()` | `.range(0, 9)` (first 10 items) |
+
+**Pagination formula**: `.range((page - 1) * pageSize, page * pageSize - 1)`
+
+### Relationships
+
+```typescript
+// One-to-many
+const { data } = await client
+ .from("posts")
+ .select("id, title, author:users(name, email)");
+
+// Many-to-many
+const { data } = await client
+ .from("posts")
+ .select("id, title, tags:post_tags(tag:tags(name))");
+
+// Nested
+const { data } = await client.from("posts").select(`
+ id, title,
+ author:users(id, name, profile:profiles(bio, avatar))
+ `);
+```
+
+### Error Handling
+
+```typescript
+const { data, error } = await client.from("items").select();
+if (error) {
+ console.error(error.message, error.code, error.details);
+ return;
+}
+```
+
+Common error codes: `PGRST116` (no rows with `.single()`), `23505` (unique violation), `23503` (FK violation), `42P01` (table not found).
+
+### Next.js Usage Examples
+
+**Server Component:**
+
+```typescript
+// app/posts/page.tsx
+import { dbClient } from "@/lib/db/client";
+
+export default async function PostsPage() {
+ const { data: posts, error } = await dbClient
+ .from("posts")
+ .select("id, title, created_at, author:users(name)")
+ .order("created_at", { ascending: false })
+ .limit(10);
+
+ if (error) return
Error loading posts
;
+
+ return (
+
+ {posts?.map((post) => (
+
+
{post.title}
+
By {post.author?.name}
+
+ ))}
+
+ );
+}
+```
+
+**API Route:**
+
+```typescript
+// app/api/posts/route.ts
+import { dbClient } from "@/lib/db/client";
+import { NextResponse } from "next/server";
+
+export async function GET() {
+ const { data, error } = await dbClient.from("posts").select();
+ if (error)
+ return NextResponse.json({ error: error.message }, { status: 500 });
+ return NextResponse.json(data);
+}
+
+export async function POST(request: Request) {
+ const body = await request.json();
+ const { data, error } = await dbClient
+ .from("posts")
+ .insert(body)
+ .select()
+ .single();
+ if (error)
+ return NextResponse.json({ error: error.message }, { status: 400 });
+ return NextResponse.json(data, { status: 201 });
+}
+```
+
+## Auth Methods
+
+### BetterAuth API (Default)
+
+```typescript
+await client.auth.signIn.email({ email, password });
+await client.auth.signUp.email({ email, password, name });
+await client.auth.signOut();
+const { data: session } = await client.auth.getSession();
+await client.auth.signIn.social({
+ provider: "google",
+ callbackURL: "/dashboard",
+});
+```
+
+### Supabase-Compatible API
+
+```typescript
+import { createClient, SupabaseAuthAdapter } from "@neondatabase/neon-js";
+
+const client = createClient({
+ auth: { adapter: SupabaseAuthAdapter(), url },
+ dataApi: { url },
+});
+
+await client.auth.signInWithPassword({ email, password });
+await client.auth.signUp({ email, password });
+const {
+ data: { session },
+} = await client.auth.getSession();
+```
+
+## Key Imports
+
+```typescript
+// Main client
+import {
+ createClient,
+ SupabaseAuthAdapter,
+ BetterAuthVanillaAdapter,
+} from "@neondatabase/neon-js";
+
+// Server auth (Next.js) -- unified instance
+import { createNeonAuth } from "@neondatabase/neon-js/auth/next/server";
+
+// Client auth (Next.js) -- auto-includes React adapter
+import { createAuthClient } from "@neondatabase/neon-js/auth/next";
+
+// Client auth (React SPA / vanilla)
+import { createAuthClient } from "@neondatabase/neon-js/auth";
+
+// React adapter (only needed for useSession() in custom components)
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+
+// UI components (use /auth/react -- superset of /auth/react/ui and /auth/react/adapters)
+import {
+ NeonAuthUIProvider,
+ AuthView,
+ AccountView,
+ SignedIn,
+ SignedOut,
+ UserButton,
+} from "@neondatabase/neon-js/auth/react";
+import { accountViewPaths } from "@neondatabase/neon-js/auth/react/ui/server";
+
+// CSS (choose one, never both)
+import "@neondatabase/neon-js/ui/css"; // Without Tailwind
+// @import '@neondatabase/neon-js/ui/tailwind'; // With Tailwind v4 (in CSS file)
+```
+
+## Generate Types
+
+```bash
+npx neon-js gen-types --db-url "$DATABASE_URL" --output src/types/database.ts
+```
+
+Use types in the client for autocomplete and compile-time checking:
+
+```typescript
+import type { Database } from "./database.types";
+const client = createClient({ ... });
+```
+
+## Supabase Migration
+
+The Neon JS SDK uses the same PostgREST API as Supabase. Query syntax is identical:
+
+```typescript
+// Before (Supabase)
+import { createClient } from "@supabase/supabase-js";
+const client = createClient(SUPABASE_URL, SUPABASE_KEY);
+
+// After (Neon)
+import { createClient, SupabaseAuthAdapter } from "@neondatabase/neon-js";
+const client = createClient({
+ auth: { adapter: SupabaseAuthAdapter(), url: NEON_AUTH_URL },
+ dataApi: { url: NEON_DATA_API_URL },
+});
+
+// Queries work the same
+const { data } = await client.from("items").select();
+```
+
+## Common Mistakes
+
+### Using old v0.1 server APIs
+
+Use `createNeonAuth()` + `auth.handler()`, not standalone `authApiHandler()`. See `neon-auth.md` for the v0.2 pattern.
+
+### Missing NEON_AUTH_COOKIE_SECRET
+
+Required for Next.js, must be 32+ characters. Generate with `openssl rand -base64 32`.
+
+### Missing force-dynamic on server components
+
+Server components using `auth.getSession()` need `export const dynamic = 'force-dynamic'`.
+
+### Wrong adapter import path
+
+`BetterAuthReactAdapter` must be imported from a subpath and called as a function:
+
+```typescript
+// WRONG
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js";
+
+// CORRECT
+import { BetterAuthReactAdapter } from "@neondatabase/neon-js/auth/react";
+auth: {
+ adapter: BetterAuthReactAdapter();
+} // Don't forget ()
+```
+
+### CSS import conflicts
+
+Choose ONE method. Never import both -- causes duplicate styles:
+
+```css
+/* With Tailwind v4 */
+@import "tailwindcss";
+@import "@neondatabase/neon-js/ui/tailwind";
+```
+
+```typescript
+/* Without Tailwind */
+import "@neondatabase/neon-js/ui/css";
+```
+
+### Missing "use client" directive
+
+Required for any component using `useSession()` or other React hooks:
+
+```typescript
+"use client"; // Required!
+import { authClient } from "@/lib/auth/client";
+```
+
+### Wrong API for adapter type
+
+| Adapter | Sign In | Sign Up |
+| ---------------------- | ----------------------------------------- | ----------------------------------- |
+| BetterAuthReactAdapter | `signIn.email({ email, password })` | `signUp.email({ email, password })` |
+| SupabaseAuthAdapter | `signInWithPassword({ email, password })` | `signUp({ email, password })` |
diff --git a/.cursor/skills/neon-postgres/references/neon-python-sdk.md b/.cursor/skills/neon-postgres/references/neon-python-sdk.md
new file mode 100644
index 00000000..76a2c613
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/neon-python-sdk.md
@@ -0,0 +1,101 @@
+# Neon Python SDK
+
+The `neon-api` Python SDK is a Pythonic wrapper around the Neon REST API for managing Neon resources programmatically.
+
+For core concepts (Organization, Project, Branch, Endpoint, etc.), see `what-is-neon.md`.
+
+See the [official Python SDK docs](https://neon.com/docs/reference/python-sdk.md) for complete details.
+
+## Installation
+
+```bash
+pip install neon-api
+```
+
+## Authentication
+
+```python
+import os
+from neon_api import NeonAPI
+
+neon = NeonAPI(api_key=os.environ["NEON_API_KEY"])
+```
+
+## Org-Aware Workflow
+
+All Neon accounts are organization-based. Discover the user's org first, then pass `org_id` to project operations:
+
+```python
+# 1. Get the user's organizations
+orgs = neon.current_user_organizations()
+org_id = orgs[0].id
+
+# 2. List projects within the org
+projects = neon.projects(org_id=org_id)
+```
+
+## Method Quick Reference
+
+### Projects
+
+| Operation | Method |
+| ------------------ | ------------------------------------------------------------------------------- |
+| List projects | `neon.projects(org_id=...)` |
+| Create project | `neon.project_create(project={ 'name': ..., 'pg_version': 17, 'org_id': ... })` |
+| Get project | `neon.project(project_id=...)` |
+| Update project | `neon.project_update(project_id=..., project={...})` |
+| Delete project | `neon.project_delete(project_id=...)` |
+| Get connection URI | `neon.connection_uri(project_id=..., database_name=..., role_name=...)` |
+
+### Branches
+
+| Operation | Method |
+| ------------- | ------------------------------------------------------------------- |
+| Create branch | `neon.branch_create(project_id=..., branch={...}, endpoints=[...])` |
+| List branches | `neon.branches(project_id=...)` |
+| Get branch | `neon.branch(project_id=..., branch_id=...)` |
+| Update branch | `neon.branch_update(project_id=..., branch_id=..., branch={...})` |
+| Delete branch | `neon.branch_delete(project_id=..., branch_id=...)` |
+
+### Databases
+
+| Operation | Method |
+| --------------- | ---------------------------------------------------------------------- |
+| Create database | `neon.database_create(project_id=..., branch_id=..., database={...})` |
+| List databases | `neon.databases(project_id=..., branch_id=...)` |
+| Delete database | `neon.database_delete(project_id=..., branch_id=..., database_id=...)` |
+
+### Roles
+
+| Operation | Method |
+| ----------- | ---------------------------------------------------------------- |
+| Create role | `neon.role_create(project_id=..., branch_id=..., role_name=...)` |
+| List roles | `neon.roles(project_id=..., branch_id=...)` |
+| Delete role | `neon.role_delete(project_id=..., branch_id=..., role_name=...)` |
+
+### Endpoints
+
+| Operation | Method |
+| ---------------- | ----------------------------------------------------------------------- |
+| Create endpoint | `neon.endpoint_create(project_id=..., endpoint={...})` |
+| Start endpoint | `neon.endpoint_start(project_id=..., endpoint_id=...)` |
+| Suspend endpoint | `neon.endpoint_suspend(project_id=..., endpoint_id=...)` |
+| Update endpoint | `neon.endpoint_update(project_id=..., endpoint_id=..., endpoint={...})` |
+| Delete endpoint | `neon.endpoint_delete(project_id=..., endpoint_id=...)` |
+
+### Organizations
+
+| Operation | Method |
+| -------------- | ----------------------------------- |
+| List user orgs | `neon.current_user_organizations()` |
+| Get org | `neon.organization(org_id=...)` |
+
+### API Keys & Operations
+
+| Operation | Method |
+| --------------- | -------------------------------------------------- |
+| List API keys | `neon.api_keys()` |
+| Create API key | `neon.api_key_create(key_name=...)` |
+| Revoke API key | `neon.api_key_revoke(key_id)` |
+| List operations | `neon.operations(project_id=...)` |
+| Get operation | `neon.operation(project_id=..., operation_id=...)` |
diff --git a/.cursor/skills/neon-postgres/references/neon-rest-api.md b/.cursor/skills/neon-postgres/references/neon-rest-api.md
new file mode 100644
index 00000000..4a33f97d
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/neon-rest-api.md
@@ -0,0 +1,73 @@
+# Neon REST API
+
+Essentials for making direct HTTP requests to the Neon Platform API.
+
+See the [official API reference](https://neon.com/docs/reference/api-reference.md) and [interactive explorer](https://api-docs.neon.tech/reference/getting-started-with-neon-api) for complete details. The full [OpenAPI spec](https://neon.com/api_spec/release/v2.json) is available for programmatic lookup of exact endpoints, request/response schemas, and required fields.
+
+## Base URL
+
+```
+https://console.neon.tech/api/v2/
+```
+
+## Authentication
+
+Include a Neon API key in every request:
+
+```
+Authorization: Bearer $NEON_API_KEY
+```
+
+### API Key Types
+
+| Type | Scope | Best For |
+| -------------- | ------------------------------- | ----------------------------- |
+| Personal | All projects user has access to | Individual use, scripting |
+| Organization | Entire organization | CI/CD, org-wide automation |
+| Project-scoped | Single project only | Project-specific integrations |
+
+## Rate Limits
+
+- 700 requests/minute (~11/second)
+- Bursts up to 40 requests/second per route
+- Handle `429 Too Many Requests` with retry + backoff
+
+## Common Endpoints
+
+| Operation | Method | Path |
+| ------------------ | -------- | -------------------------------------------------------- |
+| List projects | `GET` | `/projects?org_id={org_id}` |
+| List user orgs | `GET` | `/users/me/organizations` |
+| Create project | `POST` | `/projects` (include `org_id` in body) |
+| Get connection URI | `GET` | `/projects/{project_id}/connection_uri` |
+| Create branch | `POST` | `/projects/{project_id}/branches` |
+| List branches | `GET` | `/projects/{project_id}/branches` |
+| Delete branch | `DELETE` | `/projects/{project_id}/branches/{branch_id}` |
+| Start endpoint | `POST` | `/projects/{project_id}/endpoints/{endpoint_id}/start` |
+| Suspend endpoint | `POST` | `/projects/{project_id}/endpoints/{endpoint_id}/suspend` |
+| List databases | `GET` | `/projects/{project_id}/branches/{branch_id}/databases` |
+| Create database | `POST` | `/projects/{project_id}/branches/{branch_id}/databases` |
+| List roles | `GET` | `/projects/{project_id}/branches/{branch_id}/roles` |
+| List API keys | `GET` | `/api_keys` |
+| List operations | `GET` | `/projects/{project_id}/operations` |
+
+## Important Constraints
+
+- You **cannot delete** a project's root or default branch
+- You **cannot delete** a branch that has child branches — delete all children first
+- Creating a new role may **drop existing connections** to the active compute endpoint
+- A branch can have only one `read_write` endpoint but multiple `read_only` endpoints
+- Operations are async — poll operation status before starting dependent operations
+- Operations older than 6 months may be deleted from Neon's systems
+- The first API key must be created from the [Neon Console](https://console.neon.tech/app/settings/api-keys); subsequent keys can be created via the API
+
+## Error Codes
+
+| Status | Meaning | Action |
+| ------ | ------------ | ------------------------ |
+| 401 | Unauthorized | Check API key |
+| 404 | Not Found | Verify resource ID |
+| 429 | Rate Limited | Retry with backoff |
+| 500 | Server Error | Retry or contact support |
+
+For TypeScript SDK usage, see `neon-typescript-sdk.md`. For Python SDK, see `neon-python-sdk.md`.
diff --git a/.cursor/skills/neon-postgres/references/neon-serverless.md b/.cursor/skills/neon-postgres/references/neon-serverless.md
new file mode 100644
index 00000000..e9897d76
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/neon-serverless.md
@@ -0,0 +1,250 @@
+# Neon Serverless Driver
+
+Patterns and best practices for connecting to Neon databases in serverless environments using the `@neondatabase/serverless` driver. The driver connects over **HTTP** for fast, single queries or **WebSockets** for `node-postgres` compatibility and interactive transactions.
+
+See the [official serverless driver docs](https://neon.com/docs/serverless/serverless-driver.md) for complete details.
+
+## Installation
+
+```bash
+# Using npm
+npm install @neondatabase/serverless
+
+# Using JSR
+bunx jsr add @neon/serverless
+```
+
+**Note:** Version 1.0.0+ requires **Node.js v19 or later**.
+
+For projects that depend on `pg` but want to use Neon's WebSocket-based connection pool:
+
+```json
+"dependencies": {
+ "pg": "npm:@neondatabase/serverless@^0.10.4"
+},
+"overrides": {
+ "pg": "npm:@neondatabase/serverless@^0.10.4"
+}
+```
+
+## Connection String
+
+Always use environment variables:
+
+```typescript
+// For HTTP queries
+import { neon } from "@neondatabase/serverless";
+const sql = neon(process.env.DATABASE_URL!);
+
+// For WebSocket connections
+import { Pool } from "@neondatabase/serverless";
+const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+```
+
+**Never hardcode credentials:**
+
+```typescript
+// AVOID
+const sql = neon("postgres://username:password@host.neon.tech/neondb");
+```
+
+## HTTP Queries with `neon` function
+
+Ideal for simple, "one-shot" queries in serverless/edge environments. Uses HTTP `fetch` - fastest method for single queries.
+
+### Parameterized Queries
+
+Use tagged template literals for safe parameter interpolation:
+
+```typescript
+const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
+```
+
+For manually constructed queries:
+
+```typescript
+const [post] = await sql.query("SELECT * FROM posts WHERE id = $1", [postId]);
+```
+
+**Never concatenate user input:**
+
+```typescript
+// AVOID: SQL Injection Risk
+const [post] = await sql("SELECT * FROM posts WHERE id = " + postId);
+```
+
+### Configuration Options
+
+```typescript
+// Return rows as arrays instead of objects
+const sqlArrayMode = neon(process.env.DATABASE_URL!, { arrayMode: true });
+const rows = await sqlArrayMode`SELECT id, title FROM posts`;
+// rows -> [[1, "First Post"], [2, "Second Post"]]
+
+// Get full results including row count and field metadata
+const sqlFull = neon(process.env.DATABASE_URL!, { fullResults: true });
+const result = await sqlFull`SELECT * FROM posts LIMIT 1`;
+// result -> { rows: [...], fields: [...], rowCount: 1, ... }
+```
+
+## WebSocket Connections with `Pool` and `Client`
+
+Use for `node-postgres` compatibility, interactive transactions, or session support.
+
+### WebSocket Configuration
+
+For Node.js v21 and earlier:
+
+```typescript
+import { Pool, neonConfig } from "@neondatabase/serverless";
+import ws from "ws";
+
+// Required for Node.js < v22
+neonConfig.webSocketConstructor = ws;
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+```
+
+### Serverless Lifecycle Management
+
+Create, use, and close the pool within the same invocation:
+
+```typescript
+// Vercel Edge Functions example
+export default async (req: Request, ctx: ExecutionContext) => {
+ const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+
+ try {
+ const { rows } = await pool.query("SELECT * FROM users");
+ return new Response(JSON.stringify(rows));
+ } catch (err) {
+ console.error(err);
+ return new Response("Database error", { status: 500 });
+ } finally {
+ ctx.waitUntil(pool.end());
+ }
+};
+```
+
+**Avoid** creating a global `Pool` instance outside the handler.
+
+## Transactions
+
+### HTTP Transactions
+
+For running multiple queries in a single, non-interactive transaction:
+
+```typescript
+const [newUser, newProfile] = await sql.transaction(
+ [
+ sql`INSERT INTO users(name) VALUES(${name}) RETURNING id`,
+ sql`INSERT INTO profiles(user_id, bio) VALUES(${userId}, ${bio})`,
+ ],
+ {
+ isolationLevel: "ReadCommitted",
+ readOnly: false,
+ },
+);
+```
+
+### Interactive Transactions
+
+For complex transactions with conditional logic:
+
+```typescript
+const pool = new Pool({ connectionString: process.env.DATABASE_URL! });
+const client = await pool.connect();
+try {
+ await client.query("BEGIN");
+ const {
+ rows: [{ id }],
+ } = await client.query("INSERT INTO users(name) VALUES($1) RETURNING id", [
+ name,
+ ]);
+ await client.query("INSERT INTO profiles(user_id, bio) VALUES($1, $2)", [
+ id,
+ bio,
+ ]);
+ await client.query("COMMIT");
+} catch (err) {
+ await client.query("ROLLBACK");
+ throw err;
+} finally {
+ client.release();
+ await pool.end();
+}
+```
+
+## Environment-Specific Optimizations
+
+```javascript
+// For Vercel Edge Functions, specify nearest region
+export const config = {
+ runtime: "edge",
+ regions: ["iad1"], // Region nearest to your Neon DB
+};
+
+// For Cloudflare Workers, consider using Hyperdrive
+// https://neon.com/blog/hyperdrive-neon-faq
+```
+
+## ORM Integration
+
+For Drizzle ORM integration with the serverless driver, see `neon-drizzle.md`.
+
+### Prisma
+
+```typescript
+import { neonConfig } from "@neondatabase/serverless";
+import { PrismaNeon, PrismaNeonHTTP } from "@prisma/adapter-neon";
+import { PrismaClient } from "@prisma/client";
+import ws from "ws";
+
+const connectionString = process.env.DATABASE_URL;
+neonConfig.webSocketConstructor = ws;
+
+// HTTP adapter
+const adapterHttp = new PrismaNeonHTTP(connectionString!, {});
+export const prismaClientHttp = new PrismaClient({ adapter: adapterHttp });
+
+// WebSocket adapter
+const adapterWs = new PrismaNeon({ connectionString });
+export const prismaClientWs = new PrismaClient({ adapter: adapterWs });
+```
+
+### Kysely
+
+```typescript
+import { Pool } from "@neondatabase/serverless";
+import { Kysely, PostgresDialect } from "kysely";
+
+const dialect = new PostgresDialect({
+ pool: new Pool({ connectionString: process.env.DATABASE_URL }),
+});
+
+const db = new Kysely({ dialect });
+```
+
+**NOTE:** Do not pass the `neon()` function to ORMs that expect a `node-postgres` compatible `Pool`.
+
+## Error Handling
+
+```javascript
+// Pool error handling
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+pool.on("error", (err) => {
+ console.error("Unexpected error on idle client", err);
+ process.exit(-1);
+});
+
+// Query error handling
+try {
+ const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
+ if (!post) {
+ return new Response("Not found", { status: 404 });
+ }
+} catch (err) {
+ console.error("Database query failed:", err);
+ return new Response("Server error", { status: 500 });
+}
+```
diff --git a/.cursor/skills/neon-postgres/references/neon-typescript-sdk.md b/.cursor/skills/neon-postgres/references/neon-typescript-sdk.md
new file mode 100644
index 00000000..8dbdb8ec
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/neon-typescript-sdk.md
@@ -0,0 +1,135 @@
+# Neon TypeScript SDK
+
+The `@neondatabase/api-client` TypeScript SDK is a typed wrapper around the Neon REST API for managing Neon resources programmatically.
+
+For core concepts (Organization, Project, Branch, Endpoint, etc.), see `what-is-neon.md`.
+
+See the [official TypeScript SDK docs](https://neon.com/docs/reference/typescript-sdk.md) for complete details.
+
+## Installation
+
+```bash
+npm install @neondatabase/api-client
+```
+
+## Authentication
+
+```typescript
+import { createApiClient } from "@neondatabase/api-client";
+
+const apiClient = createApiClient({ apiKey: process.env.NEON_API_KEY! });
+```
+
+## Org-Aware Workflow
+
+All Neon accounts are organization-based. You must discover the user's org first, then pass `org_id` to project operations:
+
+```typescript
+// 1. Get the user's organizations
+const { data: orgs } = await apiClient.getCurrentUserOrganizations();
+const orgId = orgs.organizations[0].id;
+
+// 2. List projects within the org
+const { data: projects } = await apiClient.listProjects({ org_id: orgId });
+```
+
+## Method Quick Reference
+
+### Projects
+
+| Operation | Method |
+| ------------------ | ------------------------------------------------------------------------------- |
+| List projects | `apiClient.listProjects({ org_id })` |
+| Create project | `apiClient.createProject({ project: { name, pg_version, region_id, org_id } })` |
+| Get project | `apiClient.getProject(projectId)` |
+| Update project | `apiClient.updateProject(projectId, { project: { name } })` |
+| Delete project | `apiClient.deleteProject(projectId)` |
+| Get connection URI | `apiClient.getConnectionUri({ projectId, database_name, role_name, pooled })` |
+
+### Branches
+
+| Operation | Method |
+| ------------- | --------------------------------------------------------------------------------------- |
+| Create branch | `apiClient.createProjectBranch(projectId, { branch: { name }, endpoints: [{ type }] })` |
+| List branches | `apiClient.listProjectBranches({ projectId })` |
+| Get branch | `apiClient.getProjectBranch(projectId, branchId)` |
+| Update branch | `apiClient.updateProjectBranch(projectId, branchId, { branch: { name } })` |
+| Delete branch | `apiClient.deleteProjectBranch(projectId, branchId)` |
+
+### Databases
+
+| Operation | Method |
+| --------------- | ------------------------------------------------------------------------------------------------ |
+| Create database | `apiClient.createProjectBranchDatabase(projectId, branchId, { database: { name, owner_name } })` |
+| List databases | `apiClient.listProjectBranchDatabases(projectId, branchId)` |
+| Delete database | `apiClient.deleteProjectBranchDatabase(projectId, branchId, databaseName)` |
+
+### Roles
+
+| Operation | Method |
+| ----------- | ---------------------------------------------------------------------------- |
+| Create role | `apiClient.createProjectBranchRole(projectId, branchId, { role: { name } })` |
+| List roles | `apiClient.listProjectBranchRoles(projectId, branchId)` |
+| Delete role | `apiClient.deleteProjectBranchRole(projectId, branchId, roleName)` |
+
+### Endpoints
+
+| Operation | Method |
+| ---------------- | ------------------------------------------------------------------------------- |
+| Create endpoint | `apiClient.createProjectEndpoint(projectId, { endpoint: { branch_id, type } })` |
+| List endpoints | `apiClient.listProjectEndpoints(projectId)` |
+| Start endpoint | `apiClient.startProjectEndpoint(projectId, endpointId)` |
+| Suspend endpoint | `apiClient.suspendProjectEndpoint(projectId, endpointId)` |
+| Restart endpoint | `apiClient.restartProjectEndpoint(projectId, endpointId)` |
+| Update endpoint | `apiClient.updateProjectEndpoint(projectId, endpointId, { endpoint: {...} })` |
+| Delete endpoint | `apiClient.deleteProjectEndpoint(projectId, endpointId)` |
+
+### API Keys
+
+| Operation | Method |
+| ---------- | -------------------------------------- |
+| List keys | `apiClient.listApiKeys()` |
+| Create key | `apiClient.createApiKey({ key_name })` |
+| Revoke key | `apiClient.revokeApiKey(keyId)` |
+
+### Operations
+
+| Operation | Method |
+| --------------- | ------------------------------------------------------- |
+| List operations | `apiClient.listProjectOperations({ projectId })` |
+| Get operation | `apiClient.getProjectOperation(projectId, operationId)` |
+
+### Organizations
+
+| Operation | Method |
+| -------------- | ------------------------------------------------------------------------ |
+| List user orgs | `apiClient.getCurrentUserOrganizations()` |
+| Get org | `apiClient.getOrganization(orgId)` |
+| List members | `apiClient.getOrganizationMembers(orgId)` |
+| Create org key | `apiClient.createOrgApiKey(orgId, { key_name, project_id? })` |
+| Invite member | `apiClient.createOrganizationInvitations(orgId, { invitations: [...] })` |
+
+## Error Handling
+
+```typescript
+try {
+ const response = await apiClient.getProject(projectId);
+ return response.data;
+} catch (error: any) {
+ if (error.isAxiosError) {
+ const status = error.response?.status;
+ // 401 = bad API key, 404 = not found, 429 = rate limited
+ console.error("API error:", status, error.response?.data?.message);
+ }
+ return null;
+}
+```
+
+## Key Types
+
+```typescript
+import { EndpointType, MemberRole } from "@neondatabase/api-client";
+
+// EndpointType.ReadWrite, EndpointType.ReadOnly
+// MemberRole.Admin, MemberRole.Member
+```
diff --git a/.cursor/skills/neon-postgres/references/what-is-neon.md b/.cursor/skills/neon-postgres/references/what-is-neon.md
new file mode 100644
index 00000000..b2d8ba7c
--- /dev/null
+++ b/.cursor/skills/neon-postgres/references/what-is-neon.md
@@ -0,0 +1,40 @@
+# What is Neon
+
+Neon is a serverless Postgres platform that separates compute and storage to offer autoscaling, branching, instant restore, and scale-to-zero.
+
+See the [official introduction](https://neon.com/docs/introduction.md) for complete details.
+
+## Core Concepts
+
+| Concept | Description | Key Relationship |
+| ---------------- | --------------------------------------------------------------------- | ------------------------- |
+| Organization | Highest-level container for billing, users, and projects | Contains Projects |
+| Project | Primary container for all database resources for an application | Contains Branches |
+| Branch | Lightweight, copy-on-write clone of database state | Contains Databases, Roles |
+| Compute Endpoint | Running PostgreSQL instance (CPU/RAM for queries) | Attached to a Branch |
+| Database | Logical container for data (tables, schemas, views) | Exists within a Branch |
+| Role | PostgreSQL role for authentication and authorization | Belongs to a Branch |
+| Operation | Async action by the control plane (creating branch, starting compute) | Associated with Project |
+
+## Key Differentiators
+
+1. **Serverless Architecture**: Compute scales automatically and can suspend when idle
+2. **Branching**: Create instant database copies without duplicating storage
+3. **Separation of Compute and Storage**: Pay for compute only when active
+4. **Postgres Compatible**: Works with any Postgres driver, ORM, or tool
+
+## When to Use Neon
+
+- **Serverless applications**: Functions that need database access without managing connections
+- **Development workflows**: Branch databases like code for isolated testing
+- **Variable workloads**: Auto-scale during traffic spikes, scale to zero when idle
+- **Cost optimization**: Pay only for active compute time and storage used
+
+## Further Reading
+
+| Topic | URL |
+| ---------------------- | ----------------------------------------------------------- |
+| Architecture | https://neon.com/docs/introduction/architecture-overview.md |
+| Plans & Billing | https://neon.com/docs/introduction/about-billing.md |
+| Regions | https://neon.com/docs/introduction/regions.md |
+| Postgres Compatibility | https://neon.com/docs/reference/compatibility.md |
diff --git a/.cursor/skills/plugin-manager/SKILL.md b/.cursor/skills/plugin-manager/SKILL.md
new file mode 100644
index 00000000..2e55aa64
--- /dev/null
+++ b/.cursor/skills/plugin-manager/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: plugin-manager
+description: Manage plugin structure and configuration for this repository across both Cursor and Claude Code. Use when creating, updating, or reviewing plugin folders under plugins/, wiring marketplace manifests, setting up skill symlinks, assigning per-plugin mcp.json files, or adding additional plugins while preserving repo conventions.
+---
+
+# Plugin Manager
+
+Maintain plugin packaging for both ecosystems in a single repository, using a shared `plugins/` directory and a shared top-level `skills/` source of truth.
+
+## Working Rules
+
+- Keep each plugin self-contained in `plugins//`.
+- Keep shared reusable skill content in top-level `skills/`.
+- Expose shared skills per plugin via symlinks in `plugins//skills/`.
+- Keep MCP config plugin-local at `plugins//mcp.json`.
+- Keep both marketplace manifests at repo root:
+ - `.claude-plugin/marketplace.json`
+ - `.cursor-plugin/marketplace.json`
+
+## Required Plugin Layout
+
+For every plugin, ensure this layout exists:
+
+```text
+plugins//
+ .claude-plugin/plugin.json
+ .cursor-plugin/plugin.json
+ skills/
+ -> ../../../skills/ # symlink
+ mcp.json
+ assets/
+```
+
+## Create or Update a Plugin
+
+1. Create `plugins//`.
+2. Add both manifests:
+ - `plugins//.claude-plugin/plugin.json`
+ - `plugins//.cursor-plugin/plugin.json`
+3. Add or update `plugins//mcp.json` for plugin-specific MCP servers.
+4. Symlink required top-level skills into `plugins//skills/`.
+5. Add `plugins//assets/logo.svg` for Cursor.
+6. Register plugin in both marketplaces using `source: "./plugins/"`.
+7. Validate JSON and path references before finishing.
+
+## Manifest Guidelines
+
+- **Claude plugin manifest**
+ - Path: `plugins//.claude-plugin/plugin.json`
+ - Prefer plugin-local relative paths, for example:
+ - `"skills": "./skills/"`
+ - `"mcpServers": "./mcp.json"`
+- **Cursor plugin manifest**
+ - Path: `plugins//.cursor-plugin/plugin.json`
+ - Prefer plugin-local relative paths, for example:
+ - `"skills": "./skills/"`
+ - `"mcpServers": "./mcp.json"`
+ - `"logo": "assets/logo.svg"`
+- **Marketplace manifests**
+ - `.claude-plugin/marketplace.json` uses `source: "./plugins/"`.
+ - `.cursor-plugin/marketplace.json` uses `metadata.pluginRoot: "plugins"` and plugin entries with `source: ""`.
+
+## References
+
+- For detailed examples and checklists, read `references/plugin-guidelines.md`.
diff --git a/.cursor/skills/plugin-manager/references/plugin-guidelines.md b/.cursor/skills/plugin-manager/references/plugin-guidelines.md
new file mode 100644
index 00000000..f18bd6a6
--- /dev/null
+++ b/.cursor/skills/plugin-manager/references/plugin-guidelines.md
@@ -0,0 +1,57 @@
+# Plugin Guidelines
+
+## Current Repository Structure
+
+```text
+.agents/skills/
+ plugin-manager/
+ skill-creator/
+
+skills/
+ neon-postgres/
+
+plugins/
+ neon-postgres/
+ .claude-plugin/plugin.json
+ .cursor-plugin/plugin.json
+ skills/
+ neon-postgres -> ../../../skills/neon-postgres
+ mcp.json
+ assets/logo.svg
+
+.claude-plugin/marketplace.json
+.cursor-plugin/marketplace.json
+```
+
+## Why This Structure
+
+- Plugin files are co-located per plugin, making ownership and boundaries clear.
+- Reusable skill content stays top-level in `skills/` and is reused via symlink.
+- Each plugin can own its own MCP configuration in `plugins//mcp.json`.
+- Marketplace manifests remain centralized at repo root.
+
+## Create an Additional Plugin
+
+1. Create `plugins//` with:
+ - `.claude-plugin/plugin.json`
+ - `.cursor-plugin/plugin.json`
+ - `skills/` directory
+ - optional `assets/` directory
+2. Add plugin-local MCP config:
+ - `plugins//mcp.json`
+3. Symlink required skills:
+ - `plugins//skills/ -> ../../../skills/`
+4. Add plugin to both marketplaces:
+ - `.claude-plugin/marketplace.json`: `source: "./plugins/"`
+ - `.cursor-plugin/marketplace.json`: with `pluginRoot: "plugins"`, use `source: ""`
+5. Verify paths in both plugin manifests are plugin-local and relative:
+ - `skills: "./skills/"`
+ - `mcpServers: "./mcp.json"`
+ - Cursor logo path, if used: `assets/logo.svg`
+
+## Guardrails
+
+- Do not duplicate shared skills into plugin folders; always symlink.
+- Do not reference paths outside plugin roots in manifest fields.
+- Keep plugin names kebab-case and consistent between marketplace and plugin manifests.
+- Keep Cursor marketplace `pluginRoot` and `source` consistent to avoid double-prefix path resolution errors.
diff --git a/.cursor/skills/skill-creator/LICENSE.txt b/.cursor/skills/skill-creator/LICENSE.txt
new file mode 100644
index 00000000..7a4a3ea2
--- /dev/null
+++ b/.cursor/skills/skill-creator/LICENSE.txt
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
\ No newline at end of file
diff --git a/.cursor/skills/skill-creator/SKILL.md b/.cursor/skills/skill-creator/SKILL.md
new file mode 100644
index 00000000..913b0ea4
--- /dev/null
+++ b/.cursor/skills/skill-creator/SKILL.md
@@ -0,0 +1,356 @@
+---
+name: skill-creator
+description: Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+license: Complete terms in LICENSE.txt
+---
+
+# Skill Creator
+
+This skill provides guidance for creating effective skills.
+
+## About Skills
+
+Skills are modular, self-contained packages that extend Claude's capabilities by providing
+specialized knowledge, workflows, and tools. Think of them as "onboarding guides" for specific
+domains or tasks—they transform Claude from a general-purpose agent into a specialized agent
+equipped with procedural knowledge that no model can fully possess.
+
+### What Skills Provide
+
+1. Specialized workflows - Multi-step procedures for specific domains
+2. Tool integrations - Instructions for working with specific file formats or APIs
+3. Domain expertise - Company-specific knowledge, schemas, business logic
+4. Bundled resources - Scripts, references, and assets for complex and repetitive tasks
+
+## Core Principles
+
+### Concise is Key
+
+The context window is a public good. Skills share the context window with everything else Claude needs: system prompt, conversation history, other Skills' metadata, and the actual user request.
+
+**Default assumption: Claude is already very smart.** Only add context Claude doesn't already have. Challenge each piece of information: "Does Claude really need this explanation?" and "Does this paragraph justify its token cost?"
+
+Prefer concise examples over verbose explanations.
+
+### Set Appropriate Degrees of Freedom
+
+Match the level of specificity to the task's fragility and variability:
+
+**High freedom (text-based instructions)**: Use when multiple approaches are valid, decisions depend on context, or heuristics guide the approach.
+
+**Medium freedom (pseudocode or scripts with parameters)**: Use when a preferred pattern exists, some variation is acceptable, or configuration affects behavior.
+
+**Low freedom (specific scripts, few parameters)**: Use when operations are fragile and error-prone, consistency is critical, or a specific sequence must be followed.
+
+Think of Claude as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom), while an open field allows many routes (high freedom).
+
+### Anatomy of a Skill
+
+Every skill consists of a required SKILL.md file and optional bundled resources:
+
+```
+skill-name/
+├── SKILL.md (required)
+│ ├── YAML frontmatter metadata (required)
+│ │ ├── name: (required)
+│ │ ├── description: (required)
+│ │ └── compatibility: (optional, rarely needed)
+│ └── Markdown instructions (required)
+└── Bundled Resources (optional)
+ ├── scripts/ - Executable code (Python/Bash/etc.)
+ ├── references/ - Documentation intended to be loaded into context as needed
+ └── assets/ - Files used in output (templates, icons, fonts, etc.)
+```
+
+#### SKILL.md (required)
+
+Every SKILL.md consists of:
+
+- **Frontmatter** (YAML): Contains `name` and `description` fields (required), plus optional fields like `license`, `metadata`, and `compatibility`. Only `name` and `description` are read by Claude to determine when the skill triggers, so be clear and comprehensive about what the skill is and when it should be used. The `compatibility` field is for noting environment requirements (target product, system packages, etc.) but most skills don't need it.
+- **Body** (Markdown): Instructions and guidance for using the skill. Only loaded AFTER the skill triggers (if at all).
+
+#### Bundled Resources (optional)
+
+##### Scripts (`scripts/`)
+
+Executable code (Python/Bash/etc.) for tasks that require deterministic reliability or are repeatedly rewritten.
+
+- **When to include**: When the same code is being rewritten repeatedly or deterministic reliability is needed
+- **Example**: `scripts/rotate_pdf.py` for PDF rotation tasks
+- **Benefits**: Token efficient, deterministic, may be executed without loading into context
+- **Note**: Scripts may still need to be read by Claude for patching or environment-specific adjustments
+
+##### References (`references/`)
+
+Documentation and reference material intended to be loaded as needed into context to inform Claude's process and thinking.
+
+- **When to include**: For documentation that Claude should reference while working
+- **Examples**: `references/finance.md` for financial schemas, `references/mnda.md` for company NDA template, `references/policies.md` for company policies, `references/api_docs.md` for API specifications
+- **Use cases**: Database schemas, API documentation, domain knowledge, company policies, detailed workflow guides
+- **Benefits**: Keeps SKILL.md lean, loaded only when Claude determines it's needed
+- **Best practice**: If files are large (>10k words), include grep search patterns in SKILL.md
+- **Avoid duplication**: Information should live in either SKILL.md or references files, not both. Prefer references files for detailed information unless it's truly core to the skill—this keeps SKILL.md lean while making information discoverable without hogging the context window. Keep only essential procedural instructions and workflow guidance in SKILL.md; move detailed reference material, schemas, and examples to references files.
+
+##### Assets (`assets/`)
+
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+- **When to include**: When the skill needs files that will be used in the final output
+- **Examples**: `assets/logo.png` for brand assets, `assets/slides.pptx` for PowerPoint templates, `assets/frontend-template/` for HTML/React boilerplate, `assets/font.ttf` for typography
+- **Use cases**: Templates, images, icons, boilerplate code, fonts, sample documents that get copied or modified
+- **Benefits**: Separates output resources from documentation, enables Claude to use files without loading them into context
+
+#### What to Not Include in a Skill
+
+A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files, including:
+
+- README.md
+- INSTALLATION_GUIDE.md
+- QUICK_REFERENCE.md
+- CHANGELOG.md
+- etc.
+
+The skill should only contain the information needed for an AI agent to do the job at hand. It should not contain auxilary context about the process that went into creating it, setup and testing procedures, user-facing documentation, etc. Creating additional documentation files just adds clutter and confusion.
+
+### Progressive Disclosure Design Principle
+
+Skills use a three-level loading system to manage context efficiently:
+
+1. **Metadata (name + description)** - Always in context (~100 words)
+2. **SKILL.md body** - When skill triggers (<5k words)
+3. **Bundled resources** - As needed by Claude (Unlimited because scripts can be executed without reading into context window)
+
+#### Progressive Disclosure Patterns
+
+Keep SKILL.md body to the essentials and under 500 lines to minimize context bloat. Split content into separate files when approaching this limit. When splitting out content into other files, it is very important to reference them from SKILL.md and describe clearly when to read them, to ensure the reader of the skill knows they exist and when to use them.
+
+**Key principle:** When a skill supports multiple variations, frameworks, or options, keep only the core workflow and selection guidance in SKILL.md. Move variant-specific details (patterns, examples, configuration) into separate reference files.
+
+**Pattern 1: High-level guide with references**
+
+```markdown
+# PDF Processing
+
+## Quick start
+
+Extract text with pdfplumber:
+[code example]
+
+## Advanced features
+
+- **Form filling**: See [FORMS.md](FORMS.md) for complete guide
+- **API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
+- **Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns
+```
+
+Claude loads FORMS.md, REFERENCE.md, or EXAMPLES.md only when needed.
+
+**Pattern 2: Domain-specific organization**
+
+For Skills with multiple domains, organize content by domain to avoid loading irrelevant context:
+
+```
+bigquery-skill/
+├── SKILL.md (overview and navigation)
+└── reference/
+ ├── finance.md (revenue, billing metrics)
+ ├── sales.md (opportunities, pipeline)
+ ├── product.md (API usage, features)
+ └── marketing.md (campaigns, attribution)
+```
+
+When a user asks about sales metrics, Claude only reads sales.md.
+
+Similarly, for skills supporting multiple frameworks or variants, organize by variant:
+
+```
+cloud-deploy/
+├── SKILL.md (workflow + provider selection)
+└── references/
+ ├── aws.md (AWS deployment patterns)
+ ├── gcp.md (GCP deployment patterns)
+ └── azure.md (Azure deployment patterns)
+```
+
+When the user chooses AWS, Claude only reads aws.md.
+
+**Pattern 3: Conditional details**
+
+Show basic content, link to advanced content:
+
+```markdown
+# DOCX Processing
+
+## Creating documents
+
+Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).
+
+## Editing documents
+
+For simple edits, modify the XML directly.
+
+**For tracked changes**: See [REDLINING.md](REDLINING.md)
+**For OOXML details**: See [OOXML.md](OOXML.md)
+```
+
+Claude reads REDLINING.md or OOXML.md only when the user needs those features.
+
+**Important guidelines:**
+
+- **Avoid deeply nested references** - Keep references one level deep from SKILL.md. All reference files should link directly from SKILL.md.
+- **Structure longer reference files** - For files longer than 100 lines, include a table of contents at the top so Claude can see the full scope when previewing.
+
+## Skill Creation Process
+
+Skill creation involves these steps:
+
+1. Understand the skill with concrete examples
+2. Plan reusable skill contents (scripts, references, assets)
+3. Initialize the skill (run init_skill.py)
+4. Edit the skill (implement resources and write SKILL.md)
+5. Package the skill (run package_skill.py)
+6. Iterate based on real usage
+
+Follow these steps in order, skipping only if there is a clear reason why they are not applicable.
+
+### Step 1: Understanding the Skill with Concrete Examples
+
+Skip this step only when the skill's usage patterns are already clearly understood. It remains valuable even when working with an existing skill.
+
+To create an effective skill, clearly understand concrete examples of how the skill will be used. This understanding can come from either direct user examples or generated examples that are validated with user feedback.
+
+For example, when building an image-editor skill, relevant questions include:
+
+- "What functionality should the image-editor skill support? Editing, rotating, anything else?"
+- "Can you give some examples of how this skill would be used?"
+- "I can imagine users asking for things like 'Remove the red-eye from this image' or 'Rotate this image'. Are there other ways you imagine this skill being used?"
+- "What would a user say that should trigger this skill?"
+
+To avoid overwhelming users, avoid asking too many questions in a single message. Start with the most important questions and follow up as needed for better effectiveness.
+
+Conclude this step when there is a clear sense of the functionality the skill should support.
+
+### Step 2: Planning the Reusable Skill Contents
+
+To turn concrete examples into an effective skill, analyze each example by:
+
+1. Considering how to execute on the example from scratch
+2. Identifying what scripts, references, and assets would be helpful when executing these workflows repeatedly
+
+Example: When building a `pdf-editor` skill to handle queries like "Help me rotate this PDF," the analysis shows:
+
+1. Rotating a PDF requires re-writing the same code each time
+2. A `scripts/rotate_pdf.py` script would be helpful to store in the skill
+
+Example: When designing a `frontend-webapp-builder` skill for queries like "Build me a todo app" or "Build me a dashboard to track my steps," the analysis shows:
+
+1. Writing a frontend webapp requires the same boilerplate HTML/React each time
+2. An `assets/hello-world/` template containing the boilerplate HTML/React project files would be helpful to store in the skill
+
+Example: When building a `big-query` skill to handle queries like "How many users have logged in today?" the analysis shows:
+
+1. Querying BigQuery requires re-discovering the table schemas and relationships each time
+2. A `references/schema.md` file documenting the table schemas would be helpful to store in the skill
+
+To establish the skill's contents, analyze each concrete example to create a list of the reusable resources to include: scripts, references, and assets.
+
+### Step 3: Initializing the Skill
+
+At this point, it is time to actually create the skill.
+
+Skip this step only if the skill being developed already exists, and iteration or packaging is needed. In this case, continue to the next step.
+
+When creating a new skill from scratch, always run the `init_skill.py` script. The script conveniently generates a new template skill directory that automatically includes everything a skill requires, making the skill creation process much more efficient and reliable.
+
+Usage:
+
+```bash
+scripts/init_skill.py --path
+```
+
+The script:
+
+- Creates the skill directory at the specified path
+- Generates a SKILL.md template with proper frontmatter and TODO placeholders
+- Creates example resource directories: `scripts/`, `references/`, and `assets/`
+- Adds example files in each directory that can be customized or deleted
+
+After initialization, customize or remove the generated SKILL.md and example files as needed.
+
+### Step 4: Edit the Skill
+
+When editing the (newly-generated or existing) skill, remember that the skill is being created for another instance of Claude to use. Include information that would be beneficial and non-obvious to Claude. Consider what procedural knowledge, domain-specific details, or reusable assets would help another Claude instance execute these tasks more effectively.
+
+#### Learn Proven Design Patterns
+
+Consult these helpful guides based on your skill's needs:
+
+- **Multi-step processes**: See references/workflows.md for sequential workflows and conditional logic
+- **Specific output formats or quality standards**: See references/output-patterns.md for template and example patterns
+
+These files contain established best practices for effective skill design.
+
+#### Start with Reusable Skill Contents
+
+To begin implementation, start with the reusable resources identified above: `scripts/`, `references/`, and `assets/` files. Note that this step may require user input. For example, when implementing a `brand-guidelines` skill, the user may need to provide brand assets or templates to store in `assets/`, or documentation to store in `references/`.
+
+Added scripts must be tested by actually running them to ensure there are no bugs and that the output matches what is expected. If there are many similar scripts, only a representative sample needs to be tested to ensure confidence that they all work while balancing time to completion.
+
+Any example files and directories not needed for the skill should be deleted. The initialization script creates example files in `scripts/`, `references/`, and `assets/` to demonstrate structure, but most skills won't need all of them.
+
+#### Update SKILL.md
+
+**Writing Guidelines:** Always use imperative/infinitive form.
+
+##### Frontmatter
+
+Write the YAML frontmatter with `name` and `description`:
+
+- `name`: The skill name
+- `description`: This is the primary triggering mechanism for your skill, and helps Claude understand when to use the skill.
+ - Include both what the Skill does and specific triggers/contexts for when to use it.
+ - Include all "when to use" information here - Not in the body. The body is only loaded after triggering, so "When to Use This Skill" sections in the body are not helpful to Claude.
+ - Example description for a `docx` skill: "Comprehensive document creation, editing, and analysis with support for tracked changes, comments, formatting preservation, and text extraction. Use when Claude needs to work with professional documents (.docx files) for: (1) Creating new documents, (2) Modifying or editing content, (3) Working with tracked changes, (4) Adding comments, or any other document tasks"
+
+Do not include any other fields in YAML frontmatter.
+
+##### Body
+
+Write instructions for using the skill and its bundled resources.
+
+### Step 5: Packaging a Skill
+
+Once development of the skill is complete, it must be packaged into a distributable .skill file that gets shared with the user. The packaging process automatically validates the skill first to ensure it meets all requirements:
+
+```bash
+scripts/package_skill.py
+```
+
+Optional output directory specification:
+
+```bash
+scripts/package_skill.py ./dist
+```
+
+The packaging script will:
+
+1. **Validate** the skill automatically, checking:
+ - YAML frontmatter format and required fields
+ - Skill naming conventions and directory structure
+ - Description completeness and quality
+ - File organization and resource references
+
+2. **Package** the skill if validation passes, creating a .skill file named after the skill (e.g., `my-skill.skill`) that includes all files and maintains the proper directory structure for distribution. The .skill file is a zip file with a .skill extension.
+
+If validation fails, the script will report the errors and exit without creating a package. Fix any validation errors and run the packaging command again.
+
+### Step 6: Iterate
+
+After testing the skill, users may request improvements. Often this happens right after using the skill, with fresh context of how the skill performed.
+
+**Iteration workflow:**
+
+1. Use the skill on real tasks
+2. Notice struggles or inefficiencies
+3. Identify how SKILL.md or bundled resources should be updated
+4. Implement changes and test again
diff --git a/.cursor/skills/skill-creator/references/output-patterns.md b/.cursor/skills/skill-creator/references/output-patterns.md
new file mode 100644
index 00000000..219c64c2
--- /dev/null
+++ b/.cursor/skills/skill-creator/references/output-patterns.md
@@ -0,0 +1,92 @@
+# Output Patterns
+
+Use these patterns when skills need to produce consistent, high-quality output.
+
+## Template Pattern
+
+Provide templates for output format. Match the level of strictness to your needs.
+
+**For strict requirements (like API responses or data formats):**
+
+```markdown
+## Report structure
+
+ALWAYS use this exact template structure:
+
+# [Analysis Title]
+
+## Executive summary
+
+[One-paragraph overview of key findings]
+
+## Key findings
+
+- Finding 1 with supporting data
+- Finding 2 with supporting data
+- Finding 3 with supporting data
+
+## Recommendations
+
+1. Specific actionable recommendation
+2. Specific actionable recommendation
+```
+
+**For flexible guidance (when adaptation is useful):**
+
+```markdown
+## Report structure
+
+Here is a sensible default format, but use your best judgment:
+
+# [Analysis Title]
+
+## Executive summary
+
+[Overview]
+
+## Key findings
+
+[Adapt sections based on what you discover]
+
+## Recommendations
+
+[Tailor to the specific context]
+
+Adjust sections as needed for the specific analysis type.
+```
+
+## Examples Pattern
+
+For skills where output quality depends on seeing examples, provide input/output pairs:
+
+```markdown
+## Commit message format
+
+Generate commit messages following these examples:
+
+**Example 1:**
+Input: Added user authentication with JWT tokens
+Output:
+```
+
+feat(auth): implement JWT-based authentication
+
+Add login endpoint and token validation middleware
+
+```
+
+**Example 2:**
+Input: Fixed bug where dates displayed incorrectly in reports
+Output:
+```
+
+fix(reports): correct date formatting in timezone conversion
+
+Use UTC timestamps consistently across report generation
+
+```
+
+Follow this style: type(scope): brief description, then detailed explanation.
+```
+
+Examples help Claude understand the desired style and level of detail more clearly than descriptions alone.
diff --git a/.cursor/skills/skill-creator/references/workflows.md b/.cursor/skills/skill-creator/references/workflows.md
new file mode 100644
index 00000000..54b01740
--- /dev/null
+++ b/.cursor/skills/skill-creator/references/workflows.md
@@ -0,0 +1,28 @@
+# Workflow Patterns
+
+## Sequential Workflows
+
+For complex tasks, break operations into clear, sequential steps. It is often helpful to give Claude an overview of the process towards the beginning of SKILL.md:
+
+```markdown
+Filling a PDF form involves these steps:
+
+1. Analyze the form (run analyze_form.py)
+2. Create field mapping (edit fields.json)
+3. Validate mapping (run validate_fields.py)
+4. Fill the form (run fill_form.py)
+5. Verify output (run verify_output.py)
+```
+
+## Conditional Workflows
+
+For tasks with branching logic, guide Claude through decision points:
+
+```markdown
+1. Determine the modification type:
+ **Creating new content?** → Follow "Creation workflow" below
+ **Editing existing content?** → Follow "Editing workflow" below
+
+2. Creation workflow: [steps]
+3. Editing workflow: [steps]
+```
diff --git a/.cursor/skills/skill-creator/scripts/init_skill.py b/.cursor/skills/skill-creator/scripts/init_skill.py
new file mode 100644
index 00000000..da1cbfb7
--- /dev/null
+++ b/.cursor/skills/skill-creator/scripts/init_skill.py
@@ -0,0 +1,333 @@
+#!/usr/bin/env python3
+"""
+Skill Initializer - Creates a new skill from template
+
+Usage:
+ init_skill.py --path
+
+Examples:
+ init_skill.py my-new-skill --path skills/public
+ init_skill.py my-api-helper --path skills/private
+ init_skill.py custom-skill --path /custom/location
+"""
+
+import sys
+from pathlib import Path
+
+
+SKILL_TEMPLATE = """---
+name: {skill_name}
+description: [TODO: Complete and informative explanation of what the skill does and when to use it. Include WHEN to use this skill - specific scenarios, file types, or tasks that trigger it.]
+---
+
+# {skill_title}
+
+## Overview
+
+[TODO: 1-2 sentences explaining what this skill enables]
+
+## Structuring This Skill
+
+[TODO: Choose the structure that best fits this skill's purpose. Common patterns:
+
+**1. Workflow-Based** (best for sequential processes)
+- Works well when there are clear step-by-step procedures
+- Example: DOCX skill with "Workflow Decision Tree" → "Reading" → "Creating" → "Editing"
+- Structure: ## Overview → ## Workflow Decision Tree → ## Step 1 → ## Step 2...
+
+**2. Task-Based** (best for tool collections)
+- Works well when the skill offers different operations/capabilities
+- Example: PDF skill with "Quick Start" → "Merge PDFs" → "Split PDFs" → "Extract Text"
+- Structure: ## Overview → ## Quick Start → ## Task Category 1 → ## Task Category 2...
+
+**3. Reference/Guidelines** (best for standards or specifications)
+- Works well for brand guidelines, coding standards, or requirements
+- Example: Brand styling with "Brand Guidelines" → "Colors" → "Typography" → "Features"
+- Structure: ## Overview → ## Guidelines → ## Specifications → ## Usage...
+
+**4. Capabilities-Based** (best for integrated systems)
+- Works well when the skill provides multiple interrelated features
+- Example: Product Management with "Core Capabilities" → numbered capability list
+- Structure: ## Overview → ## Core Capabilities → ### 1. Feature → ### 2. Feature...
+
+Patterns can be mixed and matched as needed. Most skills combine patterns (e.g., start with task-based, add workflow for complex operations).
+
+Delete this entire "Structuring This Skill" section when done - it's just guidance.]
+
+## [TODO: Replace with the first main section based on chosen structure]
+
+[TODO: Add content here. See examples in existing skills:
+- Code samples for technical skills
+- Decision trees for complex workflows
+- Concrete examples with realistic user requests
+- References to scripts/templates/references as needed]
+
+## Resources
+
+This skill includes example resource directories that demonstrate how to organize different types of bundled resources:
+
+### scripts/
+Executable code (Python/Bash/etc.) that can be run directly to perform specific operations.
+
+**Examples from other skills:**
+- PDF skill: `fill_fillable_fields.py`, `extract_form_field_info.py` - utilities for PDF manipulation
+- DOCX skill: `document.py`, `utilities.py` - Python modules for document processing
+
+**Appropriate for:** Python scripts, shell scripts, or any executable code that performs automation, data processing, or specific operations.
+
+**Note:** Scripts may be executed without loading into context, but can still be read by Claude for patching or environment adjustments.
+
+### references/
+Documentation and reference material intended to be loaded into context to inform Claude's process and thinking.
+
+**Examples from other skills:**
+- Product management: `communication.md`, `context_building.md` - detailed workflow guides
+- BigQuery: API reference documentation and query examples
+- Finance: Schema documentation, company policies
+
+**Appropriate for:** In-depth documentation, API references, database schemas, comprehensive guides, or any detailed information that Claude should reference while working.
+
+### assets/
+Files not intended to be loaded into context, but rather used within the output Claude produces.
+
+**Examples from other skills:**
+- Brand styling: PowerPoint template files (.pptx), logo files
+- Frontend builder: HTML/React boilerplate project directories
+- Typography: Font files (.ttf, .woff2)
+
+**Appropriate for:** Templates, boilerplate code, document templates, images, icons, fonts, or any files meant to be copied or used in the final output.
+
+---
+
+**Any unneeded directories can be deleted.** Not every skill requires all three types of resources.
+"""
+
+EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
+"""
+Example helper script for {skill_name}
+
+This is a placeholder script that can be executed directly.
+Replace with actual implementation or delete if not needed.
+
+Example real scripts from other skills:
+- pdf/scripts/fill_fillable_fields.py - Fills PDF form fields
+- pdf/scripts/convert_pdf_to_images.py - Converts PDF pages to images
+"""
+
+def main():
+ print("This is an example script for {skill_name}")
+ # TODO: Add actual script logic here
+ # This could be data processing, file conversion, API calls, etc.
+
+if __name__ == "__main__":
+ main()
+'''
+
+EXAMPLE_REFERENCE = """# Reference Documentation for {skill_title}
+
+This is a placeholder for detailed reference documentation.
+Replace with actual reference content or delete if not needed.
+
+Example real reference docs from other skills:
+- product-management/references/communication.md - Comprehensive guide for status updates
+- product-management/references/context_building.md - Deep-dive on gathering context
+- bigquery/references/ - API references and query examples
+
+## When Reference Docs Are Useful
+
+Reference docs are ideal for:
+- Comprehensive API documentation
+- Detailed workflow guides
+- Complex multi-step processes
+- Information too lengthy for main SKILL.md
+- Content that's only needed for specific use cases
+
+## Structure Suggestions
+
+### API Reference Example
+- Overview
+- Authentication
+- Endpoints with examples
+- Error codes
+- Rate limits
+
+### Workflow Guide Example
+- Prerequisites
+- Step-by-step instructions
+- Common patterns
+- Troubleshooting
+- Best practices
+"""
+
+EXAMPLE_ASSET = """# Example Asset File
+
+This placeholder represents where asset files would be stored.
+Replace with actual asset files (templates, images, fonts, etc.) or delete if not needed.
+
+Asset files are NOT intended to be loaded into context, but rather used within
+the output Claude produces.
+
+Example asset files from other skills:
+- Brand guidelines: logo.png, slides_template.pptx
+- Frontend builder: hello-world/ directory with HTML/React boilerplate
+- Typography: custom-font.ttf, font-family.woff2
+- Data: sample_data.csv, test_dataset.json
+
+## Common Asset Types
+
+- Templates: .pptx, .docx, boilerplate directories
+- Images: .png, .jpg, .svg, .gif
+- Fonts: .ttf, .otf, .woff, .woff2
+- Boilerplate code: Project directories, starter files
+- Icons: .ico, .svg
+- Data files: .csv, .json, .xml, .yaml
+
+Note: This is a text placeholder. Actual assets can be any file type.
+"""
+
+
+def title_case_skill_name(skill_name):
+ """Convert hyphenated skill name to Title Case for display."""
+ return ' '.join(word.capitalize() for word in skill_name.split('-'))
+
+
+def init_skill(skill_name, path):
+ """
+ Initialize a new skill directory with template SKILL.md.
+
+ Args:
+ skill_name: Name of the skill
+ path: Path where the skill directory should be created
+
+ Returns:
+ Path to created skill directory, or None if error
+ """
+ import re
+
+ # Validate skill_name before using it in path operations
+ if not skill_name or not isinstance(skill_name, str):
+ print("❌ Error: Skill name must be a non-empty string")
+ return None
+
+ skill_name = skill_name.strip()
+
+ if not skill_name:
+ print("❌ Error: Skill name cannot be empty or whitespace")
+ return None
+
+ if len(skill_name) > 64:
+ print(f"❌ Error: Skill name too long ({len(skill_name)} chars). Maximum is 64.")
+ return None
+
+ if not re.match(r'^[a-z0-9]+(-[a-z0-9]+)*$', skill_name):
+ print(f"❌ Error: Skill name '{skill_name}' must be kebab-case")
+ print(" (lowercase letters, digits, hyphens; no leading/trailing/consecutive hyphens)")
+ return None
+
+ # Determine skill directory path
+ skill_dir = Path(path).resolve() / skill_name
+
+ # Ensure skill_dir is a subpath of the intended base path (prevent path traversal)
+ base_path = Path(path).resolve()
+ try:
+ skill_dir.relative_to(base_path)
+ except ValueError:
+ print(f"❌ Error: Invalid skill name causes path traversal: {skill_name}")
+ return None
+
+ # Check if directory already exists
+ if skill_dir.exists():
+ print(f"❌ Error: Skill directory already exists: {skill_dir}")
+ return None
+
+ # Create skill directory
+ try:
+ skill_dir.mkdir(parents=True, exist_ok=False)
+ print(f"✅ Created skill directory: {skill_dir}")
+ except Exception as e:
+ print(f"❌ Error creating directory: {e}")
+ return None
+
+ # Create SKILL.md from template
+ skill_title = title_case_skill_name(skill_name)
+ skill_content = SKILL_TEMPLATE.format(
+ skill_name=skill_name,
+ skill_title=skill_title
+ )
+
+ skill_md_path = skill_dir / 'SKILL.md'
+ try:
+ skill_md_path.write_text(skill_content)
+ print("✅ Created SKILL.md")
+ except Exception as e:
+ print(f"❌ Error creating SKILL.md: {e}")
+ return None
+
+ # Create resource directories with example files
+ try:
+ # Create scripts/ directory with example script
+ scripts_dir = skill_dir / 'scripts'
+ scripts_dir.mkdir(exist_ok=True)
+ example_script = scripts_dir / 'example.py'
+ example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
+ example_script.chmod(0o755)
+ print("✅ Created scripts/example.py")
+
+ # Create references/ directory with example reference doc
+ references_dir = skill_dir / 'references'
+ references_dir.mkdir(exist_ok=True)
+ example_reference = references_dir / 'api_reference.md'
+ example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
+ print("✅ Created references/api_reference.md")
+
+ # Create assets/ directory with example asset placeholder
+ assets_dir = skill_dir / 'assets'
+ assets_dir.mkdir(exist_ok=True)
+ example_asset = assets_dir / 'example_asset.txt'
+ example_asset.write_text(EXAMPLE_ASSET)
+ print("✅ Created assets/example_asset.txt")
+ except Exception as e:
+ print(f"❌ Error creating resource directories: {e}")
+ return None
+
+ # Print next steps
+ print(f"\n✅ Skill '{skill_name}' initialized successfully at {skill_dir}")
+ print("\nNext steps:")
+ print("1. Edit SKILL.md to complete the TODO items and update the description")
+ print("2. Customize or delete the example files in scripts/, references/, and assets/")
+ print("3. Run the validator when ready to check the skill structure")
+
+ return skill_dir
+
+
+def main():
+ if len(sys.argv) < 4 or sys.argv[2] != '--path':
+ print("Usage: init_skill.py --path ")
+ print("\nSkill name requirements:")
+ print(" - Kebab-case identifier (e.g., 'my-data-analyzer')")
+ print(" - Lowercase letters, digits, and hyphens only")
+ print(" - Max 64 characters")
+ print(" - Must match directory name exactly")
+ print("\nExamples:")
+ print(" init_skill.py my-new-skill --path skills/public")
+ print(" init_skill.py my-api-helper --path skills/private")
+ print(" init_skill.py custom-skill --path /custom/location")
+ sys.exit(1)
+
+ skill_name = sys.argv[1]
+ path = sys.argv[3]
+
+ print(f"🚀 Initializing skill: {skill_name}")
+ print(f" Location: {path}")
+ print()
+
+ result = init_skill(skill_name, path)
+
+ if result:
+ sys.exit(0)
+ else:
+ sys.exit(1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.cursor/skills/skill-creator/scripts/package_skill.py b/.cursor/skills/skill-creator/scripts/package_skill.py
new file mode 100644
index 00000000..531788db
--- /dev/null
+++ b/.cursor/skills/skill-creator/scripts/package_skill.py
@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""
+Skill Packager - Creates a distributable .skill file of a skill folder
+
+Usage:
+ python utils/package_skill.py [output-directory]
+
+Example:
+ python utils/package_skill.py skills/public/my-skill
+ python utils/package_skill.py skills/public/my-skill ./dist
+"""
+
+import sys
+import zipfile
+from pathlib import Path
+
+# Ensure sibling scripts are importable regardless of CWD
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from quick_validate import validate_skill # noqa: E402
+
+
+def package_skill(skill_path, output_dir=None):
+ """
+ Package a skill folder into a .skill file.
+
+ Args:
+ skill_path: Path to the skill folder
+ output_dir: Optional output directory for the .skill file (defaults to current directory)
+
+ Returns:
+ Path to the created .skill file, or None if error
+ """
+ skill_path = Path(skill_path).resolve()
+
+ # Validate skill folder exists
+ if not skill_path.exists():
+ print(f"❌ Error: Skill folder not found: {skill_path}")
+ return None
+
+ if not skill_path.is_dir():
+ print(f"❌ Error: Path is not a directory: {skill_path}")
+ return None
+
+ # Validate SKILL.md exists
+ skill_md = skill_path / "SKILL.md"
+ if not skill_md.exists():
+ print(f"❌ Error: SKILL.md not found in {skill_path}")
+ return None
+
+ # Run validation before packaging
+ print("🔍 Validating skill...")
+ valid, message = validate_skill(skill_path)
+ if not valid:
+ print(f"❌ Validation failed: {message}")
+ print(" Please fix the validation errors before packaging.")
+ return None
+ print(f"✅ {message}\n")
+
+ # Determine output location
+ skill_name = skill_path.name
+ if output_dir:
+ output_path = Path(output_dir).resolve()
+ output_path.mkdir(parents=True, exist_ok=True)
+ else:
+ output_path = Path.cwd()
+
+ skill_filename = output_path / f"{skill_name}.skill"
+
+ # Create the .skill file (zip format)
+ try:
+ with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
+ # Walk through the skill directory
+ for file_path in skill_path.rglob('*'):
+ if file_path.is_file():
+ # Calculate the relative path within the zip
+ arcname = file_path.relative_to(skill_path.parent)
+ zipf.write(file_path, arcname)
+ print(f" Added: {arcname}")
+
+ print(f"\n✅ Successfully packaged skill to: {skill_filename}")
+ return skill_filename
+
+ except Exception as e:
+ print(f"❌ Error creating .skill file: {e}")
+ return None
+
+
+def main():
+ if len(sys.argv) < 2:
+ print("Usage: python utils/package_skill.py [output-directory]")
+ print("\nExample:")
+ print(" python utils/package_skill.py skills/public/my-skill")
+ print(" python utils/package_skill.py skills/public/my-skill ./dist")
+ sys.exit(1)
+
+ skill_path = sys.argv[1]
+ output_dir = sys.argv[2] if len(sys.argv) > 2 else None
+
+ print(f"📦 Packaging skill: {skill_path}")
+ if output_dir:
+ print(f" Output directory: {output_dir}")
+ print()
+
+ result = package_skill(skill_path, output_dir)
+
+ if result:
+ sys.exit(0)
+ else:
+ sys.exit(1)
+
+
+if __name__ == "__main__":
+ main()
diff --git a/.cursor/skills/skill-creator/scripts/quick_validate.py b/.cursor/skills/skill-creator/scripts/quick_validate.py
new file mode 100644
index 00000000..0e499646
--- /dev/null
+++ b/.cursor/skills/skill-creator/scripts/quick_validate.py
@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+Quick validation script for skills - minimal version
+"""
+
+import sys
+import os
+import re
+import yaml
+from pathlib import Path
+
+def validate_skill(skill_path):
+ """Basic validation of a skill"""
+ skill_path = Path(skill_path)
+
+ # Check SKILL.md exists
+ skill_md = skill_path / 'SKILL.md'
+ if not skill_md.exists():
+ return False, "SKILL.md not found"
+
+ # Read and validate frontmatter
+ content = skill_md.read_text()
+ if not content.startswith('---'):
+ return False, "No YAML frontmatter found"
+
+ # Extract frontmatter
+ match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+ if not match:
+ return False, "Invalid frontmatter format"
+
+ frontmatter_text = match.group(1)
+
+ # Parse YAML frontmatter
+ try:
+ frontmatter = yaml.safe_load(frontmatter_text)
+ if not isinstance(frontmatter, dict):
+ return False, "Frontmatter must be a YAML dictionary"
+ except yaml.YAMLError as e:
+ return False, f"Invalid YAML in frontmatter: {e}"
+
+ # Define allowed properties
+ ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}
+
+ # Check for unexpected properties (excluding nested keys under metadata)
+ unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
+ if unexpected_keys:
+ return False, (
+ f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
+ f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
+ )
+
+ # Check required fields
+ if 'name' not in frontmatter:
+ return False, "Missing 'name' in frontmatter"
+ if 'description' not in frontmatter:
+ return False, "Missing 'description' in frontmatter"
+
+ # Extract name for validation
+ name = frontmatter.get('name', '')
+ if not isinstance(name, str):
+ return False, f"Name must be a string, got {type(name).__name__}"
+ name = name.strip()
+ if not name:
+ return False, "Name cannot be empty or whitespace"
+
+ # Check naming convention (kebab-case: lowercase with hyphens)
+ if not re.match(r'^[a-z0-9-]+$', name):
+ return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
+ if name.startswith('-') or name.endswith('-') or '--' in name:
+ return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
+ # Check name length (max 64 characters per spec)
+ if len(name) > 64:
+ return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
+
+ # Extract and validate description
+ description = frontmatter.get('description', '')
+ if not isinstance(description, str):
+ return False, f"Description must be a string, got {type(description).__name__}"
+ description = description.strip()
+ if not description:
+ return False, "Description cannot be empty or whitespace"
+
+ # Check for angle brackets
+ if '<' in description or '>' in description:
+ return False, "Description cannot contain angle brackets (< or >)"
+ # Check description length (max 1024 characters per spec)
+ if len(description) > 1024:
+ return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
+
+ # Validate compatibility field if present (optional)
+ compatibility = frontmatter.get('compatibility', '')
+ if compatibility:
+ if not isinstance(compatibility, str):
+ return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
+ if len(compatibility) > 500:
+ return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."
+
+ return True, "Skill is valid!"
+
+if __name__ == "__main__":
+ if len(sys.argv) != 2:
+ print("Usage: python quick_validate.py ")
+ sys.exit(1)
+
+ valid, message = validate_skill(sys.argv[1])
+ print(message)
+ sys.exit(0 if valid else 1)
\ No newline at end of file
diff --git a/backend/config.py b/backend/config.py
index 55b3c6a9..6c01408a 100644
--- a/backend/config.py
+++ b/backend/config.py
@@ -9,6 +9,13 @@
from dataclasses import dataclass
from pathlib import Path
+# Load environment variables from .env file
+try:
+ from dotenv import load_dotenv
+ load_dotenv()
+except ImportError:
+ pass # dotenv not installed, rely on system env vars
+
@dataclass
class Config:
diff --git a/backend/main.py b/backend/main.py
index ca673ad6..73b67a7f 100644
--- a/backend/main.py
+++ b/backend/main.py
@@ -58,8 +58,9 @@ async def background_initialization(app: FastAPI):
logger.info("Maharashtra data pre-loaded successfully.")
# 3. Start Telegram Bot in separate thread
- await run_in_threadpool(start_bot_thread)
- logger.info("Telegram bot started in separate thread.")
+ # Temporarily disabled for local testing
+ # await run_in_threadpool(start_bot_thread)
+ logger.info("Telegram bot initialization skipped for local testing.")
except Exception as e:
logger.error(f"Error during background initialization: {e}", exc_info=True)
@@ -141,11 +142,16 @@ async def lifespan(app: FastAPI):
dev_origins = [
"http://localhost:3000",
"http://localhost:5173",
+ "http://localhost:5174",
"http://127.0.0.1:3000",
"http://127.0.0.1:5173",
+ "http://127.0.0.1:5174",
"http://localhost:8080",
]
allowed_origins.extend(dev_origins)
+ # Also add the one from .env if it's different
+ if frontend_url not in allowed_origins:
+ allowed_origins.append(frontend_url)
app.add_middleware(
CORSMiddleware,
diff --git a/create_test_user.py b/create_test_user.py
new file mode 100644
index 00000000..650542ea
--- /dev/null
+++ b/create_test_user.py
@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Create a test user for login testing"""
+
+from backend.database import SessionLocal
+from backend.models import User, UserRole
+from backend.utils import get_password_hash
+
+def create_test_user():
+ db = SessionLocal()
+ try:
+ # Check if user already exists
+ existing = db.query(User).filter(User.email == 'test@example.com').first()
+ if existing:
+ print('❌ User already exists!')
+ print('Email: test@example.com')
+ return
+
+ # Create new user
+ user = User(
+ email='test@example.com',
+ hashed_password=get_password_hash('password123'),
+ full_name='Test User',
+ role=UserRole.USER,
+ is_active=True
+ )
+ db.add(user)
+ db.commit()
+
+ print('✅ Test user created successfully!')
+ print('Email: test@example.com')
+ print('Password: password123')
+ print('Role: USER')
+
+ except Exception as e:
+ print(f'❌ Error: {e}')
+ db.rollback()
+ finally:
+ db.close()
+
+if __name__ == '__main__':
+ create_test_user()
diff --git a/debug_login.py b/debug_login.py
new file mode 100644
index 00000000..934ada5a
--- /dev/null
+++ b/debug_login.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Debug login issue"""
+
+from backend.database import SessionLocal
+from backend.models import User
+from backend.utils import verify_password
+
+def debug_login():
+ db = SessionLocal()
+ try:
+ email = 'test@example.com'
+ password = 'password123'
+
+ user = db.query(User).filter(User.email == email).first()
+
+ if not user:
+ print(f'❌ User not found: {email}')
+ return
+
+ print(f'✅ User found: {email}')
+ print(f' Full name: {user.full_name}')
+ print(f' Role: {user.role.value}')
+ print(f' Active: {user.is_active}')
+ print(f' Hashed password: {user.hashed_password[:50]}...')
+
+ # Test password verification
+ is_valid = verify_password(password, user.hashed_password)
+ print(f'\n🔐 Password verification: {"✅ VALID" if is_valid else "❌ INVALID"}')
+
+ if not is_valid:
+ print('\n⚠️ Password does not match!')
+ print(' This is why login is failing with 401.')
+
+ except Exception as e:
+ print(f'❌ Error: {e}')
+ import traceback
+ traceback.print_exc()
+ finally:
+ db.close()
+
+if __name__ == '__main__':
+ debug_login()
diff --git a/frontend/src/App.jsx b/frontend/src/App.jsx
index fefa4561..47ba1526 100644
--- a/frontend/src/App.jsx
+++ b/frontend/src/App.jsx
@@ -42,7 +42,7 @@ const MyReportsView = React.lazy(() => import('./views/MyReportsView'));
// Auth Components
-import { AuthProvider } from './contexts/AuthContext';
+import { AuthProvider, useAuth } from './contexts/AuthContext';
import Login from './views/Login';
import ProtectedRoute from './components/ProtectedRoute';
import AdminDashboard from './views/AdminDashboard';
@@ -53,7 +53,9 @@ function AppContent() {
const navigate = useNavigate();
const location = useLocation();
const { isDarkMode } = useDarkMode();
+ const { user, loading: authLoading } = useAuth();
const [responsibilityMap, setResponsibilityMap] = useState(null);
+ const [stats, setStats] = useState({ total_issues: 0, resolved_issues: 0, pending_issues: 0 });
const [actionPlan, setActionPlan] = useState(null);
const [maharashtraRepInfo, setMaharashtraRepInfo] = useState(null);
const [recentIssues, setRecentIssues] = useState([]);
@@ -65,7 +67,7 @@ function AppContent() {
// Safe navigation helper
const navigateToView = useCallback((view) => {
- const validViews = ['home', 'map', 'report', 'action', 'mh-rep', 'pothole', 'garbage', 'vandalism', 'flood', 'infrastructure', 'parking', 'streetlight', 'fire', 'animal', 'blocked', 'tree', 'pest', 'smart-scan', 'grievance-analysis', 'noise', 'safety-check', 'my-reports', 'login', 'signup'];
+ const validViews = ['home', 'map', 'report', 'action', 'mh-rep', 'pothole', 'garbage', 'vandalism', 'flood', 'infrastructure', 'parking', 'streetlight', 'fire', 'animal', 'blocked', 'tree', 'pest', 'smart-scan', 'grievance-analysis', 'noise', 'safety-check', 'my-reports', 'grievance', 'login', 'signup'];
if (validViews.includes(view)) {
navigate(view === 'home' ? '/' : `/${view}`);
} else {
@@ -132,13 +134,10 @@ function AppContent() {
try {
const data = await miscApi.getResponsibilityMap();
setResponsibilityMap(data);
- setSuccess('Responsibility map loaded successfully');
- navigate('/map');
+ // Removed automatic navigate('/map') from here to prevent loops
} catch (error) {
console.error("Failed to fetch responsibility map", error);
- setError("Using sample data - unable to load responsibility map");
setResponsibilityMap(fakeResponsibilityMap);
- navigate('/map');
} finally {
setLoading(false);
}
@@ -146,14 +145,29 @@ function AppContent() {
// Initialize on mount
useEffect(() => {
+ fetchResponsibilityMap();
fetchRecentIssues();
- }, [fetchRecentIssues]);
+
+ // Fetch system stats
+ miscApi.getStats()
+ .then(data => setStats(data))
+ .catch(err => console.error("Failed to fetch stats", err));
+ }, [fetchRecentIssues, fetchResponsibilityMap]);
+
+ // Handle Auth Loading to prevent blinking
+ if (authLoading) {
+ return (
+
+
+
+ );
+ }
// Check if we're on the landing page
const isLandingPage = location.pathname === '/';
- // If on landing page, render it without the main layout
- if (isLandingPage) {
+ // If on landing page and NOT logged in, render it without the main layout
+ if (isLandingPage && !user) {
return (
@@ -167,149 +181,183 @@ function AppContent() {
// Otherwise render the main app layout
return (
-
- {/* Animated background elements */}
-
-
-
+
+ {/* Animated background elements - Optimized for performance */}
+