@techstream/quark-create-app 1.9.0 → 1.10.0

package/templates/base-project/.cursor/rules/quark.mdc

@@ -0,0 +1,172 @@
+---
+description: Quark project conventions for __QUARK_PROJECT_NAME__. Covers all layers: UI, backend, database, auth, jobs, testing, and deployment.
+alwaysApply: true
+---
+
+# Quark Project: __QUARK_PROJECT_NAME__
+
+Package scope: `@__QUARK_SCOPE__` — use this for ALL workspace packages.
+Scaffolded: __QUARK_SCAFFOLD_DATE__
+
+---
+
+## Non-Negotiable Rules
+
+1. **ESM only.** Always `import`/`export`. Never `require()` or `module.exports`.
+2. **No TypeScript.** Plain `.js` and `.jsx` files only — no `.ts`, `.tsx`, or type annotations.
+3. **Validate everything at boundaries.** Server Actions and API routes must use Zod. No raw `req.body` access without parsing.
+4. **Use AppError — not Error.** Throw `AppError` / `ValidationError` / `NotFoundError` from `@techstream/quark-core/errors`. Never `throw new Error()` in application code.
+5. **Log — never console.** Use `createLogger(name)` from `@techstream/quark-core`. Zero `console.log` / `console.error` in non-test code.
+6. **DB models always have timestamps.** Every Prisma model: `createdAt DateTime @default(now())` + `updatedAt DateTime @updatedAt`.
+7. **Workspace import scope.** Use `@__QUARK_SCOPE__/*` for local packages. Never `@techstream/quark-db`, `@techstream/quark-config`, etc.
+8. **Co-located tests.** `feature.test.js` lives next to `feature.js`. Tests use `node --test` — no Jest, no Vitest.
+
+---
+
+## Import Reference
+
+```javascript
+// ✅ Workspace packages — always @__QUARK_SCOPE__/*:
+import { prisma, user, post }    from "@__QUARK_SCOPE__/db";
+import { loadConfig }            from "@__QUARK_SCOPE__/config";
+import { Button, Card, Input }   from "@__QUARK_SCOPE__/ui";
+import { JOB_TYPES }             from "@__QUARK_SCOPE__/jobs";
+
+// ✅ Published runtime — @techstream/quark-core:
+import { AppError, ValidationError, NotFoundError } from "@techstream/quark-core/errors";
+import { createLogger, getCurrentSession }          from "@techstream/quark-core";
+import { createQueue, addJob }                      from "@techstream/quark-core";
+import { metrics, cache, storage }                  from "@techstream/quark-core";
+
+// ❌ Never:
+import { Button } from "@/components/ui/button";     // wrong path convention
+import { prisma } from "@techstream/quark-db";        // wrong scope for workspace pkg
+import something  from "@techstream/quark-config";    // wrong scope for workspace pkg
+```
+
+---
+
+## UI & Design System
+
+- Styling: **Tailwind CSS utility classes only**. No inline styles, no CSS modules.
+- Components from `@__QUARK_SCOPE__/ui`. All accept `className` for overrides.
+- Available: `Button`, `Input`, `Label`, `Textarea`, `Select`, `Checkbox`, `Badge`, `Card`/`CardHeader`/`CardTitle`/`CardContent`/`CardFooter`, `Table`/`TableHeader`/`TableBody`/`TableRow`/`TableHead`/`TableCell`, `Skeleton`, `Dialog` *(client)*, `Toast`/`useToast` *(client)*.
+- Loading states → `<Skeleton>` + `<Suspense>` boundaries.
+- User feedback → `useToast()` (mark component `"use client"`).
+- Modals → `<Dialog>` (mark parent `"use client"`).
+- Default to **Server Components**. Only add `"use client"` when necessary.
+
+---
+
+## Server Action Pattern
+
+```javascript
+"use server";
+import { z } from "zod";
+import { ValidationError, AppError } from "@techstream/quark-core/errors";
+import { getCurrentSession, createLogger } from "@techstream/quark-core";
+import { prisma } from "@__QUARK_SCOPE__/db";
+
+const log = createLogger("action:example");
+const schema = z.object({ title: z.string().min(1).max(255) });
+
+export async function createExample(formData) {
+  const session = await getCurrentSession();
+  if (!session) throw new AppError("Unauthorized", 401);
+
+  const parsed = schema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) throw new ValidationError(parsed.error.flatten());
+
+  const result = await prisma.example.create({ data: parsed.data });
+  log.info("created", { id: result.id });
+  return result;
+}
+```
+
+---
+
+## API Route Pattern
+
+```javascript
+import { NextResponse } from "next/server";
+import { AppError } from "@techstream/quark-core/errors";
+import { createLogger } from "@techstream/quark-core";
+
+const log = createLogger("api:example");
+
+export async function GET(request) {
+  try {
+    return NextResponse.json({ data });
+  } catch (error) {
+    log.error("request failed", { error });
+    if (error instanceof AppError)
+      return NextResponse.json({ error: error.message }, { status: error.statusCode });
+    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
+  }
+}
+```
+
+---
+
+## Database
+
+- Schema: `packages/db/prisma/schema.prisma`
+- Query helpers: `packages/db/src/queries.js` — add functions here, don't call `prisma.*` directly in components or actions.
+- Always run `pnpm db:generate` after schema changes, then `pnpm db:migrate`.
+
+---
+
+## Auth
+
+```javascript
+import { getCurrentSession } from "@techstream/quark-core";
+
+const session = await getCurrentSession();       // null if unauthenticated
+if (!session) redirect("/login");                // Server Component
+if (!session) throw new AppError("Unauthorized", 401);  // Server Action / API
+if (session.user.role !== "ADMIN") throw new AppError("Forbidden", 403);
+```
+
+---
+
+## Background Jobs
+
+```javascript
+// Dispatch (from Server Action or API route):
+import { createQueue, addJob } from "@techstream/quark-core";
+import { JOB_TYPES } from "@__QUARK_SCOPE__/jobs";
+const queue = createQueue("default");
+await addJob(queue, JOB_TYPES.MY_JOB, { userId });
+
+// Handle (apps/worker/src/handlers/):
+import { createLogger } from "@techstream/quark-core";
+const log = createLogger("job:my-job");
+export async function handleMyJob({ data }) { log.info("processing", data); }
+```
+
+---
+
+## Testing
+
+```javascript
+import { test } from "node:test";
+import assert from "node:assert";
+
+test("feature", async (t) => {
+  await t.test("does X", async () => {
+    assert.strictEqual(actual, expected);
+  });
+});
+```
+
+---
+
+## Environment
+
+New env vars must be registered in `packages/config/src/validate-env.js` before use. Load config via `loadConfig()` from `@__QUARK_SCOPE__/config`.
+
+---
+
+## Deployment
+
+Railway: two services (`web` + `worker`). Migrations auto-run on deploy via `releaseCommand` in `apps/web/railway.json`. Env vars managed in Railway dashboard — never committed.

