@idevconn/create-icore 0.4.1 → 0.5.1

package/dist/cli.js

@@ -201,6 +201,12 @@ Re-run with @latest to refresh:
   });
   if (p.isCancel(transport)) throw new Error("cancelled");
   const packageManager = flags.packageManager ?? detectPackageManager();
+  if (packageManager === "yarn") {
+    p.note(
+      "yarn 4.15+ enforces a 24h publish-age gate (npmMinimalAgeGate=1d), so a\n`yarn create @idevconn/icore@latest` run within 24h of a release resolves an\nolder version. If the banner above shows an unexpectedly old version, either:\n  \u2022 wait \u2014 the version auto-unlocks 24h after publish, or\n  \u2022 bypass once:  yarn config set npmMinimalAgeGate 0  (then re-run), or\n  \u2022 use npm/pnpm: npm init @idevconn/icore@latest <name> -- [flags]",
+      "\u26A0 yarn 24h age-gate"
+    );
+  }
   const initGit = flags.initGit ?? !await p.confirm({ message: "Initialise git repo?", initialValue: true }) === false;
   const install = flags.install ?? !await p.confirm({
     message: `Run ${packageManager} install?`,
@@ -228,6 +234,13 @@ import { copyFile, mkdir, readdir, readFile as readFile2, stat, writeFile, rm }
 import { readFileSync } from "fs";
 import { join as join2 } from "path";
 import { spawnSync } from "child_process";
+
+// src/lib/options.ts
+function pmRun(pm, script) {
+  return pm === "npm" ? `npm run ${script}` : `${pm} ${script}`;
+}
+
+// src/lib/scaffold.ts
 var IGNORE_TOP = /* @__PURE__ */ new Set([
   ".git",
   "node_modules",
@@ -260,9 +273,29 @@ async function rewriteRootPackageJson(targetDir, opts) {
   pkg["version"] = "0.0.1";
   pkg["private"] = true;
   delete pkg.description;
+  if (opts.transport === "nats") {
+    const deps = pkg["dependencies"] ??= {};
+    deps["nats"] = "^2.29.3";
+  }
   if (opts.packageManager !== "yarn") {
     delete pkg.packageManager;
   }
+  if (opts.packageManager === "pnpm") {
+    pkg["pnpm"] = {
+      onlyBuiltDependencies: [
+        "@firebase/util",
+        "@nestjs/core",
+        "@parcel/watcher",
+        "@scarf/scarf",
+        "@swc/core",
+        "less",
+        "msgpackr-extract",
+        "nx",
+        "protobufjs",
+        "unrs-resolver"
+      ]
+    };
+  }
   await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
 async function writeAuthEnv(targetDir, opts) {
@@ -300,9 +333,9 @@ async function writeNotesEnv(targetDir, opts) {
 async function writeGatewayEnv(targetDir, opts) {
   const envExample = join2(targetDir, "apps/api/.env.example");
   const env = await readFile2(envExample, "utf8");
-  let next = env.replace(/^AUTH_TRANSPORT=.*$/m, `AUTH_TRANSPORT=${opts.transport}`).replace(/^UPLOAD_TRANSPORT=.*$/m, `UPLOAD_TRANSPORT=${opts.transport}`);
+  let next = env.replace(/^AUTH_TRANSPORT=.*$/m, `AUTH_TRANSPORT=${opts.transport}`).replace(/^UPLOAD_TRANSPORT=.*$/m, `UPLOAD_TRANSPORT=${opts.transport}`).replace(/^NOTES_TRANSPORT=.*$/m, `NOTES_TRANSPORT=${opts.transport}`).replace(/^PAYMENT_TRANSPORT=.*$/m, `PAYMENT_TRANSPORT=${opts.transport}`);
   if (opts.transport !== "tcp") {
-    next = next.replace(/^# (AUTH_(?:REDIS|NATS)_URL=)/m, "$1").replace(/^# (UPLOAD_(?:REDIS|NATS)_URL=)/m, "$1");
+    next = next.replace(/^# (AUTH_(?:REDIS|NATS)_URL=)/m, "$1").replace(/^# (UPLOAD_(?:REDIS|NATS)_URL=)/m, "$1").replace(/^# (NOTES_(?:REDIS|NATS)_URL=)/m, "$1").replace(/^# (PAYMENT_(?:REDIS|NATS)_URL=)/m, "$1");
   }
   await writeFile(join2(targetDir, "apps/api/.env"), next);
 }
@@ -315,6 +348,25 @@ async function writeRootEnv(targetDir, opts) {
   ];
   await writeFile(join2(targetDir, ".env"), lines.join("\n"));
 }
+async function stripGatewayTransport(targetDir, prefix) {
+  const gatewayEnv = join2(targetDir, "apps/api/.env");
+  try {
+    const env = await readFile2(gatewayEnv, "utf8");
+    const next = env.split("\n").filter(
+      (line) => !line.startsWith(`${prefix}_`) && !line.startsWith(`# ${prefix}_`) && !line.includes(`${prefix} MS transport`)
+    ).join("\n");
+    await writeFile(gatewayEnv, next);
+  } catch {
+  }
+}
+async function writeClientEnv(targetDir) {
+  const envExample = join2(targetDir, "apps/client/.env.example");
+  try {
+    const env = await readFile2(envExample, "utf8");
+    await writeFile(join2(targetDir, "apps/client/.env"), env);
+  } catch {
+  }
+}
 async function writePaymentEnv(targetDir, opts) {
   if (opts.payment === "none") return;
   const envExample = join2(targetDir, "apps/microservices/payment/.env.example");
@@ -391,6 +443,7 @@ async function removePaymentStack(targetDir) {
     "@icore/payment-client",
     "@idevconn/payment"
   ]);
+  await stripGatewayTransport(targetDir, "PAYMENT");
 }
 async function removeNotesStack(targetDir) {
   for (const p3 of [
@@ -412,6 +465,7 @@ async function removeNotesStack(targetDir) {
   } catch {
   }
   await stripDeps(join2(targetDir, "apps/api/package.json"), ["@icore/notes-client"]);
+  await stripGatewayTransport(targetDir, "NOTES");
   const tsconfigPath = join2(targetDir, "tsconfig.base.json");
   try {
     const src = await readFile2(tsconfigPath, "utf8");
@@ -468,15 +522,17 @@ async function stripTsconfigPath(targetDir, alias) {
 }
 async function removeUnusedAuthStrategies(targetDir, authProvider) {
   const modulePath = join2(targetDir, "apps/microservices/auth/src/app/app.module.ts");
+  const AUTH_BRANCH = /if \(provider === 'supabase'\) return makeSupabaseAuth\(cfg\);\n\s*return makeFirebaseAuth\(cfg\);/m;
   if (authProvider === "supabase") {
     await rm(join2(targetDir, "libs/auth-strategies/firebase"), { recursive: true, force: true });
     await stripDeps(join2(targetDir, "apps/microservices/auth/package.json"), [
-      "@icore/auth-firebase"
+      "@icore/auth-firebase",
+      "@icore/firebase-admin"
     ]);
     await stripTsconfigPath(targetDir, "@icore/auth-firebase");
     try {
       const src = await readFile2(modulePath, "utf8");
-      const next = src.replace(/^import \* as admin from 'firebase-admin';\n/m, "").replace(/^import \{[^}]*FirebaseAuthStrategy[^}]*\} from '@icore\/auth-firebase';\n/m, "").replace(/^function makeFirebaseStrategy\b[\s\S]*?\n^}\n/m, "").replace(/(?<=\n) *case 'firebase':\n *return makeFirebaseStrategy\(cfg\);\n/, "");
+      const next = src.replace(/^import \{[^}]*\} from '@icore\/firebase-admin';\n/m, "").replace(/^import \{[^}]*FirebaseAuthStrategy[^}]*\} from '@icore\/auth-firebase';\n/m, "").replace(/^ {2}firebase: \[[^\]]*\],\n/m, "").replace(/\nfunction makeFirebaseAuth[\s\S]*?\n}\n/m, "").replace(AUTH_BRANCH, "return makeSupabaseAuth(cfg);");
       await writeFile(modulePath, next);
     } catch {
     }
@@ -489,10 +545,7 @@ async function removeUnusedAuthStrategies(targetDir, authProvider) {
     await stripTsconfigPath(targetDir, "@icore/auth-supabase");
     try {
       const src = await readFile2(modulePath, "utf8");
-      const next = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(/^import \{[^}]*SupabaseAuthStrategy[^}]*\} from '@icore\/auth-supabase';\n/m, "").replace(
-        /\n {10}case 'supabase': \{[\s\S]*?return new SupabaseAuthStrategy\(\{ client \}\);\n {10}\}\n/m,
-        ""
-      );
+      const next = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(/^import \{[^}]*SupabaseAuthStrategy[^}]*\} from '@icore\/auth-supabase';\n/m, "").replace(/\nfunction makeSupabaseAuth[\s\S]*?\n}\n/m, "").replace(AUTH_BRANCH, "return makeFirebaseAuth(cfg);");
       await writeFile(modulePath, next);
     } catch {
     }
@@ -504,7 +557,8 @@ async function removeUnusedStorageStrategies(targetDir, uploadProvider) {
   if (uploadProvider !== "firebase") {
     await rm(join2(targetDir, "libs/storage-strategies/firebase"), { recursive: true, force: true });
     await stripDeps(join2(targetDir, "apps/microservices/upload/package.json"), [
-      "@icore/storage-firebase"
+      "@icore/storage-firebase",
+      "@icore/firebase-admin"
     ]);
     await stripTsconfigPath(targetDir, "@icore/storage-firebase");
   }
@@ -528,26 +582,26 @@ async function removeUnusedStorageStrategies(targetDir, uploadProvider) {
   try {
     let src = await readFile2(modulePath, "utf8");
     if (uploadProvider !== "firebase") {
-      src = src.replace(/^import \* as admin from 'firebase-admin';\n/m, "").replace(
+      src = src.replace(/^import \{[^}]*\} from '@icore\/firebase-admin';\n/m, "").replace(
         /^import \{[^}]*FirebaseStorageStrategy[^}]*\} from '@icore\/storage-firebase';\n/m,
         ""
-      ).replace(/^function makeFirebaseStorage\b[\s\S]*?\n^}\n/m, "").replace(/(?<=\n) *case 'firebase':\n *return makeFirebaseStorage\(cfg\);\n/, "");
+      ).replace(/^ {2}firebase: \[[^\]]*\],\n/m, "").replace(/\nfunction makeFirebaseStorage[\s\S]*?\n}\n/m, "");
     }
     if (uploadProvider !== "cloudinary") {
       src = src.replace(/^import \{ v2 as cloudinary \} from 'cloudinary';\n/m, "").replace(
         /^import \{[^}]*CloudinaryStorageStrategy[^}]*\} from '@icore\/storage-cloudinary';\n/m,
         ""
