@techstream/quark-create-app 1.8.0 → 1.10.0

package/src/utils.js

@@ -0,0 +1,36 @@
+/**
+ * Shared utilities for @techstream/quark-create-app
+ */
+
+/**
+ * Format a project slug into a human-friendly application name.
+ *
+ * - Hyphens, underscores, and dots are treated as word separators
+ * - Each word is title-cased
+ * - Degenerate inputs (all separators) fall back to "Quark App"
+ *
+ * @param {string} projectName - Raw project slug (e.g. "my-cool-app")
+ * @returns {string} Title-cased display name (e.g. "My Cool App")
+ *
+ * @example
+ * formatProjectDisplayName("my-cool-app")   // "My Cool App"
+ * formatProjectDisplayName("my.app")         // "My App"
+ * formatProjectDisplayName("my_app_v2")      // "My App V2"
+ * formatProjectDisplayName("myapp")          // "Myapp"
+ * formatProjectDisplayName("---")            // "Quark App"
+ */
+export function formatProjectDisplayName(projectName) {
+	const normalized = projectName
+		.replace(/[-_.]+/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+
+	if (!normalized) {
+		return "Quark App";
+	}
+
+	return normalized
+		.split(" ")
+		.map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+		.join(" ");
+}

package/src/utils.test.js

@@ -0,0 +1,63 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { formatProjectDisplayName } from "./utils.js";
+
+// ---------------------------------------------------------------------------
+// Happy path — common slug patterns
+// ---------------------------------------------------------------------------
+
+test("formatProjectDisplayName - hyphen-separated slug", () => {
+	assert.strictEqual(formatProjectDisplayName("my-cool-app"), "My Cool App");
+});
+
+test("formatProjectDisplayName - underscore-separated slug", () => {
+	assert.strictEqual(formatProjectDisplayName("my_app_v2"), "My App V2");
+});
+
+test("formatProjectDisplayName - dot-separated slug", () => {
+	assert.strictEqual(formatProjectDisplayName("my.app"), "My App");
+});
+
+test("formatProjectDisplayName - single word (no separators)", () => {
+	assert.strictEqual(formatProjectDisplayName("myapp"), "Myapp");
+});
+
+test("formatProjectDisplayName - already title-cased input", () => {
+	// slice(1) preserves remaining chars as-is — only the first char is forced uppercase
+	assert.strictEqual(formatProjectDisplayName("MyApp"), "MyApp");
+});
+
+test("formatProjectDisplayName - mixed separators", () => {
+	assert.strictEqual(formatProjectDisplayName("my-app_v2.0"), "My App V2 0");
+});
+
+test("formatProjectDisplayName - consecutive separators collapse to single space", () => {
+	assert.strictEqual(formatProjectDisplayName("my--app"), "My App");
+	assert.strictEqual(formatProjectDisplayName("my___app"), "My App");
+	assert.strictEqual(formatProjectDisplayName("my-._app"), "My App");
+});
+
+test("formatProjectDisplayName - numbers preserved in words", () => {
+	assert.strictEqual(formatProjectDisplayName("app-v2"), "App V2");
+	assert.strictEqual(formatProjectDisplayName("project-123"), "Project 123");
+});
+
+// ---------------------------------------------------------------------------
+// Edge cases — degenerate / boundary inputs
+// ---------------------------------------------------------------------------
+
+test("formatProjectDisplayName - all separators returns fallback", () => {
+	assert.strictEqual(formatProjectDisplayName("---"), "Quark App");
+	assert.strictEqual(formatProjectDisplayName("___"), "Quark App");
+	assert.strictEqual(formatProjectDisplayName("..."), "Quark App");
+	assert.strictEqual(formatProjectDisplayName("-._-"), "Quark App");
+});
+
+test("formatProjectDisplayName - preserves casing of rest of word", () => {
+	// The function only forces the first char uppercase; the remainder is untouched
+	assert.strictEqual(formatProjectDisplayName("myApp"), "MyApp");
+});
+
+test("formatProjectDisplayName - short single-char name", () => {
+	assert.strictEqual(formatProjectDisplayName("a"), "A");
+});

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/.github/workflows/release.yml

@@ -3,9 +3,13 @@ name: Release
 on:
   workflow_dispatch:
     inputs:
-      notes:
-        description: "Release notes (optional — auto-generated if blank)"
+      prerelease:
+        description: "Tag as pre-release (staging-only, skips production deploy)"
         required: false
+        default: false
+        type: boolean
+
+concurrency: ${{ github.workflow }}
 
 permissions:
   contents: write
@@ -17,22 +21,47 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with:
+          ref: main
           fetch-depth: 0
 
-      - name: Generate date-based tag
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Push to production branch
+        if: ${{ !inputs.prerelease }}
+        run: |
+          git fetch origin
+          if git ls-remote --exit-code --heads origin production > /dev/null; then
+            git checkout production && git merge --ff-only origin/main
+          else
+            git checkout -b production origin/main
+          fi
+          git push origin production
+          git checkout main
+
+      - name: Generate tag
         id: tag
         run: |
           BASE="v$(date +%Y.%m.%d)"
-          EXISTING=$(git tag -l "${BASE}*" | wc -l | tr -d ' ')
+          SUFFIX="${{ inputs.prerelease && '-rc' || '' }}"
+          # Count only exact-format matches to avoid rc tags polluting production counts
+          EXISTING=$(git tag -l | grep -cE "^${BASE}${SUFFIX}(\.[0-9]+)?$" || true)
           if [ "$EXISTING" -eq "0" ]; then
-            echo "tag=${BASE}" >> "$GITHUB_OUTPUT"
+            echo "tag=${BASE}${SUFFIX}" >> "$GITHUB_OUTPUT"
           else
-            echo "tag=${BASE}.${EXISTING}" >> "$GITHUB_OUTPUT"
+            echo "tag=${BASE}${SUFFIX}.${EXISTING}" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Tag release
+        run: |
+          git tag -a "${{ steps.tag.outputs.tag }}" -m "Release ${{ steps.tag.outputs.tag }}"
+          git push origin "${{ steps.tag.outputs.tag }}"
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@v2
         with:
           tag_name: ${{ steps.tag.outputs.tag }}
-          generate_release_notes: ${{ github.event.inputs.notes == '' }}
-          body: ${{ github.event.inputs.notes }}
+          generate_release_notes: true
+          prerelease: ${{ inputs.prerelease }}

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.*