create-tigra 2.8.0 → 3.0.2

package/README.md

@@ -44,7 +44,7 @@ Includes `.claude/` rules for Claude Code with project-specific conventions, arc
 
 ## Prerequisites
 
-- **Node.js** 18+
+- **Node.js** 22.12+
 - **Docker** (for MySQL and Redis)
 
 ## After Scaffolding
@@ -72,8 +72,15 @@ npm run dev
 
 - Server: http://localhost:8000
 - Client: http://localhost:3000
-- phpMyAdmin: http://localhost:8080
-- Redis Commander: http://localhost:8081
+- phpMyAdmin: http://localhost:8080 (optional — see below)
+- Redis Commander: http://localhost:8081 (optional — see below)
+
+The admin UIs (phpMyAdmin, Redis Commander) are behind the docker-compose `tools` profile and do **not** start with plain `docker compose up -d`. Start them with:
+
+```bash
+cd my-app/server
+docker compose --profile tools up -d
+```
 
 ## License
 

package/bin/create-tigra.js

@@ -17,6 +17,10 @@ const VERSION = packageJson.version;
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
 
+// Non-secret placeholder written into the COMMITTED server/.env.example.
+// The real secret replaces it only in the git-ignored server/.env.
+const JWT_SECRET_PLACEHOLDER = 'CHANGE_ME_generate_with_openssl_rand_hex_48';
+
 // Files that contain template variables and need replacement
 const FILES_TO_REPLACE = [
   'server/package.json',
@@ -24,6 +28,7 @@ const FILES_TO_REPLACE = [
   'server/docker-compose.yml',
   'client/package.json',
   'client/.env.example',
+  'client/.env.example.production',
   'server/postman/collection.json',
   'server/postman/environment.json',
 ];
@@ -123,6 +128,43 @@ function replaceVariables(content, variables) {
   return result;
 }
 
+// When stdin is closed/non-interactive, `prompts` never settles its promise:
+// the event loop drains and Node exits 0 mid-await — no scaffold, no error.
+// That silently "succeeds" in CI. Track the in-flight prompt and fail loudly.
+let activePromptMessage = null;
+
+process.on('exit', (code) => {
+  if (activePromptMessage !== null && code === 0) {
+    // writeSync: stderr writes via console.error can be lost in an 'exit'
+    // handler when stderr is a pipe (async on Windows).
+    fs.writeSync(
+      2,
+      `\n  Aborted: the prompt "${activePromptMessage}" was not answered ` +
+        `(stdin is closed or non-interactive).\n` +
+        `  Run in an interactive terminal, or pipe answers via stdin.\n\n`,
+    );
+    process.exitCode = 1;
+  }
+});
+
+async function ask(question) {
+  activePromptMessage = question.message;
+  const response = await prompts(question, {
+    onCancel: () => {
+      console.error(chalk.red('\n  Cancelled.\n'));
+      process.exit(1);
+    },
+  });
+  activePromptMessage = null;
+  if (response[question.name] === undefined) {
+    console.error(
+      chalk.red(`\n  Aborted: no answer received for "${question.message}".\n`),
+    );
+    process.exit(1);
+  }
+  return response;
+}
+
 function registerAddCommand(program) {
   program
     .command('add <module>')
@@ -248,20 +290,12 @@ async function main() {
       let projectName = projectNameArg;
 
       if (!projectName) {
-        const response = await prompts(
-          {
-            type: 'text',
-            name: 'projectName',
-            message: 'What is your project name?',
-            validate: validateProjectName,
-          },
-          {
-            onCancel: () => {
-              console.log(chalk.red('\n  Cancelled.\n'));
-              process.exit(1);
-            },
-          }
-        );
+        const response = await ask({
+          type: 'text',
+          name: 'projectName',
+          message: 'What is your project name?',
+          validate: validateProjectName,
+        });
         projectName = response.projectName;
       }
 
@@ -286,34 +320,30 @@ async function main() {
       }
 
       // Ask about email verification
-      const { enableVerification } = await prompts(
-        {
-          type: 'toggle',
-          name: 'enableVerification',
-          message: 'Enable email verification for new users?',
-          initial: false,
-          active: 'Yes',
-          inactive: 'No',
-          hint: 'Users must verify email before accessing the app',
-        },
-        {
-          onCancel: () => {
-            console.log(chalk.red('\n  Cancelled.\n'));
-            process.exit(1);
-          },
-        }
-      );
+      const { enableVerification } = await ask({
+        type: 'toggle',
+        name: 'enableVerification',
+        message: 'Enable email verification for new users?',
+        initial: false,
+        active: 'Yes',
+        inactive: 'No',
+        hint: 'Users must verify email before accessing the app',
+      });
 
       // Generate random port offset (1-200) so multiple projects don't conflict
       const portOffset = crypto.randomInt(1, 201);
 
-      // Derive all variables
+      // Derive all variables.
+      // SECURITY: everything in this map is written into COMMITTED files
+      // (.env.example, docker-compose.yml, ...) — never put a real secret here.
+      // JWT_SECRET gets an instructional placeholder; the real secret is
+      // generated below and written ONLY to the git-ignored .env.
       const variables = {
         PROJECT_NAME: projectName,
         PROJECT_NAME_SNAKE: toSnakeCase(projectName),
         PROJECT_DISPLAY_NAME: toTitleCase(projectName),
         DATABASE_NAME: `${toSnakeCase(projectName)}_db`,
-        JWT_SECRET: crypto.randomBytes(48).toString('hex'),
+        JWT_SECRET: JWT_SECRET_PLACEHOLDER,
         MYSQL_PORT: String(3306 + portOffset),
         PHPMYADMIN_PORT: String(8080 + portOffset),
         REDIS_PORT: String(6379 + portOffset),
@@ -337,12 +367,21 @@ async function main() {
           }
         }
 
-        // Generate .env from .env.example (so users don't have to copy manually)
+        // Generate .env from .env.example (so users don't have to copy manually).
+        // The real JWT secret is injected HERE and only here — .env is
+        // git-ignored, while .env.example is committed and must keep the
+        // CHANGE_ME placeholder.
+        const jwtSecret = crypto.randomBytes(48).toString('hex');
         for (const envExample of ['server/.env.example', 'client/.env.example']) {
           const examplePath = path.join(targetDir, envExample);
           const envPath = path.join(targetDir, envExample.replace('.env.example', '.env'));
           if (await fs.pathExists(examplePath)) {
-            await fs.copy(examplePath, envPath);
+            const content = await fs.readFile(examplePath, 'utf-8');
+            await fs.writeFile(
+              envPath,
+              content.replaceAll(JWT_SECRET_PLACEHOLDER, jwtSecret),
+              'utf-8',
+            );
           }
         }
 
@@ -423,8 +462,9 @@ async function main() {
       console.log();
       console.log(dim('  App           ') + cyan('http://localhost:3000'));
       console.log(dim('  API           ') + cyan('http://localhost:8000'));
-      console.log(dim('  phpMyAdmin    ') + cyan(`http://localhost:${variables.PHPMYADMIN_PORT}`));
-      console.log(dim('  Redis CMD     ') + cyan(`http://localhost:${variables.REDIS_COMMANDER_PORT}`));
+      console.log(dim('  DB/Redis UIs  ') + 'optional — start with ' + cyan('npm run docker:tools'));
+      console.log(dim('    phpMyAdmin  ') + cyan(`http://localhost:${variables.PHPMYADMIN_PORT}`));
+      console.log(dim('    Redis CMD   ') + cyan(`http://localhost:${variables.REDIS_COMMANDER_PORT}`));
       console.log();
       console.log(line);
       console.log();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tigra",
-    "version": "2.8.0",
+  "version": "3.0.2",
   "type": "module",
   "description": "Create a production-ready full-stack app with Next.js 16 + Fastify 5 + Prisma + Redis",
   "bin": {
@@ -13,7 +13,7 @@
     "template"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.12.0"
   },
   "keywords": [
     "create",
@@ -46,10 +46,10 @@
   },
   "dependencies": {
     "chalk": "^5.4.1",
-    "commander": "^13.1.0",
+    "commander": "^15.0.0",
     "fs-extra": "^11.3.0",
-    "ora": "^8.2.0",
+    "ora": "^9.0.0",
     "prompts": "^2.4.2",
-    "ts-morph": "^27.0.2"
+    "ts-morph": "^28.0.0"
   }
 }

package/template/_claude/commands/create-server.md

@@ -134,12 +134,18 @@ Include: node_modules, dist, .env, .env.local, .env*.local, *.log, .prisma
 #### `docker-compose.yml`
 Create a Docker Compose file with these services:
 1. **mysql** - MySQL 8.0, port 3306, database name = `$ARGUMENTS`, root password = `rootpassword`, volume for data persistence, healthcheck
-2. **phpmyadmin** - Latest, port 8080, linked to mysql
+2. **phpmyadmin** - Latest, port 8080, linked to mysql, behind the `tools` profile
 3. **redis** - Redis 7 Alpine, port 6379, volume for data persistence, healthcheck
-4. **redis-commander** - Redis Commander UI, port 8081, linked to redis
+4. **redis-commander** - Redis Commander UI, port 8081, linked to redis, behind the `tools` profile
 
 Use a named network for all services. Add restart policies.
 
+**Security requirements (dev attack surface):**
+- Bind ALL published ports to localhost (`127.0.0.1:<port>:<container-port>`), never `0.0.0.0` — these are dev credentials (root password, unpassworded Redis).
+- Put the admin UIs (**phpmyadmin**, **redis-commander**) behind `profiles: ["tools"]` so they do NOT start by default:
+  - `docker compose up -d` → MySQL + Redis only
+  - `docker compose --profile tools up -d` → also starts phpMyAdmin + Redis Commander
+
 ---
 
 ### Step 2: Source Code Structure

package/template/_claude/rules/client/01-project-structure.md

@@ -133,3 +133,15 @@ export const CURRENCIES = { USD: 'USD', EUR: 'EUR' } as const;
 
 Protected paths: `/dashboard`, `/profile`, `/admin` — redirect to `/login` if no token.
 Auth paths: `/login`, `/register` — redirect to `/dashboard` if already authenticated.
+
+When creating a new page, always add it to `protectedPaths` and `config.matcher` in `middleware.ts` if it requires authentication. If you are unsure whether a page should be protected, **ask the user** — do not guess.
+
+### Deleting a Route
+
+When removing a page/route, you MUST update **all three** locations:
+
+1. **Delete the page file**: `app/<route>/page.tsx` (and the folder if empty)
+2. **Remove from `routes.ts`**: Delete the entry in `lib/constants/routes.ts`
+3. **Remove from `middleware.ts`**: Delete from `protectedPaths` array AND `config.matcher` array
+
+Missing any of these leaves dead references or broken middleware matches.

package/template/_claude/rules/client/03-data-and-state.md

@@ -75,7 +75,7 @@ const mutation = useMutation({
 
 ### Next.js Router Cache
 
-`next.config.ts` sets `experimental.staleTimes: { dynamic: 0, static: 0 }` to disable client-side Router Cache reuse. **Never raise these values** — doing so reintroduces the back-navigation stale-data bug across every page that uses Server Components for data fetching.
+`next.config.ts` sets `experimental.staleTimes: { dynamic: 0, static: 30 }` to minimize client-side Router Cache reuse. `static: 30` is the **Next 16.2+ minimum** — the config schema rejects values below 30, and an invalid value is silently ignored (re-enabling the default Router Cache). `dynamic: 0` is what protects data pages. **Never raise these values above these minimums** — doing so reintroduces the back-navigation stale-data bug across every page that uses Server Components for data fetching.
 
 ---
 

package/template/_claude/rules/client/04-design-system.md

@@ -339,6 +339,28 @@ Link:    transition-colors duration-150 active:opacity-70 md:hover:text-primary
 - **Sticky action bars**: Form submit buttons, checkout CTAs — `sticky bottom-0` on mobile.
 - **No hamburger menus** for ≤5 items. Use bottom tab bar instead.
 
+### BottomNav Overlap — Fixed Bottom Elements
+
+When a page has its own `fixed bottom-0` element (e.g., sticky order bar, floating CTA), it **will be hidden behind BottomNav** on mobile. The BottomNav is `fixed bottom-0 z-50` with a height of `4rem` (64px).
+
+**Define the CSS variable** in the BottomNav component:
+```css
+:root {
+  --bottom-nav-height: 4rem;
+}
+```
+
+**Every fixed bottom element on a page** must offset itself above BottomNav on mobile:
+```
+bottom-[var(--bottom-nav-height)] md:bottom-0
+```
+Or the shorthand equivalent:
+```
+bottom-16 md:bottom-0
+```
+
+This is not optional — without it, BottomNav covers the element and users cannot tap it on mobile.
+
 ---
 
 ## Images
@@ -383,3 +405,4 @@ Link:    transition-colors duration-150 active:opacity-70 md:hover:text-primary
 - Reduce shadow visibility in dark mode (use subtle light borders instead).
 - Consider `brightness-90` on images in dark mode.
 - Add `suppressHydrationWarning` to `<html>` tag.
+- **Hydration guard for conditional theme renders**: `useTheme()` returns `undefined` on the server. Any component that renders *different JSX* based on `theme` (e.g. showing a Sun icon OR a Moon icon — not both) will throw a hydration mismatch. Either render both icons and style the active one (see `components/common/ThemeToggle.tsx`), or add a `mounted` guard: `const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), []);` and return `null`/a placeholder until `mounted` is true.

package/template/_claude/rules/client/07-deployment.md

@@ -0,0 +1,99 @@
+> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
+
+# Deployment & Docker
+
+This project is deployed via **Docker** on **Coolify** (or any Docker-based platform). The `Dockerfile` is the production deployment contract. Every code change must remain compatible with it.
+
+---
+
+## Dockerfile Architecture
+
+The client uses a **3-stage multi-stage build** with Next.js `standalone` output:
+
+```
+Stage 1 (dependencies)  → Installs all node_modules (cached layer)
+Stage 2 (builder)        → Copies deps, builds Next.js with standalone output
+Stage 3 (production)     → Alpine + dumb-init, non-root user, copies standalone + static + public
+```
+
+**Entry point**: `node server.js` (generated by Next.js standalone output in `.next/standalone/`)
+**Health check**: `GET /` — returns 200 if the Next.js server is running.
+
+### Critical Config Requirement
+
+`next.config.ts` **must** have `output: "standalone"`. Without it, the Dockerfile will fail because `.next/standalone/` won't be generated. Never remove this setting.
+
+---
+
+## Build Arguments (NEXT_PUBLIC_* Variables)
+
+Next.js **inlines** all `NEXT_PUBLIC_*` values into the JavaScript bundle at build time. They are NOT read from the environment at runtime. This means:
+
+- Every `NEXT_PUBLIC_*` variable must be declared as `ARG` + `ENV` in the **builder stage** of the Dockerfile.
+- They must be passed via `--build-arg` during `docker build` (or via Coolify's Build Arguments UI).
+- **If you add a new `NEXT_PUBLIC_*` env var, you MUST add it to the Dockerfile builder stage.**
+
+```dockerfile
+# In the builder stage:
+ARG NEXT_PUBLIC_NEW_VAR
+ENV NEXT_PUBLIC_NEW_VAR=$NEXT_PUBLIC_NEW_VAR
+```
+
+Current build arguments:
+- `NEXT_PUBLIC_API_BASE_URL` — Backend API URL (e.g., `https://api.yourdomain.com/api/v1`)
+- `NEXT_PUBLIC_APP_NAME` — App display name
+
+---
+
+## When to Update the Dockerfile
+
+| You did this... | Update Dockerfile? | What to change |
+|---|---|---|
+| Added a new npm dependency | No | Automatic — installed during build |
+| Added a native/system dependency (e.g., `sharp` for image optimization) | **Yes** | Add `apk add` in the production stage |
+| Added a new `NEXT_PUBLIC_*` env var | **Yes** | Add `ARG` + `ENV` in the builder stage |
+| Changed the public directory structure | No | Automatic — `COPY /app/public ./public` |
+| Added server-only env vars (no `NEXT_PUBLIC_` prefix) | No | Injected at runtime via Coolify |
+| Changed the default port | **Yes** | Update `ENV PORT`, `EXPOSE`, and `HEALTHCHECK` |
+| Added custom `next.config.ts` rewrites/redirects | No | Baked into the build automatically |
+| Added API routes (`app/api/`) | No | Included in standalone output |
+| Removed `output: "standalone"` from next.config.ts | **BREAKING** | Entire Dockerfile depends on standalone output |
+
+---
+
+## Critical Rules
+
+1. **Never remove `output: "standalone"`** from `next.config.ts`. The entire Docker build depends on it. Without it, the standalone server won't be generated and the Dockerfile will fail.
+
+2. **Every `NEXT_PUBLIC_*` var needs a Dockerfile `ARG`.** Next.js inlines these at build time. If you add one to `.env.example` but forget the Dockerfile, the value will be `undefined` in production.
+
+3. **Static assets and public files are separate.** The standalone output does NOT include `.next/static/` or `public/`. The Dockerfile copies them explicitly. If you add a new top-level directory that must be available at runtime (unlikely), add a `COPY` line.
+
+4. **Non-root user.** The app runs as `nextjs:nodejs` (UID 1001). Next.js standalone doesn't write to disk at runtime, so this is straightforward.
+
+5. **No secrets in the image.** Server-only env vars (without `NEXT_PUBLIC_` prefix) are injected at runtime. Never hardcode secrets or use `ENV` for sensitive values in the Dockerfile.
+
+6. **Keep `.dockerignore` in sync.** When adding directories that should NOT be in the build context (test fixtures, docs, Storybook), add them to `.dockerignore`. When adding files needed at build time, ensure they're not ignored.
+
+7. **`HOSTNAME="0.0.0.0"`** is required. Without it, Next.js standalone only listens on `127.0.0.1` inside the container, making it unreachable from outside.
+
+---
+
+## Coolify-Specific Notes
+
+- **Build Arguments**: Set `NEXT_PUBLIC_API_BASE_URL` and `NEXT_PUBLIC_APP_NAME` in Coolify's "Build Arguments" section (not environment variables — those are runtime only).
+- **Environment Variables**: Server-only vars (database URLs, API keys used in Server Components/Route Handlers) go in Coolify's "Environment Variables" section — available at runtime.
+- **Port**: Default `3000`. Override via `PORT` environment variable in Coolify.
+- **No volume mounts needed**: Next.js client apps are stateless — no uploads, no local file writes.
+
+---
+
+## Files That Matter for Deployment
+
+| File | Purpose | Must exist? |
+|---|---|---|
+| `Dockerfile` | Production build instructions | Yes |
+| `.dockerignore` | Excludes files from Docker build context | Yes |
+| `next.config.ts` | Must have `output: "standalone"` | Yes |
+| `package.json` | Dependencies and build script | Yes |
+| `public/` | Static assets (favicon, images) | Yes |

package/template/_claude/rules/client/08-lockfile-cross-platform.md

@@ -0,0 +1,79 @@
+> **SCOPE**: These rules apply specifically to the **client** directory (Next.js App Router).
+
+# Lockfile — Cross-Platform Regeneration
+
+`client/package-lock.json` has burned us — and bots — multiple times in projects scaffolded from this template. Read this before touching it.
+
+## The trap
+
+`client/package-lock.json` is consumed by **three different environments**:
+
+| Environment | OS / libc | npm |
+|---|---|---|
+| Local dev (most contributors) | Windows / macOS | npm 11.x |
+| GitHub Actions CI (`server-ci.yml`, `client-ci.yml`) | `ubuntu-latest` (Debian glibc) | npm 10.x (ships with Node 20) |
+| Coolify / production deploy (`client/Dockerfile`) | `node:20-alpine` (musl) | npm 10.x |
+
+`npm ci` is **strict** — it refuses to install if the lockfile is even slightly out of sync with `package.json`, AND it only installs the platform-specific `optionalDependencies` whose top-level `node_modules/<pkg>` entries exist in the lockfile. If you regenerate on Windows with `npm install`, you get a Windows-leaning lockfile that:
+
+1. May be missing entries the newer npm 10 (CI) considers required (`Missing: @swc/helpers@0.5.21 from lock file` — common failure mode).
+2. Lacks `*-linux-x64-gnu` / `*-linuxmusl-x64` entries → CI's `next build` fails with `Cannot find module '../lightningcss.linux-x64-gnu.node'` or `No prebuild or local build of @parcel/watcher found.`
+
+Affected native packages (Next 16 + Tailwind v4 dep tree): `@parcel/watcher`, `lightningcss`, `@img/sharp`, `@next/swc`, `@swc/core`, `@tailwindcss/oxide`, `@unrs/resolver-binding`, `@rolldown/binding`.
+
+## Canonical fix (use this exactly)
+
+Whenever you regenerate `client/package-lock.json` — even just because `package.json` changed by one dep — run **all three** steps. They are additive (`--package-lock-only` doesn't touch `node_modules`).
+
+```bash
+cd client
+
+# 0. (Optional) Start fresh if the existing lockfile is already broken:
+rm -rf node_modules package-lock.json
+
+# 1. Sync the lockfile against package.json (fixes the "Missing: foo from lock file" class).
+npx -y npm@10 install --package-lock-only
+
+# 2. Add Linux/glibc native variants (GitHub Actions Ubuntu).
+npx -y npm@10 install --os=linux --cpu=x64 --libc=glibc --package-lock-only
+
+# 3. Add Linux/musl native variants (Coolify Alpine deploy).
+npx -y npm@10 install --os=linux --cpu=x64 --libc=musl --package-lock-only
+```
+
+### Required choices
+
+- **`npx -y npm@10` explicitly.** Local default npm 11.x resolves a tree npm 10 strict-checks reject. Match CI's npm version or you'll push a lockfile that fails immediately.
+- **`--package-lock-only`** keeps each command at ~1 sec (no install, no audit).
+- **Three platforms.** Even if you only intend to fix CI, do the musl pass too — Coolify deploy will fail otherwise.
+- **Skip darwin** unless a team member dev's on macOS and reports `npm ci` failing. Not worth the lockfile churn pre-emptively.
+
+## Verify before committing
+
+```bash
+cd client
+
+# A. Strict install passes with CI's npm version (this is the exact check CI runs):
+npx -y npm@10 ci --include=optional --no-audit --no-fund 2>&1 | tail -3
+# Expect: "added N packages in Xs". Any "EUSAGE" / "Missing:" means step 1 didn't take.
+
+# B. All native deps have glibc + musl entries:
+for pkg in '@next/swc' '@swc/core' '@parcel/watcher' '@rolldown/binding' \
+           '@tailwindcss/oxide' '@unrs/resolver-binding' 'lightningcss'; do
+  g=$(grep -cE "node_modules/${pkg}.*-linux-x64-(gnu|glibc)\"" package-lock.json)
+  m=$(grep -cE "node_modules/${pkg}-linux-x64-musl\"" package-lock.json)
+  echo "$pkg glibc=$g musl=$m"
+done
+# Expect every line: glibc=1 musl=1. (sharp uses different naming — check separately:
+# grep -oE 'node_modules/@img/sharp[-a-z0-9]*' package-lock.json | sort -u)
+```
+
+If either check fails, the lockfile is not ready — do not commit.
+
+## Anti-patterns (don't do these — every one has burned us)
+
+1. **Plain `npm install` on Windows/macOS.** Uses local npm 11; produces lockfiles CI rejects.
+2. **Whack-a-mole pinning** in `package.json` `optionalDependencies` (e.g., adding only `@parcel/watcher-linux-x64-glibc` and hoping it fixes everything). It doesn't — there are 7+ such native deps and you'll bounce through them one CI failure at a time.
+3. **Disabling `npm ci` in CI** by switching to `npm install` to "fix" the symptom. That makes builds non-reproducible.
+4. **Bypassing the husky pre-commit hook** with `--no-verify` to push a broken lockfile fast.
+5. **Generating inside Docker on a hung Docker daemon** without verifying the daemon is healthy first — the run silently buffers and you wait 10+ minutes. (The non-Docker `npx npm@10 install --package-lock-only` chain above is faster and equally correct.)

package/template/_claude/rules/client/core.md

@@ -12,6 +12,7 @@
 | Choosing colors, styling, typography, spacing, motion, **theme colors**, **font presets** | `04-design-system.md` |
 | Auth tokens, env vars, security headers | `05-security.md` |
 | UX psychology, cognitive load, a11y, performance | `06-ux-checklist.md` |
+| Regenerating `client/package-lock.json`, fixing CI `npm ci` failures, cross-platform native binaries (`@parcel/watcher`, `lightningcss`, `@img/sharp`, etc.) | `08-lockfile-cross-platform.md` |
 
 ---
 

package/template/_claude/rules/global/core.md

@@ -51,7 +51,7 @@ When the user asks to create, scaffold, or start a new server or client project,
 - **`.env` files are never committed.** Use `.env.example` as the template with placeholder values.
 - **Adding a new env var**: Add it to `.env.example` with a comment, and document where it's used.
 - **Keep `.env` and `.env.example` in sync**: Any change to `.env` (adding, removing, or renaming a variable) must be reflected in `.env.example`, and vice versa. They must always have the same set of variables.
-- **Keep `.env.example.production` in sync**: Every time `.env` or `.env.example` changes (variable added, removed, or renamed), also update `.env.example.production` in the same directory. If the file does not exist, create it. This file uses the same variable names but with **production-appropriate placeholder values** and comments (e.g., secure passwords, real domain URLs, SSL-enabled connection strings, stricter timeouts). This applies to both `server/` and `client/` directories.
+- **Keep `.env.example.production` in sync**: Every time `.env` or `.env.example` changes (variable added, removed, or renamed), also update `.env.example.production` in the same directory. If the file does not exist, create it. This file uses the same variable names but with **production-appropriate placeholder values** and comments (e.g., secure passwords, real domain URLs, SSL-enabled connection strings, stricter timeouts). See the server's `.env.example.production` for the expected style. This applies to both `server/` and `client/` directories.
 - **Secrets** (DB URLs, JWT secrets, API keys) must never be prefixed with `NEXT_PUBLIC_` and must never appear in client-side code.
 - **Public values only** (API base URL, app name) get the `NEXT_PUBLIC_` prefix.
 
@@ -63,6 +63,23 @@ When the user asks to create, scaffold, or start a new server or client project,
 - **Test naming**: `describe('<ModuleName>')` → `it('should <expected behavior>')`.
 - **Tests must be deterministic**: No reliance on real time, network, or random values. Mock external dependencies.
 - **Don't test implementation details** — test behavior and outputs.
+- **No "mock-echo" tests**: Don't mock a dependency (Prisma/ORM, HTTP client) and then only assert it was called with the same arguments the code passes straight through — that restates the implementation and verifies no behavior. A "was-called-with" assertion is valid only when the layer *transformed* the input first (filtering, pagination math, conditional queries) or when you ALSO assert on the returned value / observable result.
+- **Don't test logic-free layers**: If a unit only forwards to a dependency with no logic of its own (a thin repository/passthrough), don't test it — put the test on the service/behavior layer, where the branches and bugs are.
+
+---
+
+## Deployment Awareness
+
+Both server and client are deployed via **Docker on Coolify**. The `Dockerfile` in each directory is the production deployment contract. Code changes must never silently break the Docker build.
+
+**Always check deployment impact when you:**
+- Add a native/system npm dependency (needs `apk add` in Dockerfile)
+- Add, remove, or rename a `NEXT_PUBLIC_*` env var (needs `ARG` + `ENV` in client Dockerfile)
+- Change the build output directory, entry point file, or default port
+- Add runtime file dependencies (templates, static assets not in `public/`)
+- Change or remove a health check endpoint
+
+**See the deployment rules** in `server/deployment.md` and `client/07-deployment.md` for full details.
 
 ---
 
@@ -83,3 +100,5 @@ Before considering work done, verify:
 - [ ] Inputs validated with Zod.
 - [ ] Error cases handled (not just the happy path).
 - [ ] Existing tests still pass.
+- [ ] No "mock-echo" tests (asserting only that a mock was called, without asserting behavior/output or testing a real transform).
+- [ ] Dockerfile still compatible with changes (see Deployment Awareness above).

package/template/_claude/rules/global/investigation-before-conclusions.md

@@ -0,0 +1,57 @@
+> **SCOPE**: These rules apply to the **entire workspace** (server + client). Always active.
+
+# Investigation Before Conclusions
+
+This project (create-tigra) generates starter templates for developers who may not have deep coding experience. They trust AI output without questioning it. **A wrong suggestion that "fixes" a non-existent problem can introduce real problems.** Every recommendation must be grounded in verified understanding of how the code actually works.
+
+---
+
+## The Rule
+
+**Never suggest fixes, changes, or improvements until you have fully traced how the relevant system works in this codebase.** Seeing a file, a config, or a pattern is not enough. You must follow the code path end-to-end before making any claim.
+
+---
+
+## Before Answering "Is This a Bug?" or "Does This Need Fixing?"
+
+1. **Trace the actual workflow.** If the question is about uploads, go read the upload service, follow where files are saved, how they're served, how they're deleted. If it's about auth, trace the full auth flow. Don't stop at the first file you find.
+
+2. **Understand the runtime environment.** Ask yourself: does this code run in Docker or locally? Is this a dev tool or a production path? Does docker-compose run the server or just infrastructure services (MySQL, Redis)? Don't assume — verify.
+
+3. **Verify the problem exists in the real workflow.** Not in theory, not in a hypothetical scenario — in the actual way developers use this project. If no one would ever hit the issue in normal usage, it's not a problem worth fixing.
+
+4. **Don't pattern-match to conclusions.** "Uploads + Docker + no volume = must fix" is pattern-matching, not investigation. The server runs locally with `npm run dev`, not inside Docker. The `docker-compose.yml` is for MySQL and Redis only. A volume for uploads in docker-compose would solve nothing.
+
+5. **If you're unsure, say so.** "I need to check how this works before I can answer" is always better than a confident wrong answer.
+
+---
+
+## What NOT to Do
+
+| Bad behavior | Why it's dangerous |
+|---|---|
+| See a Dockerfile, immediately suggest `VOLUME` | The server may not run in Docker locally |
+| See docker-compose.yml, suggest adding volumes | docker-compose may only run infrastructure, not the app |
+| Find a missing config and assume it's a bug | It may be intentionally absent because it's not needed |
+| Suggest "best practice" improvements unprompted | Unnecessary changes confuse beginners and can introduce real bugs |
+| Stop researching after finding the first related file | The first file is not the full picture — trace the complete flow |
+| Offer a fix before confirming the problem is real | Fixing non-existent problems wastes time and creates new problems |
+
+---
+
+## The Standard
+
+Before every suggestion, ask yourself:
+
+1. **Did I trace the full code path?** Not just one file — the whole flow.
+2. **Do I understand the runtime environment?** Where does this code actually run?
+3. **Would a real developer actually hit this problem?** In normal usage, not edge cases.
+4. **Am I solving a real problem or a theoretical one?**
+
+If the answer to any of these is "no" — keep investigating before responding.
+
+---
+
+## Why This Matters
+
+create-tigra exists to help developers who are learning to code with AI assistance. These developers will trust your suggestions without pushback. A confident but wrong suggestion — like adding a Docker volume for a service that doesn't run in Docker — will send them down a rabbit hole debugging something that was never broken. **Your job is to understand what actually works and why, not to guess based on patterns.**

package/template/_claude/rules/server/core.md

@@ -17,6 +17,7 @@
 | Writing service or business logic | `project-conventions.md` (Layer Responsibilities) |
 | Changing DB schema, migrations, indexes | `database.md` |
 | Adding or changing API endpoints | `project-conventions.md` (Postman Collection) |
+| Adding dependencies, changing ports, entry points, or env vars | `deployment.md` |
 | Unsure where to start | This file |
 
 ---
@@ -48,3 +49,4 @@ Request
 5. **Logging**: Use `logger` from `src/libs/logger`. Never `console.log`.
 6. **Routes**: All prefixed with `/api/v1`. Registered as Fastify plugins.
 7. **Postman**: Every new or modified endpoint must be reflected in `postman/collection.json`. Create the collection if it doesn't exist.
+8. **Deployment**: Every change must remain compatible with the Dockerfile. Read `deployment.md` when adding system dependencies, changing ports, renaming entry points, or adding env vars.