-      ).replace(/^function makeCloudinaryStorage\b[\s\S]*?\n^}\n/m, "").replace(/(?<=\n) *case 'cloudinary':\n *return makeCloudinaryStorage\(cfg\);\n/, "");
+      ).replace(/\nfunction makeCloudinaryStorage[\s\S]*?\n}\n/m, "");
     }
     if (uploadProvider !== "supabase") {
       src = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(
         /^import \{[^}]*SupabaseStorageStrategy[^}]*\} from '@icore\/storage-supabase';\n/m,
         ""
-      ).replace(
-        /\n {10}case 'supabase': \{[\s\S]*?bucket: requireEnv\(cfg, 'SUPABASE_STORAGE_BUCKET'\),\n {12}\}\);\n {10}\}\n/m,
-        ""
-      );
+      ).replace(/\nfunction makeSupabaseStorage[\s\S]*?\n}\n/m, "");
     }
+    const STORAGE_BRANCH = /if \(provider === 'supabase'\) return makeSupabaseStorage\(cfg\);\n\s*if \(provider === 'firebase'\) return makeFirebaseStorage\(cfg\);\n\s*return makeCloudinaryStorage\(cfg\);/m;
+    const chosenReturn = `return make${uploadProvider.charAt(0).toUpperCase() + uploadProvider.slice(1)}Storage(cfg);`;
+    src = src.replace(STORAGE_BRANCH, chosenReturn);
     await writeFile(modulePath, src);
   } catch {
   }
