create-inox-app 0.1.0

package/dist/templates/claude-config/app/.agents/skills/next-cache-components/SKILL.md

@@ -0,0 +1,411 @@
+---
+name: next-cache-components
+description: Next.js 16 Cache Components - PPR, use cache directive, cacheLife, cacheTag, updateTag
+---
+
+# Cache Components (Next.js 16+)
+
+Cache Components enable Partial Prerendering (PPR) - mix static, cached, and dynamic content in a single route.
+
+## Enable Cache Components
+
+```ts
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+}
+
+export default nextConfig
+```
+
+This replaces the old `experimental.ppr` flag.
+
+---
+
+## Three Content Types
+
+With Cache Components enabled, content falls into three categories:
+
+### 1. Static (Auto-Prerendered)
+
+Synchronous code, imports, pure computations - prerendered at build time:
+
+```tsx
+export default function Page() {
+  return (
+    <header>
+      <h1>Our Blog</h1>  {/* Static - instant */}
+      <nav>...</nav>
+    </header>
+  )
+}
+```
+
+### 2. Cached (`use cache`)
+
+Async data that doesn't need fresh fetches every request:
+
+```tsx
+async function BlogPosts() {
+  'use cache'
+  cacheLife('hours')
+
+  const posts = await db.posts.findMany()
+  return <PostList posts={posts} />
+}
+```
+
+### 3. Dynamic (Suspense)
+
+Runtime data that must be fresh - wrap in Suspense:
+
+```tsx
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <>
+      <BlogPosts />  {/* Cached */}
+
+      <Suspense fallback={<p>Loading...</p>}>
+        <UserPreferences />  {/* Dynamic - streams in */}
+      </Suspense>
+    </>
+  )
+}
+
+async function UserPreferences() {
+  const theme = (await cookies()).get('theme')?.value
+  return <p>Theme: {theme}</p>
+}
+```
+
+---
+
+## `use cache` Directive
+
+### File Level
+
+```tsx
+'use cache'
+
+export default async function Page() {
+  // Entire page is cached
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Component Level
+
+```tsx
+export async function CachedComponent() {
+  'use cache'
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+### Function Level
+
+```tsx
+export async function getData() {
+  'use cache'
+  return db.query('SELECT * FROM posts')
+}
+```
+
+---
+
+## Cache Profiles
+
+### Built-in Profiles
+
+```tsx
+'use cache'                    // Default: 5m stale, 15m revalidate
+```
+
+```tsx
+'use cache: remote'           // Platform-provided cache (Redis, KV)
+```
+
+```tsx
+'use cache: private'          // For compliance, allows runtime APIs
+```
+
+### `cacheLife()` - Custom Lifetime
+
+```tsx
+import { cacheLife } from 'next/cache'
+
+async function getData() {
+  'use cache'
+  cacheLife('hours')  // Built-in profile
+  return fetch('/api/data')
+}
+```
+
+Built-in profiles: `'default'`, `'minutes'`, `'hours'`, `'days'`, `'weeks'`, `'max'`
+
+### Inline Configuration
+
+```tsx
+async function getData() {
+  'use cache'
+  cacheLife({
+    stale: 3600,      // 1 hour - serve stale while revalidating
+    revalidate: 7200, // 2 hours - background revalidation interval
+    expire: 86400,    // 1 day - hard expiration
+  })
+  return fetch('/api/data')
+}
+```
+
+---
+
+## Cache Invalidation
+
+### `cacheTag()` - Tag Cached Content
+
+```tsx
+import { cacheTag } from 'next/cache'
+
+async function getProducts() {
+  'use cache'
+  cacheTag('products')
+  return db.products.findMany()
+}
+
+async function getProduct(id: string) {
+  'use cache'
+  cacheTag('products', `product-${id}`)
+  return db.products.findUnique({ where: { id } })
+}
+```
+
+### `updateTag()` - Immediate Invalidation
+
+Use when you need the cache refreshed within the same request:
+
+```tsx
+'use server'
+
+import { updateTag } from 'next/cache'
+
+export async function updateProduct(id: string, data: FormData) {
+  await db.products.update({ where: { id }, data })
+  updateTag(`product-${id}`)  // Immediate - same request sees fresh data
+}
+```
+
+### `revalidateTag()` - Background Revalidation
+
+Use for stale-while-revalidate behavior:
+
+```tsx
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function createPost(data: FormData) {
+  await db.posts.create({ data })
+  revalidateTag('posts')  // Background - next request sees fresh data
+}
+```
+
+---
+
+## Runtime Data Constraint
+
+**Cannot** access `cookies()`, `headers()`, or `searchParams` inside `use cache`.
+
+### Solution: Pass as Arguments
+
+```tsx
+// Wrong - runtime API inside use cache
+async function CachedProfile() {
+  'use cache'
+  const session = (await cookies()).get('session')?.value  // Error!
+  return <div>{session}</div>
+}
+
+// Correct - extract outside, pass as argument
+async function ProfilePage() {
+  const session = (await cookies()).get('session')?.value
+  return <CachedProfile sessionId={session} />
+}
+
+async function CachedProfile({ sessionId }: { sessionId: string }) {
+  'use cache'
+  // sessionId becomes part of cache key automatically
+  const data = await fetchUserData(sessionId)
+  return <div>{data.name}</div>
+}
+```
+
+### Exception: `use cache: private`
+
+For compliance requirements when you can't refactor:
+
+```tsx
+async function getData() {
+  'use cache: private'
+  const session = (await cookies()).get('session')?.value  // Allowed
+  return fetchData(session)
+}
+```
+
+---
+
+## Cache Key Generation
+
+Cache keys are automatic based on:
+- **Build ID** - invalidates all caches on deploy
+- **Function ID** - hash of function location
+- **Serializable arguments** - props become part of key
+- **Closure variables** - outer scope values included
+
+```tsx
+async function Component({ userId }: { userId: string }) {
+  const getData = async (filter: string) => {
+    'use cache'
+    // Cache key = userId (closure) + filter (argument)
+    return fetch(`/api/users/${userId}?filter=${filter}`)
+  }
+  return getData('active')
+}
+```
+
+---
+
+## Complete Example
+
+```tsx
+import { Suspense } from 'react'
+import { cookies } from 'next/headers'
+import { cacheLife, cacheTag } from 'next/cache'
+
+export default function DashboardPage() {
+  return (
+    <>
+      {/* Static shell - instant from CDN */}
+      <header><h1>Dashboard</h1></header>
+      <nav>...</nav>
+
+      {/* Cached - fast, revalidates hourly */}
+      <Stats />
+
+      {/* Dynamic - streams in with fresh data */}
+      <Suspense fallback={<NotificationsSkeleton />}>
+        <Notifications />
+      </Suspense>
+    </>
+  )
+}
+
+async function Stats() {
+  'use cache'
+  cacheLife('hours')
+  cacheTag('dashboard-stats')
+
+  const stats = await db.stats.aggregate()
+  return <StatsDisplay stats={stats} />
+}
+
+async function Notifications() {
+  const userId = (await cookies()).get('userId')?.value
+  const notifications = await db.notifications.findMany({
+    where: { userId, read: false }
+  })
+  return <NotificationList items={notifications} />
+}
+```
+
+---
+
+## Migration from Previous Versions
+
+| Old Config | Replacement |
+|-----------|-------------|
+| `experimental.ppr` | `cacheComponents: true` |
+| `dynamic = 'force-dynamic'` | Remove (default behavior) |
+| `dynamic = 'force-static'` | `'use cache'` + `cacheLife('max')` |
+| `revalidate = N` | `cacheLife({ revalidate: N })` |
+| `unstable_cache()` | `'use cache'` directive |
+
+### Migrating `unstable_cache` to `use cache`
+
+`unstable_cache` has been replaced by the `use cache` directive in Next.js 16. When `cacheComponents` is enabled, convert `unstable_cache` calls to `use cache` functions:
+
+**Before (`unstable_cache`):**
+
+```tsx
+import { unstable_cache } from 'next/cache'
+
+const getCachedUser = unstable_cache(
+  async (id) => getUser(id),
+  ['my-app-user'],
+  {
+    tags: ['users'],
+    revalidate: 60,
+  }
+)
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const user = await getCachedUser(id)
+  return <div>{user.name}</div>
+}
+```
+
+**After (`use cache`):**
+
+```tsx
+import { cacheLife, cacheTag } from 'next/cache'
+
+async function getCachedUser(id: string) {
+  'use cache'
+  cacheTag('users')
+  cacheLife({ revalidate: 60 })
+  return getUser(id)
+}
+
+export default async function Page({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = await params
+  const user = await getCachedUser(id)
+  return <div>{user.name}</div>
+}
+```
+
+Key differences:
+- **No manual cache keys** - `use cache` generates keys automatically from function arguments and closures. The `keyParts` array from `unstable_cache` is no longer needed.
+- **Tags** - Replace `options.tags` with `cacheTag()` calls inside the function.
+- **Revalidation** - Replace `options.revalidate` with `cacheLife({ revalidate: N })` or a built-in profile like `cacheLife('minutes')`.
+- **Dynamic data** - `unstable_cache` did not support `cookies()` or `headers()` inside the callback. The same restriction applies to `use cache`, but you can use `'use cache: private'` if needed.
+
+---
+
+## Limitations
+
+- **Edge runtime not supported** - requires Node.js
+- **Static export not supported** - needs server
+- **Non-deterministic values** (`Math.random()`, `Date.now()`) execute once at build time inside `use cache`
+
+For request-time randomness outside cache:
+
+```tsx
+import { connection } from 'next/server'
+
+async function DynamicContent() {
+  await connection()  // Defer to request time
+  const id = crypto.randomUUID()  // Different per request
+  return <div>{id}</div>
+}
+```
+
+Sources:
+- [Cache Components Guide](https://nextjs.org/docs/app/getting-started/cache-components)
+- [use cache Directive](https://nextjs.org/docs/app/api-reference/directives/use-cache)
+- [unstable_cache (legacy)](https://nextjs.org/docs/app/api-reference/functions/unstable_cache)

package/dist/templates/claude-config/app/.agents/skills/next-upgrade/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: next-upgrade
+description: Upgrade Next.js to the latest version following official migration guides and codemods
+argument-hint: "[target-version]"
+---
+
+# Upgrade Next.js
+
+Upgrade the current project to the latest Next.js version following official migration guides.
+
+## Instructions
+
+1. **Detect current version**: Read `package.json` to identify the current Next.js version and related dependencies (React, React DOM, etc.)
+
+2. **Fetch the latest upgrade guide**: Use WebFetch to get the official upgrade documentation:
+   - Codemods: https://nextjs.org/docs/app/guides/upgrading/codemods
+   - Version-specific guides (adjust version as needed):
+     - https://nextjs.org/docs/app/guides/upgrading/version-16 
+     - https://nextjs.org/docs/app/guides/upgrading/version-15
+     - https://nextjs.org/docs/app/guides/upgrading/version-14
+
+3. **Determine upgrade path**: Based on current version, identify which migration steps apply. For major version jumps, upgrade incrementally (e.g., 13 → 14 → 15).
+
+4. **Run codemods first**: Next.js provides codemods to automate breaking changes:
+   ```bash
+   npx @next/codemod@latest <transform> <path>
+   ```
+   Common transforms:
+   - `next-async-request-api` - Updates async Request APIs (v15)
+   - `next-request-geo-ip` - Migrates geo/ip properties (v15)
+   - `next-dynamic-access-named-export` - Transforms dynamic imports (v15)
+
+5. **Update dependencies**: Upgrade Next.js and peer dependencies together:
+   ```bash
+   npm install next@latest react@latest react-dom@latest
+   ```
+
+6. **Review breaking changes**: Check the upgrade guide for manual changes needed:
+   - API changes (e.g., async params in v15)
+   - Configuration changes in `next.config.js`
+   - Deprecated features being removed
+
+7. **Update TypeScript types** (if applicable):
+   ```bash
+   npm install @types/react@latest @types/react-dom@latest
+   ```
+
+8. **Test the upgrade**:
+   - Run `npm run build` to check for build errors
+   - Run `npm run dev` and test key functionality

package/dist/templates/claude-config/app/.agents/skills/postgres-drizzle/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: postgres-drizzle
+description: Proactively apply when creating APIs, backends, or data models. Triggers on PostgreSQL, Postgres, Drizzle, database, schema, tables, columns, indexes, queries, migrations, ORM, relations, joins, transactions, SQL, drizzle-kit, connection pooling, N+1, JSONB, RLS. Use when writing database schemas, queries, migrations, or any database-related code. PostgreSQL and Drizzle ORM best practices.
+---
+
+# PostgreSQL + Drizzle ORM
+
+Type-safe database applications with PostgreSQL 18 and Drizzle ORM.
+
+## Essential Commands
+
+```bash
+npx drizzle-kit generate   # Generate migration from schema changes
+npx drizzle-kit migrate    # Apply pending migrations
+npx drizzle-kit push       # Push schema directly (dev only!)
+npx drizzle-kit studio     # Open database browser
+```
+
+## Quick Decision Trees
+
+### "How do I model this relationship?"
+
+```
+Relationship type?
+├─ One-to-many (user has posts)     → FK on "many" side + relations()
+├─ Many-to-many (posts have tags)   → Junction table + relations()
+├─ One-to-one (user has profile)    → FK with unique constraint
+└─ Self-referential (comments)      → FK to same table
+```
+
+### "Why is my query slow?"
+
+```
+Slow query?
+├─ Missing index on WHERE/JOIN columns  → Add index
+├─ N+1 queries in loop                  → Use relational queries API
+├─ Full table scan                      → EXPLAIN ANALYZE, add index
+├─ Large result set                     → Add pagination (limit/offset)
+└─ Connection overhead                  → Enable connection pooling
+```
+
+### "Which drizzle-kit command?"
+
+```
+What do I need?
+├─ Schema changed, need SQL migration   → drizzle-kit generate
+├─ Apply migrations to database         → drizzle-kit migrate
+├─ Quick dev iteration (no migration)   → drizzle-kit push
+└─ Browse/edit data visually            → drizzle-kit studio
+```
+
+## Directory Structure
+
+```
+src/db/
+├── schema/
+│   ├── index.ts          # Re-export all tables
+│   ├── users.ts          # Table + relations
+│   └── posts.ts          # Table + relations
+├── db.ts                 # Connection with pooling
+└── migrate.ts            # Migration runner
+drizzle/
+└── migrations/           # Generated SQL files
+drizzle.config.ts         # drizzle-kit config
+```
+
+## Schema Patterns
+
+### Basic Table with Timestamps
+
+```typescript
+export const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  email: varchar('email', { length: 255 }).notNull().unique(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+});
+```
+
+### Foreign Key with Index
+
+```typescript
+export const posts = pgTable('posts', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  userId: uuid('user_id').notNull().references(() => users.id),
+  title: varchar('title', { length: 255 }).notNull(),
+}, (table) => [
+  index('posts_user_id_idx').on(table.userId), // ALWAYS index FKs
+]);
+```
+
+### Relations
+
+```typescript
+export const usersRelations = relations(users, ({ many }) => ({
+  posts: many(posts),
+}));
+
+export const postsRelations = relations(posts, ({ one }) => ({
+  author: one(users, { fields: [posts.userId], references: [users.id] }),
+}));
+```
+
+## Query Patterns
+
+### Relational Query (Avoid N+1)
+
+```typescript
+// ✓ Single query with nested data
+const usersWithPosts = await db.query.users.findMany({
+  with: { posts: true },
+});
+```
+
+### Filtered Query
+
+```typescript
+const activeUsers = await db
+  .select()
+  .from(users)
+  .where(eq(users.status, 'active'));
+```
+
+### Transaction
+
+```typescript
+await db.transaction(async (tx) => {
+  const [user] = await tx.insert(users).values({ email }).returning();
+  await tx.insert(profiles).values({ userId: user.id });
+});
+```
+
+## Performance Checklist
+
+| Priority | Check | Impact |
+|----------|-------|--------|
+| CRITICAL | Index all foreign keys | Prevents full table scans on JOINs |
+| CRITICAL | Use relational queries for nested data | Avoids N+1 |
+| HIGH | Connection pooling in production | Reduces connection overhead |
+| HIGH | `EXPLAIN ANALYZE` slow queries | Identifies missing indexes |
+| MEDIUM | Partial indexes for filtered subsets | Smaller, faster indexes |
+| MEDIUM | UUIDv7 for PKs (PG18+) | Better index locality |
+
+## Anti-Patterns (CRITICAL)
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| **No FK index** | Slow JOINs, full scans | Add index on every FK column |
+| **N+1 in loops** | Query per row | Use `with:` relational queries |
+| **No pooling** | Connection per request | Use `@neondatabase/serverless` or similar |
+| **`push` in prod** | Data loss risk | Always use `generate` + `migrate` |
+| **Storing JSON as text** | No validation, bad queries | Use `jsonb()` column type |
+
+## Reference Documentation
+
+| File | Purpose |
+|------|---------|
+| [references/SCHEMA.md](references/SCHEMA.md) | Column types, constraints |
+| [references/QUERIES.md](references/QUERIES.md) | Operators, joins, aggregations |
+| [references/RELATIONS.md](references/RELATIONS.md) | One-to-many, many-to-many |
+| [references/MIGRATIONS.md](references/MIGRATIONS.md) | drizzle-kit workflows |
+| [references/POSTGRES.md](references/POSTGRES.md) | PG18 features, RLS, partitioning |
+| [references/PERFORMANCE.md](references/PERFORMANCE.md) | Indexing, optimization |
+| [references/CHEATSHEET.md](references/CHEATSHEET.md) | Quick reference |
+
+## Resources
+
+### Drizzle ORM
+- **Official Documentation**: https://orm.drizzle.team
+- **GitHub Repository**: https://github.com/drizzle-team/drizzle-orm
+- **Drizzle Kit (Migrations)**: https://orm.drizzle.team/kit-docs/overview
+
+### PostgreSQL
+- **Official Documentation**: https://www.postgresql.org/docs/
+- **SQL Commands Reference**: https://www.postgresql.org/docs/current/sql-commands.html
+- **Performance Tips**: https://www.postgresql.org/docs/current/performance-tips.html
+- **Index Types**: https://www.postgresql.org/docs/current/indexes-types.html
+- **JSON Functions**: https://www.postgresql.org/docs/current/functions-json.html
+- **Row Level Security**: https://www.postgresql.org/docs/current/ddl-rowsecurity.html