package/templates/base-project/.github/copilot-instructions.md

@@ -5,3 +5,58 @@
 <file>.github/skills/project-context/SKILL.md</file>
 </skill>
 </skills>
+
+# __QUARK_PROJECT_NAME__ — Project Conventions
+
+> Scaffolded with Quark on __QUARK_SCAFFOLD_DATE__. Package scope: `@__QUARK_SCOPE__`
+> Also see `CLAUDE.md` at the project root for the full context reference.
+
+## Non-Negotiable Rules
+
+- **ESM only** — `import`/`export` everywhere. Never `require()`.
+- **No TypeScript** — `.js` and `.jsx` only.
+- **Validate at every boundary** — Zod schemas on all Server Actions and API routes.
+- **Errors** — `AppError` / `ValidationError` from `@techstream/quark-core/errors`. Never `throw new Error()`.
+- **Logging** — `createLogger(name)` from `@techstream/quark-core`. No `console.log` in production code.
+- **DB models** — Always add `createdAt` and `updatedAt` to every Prisma model.
+- **Workspace imports** — Use `@__QUARK_SCOPE__/*` for local packages (`db`, `config`, `ui`, `jobs`). Never `@techstream/quark-db` etc.
+- **Tests** — Co-located `*.test.js`, run with `node --test`.
+
+## Import Patterns
+
+```javascript
+// Workspace packages:
+import { prisma, user }          from "@__QUARK_SCOPE__/db";
+import { loadConfig }            from "@__QUARK_SCOPE__/config";
+import { Button, Card, Input }   from "@__QUARK_SCOPE__/ui";
+import { JOB_TYPES }             from "@__QUARK_SCOPE__/jobs";
+
+// Published runtime:
+import { AppError, ValidationError } from "@techstream/quark-core/errors";
+import { createLogger, getCurrentSession, createQueue, addJob } from "@techstream/quark-core";
+```
+
+## UI & Design System
+
+Components from `@__QUARK_SCOPE__/ui` — Tailwind-only, Server Component safe:
+`Button`, `Input`, `Label`, `Textarea`, `Select`, `Checkbox`, `Badge`,
+`Card`/`CardHeader`/`CardTitle`/`CardContent`/`CardFooter`,
+`Table`/`TableHeader`/`TableBody`/`TableRow`/`TableHead`/`TableCell`,
+`Skeleton`, `Dialog` *(client)*, `Toast`/`useToast` *(client)*.
+
+All accept `className`. Never import from `@/components/ui/*`.
+
+## Standard Patterns
+
+```javascript
+// Server Action:
+"use server";
+const parsed = schema.safeParse(Object.fromEntries(formData));
+if (!parsed.success) throw new ValidationError(parsed.error.flatten());
+const session = await getCurrentSession();
+if (!session) throw new AppError("Unauthorized", 401);
+
+// New env var: register in packages/config/src/validate-env.js first.
+// New DB model: schema.prisma → pnpm db:generate → pnpm db:migrate.
+// New job: define type in packages/jobs/src/index.js, handler in apps/worker/src/handlers/.
+```