@@ -557,14 +611,15 @@ async function removeUnusedDbStrategies(targetDir, dbProvider) {
   if (dbProvider === "supabase") {
     await rm(join2(targetDir, "libs/db-strategies/firestore"), { recursive: true, force: true });
     await stripDeps(join2(targetDir, "apps/microservices/notes/package.json"), [
-      "@icore/db-firestore"
+      "@icore/db-firestore",
+      "@icore/firebase-admin"
     ]);
     await stripTsconfigPath(targetDir, "@icore/db-firestore");
     try {
       const src = await readFile2(modulePath, "utf8");
-      const next = src.replace(/^import \* as admin from 'firebase-admin';\n/m, "").replace(/^import \{[^}]*FirestoreDBStrategy[^}]*\} from '@icore\/db-firestore';\n/m, "").replace(
-        /\n {8}if \(provider === 'firestore'[\s\S]*?return new FirestoreDBStrategy\(\{[\s\S]*?\}\);\n {8}\}\n/m,
-        ""
+      const next = src.replace(/^import \{[^}]*\} from '@icore\/firebase-admin';\n/m, "").replace(/^import \{[^}]*FirestoreDBStrategy[^}]*\} from '@icore\/db-firestore';\n/m, "").replace(/^ {2}firestore: \[[^\]]*\],\n/m, "").replace(/^ {2}firebase: \[[^\]]*\],\n/m, "").replace(/\nfunction makeFirestoreDB[\s\S]*?\n}\n/m, "").replace(
+        /if \(provider === 'supabase'\) return makeSupabaseDB\(cfg\);\n\s*return makeFirestoreDB\(cfg\);/m,
+        "return makeSupabaseDB(cfg);"
       );
       await writeFile(modulePath, next);
     } catch {
@@ -578,15 +633,19 @@ async function removeUnusedDbStrategies(targetDir, dbProvider) {
     await stripTsconfigPath(targetDir, "@icore/db-supabase");
     try {
       const src = await readFile2(modulePath, "utf8");
-      const next = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(/^import \{[^}]*SupabaseDBStrategy[^}]*\} from '@icore\/db-supabase';\n/m, "").replace(
-        /\n {8}if \(provider === 'supabase'\) \{[\s\S]*?return new SupabaseDBStrategy\(\{ client \}\);\n {8}\}\n/m,
-        ""
+      const next = src.replace(/^import \{ createClient \} from '@supabase\/supabase-js';\n/m, "").replace(/^import \{[^}]*SupabaseDBStrategy[^}]*\} from '@icore\/db-supabase';\n/m, "").replace(/\nfunction makeSupabaseDB[\s\S]*?\n}\n/m, "").replace(
+        /if \(provider === 'supabase'\) return makeSupabaseDB\(cfg\);\n\s*return makeFirestoreDB\(cfg\);/m,
+        "return makeFirestoreDB(cfg);"
       );
       await writeFile(modulePath, next);
     } catch {
     }
   }
 }
