create-turbo-mono 1.0.7 → 1.0.9

package/.claude/settings.local.json

@@ -4,7 +4,8 @@
       "Bash(npm view:*)",
       "Bash(python3:*)",
       "Bash(npm install:*)",
-      "Bash(npm run build:*)"
+      "Bash(npm run build:*)",
+      "Bash(npm publish:*)"
     ]
   }
 }

package/dist/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAiC1E"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAqC1E"}

package/dist/scaffold.js

@@ -13,6 +13,7 @@ const shared_1 = require("./templates/shared");
 const docker_1 = require("./templates/docker");
 const cicd_1 = require("./templates/cicd");
 const docs_1 = require("./templates/docs");
+const claude_1 = require("./templates/claude");
 async function scaffoldProject(config) {
     const { targetDir, backends, frontends } = config;
     // Create directory structure
@@ -38,5 +39,8 @@ async function scaffoldProject(config) {
     await (0, cicd_1.createCICDFiles)(config);
     // Create documentation
     await (0, docs_1.createDocumentation)(config);
+    // Create CLAUDE.md files (root + per-app + packages/) so Claude Code
+    // auto-loads project context every session.
+    await (0, claude_1.createClaudeFiles)(config);
 }
 //# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":";;;;;AAiBA,0CAiCC;AAlDD,wDAA0B;AAC1B,gDAAwB;AACxB,2CAAmD;AACnD,iDAAuD;AACvD,mDAAyD;AACzD,+CAA0D;AAC1D,+CAAuD;AACvD,2CAAmD;AACnD,2CAAuD;AAShD,KAAK,UAAU,eAAe,CAAC,MAAqB;IACzD,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAElD,6BAA6B;IAC7B,MAAM,kBAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,MAAM,kBAAE,CAAC,SAAS,CAAC,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAC5D,MAAM,kBAAE,CAAC,SAAS,CAAC,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7D,MAAM,kBAAE,CAAC,SAAS,CAAC,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAErD,kCAAkC;IAClC,MAAM,IAAA,sBAAe,EAAC,MAAM,CAAC,CAAC;IAE9B,sBAAsB;IACtB,KAAK,MAAM,WAAW,IAAI,QAAQ,EAAE,CAAC;QACnC,MAAM,IAAA,0BAAgB,EAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACjD,CAAC;IAED,uBAAuB;IACvB,KAAK,MAAM,YAAY,IAAI,SAAS,EAAE,CAAC;QACrC,MAAM,IAAA,4BAAiB,EAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACnD,CAAC;IAED,yBAAyB;IACzB,MAAM,IAAA,6BAAoB,EAAC,SAAS,CAAC,CAAC;IAEtC,sBAAsB;IACtB,MAAM,IAAA,0BAAiB,EAAC,MAAM,CAAC,CAAC;IAEhC,qBAAqB;IACrB,MAAM,IAAA,sBAAe,EAAC,MAAM,CAAC,CAAC;IAE9B,uBAAuB;IACvB,MAAM,IAAA,0BAAmB,EAAC,MAAM,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":";;;;;AAkBA,0CAqCC;AAvDD,wDAA0B;AAC1B,gDAAwB;AACxB,2CAAmD;AACnD,iDAAuD;AACvD,mDAAyD;AACzD,+CAA0D;AAC1D,+CAAuD;AACvD,2CAAmD;AACnD,2CAAuD;AACvD,+CAAuD;AAShD,KAAK,UAAU,eAAe,CAAC,MAAqB;IACzD,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAElD,6BAA6B;IAC7B,MAAM,kBAAE,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,MAAM,kBAAE,CAAC,SAAS,CAAC,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;IAC5D,MAAM,kBAAE,CAAC,SAAS,CAAC,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAC7D,MAAM,kBAAE,CAAC,SAAS,CAAC,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAErD,kCAAkC;IAClC,MAAM,IAAA,sBAAe,EAAC,MAAM,CAAC,CAAC;IAE9B,sBAAsB;IACtB,KAAK,MAAM,WAAW,IAAI,QAAQ,EAAE,CAAC;QACnC,MAAM,IAAA,0BAAgB,EAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IACjD,CAAC;IAED,uBAAuB;IACvB,KAAK,MAAM,YAAY,IAAI,SAAS,EAAE,CAAC;QACrC,MAAM,IAAA,4BAAiB,EAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IACnD,CAAC;IAED,yBAAyB;IACzB,MAAM,IAAA,6BAAoB,EAAC,SAAS,CAAC,CAAC;IAEtC,sBAAsB;IACtB,MAAM,IAAA,0BAAiB,EAAC,MAAM,CAAC,CAAC;IAEhC,qBAAqB;IACrB,MAAM,IAAA,sBAAe,EAAC,MAAM,CAAC,CAAC;IAE9B,uBAAuB;IACvB,MAAM,IAAA,0BAAmB,EAAC,MAAM,CAAC,CAAC;IAElC,qEAAqE;IACrE,4CAA4C;IAC5C,MAAM,IAAA,0BAAiB,EAAC,MAAM,CAAC,CAAC;AAClC,CAAC"}

package/dist/templates/claude.d.ts

@@ -0,0 +1,3 @@
+import { ProjectConfig } from '../scaffold';
+export declare function createClaudeFiles(config: ProjectConfig): Promise<void>;
+//# sourceMappingURL=claude.d.ts.map

package/dist/templates/claude.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.d.ts","sourceRoot":"","sources":["../../src/templates/claude.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAc5E"}

package/dist/templates/claude.js

@@ -0,0 +1,318 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createClaudeFiles = createClaudeFiles;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+async function createClaudeFiles(config) {
+    const { targetDir, projectName, backends, frontends } = config;
+    await createRootClaudeMd(targetDir, projectName, backends, frontends);
+    for (const name of backends) {
+        await createBackendClaudeMd(targetDir, name);
+    }
+    for (const name of frontends) {
+        await createFrontendClaudeMd(targetDir, name);
+    }
+    await createSharedClaudeMd(targetDir);
+}
+async function createRootClaudeMd(targetDir, projectName, backends, frontends) {
+    const backendList = backends.length
+        ? backends.map((n, i) => `  - \`apps/backend/${n}\` — NestJS service (port ${4000 + i})`).join('\n')
+        : '  - _(none)_';
+    const frontendList = frontends.length
+        ? frontends.map((n, i) => `  - \`apps/frontend/${n}\` — Next.js app (port ${3000 + i})`).join('\n')
+        : '  - _(none)_';
+    const content = `# ${projectName}
+
+> This file is auto-loaded by Claude Code at the start of every session.
+> Keep it short, imperative, and pointed at where the truth lives in code.
+> Long-form docs belong in \`docs/\` — link to them from here.
+
+## Project overview
+
+${projectName} is a Turborepo monorepo containing NestJS backends and Next.js frontends sharing
+TypeScript packages, a single Prisma schema, and one Dockerfile with per-app build targets.
+
+- Package manager: **pnpm** (workspaces). Never use \`npm\` or \`yarn\` in this repo.
+- Build orchestrator: **Turborepo** (\`turbo.json\` defines the pipeline).
+- Database: **PostgreSQL** via Prisma in \`packages/database\`.
+- Cache/queues: **Redis**.
+
+## Repo map
+
+\`\`\`
+${projectName}/
+├── apps/
+│   ├── backend/          # NestJS services
+${backendList}
+│   └── frontend/         # Next.js apps
+${frontendList}
+├── packages/
+│   ├── database/         # Prisma schema, migrations, generated client
+│   ├── shared-backend/   # Backend-only utilities (NestJS guards, pipes, types)
+│   ├── shared-frontend/  # React components, hooks, client utilities
+│   ├── shared-common/    # Isomorphic utilities (zod schemas, constants, types)
+│   └── tsconfig/         # Shared tsconfig presets
+├── docs/                 # Human docs — see @docs/ENVIRONMENT.md
+└── Dockerfile            # Multi-stage; one target per app
+\`\`\`
+
+## Common commands
+
+Run from the repo root unless noted.
+
+\`\`\`bash
+pnpm install              # install all workspace deps
+pnpm dev                  # turbo run dev — starts every app in watch mode
+pnpm build                # turbo run build — production builds
+pnpm type-check           # turbo run type-check
+pnpm lint                 # turbo run lint
+
+pnpm db:generate          # regenerate Prisma client (run after schema changes)
+pnpm db:migrate           # prisma migrate dev — create + apply a new migration
+pnpm db:studio            # open Prisma Studio
+
+# Run a single app
+pnpm --filter <app-name> dev
+pnpm --filter <app-name> build
+\`\`\`
+
+Docker (local infra only — Postgres + Redis):
+
+\`\`\`bash
+docker compose -f docker-compose.local.yml up -d
+\`\`\`
+
+Full stack in containers:
+
+\`\`\`bash
+docker compose -f docker-compose.dev.yml up --build
+\`\`\`
+
+## Tech stack conventions
+
+- **TypeScript strict mode** everywhere. No \`any\` without a comment explaining why.
+- **ES modules**. Use \`import\`/\`export\`, not \`require\`.
+- Path aliases resolve via \`@repo/*\` for workspace packages — import shared code as
+  \`import { x } from '@repo/shared-common'\`, never via relative \`../../packages/...\` paths.
+- Validation at boundaries: **zod** schemas live in \`@repo/shared-common\` so frontend and
+  backend share one source of truth. Reuse them — do not redefine DTOs per app.
+- Errors: throw typed errors from \`@repo/shared-backend\`. Don't throw raw \`Error\` strings
+  in HTTP paths.
+
+## Architecture rules
+
+1. **Database access only from backend apps.** Frontends call backend HTTP endpoints; they
+   never import \`@prisma/client\` or \`@repo/database\`.
+2. **Schema is one file.** \`packages/database/prisma/schema.prisma\` is the only Prisma
+   schema. Do not create per-app schemas.
+3. **No cross-app imports.** \`apps/backend/foo\` must not import from \`apps/backend/bar\`.
+   If two apps need the same code, lift it into \`packages/shared-*\`.
+4. **\`shared-frontend\` is React-only**, \`shared-backend\` is Node-only, \`shared-common\` is
+   isomorphic (no \`fs\`, no \`window\`). Pick the right one.
+5. Environment variables are read **once at startup** in a typed config module — not
+   sprinkled as \`process.env.X\` throughout business logic.
+
+## Adding things
+
+- **New backend app** → \`apps/backend/<name>/\`, add a \`package.json\` named \`@app/<name>\`,
+  then add a Docker target in \`Dockerfile\` and services in the three compose files.
+  pnpm picks it up automatically via \`pnpm-workspace.yaml\`.
+- **New frontend app** → same idea under \`apps/frontend/<name>/\`.
+- **New shared package** → \`packages/<name>/\`, name it \`@repo/<name>\`, export a clean
+  public API from \`src/index.ts\`.
+- **New env var** → add to \`.env.example\` AND document in [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md).
+
+## Testing
+
+- Unit tests live next to the code: \`foo.ts\` + \`foo.spec.ts\`.
+- Integration tests that touch the DB use a real Postgres (the \`docker-compose.local.yml\`
+  one) — **do not mock Prisma**. Mocks have hidden divergence from real query behavior.
+- Run a single app's tests: \`pnpm --filter <app-name> test\`.
+
+## Git & CI
+
+- Default branch: \`main\`. Feature branches: \`feat/<short-name>\`, \`fix/<short-name>\`.
+- Conventional commits (\`feat:\`, \`fix:\`, \`chore:\`, \`docs:\`, \`refactor:\`).
+- CI runs \`type-check\`, \`lint\`, \`build\` on every PR (see \`.github/workflows/\`).
+- **Never** commit \`.env\`, \`.env.local\`, \`*.pem\`, or anything under \`packages/database/prisma/migrations\`
+  that wasn't generated by \`pnpm db:migrate\`.
+
+## Don't
+
+- Don't run \`npm install\` or \`yarn\` — use \`pnpm\`.
+- Don't bypass Turbo by \`cd\`-ing into an app and running raw scripts unless debugging.
+- Don't add a new top-level dependency to multiple apps individually — put it in the
+  appropriate \`packages/shared-*\` and re-export.
+- Don't \`prisma db push\` against a shared/dev database — always go through \`prisma migrate\`.
+- Don't edit generated files (\`packages/database/node_modules/.prisma\`, \`.next/\`, \`dist/\`).
+- Don't skip git hooks (\`--no-verify\`) without an explicit reason in the commit body.
+
+## When you finish a task
+
+1. \`pnpm type-check && pnpm lint\` — both must pass.
+2. If you changed the Prisma schema: \`pnpm db:generate\` and create a migration.
+3. If you added an env var: update \`.env.example\` and \`docs/ENVIRONMENT.md\`.
+4. If you added/removed an app: update the Dockerfile and all three compose files.
+
+## Pointers
+
+- Environment variables: @docs/ENVIRONMENT.md
+- README (human-facing setup): @README.md
+- Prisma schema: @packages/database/prisma/schema.prisma
+- Turbo pipeline: @turbo.json
+
+App-specific context lives in per-app \`CLAUDE.md\` files (e.g.
+\`apps/backend/<name>/CLAUDE.md\`). Claude Code auto-discovers them when working inside
+that subtree.
+`;
+    await fs_extra_1.default.writeFile(path_1.default.join(targetDir, 'CLAUDE.md'), content);
+}
+async function createBackendClaudeMd(targetDir, name) {
+    const dir = path_1.default.join(targetDir, 'apps', 'backend', name);
+    await fs_extra_1.default.ensureDir(dir);
+    const content = `# ${name} (backend)
+
+NestJS service. See the root [CLAUDE.md](../../../CLAUDE.md) for monorepo-wide rules;
+this file only documents what is specific to \`${name}\`.
+
+## Layout
+
+\`\`\`
+src/
+├── main.ts              # bootstrap — keep this minimal
+├── app.module.ts        # root module
+├── modules/             # feature modules (one folder per domain concept)
+│   └── <feature>/
+│       ├── <feature>.controller.ts
+│       ├── <feature>.service.ts
+│       ├── <feature>.module.ts
+│       └── dto/         # request/response shapes — prefer importing zod schemas
+│                        # from @repo/shared-common over redefining DTOs here
+└── common/              # cross-cutting filters, guards, interceptors
+\`\`\`
+
+## Conventions
+
+- One feature = one module. Don't put unrelated controllers in the same module.
+- Services are injectable and stateless. Persistent state goes in Prisma or Redis.
+- Use \`@repo/shared-backend\` guards/pipes — don't reinvent them here.
+- Validate request bodies with the zod schemas in \`@repo/shared-common\`. Pair them with
+  the shared \`ZodValidationPipe\`.
+- Health check at \`GET /health\` is required (the prod compose file probes it).
+
+## Commands
+
+\`\`\`bash
+pnpm --filter ${name} dev          # watch mode
+pnpm --filter ${name} build
+pnpm --filter ${name} test
+pnpm --filter ${name} test:e2e
+\`\`\`
+
+## Don't
+
+- Don't import from another backend app (\`apps/backend/<other>\`). Lift shared code into
+  \`packages/shared-backend\` instead.
+- Don't bypass the global validation pipe — every controller input must be validated.
+`;
+    await fs_extra_1.default.writeFile(path_1.default.join(dir, 'CLAUDE.md'), content);
+}
+async function createFrontendClaudeMd(targetDir, name) {
+    const dir = path_1.default.join(targetDir, 'apps', 'frontend', name);
+    await fs_extra_1.default.ensureDir(dir);
+    const content = `# ${name} (frontend)
+
+Next.js app (App Router). See the root [CLAUDE.md](../../../CLAUDE.md) for monorepo-wide
+rules; this file documents only what is specific to \`${name}\`.
+
+## Layout
+
+\`\`\`
+app/                # App Router routes
+  layout.tsx
+  page.tsx
+  (group)/...       # route groups
+components/         # ${name}-specific components
+  ui/               # presentational, no data fetching
+  features/         # feature components that fetch / mutate
+lib/                # ${name}-specific helpers (API client, hooks)
+\`\`\`
+
+Reusable cross-app components live in \`@repo/shared-frontend\`. If you find yourself
+copying a component to another frontend app, move it there.
+
+## Conventions
+
+- **Server Components by default.** Add \`'use client'\` only when you need state, effects,
+  or browser APIs.
+- Data fetching: server components fetch directly; client components use the typed API
+  client from \`@repo/shared-frontend\`.
+- Types and zod schemas come from \`@repo/shared-common\` — do not redefine API response
+  shapes here.
+- All env vars referenced in client code must be prefixed \`NEXT_PUBLIC_\`. Anything else is
+  server-only.
+
+## Commands
+
+\`\`\`bash
+pnpm --filter ${name} dev
+pnpm --filter ${name} build
+pnpm --filter ${name} start        # serve the production build locally
+pnpm --filter ${name} lint
+\`\`\`
+
+## Don't
+
+- Don't import server-only modules (\`fs\`, \`@repo/database\`, \`@repo/shared-backend\`) into
+  client components — Next.js will fail the build.
+- Don't fetch in a \`useEffect\` for data that could be fetched on the server.
+- Don't hand-roll API types. Reuse zod schemas from \`@repo/shared-common\`.
+`;
+    await fs_extra_1.default.writeFile(path_1.default.join(dir, 'CLAUDE.md'), content);
+}
+async function createSharedClaudeMd(targetDir) {
+    const dir = path_1.default.join(targetDir, 'packages');
+    await fs_extra_1.default.ensureDir(dir);
+    const content = `# packages/
+
+Shared workspace packages. See the root [CLAUDE.md](../CLAUDE.md) for monorepo rules.
+
+## Which package does my code go in?
+
+| Code uses...                     | Goes in              |
+| -------------------------------- | -------------------- |
+| \`fs\`, \`process\`, NestJS, Prisma  | \`shared-backend\`     |
+| \`react\`, \`window\`, \`document\`    | \`shared-frontend\`    |
+| Pure TS, zod, no env coupling    | \`shared-common\`      |
+| Prisma schema or DB client       | \`database\`           |
+| tsconfig presets                 | \`tsconfig\`           |
+
+When in doubt, default to \`shared-common\` — it's the safest place because both sides
+can import it.
+
+## Conventions
+
+- Every package exports its public API from \`src/index.ts\`. Don't let consumers
+  deep-import (\`@repo/foo/src/internal/x\`) — that's a leak.
+- Package names are \`@repo/<folder>\`. Keep them in sync with the folder name.
+- Adding a new package: copy the structure of an existing one, add it to
+  \`pnpm-workspace.yaml\` (already covered by the \`packages/*\` glob), run \`pnpm install\`.
+
+## Database package
+
+\`packages/database\` owns the Prisma schema and the generated client. After editing
+\`schema.prisma\`:
+
+\`\`\`bash
+pnpm db:generate     # regenerate the client (required before type-check passes)
+pnpm db:migrate      # create + apply a migration in dev
+\`\`\`
+
+Never run \`prisma db push\` against a shared database — it skips the migration history.
+`;
+    await fs_extra_1.default.writeFile(path_1.default.join(dir, 'CLAUDE.md'), content);
+}
+//# sourceMappingURL=claude.js.map

package/dist/templates/claude.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude.js","sourceRoot":"","sources":["../../src/templates/claude.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-turbo-mono",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "CLI tool to scaffold a monorepo with NestJS backends and Next.js frontends",
   "main": "dist/index.js",
   "bin": {

package/src/scaffold.ts

@@ -7,6 +7,7 @@ import { createSharedPackages } from './templates/shared';
 import { createDockerFiles } from './templates/docker';
 import { createCICDFiles } from './templates/cicd';
 import { createDocumentation } from './templates/docs';
+import { createClaudeFiles } from './templates/claude';
 
 export interface ProjectConfig {
   projectName: string;
@@ -48,4 +49,8 @@ export async function scaffoldProject(config: ProjectConfig): Promise<void> {
 
   // Create documentation
   await createDocumentation(config);
+
+  // Create CLAUDE.md files (root + per-app + packages/) so Claude Code
+  // auto-loads project context every session.
+  await createClaudeFiles(config);
 }

package/src/templates/claude.ts

@@ -0,0 +1,341 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { ProjectConfig } from '../scaffold';
+
+export async function createClaudeFiles(config: ProjectConfig): Promise<void> {
+  const { targetDir, projectName, backends, frontends } = config;
+
+  await createRootClaudeMd(targetDir, projectName, backends, frontends);
+
+  for (const name of backends) {
+    await createBackendClaudeMd(targetDir, name);
+  }
+
+  for (const name of frontends) {
+    await createFrontendClaudeMd(targetDir, name);
+  }
+
+  await createSharedClaudeMd(targetDir);
+}
+
+async function createRootClaudeMd(
+  targetDir: string,
+  projectName: string,
+  backends: string[],
+  frontends: string[]
+): Promise<void> {
+  const backendList = backends.length
+    ? backends.map((n, i) => `  - \`apps/backend/${n}\` — NestJS service (port ${4000 + i})`).join('\n')
+    : '  - _(none)_';
+
+  const frontendList = frontends.length
+    ? frontends.map((n, i) => `  - \`apps/frontend/${n}\` — Next.js app (port ${3000 + i})`).join('\n')
+    : '  - _(none)_';
+
+  const content = `# ${projectName}
+
+> This file is auto-loaded by Claude Code at the start of every session.
+> Keep it short, imperative, and pointed at where the truth lives in code.
+> Long-form docs belong in \`docs/\` — link to them from here.
+
+## Project overview
+
+${projectName} is a Turborepo monorepo containing NestJS backends and Next.js frontends sharing
+TypeScript packages, a single Prisma schema, and one Dockerfile with per-app build targets.
+
+- Package manager: **pnpm** (workspaces). Never use \`npm\` or \`yarn\` in this repo.
+- Build orchestrator: **Turborepo** (\`turbo.json\` defines the pipeline).
+- Database: **PostgreSQL** via Prisma in \`packages/database\`.
+- Cache/queues: **Redis**.
+
+## Repo map
+
+\`\`\`
+${projectName}/
+├── apps/
+│   ├── backend/          # NestJS services
+${backendList}
+│   └── frontend/         # Next.js apps
+${frontendList}
+├── packages/
+│   ├── database/         # Prisma schema, migrations, generated client
+│   ├── shared-backend/   # Backend-only utilities (NestJS guards, pipes, types)
+│   ├── shared-frontend/  # React components, hooks, client utilities
+│   ├── shared-common/    # Isomorphic utilities (zod schemas, constants, types)
+│   └── tsconfig/         # Shared tsconfig presets
+├── docs/                 # Human docs — see @docs/ENVIRONMENT.md
+└── Dockerfile            # Multi-stage; one target per app
+\`\`\`
+
+## Common commands
+
+Run from the repo root unless noted.
+
+\`\`\`bash
+pnpm install              # install all workspace deps
+pnpm dev                  # turbo run dev — starts every app in watch mode
+pnpm build                # turbo run build — production builds
+pnpm type-check           # turbo run type-check
+pnpm lint                 # turbo run lint
+
+pnpm db:generate          # regenerate Prisma client (run after schema changes)
+pnpm db:migrate           # prisma migrate dev — create + apply a new migration
+pnpm db:studio            # open Prisma Studio
+
+# Run a single app
+pnpm --filter <app-name> dev
+pnpm --filter <app-name> build
+\`\`\`
+
+Docker (local infra only — Postgres + Redis):
+
+\`\`\`bash
+docker compose -f docker-compose.local.yml up -d
+\`\`\`
+
+Full stack in containers:
+
+\`\`\`bash
+docker compose -f docker-compose.dev.yml up --build
+\`\`\`
+
+## Tech stack conventions
+
+- **TypeScript strict mode** everywhere. No \`any\` without a comment explaining why.
+- **ES modules**. Use \`import\`/\`export\`, not \`require\`.
+- Path aliases resolve via \`@repo/*\` for workspace packages — import shared code as
+  \`import { x } from '@repo/shared-common'\`, never via relative \`../../packages/...\` paths.
+- Validation at boundaries: **zod** schemas live in \`@repo/shared-common\` so frontend and
+  backend share one source of truth. Reuse them — do not redefine DTOs per app.
+- Errors: throw typed errors from \`@repo/shared-backend\`. Don't throw raw \`Error\` strings
+  in HTTP paths.
+
+## Architecture rules
+
+1. **Database access only from backend apps.** Frontends call backend HTTP endpoints; they
+   never import \`@prisma/client\` or \`@repo/database\`.
+2. **Schema is one file.** \`packages/database/prisma/schema.prisma\` is the only Prisma
+   schema. Do not create per-app schemas.
+3. **No cross-app imports.** \`apps/backend/foo\` must not import from \`apps/backend/bar\`.
+   If two apps need the same code, lift it into \`packages/shared-*\`.
+4. **\`shared-frontend\` is React-only**, \`shared-backend\` is Node-only, \`shared-common\` is
+   isomorphic (no \`fs\`, no \`window\`). Pick the right one.
+5. Environment variables are read **once at startup** in a typed config module — not
+   sprinkled as \`process.env.X\` throughout business logic.
+
+## Adding things
+
+- **New backend app** → \`apps/backend/<name>/\`, add a \`package.json\` named \`@app/<name>\`,
+  then add a Docker target in \`Dockerfile\` and services in the three compose files.
+  pnpm picks it up automatically via \`pnpm-workspace.yaml\`.
+- **New frontend app** → same idea under \`apps/frontend/<name>/\`.
+- **New shared package** → \`packages/<name>/\`, name it \`@repo/<name>\`, export a clean
+  public API from \`src/index.ts\`.
+- **New env var** → add to \`.env.example\` AND document in [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md).
+
+## Testing
+
+- Unit tests live next to the code: \`foo.ts\` + \`foo.spec.ts\`.
+- Integration tests that touch the DB use a real Postgres (the \`docker-compose.local.yml\`
+  one) — **do not mock Prisma**. Mocks have hidden divergence from real query behavior.
+- Run a single app's tests: \`pnpm --filter <app-name> test\`.
+
+## Git & CI
+
+- Default branch: \`main\`. Feature branches: \`feat/<short-name>\`, \`fix/<short-name>\`.
+- Conventional commits (\`feat:\`, \`fix:\`, \`chore:\`, \`docs:\`, \`refactor:\`).
+- CI runs \`type-check\`, \`lint\`, \`build\` on every PR (see \`.github/workflows/\`).
+- **Never** commit \`.env\`, \`.env.local\`, \`*.pem\`, or anything under \`packages/database/prisma/migrations\`
+  that wasn't generated by \`pnpm db:migrate\`.
+
+## Don't
+
+- Don't run \`npm install\` or \`yarn\` — use \`pnpm\`.
+- Don't bypass Turbo by \`cd\`-ing into an app and running raw scripts unless debugging.
+- Don't add a new top-level dependency to multiple apps individually — put it in the
+  appropriate \`packages/shared-*\` and re-export.
+- Don't \`prisma db push\` against a shared/dev database — always go through \`prisma migrate\`.
+- Don't edit generated files (\`packages/database/node_modules/.prisma\`, \`.next/\`, \`dist/\`).
+- Don't skip git hooks (\`--no-verify\`) without an explicit reason in the commit body.
+
+## When you finish a task
+
+1. \`pnpm type-check && pnpm lint\` — both must pass.
+2. If you changed the Prisma schema: \`pnpm db:generate\` and create a migration.
+3. If you added an env var: update \`.env.example\` and \`docs/ENVIRONMENT.md\`.
+4. If you added/removed an app: update the Dockerfile and all three compose files.
+
+## Pointers
+
+- Environment variables: @docs/ENVIRONMENT.md
+- README (human-facing setup): @README.md
+- Prisma schema: @packages/database/prisma/schema.prisma
+- Turbo pipeline: @turbo.json
+
+App-specific context lives in per-app \`CLAUDE.md\` files (e.g.
+\`apps/backend/<name>/CLAUDE.md\`). Claude Code auto-discovers them when working inside
+that subtree.
+`;
+
+  await fs.writeFile(path.join(targetDir, 'CLAUDE.md'), content);
+}
+
+async function createBackendClaudeMd(
+  targetDir: string,
+  name: string
+): Promise<void> {
+  const dir = path.join(targetDir, 'apps', 'backend', name);
+  await fs.ensureDir(dir);
+
+  const content = `# ${name} (backend)
+
+NestJS service. See the root [CLAUDE.md](../../../CLAUDE.md) for monorepo-wide rules;
+this file only documents what is specific to \`${name}\`.
+
+## Layout
+
+\`\`\`
+src/
+├── main.ts              # bootstrap — keep this minimal
+├── app.module.ts        # root module
+├── modules/             # feature modules (one folder per domain concept)
+│   └── <feature>/
+│       ├── <feature>.controller.ts
+│       ├── <feature>.service.ts
+│       ├── <feature>.module.ts
+│       └── dto/         # request/response shapes — prefer importing zod schemas
+│                        # from @repo/shared-common over redefining DTOs here
+└── common/              # cross-cutting filters, guards, interceptors
+\`\`\`
+
+## Conventions
+
+- One feature = one module. Don't put unrelated controllers in the same module.
+- Services are injectable and stateless. Persistent state goes in Prisma or Redis.
+- Use \`@repo/shared-backend\` guards/pipes — don't reinvent them here.
+- Validate request bodies with the zod schemas in \`@repo/shared-common\`. Pair them with
+  the shared \`ZodValidationPipe\`.
+- Health check at \`GET /health\` is required (the prod compose file probes it).
+
+## Commands
+
+\`\`\`bash
+pnpm --filter ${name} dev          # watch mode
+pnpm --filter ${name} build
+pnpm --filter ${name} test
+pnpm --filter ${name} test:e2e
+\`\`\`
+
+## Don't
+
+- Don't import from another backend app (\`apps/backend/<other>\`). Lift shared code into
+  \`packages/shared-backend\` instead.
+- Don't bypass the global validation pipe — every controller input must be validated.
+`;
+
+  await fs.writeFile(path.join(dir, 'CLAUDE.md'), content);
+}
+
+async function createFrontendClaudeMd(
+  targetDir: string,
+  name: string
+): Promise<void> {
+  const dir = path.join(targetDir, 'apps', 'frontend', name);
+  await fs.ensureDir(dir);
+
+  const content = `# ${name} (frontend)
+
+Next.js app (App Router). See the root [CLAUDE.md](../../../CLAUDE.md) for monorepo-wide
+rules; this file documents only what is specific to \`${name}\`.
+
+## Layout
+
+\`\`\`
+app/                # App Router routes
+  layout.tsx
+  page.tsx
+  (group)/...       # route groups
+components/         # ${name}-specific components
+  ui/               # presentational, no data fetching
+  features/         # feature components that fetch / mutate
+lib/                # ${name}-specific helpers (API client, hooks)
+\`\`\`
+
+Reusable cross-app components live in \`@repo/shared-frontend\`. If you find yourself
+copying a component to another frontend app, move it there.
+
+## Conventions
+
+- **Server Components by default.** Add \`'use client'\` only when you need state, effects,
+  or browser APIs.
+- Data fetching: server components fetch directly; client components use the typed API
+  client from \`@repo/shared-frontend\`.
+- Types and zod schemas come from \`@repo/shared-common\` — do not redefine API response
+  shapes here.
+- All env vars referenced in client code must be prefixed \`NEXT_PUBLIC_\`. Anything else is
+  server-only.
+
+## Commands
+
+\`\`\`bash
+pnpm --filter ${name} dev
+pnpm --filter ${name} build
+pnpm --filter ${name} start        # serve the production build locally
+pnpm --filter ${name} lint
+\`\`\`
+
+## Don't
+
+- Don't import server-only modules (\`fs\`, \`@repo/database\`, \`@repo/shared-backend\`) into
+  client components — Next.js will fail the build.
+- Don't fetch in a \`useEffect\` for data that could be fetched on the server.
+- Don't hand-roll API types. Reuse zod schemas from \`@repo/shared-common\`.
+`;
+
+  await fs.writeFile(path.join(dir, 'CLAUDE.md'), content);
+}
+
+async function createSharedClaudeMd(targetDir: string): Promise<void> {
+  const dir = path.join(targetDir, 'packages');
+  await fs.ensureDir(dir);
+
+  const content = `# packages/
+
+Shared workspace packages. See the root [CLAUDE.md](../CLAUDE.md) for monorepo rules.
+
+## Which package does my code go in?
+
+| Code uses...                     | Goes in              |
+| -------------------------------- | -------------------- |
+| \`fs\`, \`process\`, NestJS, Prisma  | \`shared-backend\`     |
+| \`react\`, \`window\`, \`document\`    | \`shared-frontend\`    |
+| Pure TS, zod, no env coupling    | \`shared-common\`      |
+| Prisma schema or DB client       | \`database\`           |
+| tsconfig presets                 | \`tsconfig\`           |
+
+When in doubt, default to \`shared-common\` — it's the safest place because both sides
+can import it.
+
+## Conventions
+
+- Every package exports its public API from \`src/index.ts\`. Don't let consumers
+  deep-import (\`@repo/foo/src/internal/x\`) — that's a leak.
+- Package names are \`@repo/<folder>\`. Keep them in sync with the folder name.
+- Adding a new package: copy the structure of an existing one, add it to
+  \`pnpm-workspace.yaml\` (already covered by the \`packages/*\` glob), run \`pnpm install\`.
+
+## Database package
+
+\`packages/database\` owns the Prisma schema and the generated client. After editing
+\`schema.prisma\`:
+
+\`\`\`bash
+pnpm db:generate     # regenerate the client (required before type-check passes)
+pnpm db:migrate      # create + apply a migration in dev
+\`\`\`
+
+Never run \`prisma db push\` against a shared database — it skips the migration history.
+`;
+
+  await fs.writeFile(path.join(dir, 'CLAUDE.md'), content);
+}