package/templates/base-project/CLAUDE.md

@@ -0,0 +1,273 @@
+# __QUARK_PROJECT_NAME__ — AI Context
+
+> Scaffolded with [Quark](https://github.com/Bobnoddle/quark) on __QUARK_SCAFFOLD_DATE__.
+> **Keep this file updated** as your project grows — it's what Claude Code, Cursor, and other AI tools read first.
+
+## Quick Start
+
+```bash
+docker compose up -d     # Start PostgreSQL, Redis, Mailpit
+pnpm install             # Install dependencies
+pnpm db:generate         # Generate Prisma client
+pnpm db:migrate          # Apply database migrations
+pnpm db:seed             # Seed development data
+pnpm dev                 # Start web + worker
+```
+
+## Scaffolding Another Project (non-interactive)
+
+```bash
+# With default features (ui + jobs):
+npx @techstream/quark-create-app my-app --no-prompts
+
+# With specific features:
+npx @techstream/quark-create-app my-app --no-prompts --features ui,jobs
+npx @techstream/quark-create-app my-app --no-prompts --features ui,jobs,admin
+npx @techstream/quark-create-app my-app --no-prompts --features ""    # minimal (db + config only)
+```
+
+## Project Structure
+
+```
+__QUARK_PROJECT_NAME__/
+├── apps/
+│   ├── web/                  # Next.js 16 (App Router, Server Actions)
+│   └── worker/               # BullMQ background worker
+├── packages/
+│   ├── db/                   # Prisma schema, client, query functions
+│   ├── config/               # Environment validation & shared config
+__QUARK_OPTIONAL_PACKAGES__├── docker-compose.yml
+├── .env                      # Local environment secrets (never commit)
+└── .env.example              # Template — copy to .env to get started
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Framework | Next.js 16 (App Router) |
+| Language | JavaScript — ESM only, no TypeScript |
+| Database | PostgreSQL 16 + Prisma 7 |
+| Queue | BullMQ + Redis 7 |
+| Auth | NextAuth v5 |
+| Validation | Zod 4 |
+| UI | Tailwind CSS + `@__QUARK_SCOPE__/ui` components |
+| Email | Nodemailer (Mailpit local / Resend or Zeptomail prod) |
+| Storage | Local filesystem or S3/R2 (pluggable via `STORAGE_PROVIDER`) |
+| Logging | Structured logger via `createLogger()` from `@techstream/quark-core` |
+| Metrics | Prometheus via `metrics` singleton from `@techstream/quark-core` |
+| Testing | Node.js built-in `node --test` |
+| Linting | Biome |
+| Monorepo | Turborepo + pnpm workspaces |
+| Deployment | Railway (web service + worker service) |
+
+## Package Imports
+
+```javascript
+// Published (installed from npm) — use @techstream/ prefix:
+import { AppError, ValidationError, NotFoundError, UnauthorizedError } from "@techstream/quark-core/errors";
+import { createLogger } from "@techstream/quark-core";
+import { getCurrentSession } from "@techstream/quark-core";
+import { createQueue, addJob } from "@techstream/quark-core";
+import { metrics } from "@techstream/quark-core";
+import { cache } from "@techstream/quark-core";
+import { rateLimit } from "@techstream/quark-core";
+import { storage } from "@techstream/quark-core";
+
+// Workspace packages — ALWAYS use @__QUARK_SCOPE__/* (never @techstream/quark-*):
+import { prisma, user } from "@__QUARK_SCOPE__/db";         // add more as you create query helpers
+import { loadConfig } from "@__QUARK_SCOPE__/config";
+import { Button, Card, Input } from "@__QUARK_SCOPE__/ui";   // if ui package selected
+import { JOB_TYPES } from "@__QUARK_SCOPE__/jobs";           // if jobs package selected
+```
+
+## UI & Design System
+
+All UI components come from `@__QUARK_SCOPE__/ui`. They are Tailwind-only, dependency-free, and Server Component-safe.
+
+**Available components:**
+- `Button`, `Input`, `Label`, `Textarea`, `Select`, `Checkbox` — form primitives
+- `Badge` — status labels
+- `Card` / `CardHeader` / `CardTitle` / `CardContent` / `CardFooter` — content containers
+- `Table` / `TableHeader` / `TableBody` / `TableRow` / `TableHead` / `TableCell` — data tables
+- `Skeleton` — loading placeholders
+- `Dialog` *(client)* — modal dialogs
+- `Toast` / `useToast` *(client)* — notifications
+
+**Rules:**
+- All styling via Tailwind CSS utility classes. No inline styles, no CSS modules.
+- Import from `@__QUARK_SCOPE__/ui` — never from `@/components/ui/*` or direct paths.
+- Every component accepts `className` for Tailwind overrides.
+- Loading states → `<Skeleton>` / `<Suspense>`.
+- User feedback → `useToast()` hook (client component).
+- Modals → `<Dialog>` (mark parent as `"use client"`).
+- Server Components are the default — only add `"use client"` when the component uses hooks, browser APIs, or the marked client components above.
+
+## Server Actions (preferred for all mutations)
+
+```javascript
+"use server";
+import { z } from "zod";
+import { ValidationError, AppError } from "@techstream/quark-core/errors";
+import { getCurrentSession } from "@techstream/quark-core";
+import { createLogger } from "@techstream/quark-core";
+import { prisma } from "@__QUARK_SCOPE__/db";
+
+const log = createLogger("action:example");
+
+const schema = z.object({
+  title: z.string().min(1).max(255),
+  body:  z.string().optional(),
+});
+
+export async function createExample(formData) {
+  const session = await getCurrentSession();
+  if (!session) throw new AppError("Unauthorized", 401);
+
+  const parsed = schema.safeParse(Object.fromEntries(formData));
+  if (!parsed.success) throw new ValidationError(parsed.error.flatten());
+
+  const result = await prisma.example.create({ data: parsed.data });
+  log.info("created", { id: result.id });
+  return result;
+}
+```
+
+## API Routes
+
+```javascript
+// apps/web/src/app/api/example/route.js
+import { NextResponse } from "next/server";
+import { AppError } from "@techstream/quark-core/errors";
+import { createLogger } from "@techstream/quark-core";
+
+const log = createLogger("api:example");
+
+export async function GET(request) {
+  try {
+    // ... logic
+    return NextResponse.json({ data });
+  } catch (error) {
+    log.error("request failed", { error });
+    if (error instanceof AppError) {
+      return NextResponse.json({ error: error.message }, { status: error.statusCode });
+    }
+    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
+  }
+}
+```
+
+## Database
+
+- Schema: `packages/db/prisma/schema.prisma`
+- Query helpers: `packages/db/src/queries.js`
+- Every model **must** include `createdAt DateTime @default(now())` and `updatedAt DateTime @updatedAt`.
+- After any schema change: `pnpm db:generate` then `pnpm db:migrate`.
+
+```javascript
+// Add query functions in packages/db/src/queries.js:
+export const example = {
+  findMany: (args) => prisma.example.findMany(args),
+  findById: (id)   => prisma.example.findUnique({ where: { id } }),
+  create:   (data) => prisma.example.create({ data }),
+  update:   (id, data) => prisma.example.update({ where: { id }, data }),
+  delete:   (id)   => prisma.example.delete({ where: { id } }),
+};
+```
+
+Do not call `prisma.*` directly inside pages or Server Actions — use the query helper functions.
+
+## Auth & Authorization
+
+```javascript
+import { getCurrentSession } from "@techstream/quark-core";
+
+// Server Component — check session:
+const session = await getCurrentSession();
+if (!session) redirect("/login");
+
+// Server Action — guard:
+const session = await getCurrentSession();
+if (!session) throw new AppError("Unauthorized", 401);
+
+// Role check (ADMIN | VIEWER defined in Prisma schema):
+if (session.user.role !== "ADMIN") throw new AppError("Forbidden", 403);
+```
+
+## Background Jobs (if jobs package selected)
+
+```javascript
+// 1. Dispatch from web (Server Action or API route):
+import { createQueue, addJob } from "@techstream/quark-core";
+import { JOB_TYPES } from "@__QUARK_SCOPE__/jobs";
+const queue = createQueue("default");
+await addJob(queue, JOB_TYPES.SEND_EMAIL, { userId: session.user.id, template: "welcome" });
+
+// 2. Handle in apps/worker/src/handlers/<job-name>.js:
+import { createLogger } from "@techstream/quark-core";
+const log = createLogger("job:send-email");
+export async function handleSendEmail({ data }) {
+  log.info("processing", data);
+  // ... job logic
+}
+```
+
+## Environment Variables
+
+Validated at startup in `packages/config/src/validate-env.js`. **Always add new env vars there before using them.**
+
+Config loaded via `loadConfig()` from `@__QUARK_SCOPE__/config`.
+
+Key variables:
+| Variable | Purpose |
+|---|---|
+| `DATABASE_URL` / `POSTGRES_*` | PostgreSQL connection |
+| `REDIS_URL` / `REDIS_HOST` + `REDIS_PORT` | Redis connection |
+| `NEXTAUTH_SECRET` | Auth JWT encryption (`openssl rand -base64 32`) |
+| `APP_URL` | Production domain (auto-derived from `PORT` in dev) |
+| `STORAGE_PROVIDER` | `local` (default) or `s3` |
+| `APP_NAME` / `APP_DESCRIPTION` | Used in metadata, emails, page titles |
+
+## Testing
+
+```javascript
+import { test } from "node:test";
+import assert from "node:assert";
+
+test("feature name", async (t) => {
+  await t.test("does the thing", async () => {
+    // arrange → act → assert
+    assert.strictEqual(actual, expected);
+  });
+});
+```
+
+- Tests are co-located: `feature.test.js` lives next to `feature.js`.
+- Run all: `pnpm test` | Run one package: `pnpm --filter @__QUARK_SCOPE__/web test`.
+- Test utilities and model factories: `@techstream/quark-core/testing`.
+
+## Deployment
+
+Railway with two services: **web** (`apps/web`) and **worker** (`apps/worker`).
+
+- Migrations run automatically on every deploy via `releaseCommand` in `apps/web/railway.json`.
+- Environment variables live in Railway dashboard — never in committed files.
+- Staging: auto-deploys on push to `main`. Production: deploy from a version tag.
+- Generate a production seed: `SEED_PROFILE=minimal pnpm db:seed`.
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `packages/db/prisma/schema.prisma` | Database schema — edit this to add models |
+| `packages/db/src/queries.js` | Database query functions — add helpers here |
+| `packages/config/src/validate-env.js` | Environment variable validation — register new vars here |
+| `apps/web/src/app/` | Next.js pages and API routes |
+| `apps/web/src/lib/auth.js` | NextAuth configuration |
+| `apps/worker/src/handlers/` | Background job handler functions |
+| `packages/ui/src/` | UI component source |
+| `.github/skills/project-context/SKILL.md` | VS Code Copilot skill context |
+
+---
+
+*Update this file whenever you make structural changes: new packages, deployment targets, major new conventions, or significant architectural decisions. The AI tools you use daily depend on it being accurate.*

package/templates/base-project/README.md

@@ -1,49 +1,91 @@
-# My Quark Project
+# __QUARK_PROJECT_NAME__
 
-A modern, scalable monorepo built with Quark.
+Scaffolded with [Quark](https://github.com/Bobnoddle/quark) on __QUARK_SCAFFOLD_DATE__.
 
-## Quick Start
+## Local Development
 
 ```bash
-pnpm install
-docker compose up -d
-pnpm db:migrate
-pnpm dev
+docker compose up -d   # Start PostgreSQL, Redis, Mailpit
+pnpm install           # Install dependencies
+pnpm db:migrate        # Apply migrations
+pnpm dev               # Start web + worker
 ```
 
-Open http://localhost:3000
+Open [http://localhost:3000](http://localhost:3000)
 
-## Services
+## Database
 
-- **Docker**: `docker compose up -d`
-- **Database**: PostgreSQL
-- **Cache**: Redis
-- **Email**: Mailpit
+| Task | Command |
+|------|---------|
+| Run migrations | `pnpm db:migrate` |
+| Push schema (no migration) | `pnpm db:push` |
+| Generate Prisma client | `pnpm db:generate` |
+| Seed database | `pnpm db:seed` |
+| Open Prisma Studio | `pnpm db:studio` |
 
-## Development
+## Other Commands
 
 ```bash
-# Build all packages
-pnpm build
+pnpm build    # Build all packages
+pnpm test     # Run all tests (requires Docker)
+pnpm lint     # Lint + format check (Biome)
+```
 
-# Run tests
-pnpm test
+## Launch
 
-# Lint
-pnpm lint
+### 1. Push to GitHub
+
+```bash
+gh repo create __QUARK_PROJECT_NAME__ --private --source=. --push
 ```
 
-## Database
+No `gh` CLI? Go to [github.com/new](https://github.com/new), create the repo, then:
 
-| Task | Command |
-|------|--------|
-| Run migrations | `pnpm db:migrate` |
-| Push schema (no migration) | `pnpm db:push` |
-| Generate Prisma client | `pnpm db:generate` |
-| Seed database | `pnpm db:seed` |
-| Open Prisma Studio | `pnpm db:studio` |
+```bash
+git remote add origin https://github.com/<you>/__QUARK_PROJECT_NAME__.git
+git push -u origin main
+```
+
+### 2. Deploy on Railway
+
+> **One-click Railway template coming soon.** For now, follow these steps:
+
+1. Go to [railway.app](https://railway.app) → **New Project** → **Deploy from GitHub repo** → select `__QUARK_PROJECT_NAME__`
+2. In the service → **Settings** → **Source** → set **Config File** to `apps/web/railway.json`
+3. In the project → **+ New** → **Database** → **Add PostgreSQL** (injects `DATABASE_URL` automatically)
+4. In the project → **+ New** → **Database** → **Add Redis** (injects `REDIS_URL` automatically)
+5. In your web service → **Variables** → add:
+   - `NEXTAUTH_SECRET` → run `openssl rand -base64 32` locally and paste the result
+   - `APP_URL` → your Railway public domain (e.g. `https://__QUARK_PROJECT_NAME__.railway.app`)
+6. *(If you included the worker)* **+ New** → **GitHub Repo** → same repo → **Config File** → `apps/worker/railway.json`
+
+Railway auto-deploys on every push to `main`. Migrations run automatically before each deploy.
+
+## AI-Assisted Development
+
+This project ships with pre-loaded context for Claude Code, Cursor, GitHub Copilot, and others — see `CLAUDE.md` for the full reference.
+
+**Suggested first prompt:**
+
+> I'm building __QUARK_PROJECT_NAME__ — [describe what your app does in one sentence].
+>
+> Start by reviewing `CLAUDE.md` so you understand the full stack, then:
+> 1. Add the Prisma models we need to `packages/db/prisma/schema.prisma`
+> 2. Create the query helpers in `packages/db/src/queries.js`
+> 3. Build the first page in `apps/web/src/app/` using our UI component system
+
+Replace that bracketed description with what you're actually building, and the AI has everything it needs.
 
 ## Structure
 
-- `apps/` - Applications (web, worker, etc.)
-- `packages/` - Shared packages (ui, jobs, config, core, db, cli)
+```
+__QUARK_PROJECT_NAME__/
+├── apps/
+│   ├── web/         # Next.js 16 (App Router, Server Actions)
+│   └── worker/      # BullMQ background worker
+├── packages/
+│   ├── db/          # Prisma schema + query helpers
+│   └── config/      # Environment validation
+├── docker-compose.yml
+└── CLAUDE.md        # AI tool context — keep this updated
+```

package/templates/base-project/apps/web/next.config.js

@@ -43,8 +43,12 @@ const nextConfig = {
 					},
 					{
 						key: "Content-Security-Policy",
+						// unsafe-eval is required by Turbopack in development only.
+						// It is deliberately excluded from the production directive.
 						value:
-							"default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';",
+							process.env.NODE_ENV !== "production"
+								? "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';"
+								: "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self';",
 					},
 				],
 			},

package/templates/base-project/apps/web/package.json

@@ -12,8 +12,8 @@
 	},
 	"dependencies": {
 		"@auth/prisma-adapter": "^2.11.1",
-		"@aws-sdk/client-s3": "^3.1002.0",
-		"@aws-sdk/s3-request-presigner": "^3.1002.0",
+		"@aws-sdk/client-s3": "^3.1004.0",
+		"@aws-sdk/s3-request-presigner": "^3.1004.0",
 		"@techstream/quark-core": "^1.0.0",
 		"@techstream/quark-db": "workspace:*",
 		"@techstream/quark-jobs": "workspace:*",
@@ -28,7 +28,7 @@
 	},
 	"devDependencies": {
 		"@tailwindcss/postcss": "^4.2.1",
-		"@types/node": "^25.3.3",
+		"@types/node": "^25.3.5",
 		"tailwindcss": "^4.2.1",
 		"@techstream/quark-config": "workspace:*"
 	}