create-tigra 2.5.0 → 2.6.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/bin/create-tigra.js +5 -2
  2. package/package.json +1 -1
  3. package/template/_claude/commands/create-client.md +1 -1
  4. package/template/_claude/rules/client/01-project-structure.md +8 -0
  5. package/template/_claude/rules/client/04-design-system.md +162 -45
  6. package/template/_claude/rules/client/core.md +8 -6
  7. package/template/_claude/rules/global/completion-reports.md +178 -0
  8. package/template/_claude/rules/global/core.md +6 -0
  9. package/template/client/.env.example.production +5 -0
  10. package/template/client/README.md +1 -1
  11. package/template/client/src/app/error.tsx +1 -1
  12. package/template/client/src/app/globals.css +33 -85
  13. package/template/client/src/app/layout.tsx +6 -6
  14. package/template/client/src/app/page.tsx +10 -3
  15. package/template/client/src/components/common/ThemeSwitcher.tsx +112 -0
  16. package/template/client/src/components/layout/Header.tsx +1 -1
  17. package/template/client/src/features/auth/components/AuthInitializer.tsx +1 -1
  18. package/template/client/src/features/auth/components/LoginForm.tsx +1 -1
  19. package/template/client/src/features/auth/components/RegisterForm.tsx +1 -1
  20. package/template/client/src/features/auth/services/auth.service.ts +0 -4
  21. package/template/client/src/lib/constants/api-endpoints.ts +0 -2
  22. package/template/client/src/styles/fonts/inter-jetbrains.css +16 -0
  23. package/template/client/src/styles/themes/electric-indigo.css +90 -0
  24. package/template/client/src/styles/themes/ocean-teal.css +90 -0
  25. package/template/client/src/styles/themes/rose-pink.css +90 -0
  26. package/template/client/src/styles/themes/warm-orange.css +90 -0
  27. package/template/server/prisma/schema.prisma +0 -1
  28. package/template/server/src/modules/admin/admin.controller.ts +3 -9
  29. package/template/server/src/modules/admin/admin.routes.ts +7 -0
  30. package/template/server/src/modules/admin/admin.schemas.ts +13 -0
  31. package/template/server/src/modules/auth/auth.repo.ts +9 -8
  32. package/template/server/postman_collection.json +0 -666
@@ -12,6 +12,9 @@ import crypto from 'crypto';
12
12
  const __filename = fileURLToPath(import.meta.url);
13
13
  const __dirname = path.dirname(__filename);
14
14
 
15
+ const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
16
+ const VERSION = packageJson.version;
17
+
15
18
  const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
16
19
 
17
20
  // Files that contain template variables and need replacement