+async function removeFirebaseAdminLib(targetDir) {
+  await rm(join2(targetDir, "libs/firebase-admin"), { recursive: true, force: true });
+  await stripTsconfigPath(targetDir, "@icore/firebase-admin");
+}
 async function removeUploadStack(targetDir) {
   const paths = [
     "apps/microservices/upload",
@@ -691,6 +750,7 @@ async function scaffold(opts, templatesDir2) {
   await writeGatewayEnv(opts.targetDir, opts);
   await writeRootEnv(opts.targetDir, opts);
   await selectClientTemplate(opts.targetDir, opts);
+  await writeClientEnv(opts.targetDir);
   if (opts.upload === "none") await removeUploadStack(opts.targetDir);
   if (opts.payment === "none") await removePaymentStack(opts.targetDir);
   if (opts.jobs === "none") await removeJobsStack(opts.targetDir);
@@ -698,12 +758,230 @@ async function scaffold(opts, templatesDir2) {
   await removeUnusedAuthStrategies(opts.targetDir, opts.authProvider);
   await removeUnusedStorageStrategies(opts.targetDir, opts.upload);
   await removeUnusedDbStrategies(opts.targetDir, opts.dbProvider);
+  const firebaseUsed = opts.authProvider === "firebase" || opts.dbProvider === "firebase" || opts.upload === "firebase";
+  if (!firebaseUsed) await removeFirebaseAdminLib(opts.targetDir);
   if (opts.packageManager === "yarn") {
     await writeFile(join2(opts.targetDir, "yarn.lock"), "");
+  } else {
+    await rm(join2(opts.targetDir, ".yarn"), { recursive: true, force: true });
+    await rm(join2(opts.targetDir, ".yarnrc.yml"), { force: true });
   }
+  await patchGitignoreForPm(opts.targetDir, opts.packageManager);
+  await writeAiFiles(opts.targetDir, opts);
   if (opts.install) runInstall(opts.targetDir, opts.packageManager);
   if (opts.initGit) gitInit(opts.targetDir, opts.projectName);
 }
+async function patchGitignoreForPm(targetDir, pm) {
+  const giPath = join2(targetDir, ".gitignore");
+  try {
+    let src = await readFile2(giPath, "utf8");
+    src = src.replace(/^# Build artifacts.*\ntools\/create-icore\/templates\/\s*\n/m, "");
+    if (pm !== "yarn") {
+      src = src.replace(/^\.yarn\/\*\s*\n/m, "").replace(/^!\.yarn\/patches\s*\n/m, "").replace(/^!\.yarn\/plugins\s*\n/m, "").replace(/^!\.yarn\/releases\s*\n/m, "").replace(/^!\.yarn\/sdks\s*\n/m, "").replace(/^!\.yarn\/versions\s*\n/m, "").replace(/^\.pnp\.\*\s*\n/m, "");
+    }
+    if (pm === "pnpm") {
+      if (!src.includes(".pnpm-debug.log")) {
+        src += "\n# pnpm\n.pnpm-debug.log*\n";
+      }
+    }
+    if (pm === "npm") {
+      if (!src.includes("npm-debug.log")) {
+        src += "\n# npm\nnpm-debug.log*\n";
+      }
+    }
+    await writeFile(giPath, src);
+  } catch {
+  }
+}
+async function writeAiFiles(targetDir, opts) {
+  const pm = opts.packageManager;
+  const nx = pm === "npm" ? "npx nx" : `${pm} nx`;
+  const devCmd = pmRun(pm, "dev");
+  const activeMSes = ["auth (port 4001)"];
+  if (opts.upload !== "none") activeMSes.push(`upload (port 4002)`);
+  if (opts.payment !== "none") activeMSes.push(`payment (port 4003)`);
+  if (opts.example !== "none") activeMSes.push(`notes (port 4004)`);
+  if (opts.jobs !== "none") activeMSes.push(`jobs (standalone)`);
+  const usesSupabase = opts.authProvider === "supabase" || opts.dbProvider === "supabase" || opts.upload === "supabase";
+  const usesFirebase = opts.authProvider === "firebase" || opts.dbProvider === "firebase" || opts.upload === "firebase";
+  await writeFile(join2(targetDir, "CLAUDE.md"), "@AGENTS.md\n");
+  const uiLabel = { shadcn: "shadcn/ui + Tailwind", antd: "Ant Design 6", mui: "MUI 6" }[opts.ui];
+  const readme = `# ${opts.projectName}
+
+> Scaffolded with [iCore](https://github.com/iDEVconn/create-icore) \u2014 Nx + NestJS + React full-stack template.
+
+## Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Monorepo | Nx + ${pm} |
+| Gateway | NestJS 11 + Swagger |
+| Auth | ${opts.authProvider} |
+| Database | ${opts.dbProvider} |
+| Upload | ${opts.upload === "none" ? "\u2014" : opts.upload} |
+| UI | ${uiLabel} + TanStack Router + Query |
+| i18n | i18next (en / ru / he) |
+
+## Quick start
+
+\`\`\`bash
+# 1. Fill in provider credentials
+#    apps/microservices/auth/.env
+#    apps/microservices/upload/.env  (if upload is enabled)
+#    apps/client/.env               (VITE_API_URL \u2014 already defaults to /api)
+
+# 2. Start everything
+${devCmd}
+# \u2192 http://localhost:4200        client
+# \u2192 http://localhost:3001/api/docs  Swagger
+\`\`\`
+
+## Commands
+
+\`\`\`bash
+${nx} run <project>:serve   # start a single service
+${nx} test <project>         # unit tests
+${nx} lint <project>         # lint
+${nx} build <project>        # production build
+${pm === "yarn" ? "yarn remove-notes" : pm === "pnpm" ? "pnpm remove-notes" : "npm run remove-notes"}                  # strip the notes sample feature
+\`\`\`
+
+## Scaffolded by
+
+[iCore](https://github.com/iDEVconn/create-icore) \u2014 [@idevconn/create-icore](https://www.npmjs.com/package/@idevconn/create-icore)
+
+## License
+
+Apache-2.0
+`;
+  await writeFile(join2(targetDir, "README.md"), readme);
+  const agents = `# ${opts.projectName} \u2014 Agent Instructions
+
+## Stack snapshot
+
+| Dimension  | Choice |
+|------------|--------|
+| Auth       | ${opts.authProvider} |
+| Database   | ${opts.dbProvider} |
+| Upload     | ${opts.upload} |
+| Payment    | ${opts.payment} |
+| Jobs       | ${opts.jobs} |
+| UI         | ${opts.ui} |
+| Transport  | ${opts.transport} |
+| PM         | ${pm} |
+
+## \u{1F680} Mandatory Workflow
+
+- **Branch strategy**: \`dev\` is default. Cut \`feature/<name>\` or \`bug/<name>\` from dev. PRs only target dev. Never push directly to main.
+- **No code without approval**: Propose changes first, wait for go-ahead.
+- **\u0417\u0410\u041A\u041E\u041D \u2014 no crash on missing .env**: MS factories must catch config errors, print a boxed banner with ALL missing vars, and return a Fake strategy in dev. In prod (\`NODE_ENV=production\`) throw the same banner. The \`formatEnvBanner\` + \`missingEnv\` helpers from \`@icore/shared\` handle this.
+- **Post-coding routine**: \`npx prettier --write <files>\` \u2192 \`${nx} lint <project>\` \u2192 \`${nx} build <project>\` \u2014 all green before committing.
+- **Nx generators only**: never hand-write \`project.json\` / tsconfig stacks. Use \`${nx} g @nx/<plugin>:<schematic>\`.
+
+## Architecture
+
+\`\`\`
+apps/
+\u251C\u2500\u2500 api/               NestJS gateway \u2014 all client traffic enters here (:3001)
+\u251C\u2500\u2500 microservices/
+${activeMSes.map((s) => `\u2502   \u251C\u2500\u2500 ${s.split(" ")[0]}/`).join("\n")}
+\u2514\u2500\u2500 client/            Vite + React 19 + ${opts.ui} (:4200)
+libs/
+\u251C\u2500\u2500 shared/            contracts, CASL, transport helpers, env banner utils
+\u251C\u2500\u2500 auth-strategies/${opts.authProvider}/
+${opts.upload !== "none" ? `\u251C\u2500\u2500 storage-strategies/${opts.upload}/
+` : ""}\u251C\u2500\u2500 db-strategies/${opts.dbProvider === "firebase" ? "firestore" : opts.dbProvider}/
+\u251C\u2500\u2500 auth-client/       gateway \u2192 auth MS (TCP/Redis/NATS)
+${opts.upload !== "none" ? `\u251C\u2500\u2500 upload-client/     gateway \u2192 upload MS
+` : ""}\u2514\u2500\u2500 template-shared/   browser-safe React foundation (stores, i18n, CASL)
+\`\`\`
+
+## Key patterns
+
+**Strategy swap** \u2014 provider is chosen at runtime via env. Never import a concrete strategy in app code; always inject via the factory token (\`AuthStrategy\`, \`StorageStrategy\`, \`DBStrategy\`).
+
+**Transport** \u2014 \`buildTransport(prefix)\` reads \`${opts.transport.toUpperCase()}*\` vars. Same helper on gateway client-modules and each MS \`main.ts\`. Supports tcp / redis / nats \u2014 change by flipping \`*_TRANSPORT\` in \`.env\`.
+
+**Env layering**:
+1. Root \`.env\` \u2014 \`DB_PROVIDER\`
+2. \`apps/api/.env\` \u2014 gateway transport endpoints
+3. \`apps/microservices/<name>/.env\` \u2014 each MS provider + transport
+4. \`apps/client/.env\` \u2014 \`VITE_API_URL\`
+
+## Commands
+
+\`\`\`bash
+${devCmd}                     # start all services
+${nx} run api:serve           # gateway only
+${nx} run auth:serve          # auth MS only
+${nx} test <project>          # run tests
+${nx} lint <project>          # lint
+${nx} build <project>         # build
+${nx} g @nx/nest:resource     # generate NestJS resource
+\`\`\`
+
+## .env files to configure
+
+| File | Key vars |
+|------|----------|
+| \`apps/microservices/auth/.env\` | \`AUTH_PROVIDER=${opts.authProvider}\`, ${opts.authProvider === "supabase" ? "`SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`" : "`FB_ADMIN_*`, `FIREBASE_WEB_API_KEY`"} |
+${opts.upload !== "none" ? `| \`apps/microservices/upload/.env\` | \`STORAGE_PROVIDER=${opts.upload}\`, provider creds |
+` : ""}| \`apps/microservices/notes/.env\` | \`DB_PROVIDER=${opts.dbProvider}\`, DB creds |
+| \`apps/client/.env\` | \`VITE_API_URL=/api\` (proxied to :3001 in dev) |
+
+## Testing
+
+- Unit tests: Vitest, files named \`*.unit.test.ts(x)\` in \`__tests__/\` next to source.
+- Test behaviour, not implementation. Fake strategies from \`@icore/shared\` (FakeAuthStrategy etc.) serve as test doubles.
+- Run: \`${nx} test <project>\`
+`;
+  await writeFile(join2(targetDir, "AGENTS.md"), agents);
+  await mkdir(join2(targetDir, ".claude"), { recursive: true });
+  const mcpServers = {
+    nx: {
+      command: "npx",
+      args: ["-y", "@nx/mcp@latest", "--directory", "."],
+      type: "stdio"
+    }
+  };
+  if (usesSupabase) {
+    mcpServers["supabase"] = {
+      command: "npx",
+      args: [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--access-token",
+        "<SUPABASE_PERSONAL_ACCESS_TOKEN>"
+      ],
+      type: "stdio"
+    };
+  }
+  if (usesFirebase) {
+    mcpServers["firebase"] = {
+      command: "npx",
+      args: ["-y", "firebase-tools@latest", "experimental:mcp"],
+      type: "stdio"
+    };
+  }
+  const nxCmds = [`Bash(${nx} *)`, `Bash(${devCmd})`];
+  if (pm !== "npm") nxCmds.push(`Bash(npx nx *)`);
+  const settings = {
+    mcpServers,
+    permissions: {
+      allow: [
+        ...nxCmds,
+        "Bash(npx prettier *)",
+        "Bash(git status)",
+        "Bash(git diff *)",
+        "Bash(git log *)"
+      ]
+    }
+  };
+  await writeFile(
+    join2(targetDir, ".claude", "settings.json"),
+    JSON.stringify(settings, null, 2) + "\n"
+  );
+}
 
 // src/cli.ts
 var [nodeMajor] = process.versions.node.split(".").map(Number);
@@ -735,7 +1013,9 @@ async function main() {
   p2.log.info(`Next:`);
   p2.log.info(`  cd ${opts.projectName}`);
   if (!opts.install) p2.log.info(`  ${opts.packageManager} install`);
-  p2.log.info(`  ${opts.packageManager} dev      # gateway + auth MS + upload MS + client`);
+  p2.log.info(
+    `  ${pmRun(opts.packageManager, "dev")}      # gateway + auth MS + upload MS + client`
+  );
   p2.log.info(`  open http://localhost:4200`);
   p2.log.info(`  edit apps/microservices/auth/.env to plug in real ${opts.authProvider} creds`);
 }