@idevconn/create-icore 0.4.0 → 0.5.0

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?`,
@@ -225,6 +231,7 @@ Re-run with @latest to refresh:
 
 // src/lib/scaffold.ts
 import { copyFile, mkdir, readdir, readFile as readFile2, stat, writeFile, rm } from "fs/promises";
+import { readFileSync } from "fs";
 import { join as join2 } from "path";
 import { spawnSync } from "child_process";
 var IGNORE_TOP = /* @__PURE__ */ new Set([
@@ -262,6 +269,22 @@ async function rewriteRootPackageJson(targetDir, opts) {
   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) {
@@ -314,6 +337,14 @@ async function writeRootEnv(targetDir, opts) {
   ];
   await writeFile(join2(targetDir, ".env"), lines.join("\n"));
 }
+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");
@@ -662,9 +693,23 @@ function gitInit(cwd, projectName) {
     { cwd, stdio: "inherit" }
   );
 }
+function resolveYarnBin(cwd) {
+  try {
+    const yarnrc = readFileSync(join2(cwd, ".yarnrc.yml"), "utf8");
+    const match = yarnrc.match(/^yarnPath:\s*(.+)$/m);
+    if (match?.[1]) return join2(cwd, match[1].trim());
+  } catch {
+  }
+  return join2(cwd, ".yarn", "releases", "yarn-4.5.0.cjs");
+}
 function runInstall(cwd, pm) {
-  const [cmd, ...args] = pm === "npm" ? ["npm", "install"] : pm === "pnpm" ? ["pnpm", "install"] : ["yarn", "install"];
-  spawnSync(cmd, args, { cwd, stdio: "inherit" });
+  if (pm === "yarn") {
+    spawnSync("node", [resolveYarnBin(cwd), "install"], { cwd, stdio: "inherit" });
+  } else if (pm === "npm") {
+    spawnSync("npm", ["install"], { cwd, stdio: "inherit" });
+  } else {
+    spawnSync("pnpm", ["install"], { cwd, stdio: "inherit" });
+  }
 }
 async function scaffold(opts, templatesDir2) {
   await copyTree(templatesDir2, opts.targetDir);
@@ -676,6 +721,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);
@@ -686,9 +732,199 @@ async function scaffold(opts, templatesDir2) {
   if (opts.packageManager === "yarn") {
     await writeFile(join2(opts.targetDir, "yarn.lock"), "");
   }
+  await writeAiFiles(opts.targetDir, opts);
   if (opts.install) runInstall(opts.targetDir, opts.packageManager);
   if (opts.initGit) gitInit(opts.targetDir, opts.projectName);
 }
+async function writeAiFiles(targetDir, opts) {
+  const pm = opts.packageManager;
+  const nx = pm === "npm" ? "npx nx" : `${pm} nx`;
+  const devCmd = `${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);

package/dist/index.cjs

@@ -41,6 +41,7 @@ var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
 // src/lib/scaffold.ts
 var import_promises = require("fs/promises");
+var import_node_fs = require("fs");
 var import_node_path = require("path");
 var import_node_child_process = require("child_process");
 var IGNORE_TOP = /* @__PURE__ */ new Set([
@@ -78,6 +79,22 @@ async function rewriteRootPackageJson(targetDir, opts) {
   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 (0, import_promises.writeFile)(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 }
 async function writeAuthEnv(targetDir, opts) {
@@ -130,6 +147,14 @@ async function writeRootEnv(targetDir, opts) {
   ];
   await (0, import_promises.writeFile)((0, import_node_path.join)(targetDir, ".env"), lines.join("\n"));
 }
+async function writeClientEnv(targetDir) {
+  const envExample = (0, import_node_path.join)(targetDir, "apps/client/.env.example");
+  try {
+    const env = await (0, import_promises.readFile)(envExample, "utf8");
+    await (0, import_promises.writeFile)((0, import_node_path.join)(targetDir, "apps/client/.env"), env);
+  } catch {
+  }
+}
 async function writePaymentEnv(targetDir, opts) {
   if (opts.payment === "none") return;
   const envExample = (0, import_node_path.join)(targetDir, "apps/microservices/payment/.env.example");
@@ -478,9 +503,23 @@ function gitInit(cwd, projectName) {
     { cwd, stdio: "inherit" }
   );
 }
+function resolveYarnBin(cwd) {
+  try {
+    const yarnrc = (0, import_node_fs.readFileSync)((0, import_node_path.join)(cwd, ".yarnrc.yml"), "utf8");
+    const match = yarnrc.match(/^yarnPath:\s*(.+)$/m);
+    if (match?.[1]) return (0, import_node_path.join)(cwd, match[1].trim());
+  } catch {
+  }
+  return (0, import_node_path.join)(cwd, ".yarn", "releases", "yarn-4.5.0.cjs");
+}
 function runInstall(cwd, pm) {
-  const [cmd, ...args] = pm === "npm" ? ["npm", "install"] : pm === "pnpm" ? ["pnpm", "install"] : ["yarn", "install"];
-  (0, import_node_child_process.spawnSync)(cmd, args, { cwd, stdio: "inherit" });
+  if (pm === "yarn") {
+    (0, import_node_child_process.spawnSync)("node", [resolveYarnBin(cwd), "install"], { cwd, stdio: "inherit" });
+  } else if (pm === "npm") {
+    (0, import_node_child_process.spawnSync)("npm", ["install"], { cwd, stdio: "inherit" });
+  } else {
+    (0, import_node_child_process.spawnSync)("pnpm", ["install"], { cwd, stdio: "inherit" });
+  }
 }
 async function scaffold(opts, templatesDir) {
   await copyTree(templatesDir, opts.targetDir);
@@ -492,6 +531,7 @@ async function scaffold(opts, templatesDir) {
   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);
@@ -502,9 +542,199 @@ async function scaffold(opts, templatesDir) {
   if (opts.packageManager === "yarn") {
     await (0, import_promises.writeFile)((0, import_node_path.join)(opts.targetDir, "yarn.lock"), "");
   }
+  await writeAiFiles(opts.targetDir, opts);
   if (opts.install) runInstall(opts.targetDir, opts.packageManager);
   if (opts.initGit) gitInit(opts.targetDir, opts.projectName);
 }
+async function writeAiFiles(targetDir, opts) {
+  const pm = opts.packageManager;
+  const nx = pm === "npm" ? "npx nx" : `${pm} nx`;
+  const devCmd = `${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 (0, import_promises.writeFile)((0, import_node_path.join)(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 (0, import_promises.writeFile)((0, import_node_path.join)(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 (0, import_promises.writeFile)((0, import_node_path.join)(targetDir, "AGENTS.md"), agents);
+  await (0, import_promises.mkdir)((0, import_node_path.join)(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 (0, import_promises.writeFile)(
+    (0, import_node_path.join)(targetDir, ".claude", "settings.json"),
+    JSON.stringify(settings, null, 2) + "\n"
+  );
+}
 
 // src/lib/prompts.ts
 var p = __toESM(require("@clack/prompts"), 1);
@@ -700,6 +930,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?`,