@@ -126,11 +129,11 @@ async function main() {
126
129
  program
127
130
  .name('create-tigra')
128
131
  .description('Create a production-ready full-stack app with Next.js + Fastify + Prisma + Redis')
129
- .version('2.1.0')
132
+ .version(VERSION)
130
133
  .argument('[project-name]', 'Name for your new project')
131
134
  .action(async (projectNameArg) => {
132
135
  console.log();
133
- console.log(chalk.bold(' Create Tigra') + chalk.dim(' v2.1.0'));
136
+ console.log(chalk.bold(' Create Tigra') + chalk.dim(` v${VERSION}`));
134
137
  console.log();
135
138
 
136
139
  let projectName = projectNameArg;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-tigra",
3
- "version": "2.5.0",
3
+ "version": "2.6.5",
4
4
  "type": "module",
5
5
  "description": "Create a production-ready full-stack app with Next.js 16 + Fastify 5 + Prisma + Redis",
6
6
  "bin": {
@@ -463,7 +463,7 @@ export function Providers({ children }: { children: React.ReactNode }): React.Re
463
463
 
464
464
  #### `src/app/layout.tsx`
465
465
  Root layout:
466
- - Import and use `next/font` (Inter or Geist Sans)
466
+ - Import and use `next/font/google` (fonts defined by the active font preset — default: Inter + JetBrains Mono)
467
467
  - `<html lang="en" suppressHydrationWarning>`
468
468
  - Wrap children in `<Providers>`
469
469
  - Default metadata with app name
@@ -32,6 +32,14 @@ src/
32
32
  │ ├── store/ # <domain>Slice.ts (if needed)
33
33
  │ ├── types/ # <domain>.types.ts
34
34
  │ └── actions/ # <domain>.actions.ts (Server Actions)
35
+ ├── styles/
36
+ │ ├── themes/ # Color theme presets (switch in globals.css import)
37
+ │ │ ├── warm-orange.css # Default — earthy, warm
38
+ │ │ ├── electric-indigo.css
39
+ │ │ ├── ocean-teal.css
40
+ │ │ └── rose-pink.css
41
+ │ └── fonts/ # Font presets (switch in globals.css import)
42
+ │ └── inter-jetbrains.css # Default — Inter + JetBrains Mono
35
43
  ├── hooks/ # Global hooks (useDebounce, useLocalStorage, useMediaQuery)
36
44
  ├── lib/
37
45
  │ ├── api/ # axios.config.ts, api.types.ts
@@ -14,60 +14,177 @@ Clean, airy, "expensive" look inspired by Linear, Vercel, Stripe, Arc. Every vis
14
14
 
15
15
  This project uses **Tailwind CSS v4** with **OKLCH color space** and the `@theme inline` directive (not the legacy `tailwind.config.ts`).
16
16
 
17
+ **Key differences from Tailwind v3:**
18
+ - No `tailwind.config.ts` — all config is CSS-based via `@theme inline`
19
+ - Colors use **OKLCH** (perceptually uniform) not HSL
20
+ - `@custom-variant dark` replaces `darkMode: 'class'`
21
+ - No `@layer base { :root { } }` — variables defined on `:root` via theme preset files
22
+
23
+ ---
24
+
25
+ ## Theme Preset System (Color Management)
26
+
27
+ **ALL color variables live in theme preset files, NOT in `globals.css`.** This is the single source of truth for the entire app's color palette.
28
+
29
+ ### How It Works
30
+
31
+ ```
32
+ src/
33
+ ├── app/globals.css ← imports ONE theme preset (switch here)
34
+ └── styles/themes/
35
+ ├── warm-orange.css ← Earthy, warm (default)
36
+ ├── electric-indigo.css ← Modern, bold, tech-forward
37
+ ├── ocean-teal.css ← Calm, professional
38
+ └── rose-pink.css ← Elegant, creative
39
+ ```
40
+
41
+ `globals.css` imports the active theme via a single line:
42
+
17
43
  ```css
18
- /* app/globals.css */
19
- @import "tailwindcss";
20
- @import "tw-animate-css";
21
- @import "shadcn/tailwind.css";
22
-
23
- @custom-variant dark (&:is(.dark *));
24
-
25
- @theme inline {
26
- --color-background: var(--background);
27
- --color-foreground: var(--foreground);
28
- --font-sans: var(--font-geist-sans);
29
- --font-mono: var(--font-geist-mono);
30
- /* ... maps all semantic tokens to Tailwind */
31
- }
44
+ @import "../styles/themes/warm-orange.css";
45
+ ```
46
+
47
+ **To switch the entire palette**: change that ONE import line. That's it. Every color in the app updates instantly — light mode, dark mode, charts, sidebar, everything.
32
48
 
49
+ ### Theme Preset Structure
50
+
51
+ Each preset file defines ALL semantic color variables for both `:root` (light) and `.dark` (dark mode):
52
+
53
+ ```css
33
54
  :root {
34
55
  --radius: 0.625rem;
35
- --background: oklch(1 0 0);
36
- --foreground: oklch(0.145 0 0);
37
- --primary: oklch(0.45 0.2 260);
38
- --primary-foreground: oklch(0.985 0 0);
39
- --secondary: oklch(0.97 0 0);
40
- --secondary-foreground: oklch(0.205 0 0);
41
- --muted: oklch(0.97 0 0);
42
- --muted-foreground: oklch(0.556 0 0);
43
- --accent: oklch(0.97 0 0);
44
- --accent-foreground: oklch(0.205 0 0);
45
- --destructive: oklch(0.577 0.245 27.325);
46
- --border: oklch(0.922 0 0);
47
- --input: oklch(0.922 0 0);
48
- --ring: oklch(0.45 0.2 260);
49
- --success: oklch(0.52 0.17 155);
50
- --success-foreground: oklch(1 0 0);
51
- --warning: oklch(0.75 0.18 75);
52
- --warning-foreground: oklch(0.2 0 0);
53
- --info: oklch(0.55 0.15 240);
54
- --info-foreground: oklch(1 0 0);
55
- --chart-1 through --chart-5 /* Data visualization colors */
56
- --sidebar, --sidebar-foreground, etc. /* Sidebar-specific tokens */
56
+ --background: oklch(...);
57
+ --foreground: oklch(...);
58
+ --primary: oklch(...);
59
+ --primary-foreground: oklch(...);
60
+ /* ... all ~35 semantic tokens */
57
61
  }
58
62
 
59
63
  .dark {
60
- --background: oklch(0.145 0 0);
61
- --foreground: oklch(0.985 0 0);
64
+ --background: oklch(...);
65
+ --foreground: oklch(...);
66
+ --primary: oklch(...);
62
67
  /* ... dark mode overrides for all tokens */
63
68
  }
64
69
  ```
65
70
 
66
- **Key differences from Tailwind v3:**
67
- - No `tailwind.config.ts` — all config is CSS-based via `@theme inline`
68
- - Colors use **OKLCH** (perceptually uniform) not HSL
69
- - `@custom-variant dark` replaces `darkMode: 'class'`
70
- - No `@layer base { :root { } }` — variables defined directly on `:root`
71
+ ### Creating a Custom Theme
72
+
73
+ 1. Copy any existing preset file (e.g., `warm-orange.css`)
74
+ 2. Rename it (e.g., `my-brand.css`)
75
+ 3. Edit the OKLCH values to match your brand palette
76
+ 4. Update the import in `globals.css`: `@import "../styles/themes/my-brand.css";`
77
+
78
+ ### Available Presets
79
+
80
+ | Preset | Accent | Vibe | Inspired by |
81
+ |--------|--------|------|-------------|
82
+ | `warm-orange.css` | Terracotta orange | Earthy, warm, approachable | Claude |
83
+ | `electric-indigo.css` | Deep indigo-violet | Modern, bold, tech-forward | Linear, Figma |
84
+ | `ocean-teal.css` | Deep teal-cyan | Calm, professional, trustworthy | Stripe, Vercel |
85
+ | `rose-pink.css` | Soft rose-magenta | Elegant, creative, premium | Dribbble, Notion |
86
+
87
+ ### CRITICAL RULES — Color Management
88
+
89
+ 1. **NEVER add or modify color variables directly in `globals.css`.** All `:root` and `.dark` color variables belong in the active theme preset file only.
90
+ 2. **NEVER hardcode OKLCH/hex/rgb values in components.** Always use semantic tokens (`bg-primary`, `text-foreground`).
91
+ 3. **To change the brand palette**: switch the import in `globals.css` or edit the active preset file. Never scatter color values across multiple files.
92
+ 4. **New semantic tokens**: If you need a new color token (rare), add it to ALL preset files to keep them in sync.
93
+ 5. **The `@theme inline` block in `globals.css` maps CSS vars to Tailwind** — it does NOT define colors. Colors come from the preset.
94
+
95
+ ---
96
+
97
+ ## Font Preset System (Font Management)
98
+
99
+ **Font families are defined in font preset files, NOT hardcoded in components.** This mirrors the color theme preset system — switch the entire font pairing by changing one import.
100
+
101
+ ### How It Works
102
+
103
+ ```
104
+ src/
105
+ ├── app/
106
+ │ ├── layout.tsx ← loads fonts via next/font/google
107
+ │ └── globals.css ← imports ONE font preset (switch here)
108
+ └── styles/fonts/
109
+ └── inter-jetbrains.css ← Default (Inter + JetBrains Mono)
110
+ ```
111
+
112
+ ### Three Semantic Font Roles
113
+
114
+ | Role | CSS Variable | Tailwind Class | Default Font |
115
+ |------|-------------|----------------|--------------|
116
+ | Body text | `--font-sans-value` | `font-sans` | Inter |
117
+ | Headings | `--font-heading-value` | `font-heading` | Inter |
118
+ | Code/mono | `--font-mono-value` | `font-mono` | JetBrains Mono |
119
+
120
+ ### How to Switch Fonts
121
+
122
+ Switching fonts requires two changes:
123
+
124
+ **Step 1 — Update font imports in `layout.tsx`:**
125
+
126
+ ```tsx
127
+ // Change these imports to your desired fonts
128
+ import { Roboto, Fira_Code } from 'next/font/google';
129
+
130
+ const roboto = Roboto({
131
+ variable: '--font-roboto',
132
+ subsets: ['latin'],
133
+ weight: ['400', '500', '600', '700'],
134
+ });
135
+
136
+ const firaCode = Fira_Code({
137
+ variable: '--font-fira-code',
138
+ subsets: ['latin'],
139
+ });
140
+
141
+ // Update the className to use new variables
142
+ <body className={`${roboto.variable} ${firaCode.variable} font-sans antialiased`}>
143
+ ```
144
+
145
+ **Step 2 — Update the font preset file (or create a new one):**
146
+
147
+ ```css
148
+ /* styles/fonts/roboto-fira.css */
149
+ :root {
150
+ --font-sans-value: var(--font-roboto);
151
+ --font-heading-value: var(--font-roboto);
152
+ --font-mono-value: var(--font-fira-code);
153
+ }
154
+ ```
155
+
156
+ Then update the import in `globals.css`:
157
+ ```css
158
+ @import "../styles/fonts/roboto-fira.css";
159
+ ```
160
+
161
+ ### Font Preset Structure
162
+
163
+ Each preset maps raw font variables (set by `next/font/google` in `layout.tsx`) to semantic roles:
164
+
165
+ ```css
166
+ :root {
167
+ --font-sans-value: var(--font-inter); /* body text */
168
+ --font-heading-value: var(--font-inter); /* headings */
169
+ --font-mono-value: var(--font-jetbrains-mono); /* code */
170
+ }
171
+ ```
172
+
173
+ ### Creating a Custom Font Preset
174
+
175
+ 1. Choose your fonts from [Google Fonts](https://fonts.google.com)
176
+ 2. Update `layout.tsx` — import fonts via `next/font/google`, set CSS variable names
177
+ 3. Create a new preset file in `src/styles/fonts/` (or edit the existing one)
178
+ 4. Map your font variables to the three semantic roles
179
+ 5. Update the import in `globals.css` to point to your preset
180
+
181
+ ### CRITICAL RULES — Font Management
182
+
183
+ 1. **NEVER hardcode font-family values in components.** Always use Tailwind classes (`font-sans`, `font-heading`, `font-mono`).
184
+ 2. **ALL font-family mappings live in the font preset file**, not in `globals.css` or components.
185
+ 3. **To change fonts**: update `layout.tsx` imports + update the font preset file. Never scatter font-family values across the codebase.
186
+ 4. **The `@theme inline` block in `globals.css` maps preset variables to Tailwind** — it does NOT define fonts. Fonts come from the preset.
187
+ 5. **Fonts are loaded via `next/font/google`** — this self-hosts fonts automatically at build time. No external requests at runtime, no manual file downloads needed.
71
188
 
72
189
  ---
73
190
 
@@ -117,7 +234,7 @@ This project uses **Tailwind CSS v4** with **OKLCH color space** and the `@theme
117
234
  1. **Never hardcode**: No `bg-blue-500`, no `bg-[#3b82f6]`, no `style={{ color }}`. Always semantic tokens.
118
235
  2. **Semantic names by purpose**: `bg-destructive` not `bg-red`.
119
236
  3. **Always pair bg + foreground**: `bg-primary text-primary-foreground` for contrast.
120
- 4. **Single source of truth**: Change colors only in `globals.css` variables.
237
+ 4. **Single source of truth**: Change colors ONLY in the active theme preset file (`src/styles/themes/*.css`). Never in `globals.css`, never in components.
121
238
  5. **90% monochrome**: 90% of UI uses `background`, `foreground`, `muted`, `border`. Color is the exception.
122
239
  6. **Opacity for hierarchy**: Use `bg-primary/10`, `bg-primary/5` for tinted backgrounds.
123
240
 
@@ -138,7 +255,7 @@ This project uses **Tailwind CSS v4** with **OKLCH color space** and the `@theme
138
255
 
139
256
  ## Typography
140
257
 
141
- - **Font**: Inter v4 (variable) or Geist Sans via `next/font`.
258
+ - **Font**: Defined by the active font preset (default: Inter for sans/heading, JetBrains Mono for mono). See "Font Preset System" above for how to switch.
142
259
  - **Headings**: `text-wrap: balance`, `leading-tight`. Mobile-first responsive sizes:
143
260
  - H1: `text-2xl md:text-3xl lg:text-4xl`
144
261
  - H2: `text-xl md:text-2xl`
@@ -9,7 +9,7 @@
9
9
  | Creating files, folders, feature modules | `01-project-structure.md` |
10
10
  | Building components, writing types/interfaces | `02-components-and-types.md` |
11
11
  | Fetching data, managing state, calling APIs, forms | `03-data-and-state.md` |
12
- | Choosing colors, styling, typography, spacing, motion | `04-design-system.md` |
12
+ | Choosing colors, styling, typography, spacing, motion, **theme presets**, **font presets** | `04-design-system.md` |
13
13
  | Auth tokens, env vars, security headers | `05-security.md` |
14
14
  | UX psychology, cognitive load, a11y, performance | `06-ux-checklist.md` |
15
15
 
@@ -36,8 +36,10 @@ State: Server data (SSR) → Server Components
36
36
  1. **Mobile-first**: All Tailwind classes start at mobile. Desktop is the enhancement (`md:`, `lg:`). Touch targets min 44x44px. No functionality behind hover-only states.
37
37
  2. **Server Components by default.** Only add `'use client'` when you need hooks, state, or event handlers.
38
38
  3. **Component limits**: Max 250 lines, max 5 props, max 3 JSX nesting levels.
39
- 4. **No hardcoded colors**: Use Tailwind semantic tokens (`bg-primary`, `text-foreground`). Never hex/rgb.
40
- 5. **No inline styles**: Tailwind only. Use `cn()` for conditional classes.
41
- 6. **Import order**: React/Next third-party UI local → hooks → services → types → utils.
42
- 7. **Forms**: Validate with Zod. Always validate client-side AND server-side.
43
- 8. **Security**: Never inject raw HTML without sanitization. Never prefix secrets with `NEXT_PUBLIC_`.
39
+ 4. **No hardcoded colors**: Use Tailwind semantic tokens (`bg-primary`, `text-foreground`). Never hex/rgb. **All color variables live in theme preset files (`src/styles/themes/*.css`), NOT in `globals.css` or components.** To change the palette, switch the import in `globals.css` or edit the active preset. Read `04-design-system.md` → "Theme Preset System" for details.
40
+ 5. **No hardcoded fonts**: Use Tailwind font classes (`font-sans`, `font-heading`, `font-mono`). Never hardcode `font-family` in components. **Font families are defined in font preset files (`src/styles/fonts/*.css`).** To change fonts, update the `next/font/google` imports in `layout.tsx` and the font preset file. Read `04-design-system.md` → "Font Preset System" for details.
41
+ 6. **No inline styles**: Tailwind only. Use `cn()` for conditional classes.
42
+ 7. **Import order**: React/Next third-party UI local → hooks → services → types → utils.
43
+ 8. **Forms**: Validate with Zod. Always validate client-side AND server-side.
44
+ 9. **Security**: Never inject raw HTML without sanitization. Never prefix secrets with `NEXT_PUBLIC_`.
45
+ 10. **Deployment**: Never remove `output: "standalone"` from `next.config.ts`. When adding `NEXT_PUBLIC_*` env vars, also add them as `ARG` + `ENV` in the Dockerfile builder stage. Read `07-deployment.md` for details.
@@ -0,0 +1,178 @@
1
+ > **SCOPE**: These rules apply to the **entire workspace** (server + client). Always active.
2
+
3
+ # Task Completion Reports
4
+
5
+ When you finish a task, phase, or multi-step implementation, you MUST provide a structured completion report. Freeform paragraphs like "Fixed issues and completed remaining tasks" are not acceptable. The report must give the user a clear, scannable picture of everything that changed, why, and what to do next.
6
+
7
+ ---
8
+
9
+ ## When to Report
10
+
11
+ | Situation | Report required? |
12
+ |-----------|-----------------|
13
+ | Completed a full task or feature | **Yes — Full Report** |
14
+ | Completed a phase in a multi-phase plan | **Yes — Phase Report** (subset of Full Report) |
15
+ | Fixed a bug | **Yes — Bug Fix Report** |
16
+ | Small config change, typo fix, single-file edit | **No** — a 1-2 sentence explanation is fine |
17
+
18
+ ---
19
+
20
+ ## Full Report Template
21
+
22
+ Use this structure after completing a feature or multi-phase task. Omit sections that don't apply (e.g., skip "Database Changes" if no migrations were created), but never omit "Files Changed" or "How to Test".
23
+
24
+ ```
25
+ ## Summary
26
+ [1-3 sentences: what was built/changed and why]
27
+
28
+ ## Files Changed
29
+
30
+ ### Created
31
+ - `path/to/file.ts` — [purpose: what this file does]
32
+
33
+ ### Modified
34
+ - `path/to/file.ts` — [what changed and why]
35
+
36
+ ### Deleted
37
+ - `path/to/file.ts` — [why it was removed]
38
+
39
+ ## New API Endpoints (if applicable)
40
+ | Method | Path | Auth | Description |
41
+ |--------|------|------|-------------|
42
+
43
+ ## Database Changes (if applicable)
44
+ - Migration: `YYYYMMDD_name` — [what it does]
45
+ - New tables: [list]
46
+ - Modified tables: [what changed]
47
+ - Indexes added: [list]
48
+
49
+ ## Environment Variables (if applicable)
50
+ | Variable | Required | Where | Description |
51
+ |----------|----------|-------|-------------|
52
+ [Where = .env / .env.example / Dockerfile ARG / Coolify]
53
+
54
+ ## Dependencies Added (if applicable)
55
+ | Package | Purpose |
56
+ |---------|---------|
57
+ - Note if any require system-level installs (apk add)
58
+
59
+ ## Key Decisions & Trade-offs
60
+ [Explain non-obvious choices. Why was approach A chosen over B? What assumptions were made? What are the limitations?]
61
+
62
+ ## Deployment & Production Impact (if applicable)
63
+ [This section is REQUIRED whenever changes affect deployment, infrastructure, or production behavior. Include ALL that apply:]
64
+
65
+ ### Dockerfile Changes
66
+ - [New ARG/ENV added, new COPY lines, new apk packages, port changes, etc.]
67
+
68
+ ### Environment / Coolify Configuration
69
+ - [New env vars that must be set in Coolify/hosting platform]
70
+ - [Build arguments that must be added]
71
+ - [Volume mounts needed]
72
+
73
+ ### Database Migration Required
74
+ - [Migration name and what it does]
75
+ - [Must run `prisma migrate deploy` before/after deploying]
76
+ - [Any data migration or backfill needed]
77
+
78
+ ### Infrastructure Changes
79
+ - [New external services required (Redis, S3, third-party APIs)]
80
+ - [DNS/domain changes needed]
81
+ - [SSL/certificate changes]
82
+ - [New cron jobs or background workers]
83
+
84
+ ### Deployment Order
85
+ - [If server and client must be deployed in a specific order, state it]
86
+ - [If a migration must run before the new code deploys, state it]
87
+
88
+ ### Rollback Plan
89
+ - [What happens if this deployment fails — is it safe to roll back?]
90
+ - [Are the database changes backwards-compatible with the previous code version?]
91
+
92
+ ## Breaking Changes (if any)
93
+ - [What breaks, what to update, and how]
94
+
95
+ ## Manual Steps Required
96
+ 1. [Ordered list of things the user must do before this works]
97
+ - e.g., "Add GEMINI_API_KEY to .env"
98
+ - e.g., "Run npm run prisma:migrate dev"
99
+
100
+ ## How to Test
101
+ 1. [Step-by-step verification the user can follow]
102
+ - Be specific: exact commands, exact Postman steps, exact URLs
103
+ - Include expected responses where helpful
104
+
105
+ ## Known Limitations / TODOs (if any)
106
+ - [Things not yet implemented, edge cases not handled, future improvements needed]
107
+ ```
108
+
109
+ ---
110
+
111
+ ## Phase Report Template
112
+
113
+ Use this when completing one phase of a multi-phase plan. Shorter than a Full Report but still structured.
114
+
115
+ ```
116
+ ## Phase N Complete: [Phase Title]
117
+
118
+ ### What was done
119
+ - [Bullet list of concrete changes]
120
+
121
+ ### Files Changed
122
+ - `path/to/file.ts` — [what and why]
123
+
124
+ ### Key Decisions
125
+ - [Any non-obvious choices made during this phase]
126
+
127
+ ### Blockers or Concerns
128
+ - [Anything that might affect subsequent phases]
129
+
130
+ ### Phase Status
131
+ - [x] Phase N complete
132
+ - [ ] Phase N+1: [title] — next
133
+ ```
134
+
135
+ ---
136
+
137
+ ## Bug Fix Report Template
138
+
139
+ ```
140
+ ## Bug Fix: [Short description]
141
+
142
+ ### Root Cause
143
+ [What was actually wrong — not just the symptom, but the underlying cause]
144
+
145
+ ### Fix Applied
146
+ - `path/to/file.ts` — [what changed]
147
+
148
+ ### Why This Fix
149
+ [Why this approach was chosen. What other approaches were considered and rejected.]
150
+
151
+ ### How to Verify
152
+ 1. [Steps to confirm the fix works]
153
+
154
+ ### Regression Risk
155
+ - [Could this fix break anything else? What was checked?]
156
+ ```
157
+
158
+ ---
159
+
160
+ ## Rules
161
+
162
+ 1. **Structure over prose.** Use the templates above. Tables, bullet points, and headers — not paragraphs.
163
+ 2. **Every file gets a "why".** Don't just list `file.ts` — explain what changed and why. "Added creditBalance: 0 to mocks" → "Added `creditBalance: 0` to user mocks in `setup.ts` because the new credits module added this required field to the User model, and existing test fixtures would fail validation without it."
164
+ 3. **Be specific in "How to Test".** Not "use Postman to test." Instead: "1. POST `{{baseUrl}}/auth/login` with test credentials. 2. POST `{{baseUrl}}/generations` with body `{ templateId: '...', image: <file> }`. 3. Expected: 201 with `{ success: true, data: { id, status: 'pending' } }`."
165
+ 4. **Explain decisions, not just actions.** "Used upsert for seed data" → "Used `upsert` instead of `create` for seed data so the seed script is idempotent — running it twice won't throw duplicate key errors."
166
+ 5. **Surface what the user needs to do.** If the user must add an env var, run a migration, install something, or restart a service — put it in "Manual Steps Required" prominently. Don't bury it in a paragraph.
167
+ 6. **Honest about limitations.** If something is incomplete, has edge cases, or needs future work — say so in "Known Limitations." Don't pretend everything is perfect.
168
+ 7. **Scale to the task.** A 5-phase feature gets a full report with every section. A single service method gets a shorter report. Use judgment, but always use the structured format.
169
+ 8. **Deployment impact is never optional.** If ANY of the following changed, the "Deployment & Production Impact" section is REQUIRED — no exceptions:
170
+ - New or modified environment variables
171
+ - New npm packages with native dependencies
172
+ - Database schema changes (new tables, columns, indexes)
173
+ - Dockerfile modifications needed
174
+ - New external service dependencies (APIs, Redis, S3, etc.)
175
+ - Port, entry point, or health check changes
176
+ - File upload/storage changes requiring volume mounts
177
+ - Changes to build process or build arguments
178
+ If none of these apply, explicitly state: "No deployment impact — no infrastructure, env, or database changes."
@@ -66,6 +66,12 @@ When the user asks to create, scaffold, or start a new server or client project,
66
66
 
67
67
  ---
68
68
 
69
+ ## Task Completion Reports
70
+
71
+ After completing any task, phase, or bug fix, you MUST provide a structured completion report — not freeform paragraphs. **Read `completion-reports.md`** for the required templates and rules. This includes deployment/production impact analysis whenever infrastructure, env vars, database, or Docker changes are involved.
72
+
73
+ ---
74
+
69
75
  ## Code Review Checklist
70
76
 
71
77
  Before considering work done, verify:
@@ -0,0 +1,5 @@
1
+ # Public API URL - points to the production server's base URL
2
+ NEXT_PUBLIC_API_BASE_URL=https://api.yourdomain.com/api/v1
3
+
4
+ # App name displayed in the UI
5
+ NEXT_PUBLIC_APP_NAME={{PROJECT_DISPLAY_NAME}}
@@ -18,7 +18,7 @@ Open [http://localhost:3000](http://localhost:3000) with your browser to see the
18
18
 
19
19
  You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
20
20
 
21
- This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
21
+ This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Inter](https://fonts.google.com/specimen/Inter) and [JetBrains Mono](https://fonts.google.com/specimen/JetBrains+Mono). Fonts are managed via the font preset system in `src/styles/fonts/` — see the design system rules for how to switch fonts.
22
22
 
23
23
  ## Learn More
24
24
 
@@ -13,7 +13,7 @@ export default function GlobalError({
13
13
  reset: () => void;
14
14
  }): React.ReactElement {
15
15
  return (
16
- <div className="flex min-h-[400px] flex-col items-center justify-center p-8 text-center">
16
+ <div className="flex min-h-dvh flex-col items-center justify-center p-8 text-center">
17
17
  <AlertCircle className="mb-4 h-12 w-12 text-destructive" />
18
18
  <h2 className="mb-2 text-2xl font-bold">Something went wrong</h2>
19
19
  <p className="mb-4 text-muted-foreground">