From 1d3b74b378444e32b3c3abdf4255b3381d5afe80 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 17:13:05 +0500
Subject: [PATCH 01/20] fix(create-nextly-app): validate --template against the
 template registry

---
 packages/create-nextly-app/src/cli.ts           | 17 +++++++++--------
 .../create-nextly-app/src/utils/template.ts     |  3 ++-
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/packages/create-nextly-app/src/cli.ts b/packages/create-nextly-app/src/cli.ts
index 5b174468d..7ac3737e4 100644
--- a/packages/create-nextly-app/src/cli.ts
+++ b/packages/create-nextly-app/src/cli.ts
@@ -5,6 +5,7 @@ import { Command } from "commander";
 
 import { resolveProjectArg, validateProjectName } from "./cli-args";
 import { createNextly } from "./create-nextly";
+import { getAvailableTemplateNames } from "./lib/templates";
 import type { DatabaseType, ProjectApproach, ProjectType } from "./types";
 
 // Static require for package.json. Works because tsup adds the createRequire
@@ -33,11 +34,8 @@ program
     "-y, --yes",
     "Skip prompts and use defaults (blank template, SQLite, local storage)"
   )
-  .option("-t, --template <template>", "Project template (blank, blog)")
-  .option(
-    "-a, --approach <approach>",
-    "Schema approach (code-first, visual)"
-  )
+  .option("-t, --template <template>", "Project template (blank, blog, plugin)")
+  .option("-a, --approach <approach>", "Schema approach (code-first, visual)")
   .option("-d, --database <db>", "Database type (sqlite, postgresql, mysql)")
   .option("-b, --branch <branch>", "Git branch for template download", "main")
   .option(
@@ -93,15 +91,18 @@ Examples:
         if (projectName) {
           const nameError = validateProjectName(projectName);
           if (nameError) {
-            console.error(`Error: Invalid project name '${projectName}'. ${nameError}.`);
+            console.error(
+              `Error: Invalid project name '${projectName}'. ${nameError}.`
+            );
             process.exit(1);
           }
         }
 
         const projectType = options.template as ProjectType | undefined;
 
-        // Validate --template flag
-        const validTypes = ["blank", "blog"];
+        // Validate --template flag against the template registry so newly
+        // registered templates are accepted without touching this file.
+        const validTypes = getAvailableTemplateNames();
         if (projectType && !validTypes.includes(projectType)) {
           console.error(
             `Error: Template '${projectType}' is not available. Use: ${validTypes.join(", ")}`
diff --git a/packages/create-nextly-app/src/utils/template.ts b/packages/create-nextly-app/src/utils/template.ts
index 3108064bc..d1c0e2a96 100644
--- a/packages/create-nextly-app/src/utils/template.ts
+++ b/packages/create-nextly-app/src/utils/template.ts
@@ -4,6 +4,7 @@ import { fileURLToPath } from "url";
 import fs from "fs-extra";
 
 import { buildNextConfigTemplate } from "../generators/next-config";
+import { getAvailableTemplateNames } from "../lib/templates";
 import type { DatabaseConfig, ProjectApproach, ProjectType } from "../types";
 
 /**
@@ -666,7 +667,7 @@ export async function copyTemplate(
 
   if (!(await fs.pathExists(typeDir))) {
     throw new Error(
-      `Template "${projectType}" not found at ${typeDir}. Available templates: blank, blog.`
+      `Template "${projectType}" not found at ${typeDir}. Available templates: ${getAvailableTemplateNames().join(", ")}.`
     );
   }
 

From 83fb16aeeba5e0487467357db0c00156a6ba0518 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 17:14:58 +0500
Subject: [PATCH 02/20] fix(create-nextly-app): skip app-shaped project
 detection for plugin scaffolds

---
 .../create-nextly-app/src/create-nextly.ts    | 37 +++++++++++++++++--
 1 file changed, 34 insertions(+), 3 deletions(-)

diff --git a/packages/create-nextly-app/src/create-nextly.ts b/packages/create-nextly-app/src/create-nextly.ts
index dc0cfe36d..665fa09c3 100644
--- a/packages/create-nextly-app/src/create-nextly.ts
+++ b/packages/create-nextly-app/src/create-nextly.ts
@@ -37,9 +37,10 @@ import type {
   DatabaseConfig,
   DatabaseType,
   ProjectApproach,
+  ProjectInfo,
   ProjectType,
 } from "./types";
-import { detectProject } from "./utils/detect";
+import { detectPackageManager, detectProject } from "./utils/detect";
 import { emptyDirectory, isDirectoryNotEmpty } from "./utils/fs";
 import { copyTemplate } from "./utils/template";
 
@@ -213,6 +214,17 @@ export async function createNextly(
     projectType = isValidTemplateSelection(template) ? template : "blank";
   }
 
+  // The plugin template scaffolds a standalone publishable package. In an
+  // existing Next.js project the fresh-scaffold path is skipped entirely, so
+  // proceeding would install app dependencies and generate app config while
+  // never copying the plugin source — a broken hybrid. Fail fast instead.
+  if (projectType === "plugin" && !isFreshProject) {
+    p.cancel(
+      "The Plugin template creates a standalone package and cannot be installed into an existing Next.js project. Run create-nextly-app in an empty directory instead."
+    );
+    return;
+  }
+
   // --- Step 3: Schema approach (only for content templates with approaches) ---
 
   let approach: ProjectApproach | undefined;
@@ -420,8 +432,27 @@ export async function createNextly(
     const s = p.spinner();
     s.start("Detecting project...");
     try {
-      projectInfo = await detectProject(cwd);
-      s.stop(`Detected Next.js ${projectInfo.nextVersion || "unknown"}`);
+      if (projectType === "plugin") {
+        // A plugin scaffold is a publishable library, not a Next.js app: the
+        // library code lives at src/ and the Next app lives in dev/, so the
+        // app-shaped detection would reject it ("App Router not detected").
+        // Downstream only consumes packageManager for fresh scaffolds
+        // (install + next-steps), so detect that and describe the fixed
+        // plugin layout statically.
+        projectInfo = {
+          isNextJs: false,
+          isAppRouter: false,
+          hasTypescript: true,
+          packageManager: await detectPackageManager(cwd),
+          nextVersion: null,
+          srcDir: true,
+          appDir: "dev/src/app",
+        } satisfies ProjectInfo;
+        s.stop("Detected plugin package");
+      } else {
+        projectInfo = await detectProject(cwd);
+        s.stop(`Detected Next.js ${projectInfo.nextVersion || "unknown"}`);
+      }
     } catch (error) {
       s.stop("Detection failed");
       telemetry.capture("scaffold_failed", {

From 9993cf4974a6d373d2f296612b6df6cefa44f1a9 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 17:15:48 +0500
Subject: [PATCH 03/20] fix(create-nextly-app): materialize dev/.env when
 scaffolding a plugin

---
 .../src/__tests__/scaffold-plugin.test.ts             |  8 ++++++++
 packages/create-nextly-app/src/utils/template.ts      | 11 +++++++++++
 templates/plugin/dev/.env.example                     |  3 ++-
 3 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index af3398674..2e34a9113 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -89,6 +89,14 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     expect(workspaceYaml).toContain("allowBuilds:");
     expect(workspaceYaml).toContain("better-sqlite3");
 
+    // The dev playground must boot with zero manual steps: without dev/.env
+    // the dialect defaults to postgresql and `next dev` aborts in the
+    // instrumentation hook asking for DATABASE_URL. The scaffold
+    // materializes the committed example env into the real one.
+    expect(await exists(path.join(target, "dev/.env"))).toBe(true);
+    const devEnv = await readFile(path.join(target, "dev/.env"), "utf-8");
+    expect(devEnv).toContain("DB_DIALECT=sqlite");
+
     // Placeholders are replaced everywhere (no leftover {{ ... }} tokens).
     const pluginSrc = await readFile(
       path.join(target, "src/plugin.ts"),
diff --git a/packages/create-nextly-app/src/utils/template.ts b/packages/create-nextly-app/src/utils/template.ts
index d1c0e2a96..bb4138776 100644
--- a/packages/create-nextly-app/src/utils/template.ts
+++ b/packages/create-nextly-app/src/utils/template.ts
@@ -828,6 +828,17 @@ async function copyPluginTemplate(opts: {
     },
   });
 
+  // Materialize the dev playground env so `pnpm dev` boots with zero manual
+  // steps: without dev/.env the dialect defaults to postgresql and the
+  // instrumentation hook aborts asking for DATABASE_URL. `overwrite: false`
+  // preserves a user's own dev/.env when scaffolding over an existing dir.
+  const devEnvExample = path.join(targetDir, "dev", ".env.example");
+  if (await fs.pathExists(devEnvExample)) {
+    await fs.copy(devEnvExample, path.join(targetDir, "dev", ".env"), {
+      overwrite: false,
+    });
+  }
+
   // Generate the plugin package.json (database arg is unused for plugins).
   const packageJsonContent = await generatePackageJson(
     projectName,
diff --git a/templates/plugin/dev/.env.example b/templates/plugin/dev/.env.example
index db2073883..bd0a708a3 100644
--- a/templates/plugin/dev/.env.example
+++ b/templates/plugin/dev/.env.example
@@ -1,4 +1,5 @@
-# Dev playground env. Copy to dev/.env and run `pnpm dev`.
+# Dev playground env. create-nextly-app copies this file to dev/.env for you;
+# recreate dev/.env from this example if you ever delete it.
 DB_DIALECT=sqlite
 DATABASE_URL=file:./nextly-dev.db
 

From 1bf5c5918d08bbd3725a3aaf69ad702ecbcf8c74 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 17:16:37 +0500
Subject: [PATCH 04/20] fix(create-nextly-app): wrap the plugin playground
 admin in QueryProvider

---
 .../src/__tests__/scaffold-plugin.test.ts            | 10 ++++++++++
 .../plugin/dev/src/app/admin/[[...params]]/page.tsx  | 12 ++++++++++--
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index 2e34a9113..a1802404a 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -97,6 +97,16 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     const devEnv = await readFile(path.join(target, "dev/.env"), "utf-8");
     expect(devEnv).toContain("DB_DIALECT=sqlite");
 
+    // /admin must render through QueryProvider — the admin's data hooks
+    // resolve their QueryClient from it, and mounting RootLayout without it
+    // crashes the page on first load ("No QueryClient set").
+    const adminPage = await readFile(
+      path.join(target, "dev/src/app/admin/[[...params]]/page.tsx"),
+      "utf-8"
+    );
+    expect(adminPage).toContain("QueryProvider");
+    expect(adminPage).toContain("ErrorBoundary");
+
     // Placeholders are replaced everywhere (no leftover {{ ... }} tokens).
     const pluginSrc = await readFile(
       path.join(target, "src/plugin.ts"),
diff --git a/templates/plugin/dev/src/app/admin/[[...params]]/page.tsx b/templates/plugin/dev/src/app/admin/[[...params]]/page.tsx
index b6cfd625d..8d025d496 100644
--- a/templates/plugin/dev/src/app/admin/[[...params]]/page.tsx
+++ b/templates/plugin/dev/src/app/admin/[[...params]]/page.tsx
@@ -1,9 +1,17 @@
 "use client";
 
 import "@nextlyhq/admin/style.css";
-import { RootLayout } from "@nextlyhq/admin";
+import { ErrorBoundary, QueryProvider, RootLayout } from "@nextlyhq/admin";
 
 // Mounts the Nextly admin shell. Your plugin's menu/pages/settings appear here.
+// QueryProvider is required: the admin's data hooks resolve their QueryClient
+// from it, and mounting RootLayout without it crashes the page.
 export default function AdminPage() {
-  return <RootLayout />;
+  return (
+    <ErrorBoundary>
+      <QueryProvider>
+        <RootLayout />
+      </QueryProvider>
+    </ErrorBoundary>
+  );
 }

From 4a8587c2bb767d25848e918b94f5547db1ba814e Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 17:17:16 +0500
Subject: [PATCH 05/20] fix(create-nextly-app): update the plugin template test
 to the current direct api

---
 .../src/__tests__/scaffold-plugin.test.ts     | 12 +++++++++++
 templates/plugin/src/plugin.test.ts           | 20 +++++++++++--------
 2 files changed, 24 insertions(+), 8 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index a1802404a..351fcc224 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -107,6 +107,18 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     expect(adminPage).toContain("QueryProvider");
     expect(adminPage).toContain("ErrorBoundary");
 
+    // The generated test must match the current harness + Direct API: the
+    // harness applies plugin schema contributions itself (passing them again
+    // via `collections` is a slug collision), and CRUD methods take a single
+    // args object (`create({ collection, data })`, `findByID({ ... })`).
+    const pluginTest = await readFile(
+      path.join(target, "src/plugin.test.ts"),
+      "utf-8"
+    );
+    expect(pluginTest).not.toContain("contributes?.collections");
+    expect(pluginTest).toContain("findByID({");
+    expect(pluginTest).toContain("create({");
+
     // Placeholders are replaced everywhere (no leftover {{ ... }} tokens).
     const pluginSrc = await readFile(
       path.join(target, "src/plugin.ts"),
diff --git a/templates/plugin/src/plugin.test.ts b/templates/plugin/src/plugin.test.ts
index 0f9cdf6d2..0efd8249f 100644
--- a/templates/plugin/src/plugin.test.ts
+++ b/templates/plugin/src/plugin.test.ts
@@ -6,12 +6,10 @@ import { myPlugin } from "./index";
 let t: Awaited<ReturnType<typeof createTestNextly>>;
 
 beforeEach(async () => {
-  const plugin = myPlugin();
-  t = await createTestNextly({
-    plugins: [plugin],
-    // Pass the plugin's collections so the harness creates their SQLite tables.
-    collections: plugin.contributes?.collections,
-  });
+  // The harness runs the full plugin lifecycle, including schema
+  // contributions — contributed collections must NOT be passed again via
+  // `collections` (that registers them twice and fails as a slug collision).
+  t = await createTestNextly({ plugins: [myPlugin()] });
 });
 
 afterEach(async () => {
@@ -21,9 +19,15 @@ afterEach(async () => {
 it("boots and exposes the plugin's example collection (real table)", async () => {
   // Creating an entry proves the contributed collection got a real table and
   // the plugin's lifecycle ran. Replace with assertions for your own behavior.
-  const created = await t.nextly.create("examples", { title: "First example" });
+  const created = await t.nextly.create({
+    collection: "examples",
+    data: { title: "First example" },
+  });
   expect(created.item.id).toBeDefined();
 
-  const fetched = await t.nextly.findById("examples", created.item.id);
+  const fetched = await t.nextly.findByID({
+    collection: "examples",
+    id: String(created.item.id),
+  });
   expect(fetched?.title).toBe("First example");
 });

From 94a866aa770dbd73d751318d4b3f71954fe77d4e Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 17:18:16 +0500
Subject: [PATCH 06/20] feat(create-nextly-app): seed the dev auto-login user
 in the plugin playground

---
 .../src/__tests__/scaffold-plugin.test.ts     |  8 ++++++++
 .../create-nextly-app/src/create-nextly.ts    |  2 +-
 templates/plugin/README.md                    |  4 +++-
 templates/plugin/dev/instrumentation.ts       | 20 +++++++++++++++++++
 4 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index 351fcc224..a5312f5dd 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -119,6 +119,14 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     expect(pluginTest).toContain("findByID({");
     expect(pluginTest).toContain("create({");
 
+    // The playground seeds the auto-login user at boot; without it the first
+    // /admin visit dead-ends on the setup wizard despite devAutoLogin.
+    const instrumentation = await readFile(
+      path.join(target, "dev/instrumentation.ts"),
+      "utf-8"
+    );
+    expect(instrumentation).toContain("seedSuperAdmin");
+
     // Placeholders are replaced everywhere (no leftover {{ ... }} tokens).
     const pluginSrc = await readFile(
       path.join(target, "src/plugin.ts"),
diff --git a/packages/create-nextly-app/src/create-nextly.ts b/packages/create-nextly-app/src/create-nextly.ts
index 665fa09c3..d7d5bbeb2 100644
--- a/packages/create-nextly-app/src/create-nextly.ts
+++ b/packages/create-nextly-app/src/create-nextly.ts
@@ -558,7 +558,7 @@ export async function createNextly(
     );
     lines.push("");
     lines.push(
-      `  Open ${pc.cyan("http://localhost:3000/admin")} — your plugin is registered.`
+      `  Open ${pc.cyan("http://localhost:3000/admin")} — auto-logged-in with your plugin registered.`
     );
     lines.push(
       `  Edit your plugin in ${pc.dim("src/")}; the ${pc.dim("dev/")} app is never published.`
diff --git a/templates/plugin/README.md b/templates/plugin/README.md
index f4c2e8164..8046801b6 100644
--- a/templates/plugin/README.md
+++ b/templates/plugin/README.md
@@ -11,7 +11,9 @@ pnpm dev      # runs the embedded /dev playground → open http://localhost:3000
 
 Your plugin lives in `src/`. The `dev/` folder is a minimal Nextly app on SQLite
 that registers this plugin so you can exercise it in a real admin with hot-reload.
-Editing files under `src/` reloads the playground. **`dev/` is never published.**
+It seeds `dev@nextly.local` / `DevPassword123!` and auto-logs-in on `/admin`
+(dev-only; auto-login is hard-blocked in production). Editing files under `src/`
+reloads the playground. **`dev/` is never published.**
 
 ## Test
 
diff --git a/templates/plugin/dev/instrumentation.ts b/templates/plugin/dev/instrumentation.ts
index 8de0a91fe..eaa3f9976 100644
--- a/templates/plugin/dev/instrumentation.ts
+++ b/templates/plugin/dev/instrumentation.ts
@@ -7,4 +7,24 @@ export async function register(): Promise<void> {
   const { createRegister } = await import("nextly");
   const { default: config } = await import("./nextly.config");
   await createRegister(config)();
+
+  // Seed the dev auto-login user (matching admin.devAutoLogin in
+  // dev/nextly.config.ts) so the first /admin visit lands on the dashboard
+  // instead of the /admin/setup wizard. Both seeders skip rows that already
+  // exist, so re-running on every dev boot is safe. Guarded to non-production
+  // like devAutoLogin itself; this playground is never deployed.
+  if (process.env.NODE_ENV !== "production") {
+    const { getService } = await import("nextly");
+    const { seedPermissions, seedSuperAdmin } = await import(
+      "nextly/database/seeders"
+    );
+    const adapter = getService("adapter");
+    await seedPermissions(adapter, { silent: true });
+    await seedSuperAdmin(adapter, {
+      email: "dev@nextly.local",
+      password: "DevPassword123!",
+      name: "Dev User",
+      silent: true,
+    });
+  }
 }

From 35585e00acd2f8d08928cd555f2d91bc7aee5de5 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 17:21:10 +0500
Subject: [PATCH 07/20] fix(create-nextly-app): scaffold plugins from the
 bundled template

---
 .../create-nextly-app/src/create-nextly.ts    | 24 +++++++++++++------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/packages/create-nextly-app/src/create-nextly.ts b/packages/create-nextly-app/src/create-nextly.ts
index d7d5bbeb2..67c854139 100644
--- a/packages/create-nextly-app/src/create-nextly.ts
+++ b/packages/create-nextly-app/src/create-nextly.ts
@@ -355,13 +355,23 @@ export async function createNextly(
 
     try {
       // Resolve template source (download from GitHub or use local path).
-      // For "blank" template without --local-template, we use the bundled
-      // fallback embedded in the CLI. For content templates (blog) we
-      // resolve via GitHub or a local path. --use-yalc also triggers
-      // resolution for the blank template so local-dev runs always pair
-      // yalc-linked packages with the live template rather than a
-      // potentially-stale bundled copy.
-      if (projectType !== "blank" || options.localTemplatePath || useYalc) {
+      // "blank" and "plugin" ship bundled inside the CLI package, so their
+      // default scaffolds work offline and always match the installed CLI's
+      // package versions (a GitHub-main template can drift ahead of the npm
+      // packages the scaffold installs). Content templates (blog) resolve
+      // via GitHub. --local-template, --use-yalc, or an explicit non-main
+      // --branch still force resolution so development workflows keep
+      // pairing live templates with local packages.
+      const usesBundledPluginTemplate =
+        projectType === "plugin" &&
+        !options.localTemplatePath &&
+        !useYalc &&
+        (options.branch ?? "main") === "main";
+      if (
+        (projectType !== "blank" && !usesBundledPluginTemplate) ||
+        options.localTemplatePath ||
+        useYalc
+      ) {
         s.start("Resolving template...");
         templateSource = await resolveTemplateSource(projectType, {
           localTemplatePath: options.localTemplatePath,

From e376185dba9c30137c13d1eba90efe76e7b6e6aa Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 17:26:12 +0500
Subject: [PATCH 08/20] chore(release): add changeset for the plugin template
 fixes

---
 .changeset/plugin-template-scaffold-fixes.md | 27 ++++++++++++++++++++
 1 file changed, 27 insertions(+)
 create mode 100644 .changeset/plugin-template-scaffold-fixes.md

diff --git a/.changeset/plugin-template-scaffold-fixes.md b/.changeset/plugin-template-scaffold-fixes.md
new file mode 100644
index 000000000..2990ff54a
--- /dev/null
+++ b/.changeset/plugin-template-scaffold-fixes.md
@@ -0,0 +1,27 @@
+---
+"@nextlyhq/adapter-drizzle": patch
+"@nextlyhq/adapter-mysql": patch
+"@nextlyhq/adapter-postgres": patch
+"@nextlyhq/adapter-sqlite": patch
+"@nextlyhq/admin": patch
+"create-nextly-app": patch
+"@nextlyhq/eslint-config": patch
+"nextly": patch
+"@nextlyhq/plugin-form-builder": patch
+"@nextlyhq/plugin-page-builder": patch
+"@nextlyhq/plugin-sdk": patch
+"@nextlyhq/prettier-config": patch
+"@nextlyhq/storage-s3": patch
+"@nextlyhq/storage-uploadthing": patch
+"@nextlyhq/storage-vercel-blob": patch
+"@nextlyhq/telemetry": patch
+"@nextlyhq/tsconfig": patch
+"@nextlyhq/ui": patch
+---
+
+The Plugin template now works end to end. `--template plugin` is accepted, the
+scaffold no longer aborts with "App Router not detected", the dev playground's
+env file is created automatically, `/admin` renders (QueryProvider) and lands
+already logged in as the seeded dev user, the generated test suite matches the
+current plugin-sdk API, and plugin scaffolds use the template bundled with the
+CLI so it can no longer drift ahead of the published packages.

From 4b3c8a097de3d751201275603a2f3dcb6e1bf6ee Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 18:11:11 +0500
Subject: [PATCH 09/20] fix(create-nextly-app): keep the latest dist-tag out of
 plugin peer dependencies

---
 .../create-nextly-app/src/utils/template.ts    | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/packages/create-nextly-app/src/utils/template.ts b/packages/create-nextly-app/src/utils/template.ts
index bb4138776..ac454f89d 100644
--- a/packages/create-nextly-app/src/utils/template.ts
+++ b/packages/create-nextly-app/src/utils/template.ts
@@ -440,10 +440,22 @@ async function generatePluginPackageJson(
   const runtimeVersions = await resolveRuntimeVersions();
   const range = (pkg: string): string => versions[pkg] ?? "latest";
 
+  // peerDependencies must be a valid semver range: pnpm 11 rejects the
+  // "latest" dist-tag there (ERR_PNPM_INVALID_PEER_DEPENDENCY_SPECIFICATION)
+  // and then refuses to run ANY script in the scaffold, including `pnpm dev`.
+  // The dist-tag can appear whenever a registry version lookup fails
+  // (offline, transient npm error) or under --use-yalc, so fall back to an
+  // open range instead. Dev/regular dependencies keep "latest" — the
+  // dist-tag is valid there and installs the newest release.
+  const peerRange = (pkg: string): string => {
+    const v = range(pkg);
+    return v === "latest" ? ">=0.0.0" : v;
+  };
+
   const peerDependencies: Record<string, string> = {
-    nextly: range("nextly"),
-    "@nextlyhq/admin": range("@nextlyhq/admin"),
-    "@nextlyhq/plugin-sdk": range("@nextlyhq/plugin-sdk"),
+    nextly: peerRange("nextly"),
+    "@nextlyhq/admin": peerRange("@nextlyhq/admin"),
+    "@nextlyhq/plugin-sdk": peerRange("@nextlyhq/plugin-sdk"),
     react: PINNED_VERSIONS.react,
     "react-dom": PINNED_VERSIONS["react-dom"],
   };

From 9e7f5dc8be20f3471bf7937a2b7ce19c3b64da26 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 18:11:20 +0500
Subject: [PATCH 10/20] fix(create-nextly-app): close the super-admin seeding
 race in the plugin playground

---
 .../src/__tests__/scaffold-plugin.test.ts     | 17 +++++++++++-
 templates/plugin/dev/instrumentation.ts       | 27 ++++++++++++++-----
 2 files changed, 37 insertions(+), 7 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index a5312f5dd..7ab23b2aa 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -77,6 +77,17 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     expect(pkg.files).toEqual(["dist"]);
     expect(pkg.keywords).toContain("nextly-plugin");
     expect(pkg.scripts.dev).toContain("next dev dev");
+
+    // peerDependencies must never carry the "latest" dist-tag: pnpm 11
+    // rejects it (ERR_PNPM_INVALID_PEER_DEPENDENCY_SPECIFICATION) and then
+    // refuses to run any script in the scaffold. This test runs with the
+    // registry stubbed offline, so every version lookup exercises the
+    // fallback path — exactly where the dist-tag used to leak in.
+    for (const [peer, spec] of Object.entries(
+      pkg.peerDependencies as Record<string, string>
+    )) {
+      expect(spec, `peerDependencies.${peer}`).not.toBe("latest");
+    }
     // The native-build allowlist lives in pnpm-workspace.yaml, NOT the package.json
     // `pnpm` field (pnpm 11 ignores that field). Without this, `pnpm install` aborts
     // on better-sqlite3 (the dev playground's native dep) with ERR_PNPM_IGNORED_BUILDS.
@@ -120,12 +131,16 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     expect(pluginTest).toContain("create({");
 
     // The playground seeds the auto-login user at boot; without it the first
-    // /admin visit dead-ends on the setup wizard despite devAutoLogin.
+    // /admin visit dead-ends on the setup wizard despite devAutoLogin. The
+    // seed must run twice: the runtime's background permission seeding races
+    // the first pass, and the second pass (role-exists path) tops up any
+    // permissions created in between so the role is complete either way.
     const instrumentation = await readFile(
       path.join(target, "dev/instrumentation.ts"),
       "utf-8"
     );
     expect(instrumentation).toContain("seedSuperAdmin");
+    expect(instrumentation.match(/await seedDevUser\(\)/g)).toHaveLength(2);
 
     // Placeholders are replaced everywhere (no leftover {{ ... }} tokens).
     const pluginSrc = await readFile(
diff --git a/templates/plugin/dev/instrumentation.ts b/templates/plugin/dev/instrumentation.ts
index eaa3f9976..4b0eb97f6 100644
--- a/templates/plugin/dev/instrumentation.ts
+++ b/templates/plugin/dev/instrumentation.ts
@@ -19,12 +19,27 @@ export async function register(): Promise<void> {
       "nextly/database/seeders"
     );
     const adapter = getService("adapter");
+    const seedDevUser = () =>
+      seedSuperAdmin(adapter, {
+        email: "dev@nextly.local",
+        password: "DevPassword123!",
+        name: "Dev User",
+        silent: true,
+      });
+
     await seedPermissions(adapter, { silent: true });
-    await seedSuperAdmin(adapter, {
-      email: "dev@nextly.local",
-      password: "DevPassword123!",
-      name: "Dev User",
-      silent: true,
-    });
+    await seedDevUser();
+
+    // createRegister() fires the runtime's own permission seeding in the
+    // background (post-init tasks are not awaited), and its new-permission
+    // assignment silently no-ops while the Super Admin role does not exist.
+    // Permissions it creates can therefore miss both the role-creation
+    // snapshot above and that assignment. The runtime's assignment call runs
+    // after all of its inserts, so either it sees the role created above and
+    // assigns everything itself, or every insert it made is already visible
+    // to this second run — which takes the role-exists path, re-lists all
+    // permissions, and tops up any that are missing. In both orderings the
+    // role ends up with the complete permission set.
+    await seedDevUser();
   }
 }

From b4c83132a2940a9716b8b5a137e6802b2498d9d9 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 18:18:09 +0500
Subject: [PATCH 11/20] fix(create-nextly-app): honor a non-main --branch for
 bundled templates

---
 .../src/__tests__/templates.test.ts           | 31 +++++++++++++++++
 packages/create-nextly-app/src/cli.ts         |  7 +++-
 .../create-nextly-app/src/create-nextly.ts    | 30 ++++++++---------
 .../create-nextly-app/src/lib/templates.ts    | 33 +++++++++++++++++++
 .../create-nextly-app/src/utils/template.ts   |  2 ++
 5 files changed, 86 insertions(+), 17 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/templates.test.ts b/packages/create-nextly-app/src/__tests__/templates.test.ts
index e7875f8e0..0ad7aa704 100644
--- a/packages/create-nextly-app/src/__tests__/templates.test.ts
+++ b/packages/create-nextly-app/src/__tests__/templates.test.ts
@@ -3,6 +3,7 @@ import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
 import {
   getAvailableTemplateNames,
   getTemplate,
+  shouldUseBundledTemplate,
   templateHasApproaches,
   templateHasDemoData,
 } from "../lib/templates";
@@ -80,3 +81,33 @@ describe("plugin package.json generation (D44/D45)", () => {
     expect(pkg.dependencies).toBeUndefined();
   });
 });
+
+describe("shouldUseBundledTemplate", () => {
+  it("uses the bundled copy for blank and plugin by default", () => {
+    expect(shouldUseBundledTemplate("blank", {})).toBe(true);
+    expect(shouldUseBundledTemplate("plugin", {})).toBe(true);
+    // The CLI always passes commander's default branch; "main" must not
+    // force a download on its own.
+    expect(shouldUseBundledTemplate("blank", { branch: "main" })).toBe(true);
+    expect(shouldUseBundledTemplate("plugin", { branch: "main" })).toBe(true);
+  });
+
+  it("always resolves content templates live", () => {
+    expect(shouldUseBundledTemplate("blog", {})).toBe(false);
+  });
+
+  it("forces live resolution for every explicit source override", () => {
+    // A user passing --branch expects that branch's template, not the
+    // bundled copy silently substituted for it.
+    expect(shouldUseBundledTemplate("blank", { branch: "release" })).toBe(
+      false
+    );
+    expect(shouldUseBundledTemplate("plugin", { branch: "release" })).toBe(
+      false
+    );
+    expect(
+      shouldUseBundledTemplate("blank", { localTemplatePath: "/tmp/t" })
+    ).toBe(false);
+    expect(shouldUseBundledTemplate("plugin", { useYalc: true })).toBe(false);
+  });
+});
diff --git a/packages/create-nextly-app/src/cli.ts b/packages/create-nextly-app/src/cli.ts
index 7ac3737e4..dfc73af9a 100644
--- a/packages/create-nextly-app/src/cli.ts
+++ b/packages/create-nextly-app/src/cli.ts
@@ -34,7 +34,12 @@ program
     "-y, --yes",
     "Skip prompts and use defaults (blank template, SQLite, local storage)"
   )
-  .option("-t, --template <template>", "Project template (blank, blog, plugin)")
+  .option(
+    "-t, --template <template>",
+    // Derive the list from the registry so --help stays in sync with what
+    // validation accepts as new templates are registered.
+    `Project template (${getAvailableTemplateNames().join(", ")})`
+  )
   .option("-a, --approach <approach>", "Schema approach (code-first, visual)")
   .option("-d, --database <db>", "Database type (sqlite, postgresql, mysql)")
   .option("-b, --branch <branch>", "Git branch for template download", "main")
diff --git a/packages/create-nextly-app/src/create-nextly.ts b/packages/create-nextly-app/src/create-nextly.ts
index 67c854139..275efae86 100644
--- a/packages/create-nextly-app/src/create-nextly.ts
+++ b/packages/create-nextly-app/src/create-nextly.ts
@@ -19,7 +19,11 @@ import {
   cleanupDownload,
   type TemplateSource,
 } from "./lib/download-template";
-import { templateHasApproaches, getDefaultApproach } from "./lib/templates";
+import {
+  templateHasApproaches,
+  getDefaultApproach,
+  shouldUseBundledTemplate,
+} from "./lib/templates";
 import { getApproachPromptOptions } from "./prompts/approach";
 import { DATABASE_CONFIGS, DATABASE_LABELS } from "./prompts/database";
 import {
@@ -355,22 +359,16 @@ export async function createNextly(
 
     try {
       // Resolve template source (download from GitHub or use local path).
-      // "blank" and "plugin" ship bundled inside the CLI package, so their
-      // default scaffolds work offline and always match the installed CLI's
-      // package versions (a GitHub-main template can drift ahead of the npm
-      // packages the scaffold installs). Content templates (blog) resolve
-      // via GitHub. --local-template, --use-yalc, or an explicit non-main
-      // --branch still force resolution so development workflows keep
-      // pairing live templates with local packages.
-      const usesBundledPluginTemplate =
-        projectType === "plugin" &&
-        !options.localTemplatePath &&
-        !useYalc &&
-        (options.branch ?? "main") === "main";
+      // Bundled templates (blank, plugin) scaffold from the copy shipped
+      // inside the CLI package by default; content templates (blog) and any
+      // explicit source override (--local-template, --use-yalc, a non-main
+      // --branch) resolve live. See shouldUseBundledTemplate for the rules.
       if (
-        (projectType !== "blank" && !usesBundledPluginTemplate) ||
-        options.localTemplatePath ||
-        useYalc
+        !shouldUseBundledTemplate(projectType, {
+          localTemplatePath: options.localTemplatePath,
+          useYalc,
+          branch: options.branch,
+        })
       ) {
         s.start("Resolving template...");
         templateSource = await resolveTemplateSource(projectType, {
diff --git a/packages/create-nextly-app/src/lib/templates.ts b/packages/create-nextly-app/src/lib/templates.ts
index dbef4924e..845a2ef40 100644
--- a/packages/create-nextly-app/src/lib/templates.ts
+++ b/packages/create-nextly-app/src/lib/templates.ts
@@ -96,3 +96,36 @@ export function getDefaultApproach(name: string): ProjectApproach {
   const template = getTemplate(name);
   return template?.defaultApproach ?? "code-first";
 }
+
+/**
+ * Templates whose files ship inside the CLI package itself (copied by the
+ * build; see tsup.config.ts). Content templates (blog) are download-only.
+ */
+const BUNDLED_TEMPLATES: ReadonlySet<string> = new Set(["blank", "plugin"]);
+
+/**
+ * Decide whether a scaffold should use the CLI-bundled copy of a template
+ * instead of resolving one from GitHub or a local path.
+ *
+ * Bundled copies keep offline scaffolds working and always match the
+ * installed CLI's package versions (a GitHub-main template can drift ahead
+ * of the npm packages the scaffold installs). Any explicit source override
+ * — --local-template, --use-yalc, or a non-main --branch — forces live
+ * resolution so development workflows pair live templates with local
+ * packages and users can scaffold from release branches.
+ */
+export function shouldUseBundledTemplate(
+  projectType: string,
+  options: {
+    localTemplatePath?: string;
+    useYalc?: boolean;
+    branch?: string;
+  }
+): boolean {
+  return (
+    BUNDLED_TEMPLATES.has(projectType) &&
+    !options.localTemplatePath &&
+    !options.useYalc &&
+    (options.branch ?? "main") === "main"
+  );
+}
diff --git a/packages/create-nextly-app/src/utils/template.ts b/packages/create-nextly-app/src/utils/template.ts
index ac454f89d..664385397 100644
--- a/packages/create-nextly-app/src/utils/template.ts
+++ b/packages/create-nextly-app/src/utils/template.ts
@@ -678,6 +678,8 @@ export async function copyTemplate(
   }
 
   if (!(await fs.pathExists(typeDir))) {
+    // The registry supplies the template list so this message stays current
+    // as templates are added, instead of drifting like a hardcoded list.
     throw new Error(
       `Template "${projectType}" not found at ${typeDir}. Available templates: ${getAvailableTemplateNames().join(", ")}.`
     );

From 49136019eb30356258802da4061f6bd31c2bd4d3 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 18:18:20 +0500
Subject: [PATCH 12/20] fix(create-nextly-app): restrict playground credential
 seeding to next dev

---
 .../src/__tests__/scaffold-plugin.test.ts                  | 3 +++
 templates/plugin/dev/instrumentation.ts                    | 7 ++++---
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index 7ab23b2aa..636cd53a0 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -141,6 +141,9 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     );
     expect(instrumentation).toContain("seedSuperAdmin");
     expect(instrumentation.match(/await seedDevUser\(\)/g)).toHaveLength(2);
+    // Credential seeding must be locked to `next dev` — a broader guard
+    // (e.g. !== "production") would also seed under NODE_ENV=test.
+    expect(instrumentation).toContain('process.env.NODE_ENV === "development"');
 
     // Placeholders are replaced everywhere (no leftover {{ ... }} tokens).
     const pluginSrc = await readFile(
diff --git a/templates/plugin/dev/instrumentation.ts b/templates/plugin/dev/instrumentation.ts
index 4b0eb97f6..9e8aa4602 100644
--- a/templates/plugin/dev/instrumentation.ts
+++ b/templates/plugin/dev/instrumentation.ts
@@ -11,9 +11,10 @@ export async function register(): Promise<void> {
   // Seed the dev auto-login user (matching admin.devAutoLogin in
   // dev/nextly.config.ts) so the first /admin visit lands on the dashboard
   // instead of the /admin/setup wizard. Both seeders skip rows that already
-  // exist, so re-running on every dev boot is safe. Guarded to non-production
-  // like devAutoLogin itself; this playground is never deployed.
-  if (process.env.NODE_ENV !== "production") {
+  // exist, so re-running on every dev boot is safe. Strictly `next dev` only:
+  // credentials must never be seeded in a production build, and test runners
+  // (NODE_ENV=test) manage their own fixtures.
+  if (process.env.NODE_ENV === "development") {
     const { getService } = await import("nextly");
     const { seedPermissions, seedSuperAdmin } = await import(
       "nextly/database/seeders"

From a042580cbe43f608e34dae84d7c5825cea1065ee Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 18:18:24 +0500
Subject: [PATCH 13/20] docs(create-nextly-app): explain the direct api usage
 in the plugin template test

---
 templates/plugin/src/plugin.test.ts | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/templates/plugin/src/plugin.test.ts b/templates/plugin/src/plugin.test.ts
index 0efd8249f..48c90885d 100644
--- a/templates/plugin/src/plugin.test.ts
+++ b/templates/plugin/src/plugin.test.ts
@@ -19,12 +19,16 @@ afterEach(async () => {
 it("boots and exposes the plugin's example collection (real table)", async () => {
   // Creating an entry proves the contributed collection got a real table and
   // the plugin's lifecycle ran. Replace with assertions for your own behavior.
+  // Direct API methods take a single args object ({ collection, data, id }),
+  // and mutations return a { message, item } envelope.
   const created = await t.nextly.create({
     collection: "examples",
     data: { title: "First example" },
   });
   expect(created.item.id).toBeDefined();
 
+  // String() narrows the loosely typed id — a fresh scaffold has no
+  // generated collection types yet, and findByID expects a string id.
   const fetched = await t.nextly.findByID({
     collection: "examples",
     id: String(created.item.id),

From ed4ccb6353a919c56f0465b01f0d905a4fff054d Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 18:18:27 +0500
Subject: [PATCH 14/20] fix(create-nextly-app): yalc-link plugin-sdk for plugin
 scaffolds

---
 packages/create-nextly-app/src/installers/dependencies.ts | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/packages/create-nextly-app/src/installers/dependencies.ts b/packages/create-nextly-app/src/installers/dependencies.ts
index 4240e3d02..56f6635f6 100644
--- a/packages/create-nextly-app/src/installers/dependencies.ts
+++ b/packages/create-nextly-app/src/installers/dependencies.ts
@@ -102,6 +102,11 @@ export async function installDependencies(
           "@nextlyhq/adapter-drizzle",
           ...ALL_ADAPTER_PACKAGES,
           ...pluginPackages,
+          // A plugin scaffold imports @nextlyhq/plugin-sdk directly (its
+          // definePlugin surface + test harness). Linking it from the yalc
+          // store keeps it in lockstep with the other local packages instead
+          // of mixing the published SDK into a local-package scaffold.
+          ...(projectType === "plugin" ? ["@nextlyhq/plugin-sdk"] : []),
         ]),
       ];
 

From 532c1000b6dfcddf6cb83c7075badba8dad852b5 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Thu, 23 Jul 2026 18:18:32 +0500
Subject: [PATCH 15/20] chore(release): add admin-css to the plugin template
 changeset

---
 .changeset/plugin-template-scaffold-fixes.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.changeset/plugin-template-scaffold-fixes.md b/.changeset/plugin-template-scaffold-fixes.md
index 2990ff54a..30cd77d9a 100644
--- a/.changeset/plugin-template-scaffold-fixes.md
+++ b/.changeset/plugin-template-scaffold-fixes.md
@@ -4,6 +4,7 @@
 "@nextlyhq/adapter-postgres": patch
 "@nextlyhq/adapter-sqlite": patch
 "@nextlyhq/admin": patch
+"@nextlyhq/admin-css": patch
 "create-nextly-app": patch
 "@nextlyhq/eslint-config": patch
 "nextly": patch

From ebc7d2c585246e424f798e16bc879e4ba9d571ce Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Tue, 28 Jul 2026 13:00:55 +0500
Subject: [PATCH 16/20] chore(release): add blocks-engine and plugin-seo to the
 plugin template changeset

---
 .changeset/plugin-template-scaffold-fixes.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.changeset/plugin-template-scaffold-fixes.md b/.changeset/plugin-template-scaffold-fixes.md
index 30cd77d9a..7cc133a6d 100644
--- a/.changeset/plugin-template-scaffold-fixes.md
+++ b/.changeset/plugin-template-scaffold-fixes.md
@@ -5,6 +5,8 @@
 "@nextlyhq/adapter-sqlite": patch
 "@nextlyhq/admin": patch
 "@nextlyhq/admin-css": patch
+"@nextlyhq/blocks-engine": patch
+"@nextlyhq/plugin-seo": patch
 "create-nextly-app": patch
 "@nextlyhq/eslint-config": patch
 "nextly": patch

From 1cd8634cd1442ec10167857414246ea18d1bf963 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Tue, 28 Jul 2026 14:16:14 +0500
Subject: [PATCH 17/20] fix(create-nextly-app): harden plugin scaffolds against
 packing and channel drift
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bundled templates now carry .gitignore under the publish-safe name
gitignore: npm's packer strips dotted .gitignore files from tarballs, so
published-CLI scaffolds silently lost their ignore rules — including for
the materialized dev/.env. The build renames on copy and the scaffolder
renames back.

Plugin scaffolds resolve the Nextly family from the alpha train (the
template ships inside the CLI, so its generated test and dev playground
exercise current plugin-sdk/admin APIs the lagging latest tag may lack),
with peer ranges still falling back to valid semver.

Under --use-yalc the generator omits Nextly-family devDeps and the
installer yalc-adds before the first install, so the local-package flow
never fetches published Nextly packages it is about to replace.
---
 .../src/__tests__/scaffold-plugin.test.ts     |  55 ++++++--
 .../src/__tests__/template-channel.test.ts    |  77 ++++++++++--
 .../src/installers/dependencies.ts            |  31 +++--
 .../create-nextly-app/src/utils/template.ts   | 118 +++++++++++++-----
 packages/create-nextly-app/tsup.config.ts     |  25 +++-
 5 files changed, 254 insertions(+), 52 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index 636cd53a0..c2d294f95 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -1,4 +1,4 @@
-import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { cp, mkdtemp, readFile, rename, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -78,15 +78,17 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     expect(pkg.keywords).toContain("nextly-plugin");
     expect(pkg.scripts.dev).toContain("next dev dev");
 
-    // peerDependencies must never carry the "latest" dist-tag: pnpm 11
-    // rejects it (ERR_PNPM_INVALID_PEER_DEPENDENCY_SPECIFICATION) and then
-    // refuses to run any script in the scaffold. This test runs with the
-    // registry stubbed offline, so every version lookup exercises the
-    // fallback path — exactly where the dist-tag used to leak in.
+    // peerDependencies must never carry a dist-tag name (latest, alpha, …):
+    // pnpm 11 rejects non-semver peer specs
+    // (ERR_PNPM_INVALID_PEER_DEPENDENCY_SPECIFICATION) and then refuses to
+    // run any script in the scaffold. This test runs with the registry
+    // stubbed offline, so every version lookup exercises the fallback path —
+    // exactly where a dist-tag used to leak in. Semver ranges start with a
+    // digit or range operator; dist-tag names start with a letter.
     for (const [peer, spec] of Object.entries(
       pkg.peerDependencies as Record<string, string>
     )) {
-      expect(spec, `peerDependencies.${peer}`).not.toBe("latest");
+      expect(spec, `peerDependencies.${peer}`).toMatch(/^[\d^~><=*]/);
     }
     // The native-build allowlist lives in pnpm-workspace.yaml, NOT the package.json
     // `pnpm` field (pnpm 11 ignores that field). Without this, `pnpm install` aborts
@@ -108,6 +110,10 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     const devEnv = await readFile(path.join(target, "dev/.env"), "utf-8");
     expect(devEnv).toContain("DB_DIALECT=sqlite");
 
+    // The ignore rules must land — the materialized dev/.env (dev
+    // credentials) is only safe because .gitignore excludes it.
+    expect(await exists(path.join(target, ".gitignore"))).toBe(true);
+
     // /admin must render through QueryProvider — the admin's data hooks
     // resolve their QueryClient from it, and mounting RootLayout without it
     // crashes the page on first load ("No QueryClient set").
@@ -160,4 +166,39 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     expect(devConfig).toContain('"@acme/nextly-plugin-test"');
     expect(devConfig).not.toMatch(/\{\{\s*\w+\s*\}\}/);
   });
+
+  it("restores .gitignore from the publish-safe bundled name", async () => {
+    workdir = await mkdtemp(path.join(tmpdir(), "nextly-plugin-packed-"));
+    target = path.join(workdir, "my-plugin");
+
+    // Simulate the layout the PUBLISHED CLI carries: npm's packer strips
+    // dotted .gitignore files from tarballs, so the build stores them as
+    // `gitignore` (see tsup.config.ts) and the scaffolder renames them back.
+    const packedTemplate = path.join(workdir, "packed-template");
+    await cp(path.join(templatesRoot, "plugin"), packedTemplate, {
+      recursive: true,
+    });
+    await rename(
+      path.join(packedTemplate, ".gitignore"),
+      path.join(packedTemplate, "gitignore")
+    );
+
+    await copyTemplate({
+      projectName: "packed-plugin",
+      projectType: "plugin",
+      targetDir: target,
+      database: { type: "sqlite" } as unknown as DatabaseConfig,
+      templateSource: {
+        basePath: path.join(templatesRoot, "base"),
+        templatePath: packedTemplate,
+      },
+    });
+
+    // The dotted file is restored with its rules intact, and the transport
+    // name does not leak into the scaffold.
+    const gitignore = await readFile(path.join(target, ".gitignore"), "utf-8");
+    expect(gitignore).toContain("node_modules");
+    expect(gitignore).toContain(".env");
+    expect(await exists(path.join(target, "gitignore"))).toBe(false);
+  });
 });
diff --git a/packages/create-nextly-app/src/__tests__/template-channel.test.ts b/packages/create-nextly-app/src/__tests__/template-channel.test.ts
index c676b5261..15f7839ee 100644
--- a/packages/create-nextly-app/src/__tests__/template-channel.test.ts
+++ b/packages/create-nextly-app/src/__tests__/template-channel.test.ts
@@ -1,10 +1,12 @@
 /**
- * Tests for the content-template npm dist-tag channel.
+ * Tests for the per-template npm dist-tag channel.
  *
- * Content templates (blog) render CMS content through `nextly/runtime` cache
- * helpers, which ship on the active `alpha` channel; the conservative `latest`
- * tag can lag behind it during the alpha. So a blog scaffold must pin nextly +
- * @nextlyhq/* to `alpha`, while blank/plugin stay on `latest`.
+ * Train-coupled templates pin nextly + @nextlyhq/* to `alpha`: blog renders
+ * through `nextly/runtime` cache helpers that ship on the active alpha
+ * channel, and plugin ships bundled with the CLI so its generated test and
+ * dev playground exercise current plugin-sdk/admin APIs. The conservative
+ * `latest` tag can lag the train during the alpha, so only blank stays on
+ * `latest`.
  */
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -26,10 +28,18 @@ const LATEST = "0.0.2-alpha.37";
 const ALPHA = "0.0.2-alpha.42";
 
 describe("templateNextlyChannel", () => {
-  it("routes content templates to alpha and everything else to latest", () => {
+  it("routes content templates to alpha and blank to latest", () => {
     expect(templateNextlyChannel("blog")).toBe("alpha");
     expect(templateNextlyChannel("blank")).toBe("latest");
-    expect(templateNextlyChannel("plugin")).toBe("latest");
+  });
+
+  it("keeps plugin on the same channel as the other train-coupled templates", () => {
+    // The plugin template ships bundled inside the CLI, so its scaffolds
+    // must install from the same release train the CLI was published on —
+    // whichever dist-tag that is. Asserted relationally (not against a
+    // literal tag) so this test survives channel renames when the alpha
+    // phase ends.
+    expect(templateNextlyChannel("plugin")).toBe(templateNextlyChannel("blog"));
   });
 });
 
@@ -64,6 +74,42 @@ describe("content-template dist-tag pinning", () => {
     expect(pkg.dependencies["nextly"]).toBe(`^${LATEST}`);
     expect(pkg.dependencies["@nextlyhq/admin"]).toBe(`^${LATEST}`);
   });
+
+  it("pins the plugin scaffold's nextly family to its template channel", async () => {
+    // Expected version derived from the channel mapping (not a hardcoded
+    // tag), so the assertion keeps holding when the channel changes.
+    const tagVersions: Record<string, string> = {
+      latest: LATEST,
+      alpha: ALPHA,
+    };
+    const expected = `^${tagVersions[templateNextlyChannel("plugin")]}`;
+
+    const pkg = JSON.parse(
+      await generatePackageJson("my-plugin", pgDatabase, false, "plugin")
+    );
+    // The template ships with the CLI, so its devDeps and the declared peer
+    // compat range must come from the CLI's own release train.
+    expect(pkg.devDependencies["nextly"]).toBe(expected);
+    expect(pkg.devDependencies["@nextlyhq/plugin-sdk"]).toBe(expected);
+    expect(pkg.peerDependencies["nextly"]).toBe(expected);
+  });
+
+  it("omits the nextly family from plugin devDeps under --use-yalc", async () => {
+    const pkg = JSON.parse(
+      await generatePackageJson("my-plugin", pgDatabase, true, "plugin")
+    );
+    // The installer yalc-adds these before the first install; registry specs
+    // here would race it into fetching published packages it is about to
+    // replace. Non-nextly tooling stays.
+    for (const dep of Object.keys(pkg.devDependencies)) {
+      expect(dep, "yalc plugin devDep").not.toMatch(/^nextly$|^@nextlyhq\//);
+    }
+    expect(pkg.devDependencies["tsup"]).toBeDefined();
+    expect(pkg.devDependencies["vitest"]).toBeDefined();
+    // Peers stay declared (publish metadata) but with a valid semver range,
+    // never a dist-tag name pnpm would reject.
+    expect(pkg.peerDependencies["nextly"]).toBe(">=0.0.0");
+  });
 });
 
 // Reset modules per test so the per-channel version cache never masks the
@@ -102,4 +148,21 @@ describe("alpha pin survives a registry lookup failure", () => {
     const pkg = JSON.parse(await gen("blog-app", pgDatabase, false, "blog"));
     expect(pkg.dependencies["nextly"]).toBe("alpha");
   });
+
+  it("keeps plugin devDeps on its channel tag but peers on a semver range when the registry fails", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({ ok: false, json: async () => ({}) }))
+    );
+    const { generatePackageJson: gen, templateNextlyChannel: channelOf } =
+      await import("../utils/template");
+    const pkg = JSON.parse(await gen("my-plugin", pgDatabase, false, "plugin"));
+    // devDeps may carry the dist-tag name (a valid install spec) — asserted
+    // via the channel mapping, not a literal tag...
+    expect(pkg.devDependencies["nextly"]).toBe(channelOf("plugin"));
+    // ...but peerDependencies must stay a semver range: pnpm 11 rejects a
+    // dist-tag there and then refuses to run any script in the scaffold.
+    expect(pkg.peerDependencies["nextly"]).toBe(">=0.0.0");
+    expect(pkg.peerDependencies["@nextlyhq/plugin-sdk"]).toBe(">=0.0.0");
+  });
 });
diff --git a/packages/create-nextly-app/src/installers/dependencies.ts b/packages/create-nextly-app/src/installers/dependencies.ts
index 56f6635f6..52979efb5 100644
--- a/packages/create-nextly-app/src/installers/dependencies.ts
+++ b/packages/create-nextly-app/src/installers/dependencies.ts
@@ -110,16 +110,29 @@ export async function installDependencies(
         ]),
       ];
 
-      // Step 1: Install non-@nextlyhq packages
-      await execa(pm, ["install"], { cwd });
-
-      // Step 2: Add @nextlyhq/* packages from local yalc store
-      for (const pkg of yalcPackages) {
-        await execa("yalc", ["add", pkg], { cwd });
+      if (projectType === "plugin") {
+        // Plugin scaffolds declare Nextly peers with open ranges, and pnpm
+        // auto-installs unmet peers — an install before yalc-add would pull
+        // the PUBLISHED packages from the registry only to replace them.
+        // yalc-add first (it only copies files and edits package.json, so it
+        // needs no node_modules), then one install resolves everything
+        // against the local store.
+        for (const pkg of yalcPackages) {
+          await execa("yalc", ["add", pkg], { cwd });
+        }
+        await execa(pm, ["install"], { cwd });
+      } else {
+        // Step 1: Install non-@nextlyhq packages
+        await execa(pm, ["install"], { cwd });
+
+        // Step 2: Add @nextlyhq/* packages from local yalc store
+        for (const pkg of yalcPackages) {
+          await execa("yalc", ["add", pkg], { cwd });
+        }
+
+        // Step 3: Install again to resolve yalc transitive dependencies
+        await execa(pm, ["install"], { cwd });
       }
-
-      // Step 3: Install again to resolve yalc transitive dependencies
-      await execa(pm, ["install"], { cwd });
     } else {
       // Plain install - all deps are already in package.json
       await execa(pm, ["install"], { cwd });
diff --git a/packages/create-nextly-app/src/utils/template.ts b/packages/create-nextly-app/src/utils/template.ts
index 57bc57b80..28d1fdacb 100644
--- a/packages/create-nextly-app/src/utils/template.ts
+++ b/packages/create-nextly-app/src/utils/template.ts
@@ -26,23 +26,29 @@ export function projectUsesFormBuilder(projectType: ProjectType): boolean {
 export type NextlyDistTag = "latest" | "alpha";
 
 /**
- * Templates that render CMS content through `nextly/runtime` cache helpers
- * (`cachedFind` / `nextlyTags`) install `nextly` + `@nextlyhq/*` from the
- * `alpha` dist-tag rather than `latest`. Those helpers ship on the active
- * alpha channel, and during the alpha the conservative `latest` tag can lag
- * behind it — a content scaffold pinned to `latest` would then install a
- * `nextly` missing the helpers its pages import, and fail to build. Non-content
- * scaffolds (blank, plugin) stay on `latest`.
+ * Templates whose files are coupled to the current alpha train install
+ * `nextly` + `@nextlyhq/*` from the `alpha` dist-tag rather than `latest`.
+ * During the alpha the conservative `latest` tag can lag the train, and a
+ * scaffold pinned to it would pair current template code with older packages:
+ * - `blog` renders through `nextly/runtime` cache helpers (`cachedFind` /
+ *   `nextlyTags`) that only ship on the alpha channel.
+ * - `plugin` ships with the CLI itself (bundled) and exercises the current
+ *   `@nextlyhq/plugin-sdk/testing` harness and admin surface; older packages
+ *   fail its generated test and dev playground.
+ * Only `blank` stays on `latest` — its files use no train-coupled APIs.
  */
-const CONTENT_TEMPLATE_TYPES: ReadonlySet<ProjectType> = new Set(["blog"]);
+const ALPHA_CHANNEL_TEMPLATE_TYPES: ReadonlySet<ProjectType> = new Set([
+  "blog",
+  "plugin",
+]);
 
 /**
  * The npm dist-tag a scaffold of `projectType` installs `nextly` + `@nextlyhq/*`
- * from: content templates track `alpha` (see {@link CONTENT_TEMPLATE_TYPES}),
- * everything else tracks `latest`.
+ * from: train-coupled templates track `alpha` (see
+ * {@link ALPHA_CHANNEL_TEMPLATE_TYPES}), everything else tracks `latest`.
  */
 export function templateNextlyChannel(projectType: ProjectType): NextlyDistTag {
-  return CONTENT_TEMPLATE_TYPES.has(projectType) ? "alpha" : "latest";
+  return ALPHA_CHANNEL_TEMPLATE_TYPES.has(projectType) ? "alpha" : "latest";
 }
 
 // ============================================================
@@ -197,6 +203,31 @@ async function replacePlaceholders(
   }
 }
 
+/**
+ * Restore `.gitignore` files that the bundled templates carry under the
+ * publish-safe name `gitignore` (recursive).
+ *
+ * npm's packer (npm-packlist, used by both npm and pnpm pack) always strips
+ * `.gitignore` files from tarballs, so the CLI build renames them when
+ * copying templates into the package (see tsup.config.ts). Templates
+ * resolved from a GitHub download or --local-template still carry the
+ * dotted name, so this is a no-op for those sources.
+ */
+export async function restoreBundledGitignores(dir: string): Promise<void> {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
+      await restoreBundledGitignores(fullPath);
+    } else if (entry.isFile() && entry.name === "gitignore") {
+      await fs.rename(fullPath, path.join(dir, ".gitignore"));
+    }
+  }
+}
+
 // ============================================================
 // Package.json Generation
 // ============================================================
@@ -461,9 +492,13 @@ export async function generatePackageJson(
  */
 async function resolvePluginNextlyRange(useYalc: boolean): Promise<string> {
   if (useYalc) return ">=0.0.0";
-  const versions = await resolveNextlyVersions();
+  // Plugin scaffolds track the alpha train (see templateNextlyChannel), so
+  // the declared compat range comes from the same channel the devDeps
+  // install from. A failed lookup yields the dist-tag NAME, which is not a
+  // valid semver range — fall back to an open range instead.
+  const versions = await resolveNextlyVersions(templateNextlyChannel("plugin"));
   const v = versions["nextly"];
-  return v && v !== "latest" ? v : ">=0.0.0";
+  return v && v.startsWith("^") ? v : ">=0.0.0";
 }
 
 /**
@@ -475,20 +510,25 @@ async function generatePluginPackageJson(
   projectName: string,
   useYalc: boolean
 ): Promise<string> {
-  const versions = useYalc ? {} : await resolveNextlyVersions();
+  // Plugin scaffolds resolve the Nextly family from the alpha train: the
+  // template ships inside the CLI itself, so its generated test and dev
+  // playground exercise current plugin-sdk/admin APIs that the lagging
+  // `latest` tag may not have yet (see templateNextlyChannel).
+  const channel = templateNextlyChannel("plugin");
+  const versions = useYalc ? {} : await resolveNextlyVersions(channel);
   const runtimeVersions = await resolveRuntimeVersions();
-  const range = (pkg: string): string => versions[pkg] ?? "latest";
+  const range = (pkg: string): string => versions[pkg] ?? channel;
 
-  // peerDependencies must be a valid semver range: pnpm 11 rejects the
-  // "latest" dist-tag there (ERR_PNPM_INVALID_PEER_DEPENDENCY_SPECIFICATION)
-  // and then refuses to run ANY script in the scaffold, including `pnpm dev`.
-  // The dist-tag can appear whenever a registry version lookup fails
+  // peerDependencies must be a valid semver range: pnpm 11 rejects a
+  // dist-tag there (ERR_PNPM_INVALID_PEER_DEPENDENCY_SPECIFICATION) and
+  // then refuses to run ANY script in the scaffold, including `pnpm dev`.
+  // The dist-tag name can appear whenever a registry version lookup fails
   // (offline, transient npm error) or under --use-yalc, so fall back to an
-  // open range instead. Dev/regular dependencies keep "latest" — the
-  // dist-tag is valid there and installs the newest release.
+  // open range instead. Dev dependencies keep the dist-tag — it is valid
+  // there and installs the channel's newest release.
   const peerRange = (pkg: string): string => {
     const v = range(pkg);
-    return v === "latest" ? ">=0.0.0" : v;
+    return v === channel ? ">=0.0.0" : v;
   };
 
   const peerDependencies: Record<string, string> = {
@@ -501,13 +541,23 @@ async function generatePluginPackageJson(
 
   // devDeps cover: build (tsup/tsc), test (vitest), lint (eslint), AND the
   // embedded dev/ playground (next + nextly + admin + sqlite adapter).
+  // Under --use-yalc the Nextly-family entries are omitted entirely
+  // (mirroring the app scaffold): the installer yalc-adds them from the
+  // local store before the first install, so registry specs here would
+  // only race it into fetching published packages it is about to replace.
+  const nextlyDevDependencies: Record<string, string> = useYalc
+    ? {}
+    : {
+        nextly: range("nextly"),
+        "@nextlyhq/admin": range("@nextlyhq/admin"),
+        "@nextlyhq/ui": range("@nextlyhq/ui"),
+        "@nextlyhq/plugin-sdk": range("@nextlyhq/plugin-sdk"),
+        "@nextlyhq/adapter-drizzle": range("@nextlyhq/adapter-drizzle"),
+        "@nextlyhq/adapter-sqlite": range("@nextlyhq/adapter-sqlite"),
+      };
+
   const devDependencies: Record<string, string> = {
-    nextly: range("nextly"),
-    "@nextlyhq/admin": range("@nextlyhq/admin"),
-    "@nextlyhq/ui": range("@nextlyhq/ui"),
-    "@nextlyhq/plugin-sdk": range("@nextlyhq/plugin-sdk"),
-    "@nextlyhq/adapter-drizzle": range("@nextlyhq/adapter-drizzle"),
-    "@nextlyhq/adapter-sqlite": range("@nextlyhq/adapter-sqlite"),
+    ...nextlyDevDependencies,
     next: runtimeVersions.next,
     react: PINNED_VERSIONS.react,
     "react-dom": PINNED_VERSIONS["react-dom"],
@@ -742,6 +792,11 @@ export async function copyTemplate(
     });
   }
 
+  // Bundled templates carry .gitignore under the publish-safe name
+  // `gitignore` (npm pack strips the dotted form); give the scaffold its
+  // real ignore rules back.
+  await restoreBundledGitignores(targetDir);
+
   // Also copy template's nextly.config.ts if it exists at root (for blank template)
   const templateRootConfig = path.join(typeDir, "nextly.config.ts");
   if (await fs.pathExists(templateRootConfig)) {
@@ -881,6 +936,13 @@ async function copyPluginTemplate(opts: {
     },
   });
 
+  // Bundled templates carry .gitignore under the publish-safe name
+  // `gitignore` (npm pack strips the dotted form); give the scaffold its
+  // real ignore rules back. Without this, a plugin scaffolded from the
+  // published CLI has no ignore rules — and dev/.env (materialized below)
+  // would be committable.
+  await restoreBundledGitignores(targetDir);
+
   // Materialize the dev playground env so `pnpm dev` boots with zero manual
   // steps: without dev/.env the dialect defaults to postgresql and the
   // instrumentation hook aborts asking for DATABASE_URL. `overwrite: false`
diff --git a/packages/create-nextly-app/tsup.config.ts b/packages/create-nextly-app/tsup.config.ts
index 2c6007ba3..b43aa7422 100644
--- a/packages/create-nextly-app/tsup.config.ts
+++ b/packages/create-nextly-app/tsup.config.ts
@@ -1,4 +1,4 @@
-import { cpSync, existsSync, rmSync } from "fs";
+import { cpSync, existsSync, readdirSync, renameSync, rmSync } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
 
@@ -11,6 +11,26 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // `plugin` is bundled so plugins are scaffoldable offline (D44).
 const BUNDLED_TEMPLATES = ["base", "blank", "plugin"] as const;
 
+/**
+ * Rename every `.gitignore` in the copied tree to the publish-safe name
+ * `gitignore`. npm's packer (npm-packlist, used by npm and pnpm pack alike)
+ * always strips `.gitignore` files from tarballs, so a bundled template
+ * shipped with the dotted name silently loses its ignore rules in the
+ * published CLI — scaffolds would then happily commit node_modules, dist,
+ * and the generated dev/.env. The scaffolder renames it back at copy time
+ * (see restoreBundledGitignores in src/utils/template.ts).
+ */
+function renameGitignoresForPacking(dir: string): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      renameGitignoresForPacking(full);
+    } else if (entry.name === ".gitignore") {
+      renameSync(full, path.join(dir, "gitignore"));
+    }
+  }
+}
+
 function copyBundledTemplates(): void {
   const monoRepoTemplates = path.resolve(__dirname, "../../templates");
   const dest = path.resolve(__dirname, "templates");
@@ -38,6 +58,9 @@ function copyBundledTemplates(): void {
     }
 
     cpSync(src, target, { recursive: true });
+    // Publish-safe rename: a dotted .gitignore would be stripped from the
+    // npm tarball, so the bundled copy carries `gitignore` instead.
+    renameGitignoresForPacking(target);
   }
 
   console.log(`✓ Bundled templates copied: ${BUNDLED_TEMPLATES.join(", ")}`);

From fe1320f5963eb6c9dc6758c7962d15b3a1045324 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Tue, 28 Jul 2026 14:32:41 +0500
Subject: [PATCH 18/20] fix(create-nextly-app): pin yalc plugin scaffolds'
 nested resolutions to the local store
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Yalc rewrites workspace:* inter-package ranges to *, and semver * never
matches prereleases — so pnpm resolved the linked packages' nested copies
of each other from the registry's last stable release (0.0.1) and the
mixed versions crashed the scaffold's test harness at runtime
(mapKeysToSqlColumns missing from the ancient adapter). The generated
pnpm-workspace.yaml now carries an overrides map pinning every resolution
of the yalc set to file:.yalc copies, and the installer shares the same
package list so the two can never drift.
---
 .../src/__tests__/scaffold-plugin.test.ts     | 37 +++++++++++++
 .../src/installers/dependencies.ts            | 38 +++++++------
 .../create-nextly-app/src/utils/template.ts   | 54 +++++++++++++++++--
 3 files changed, 109 insertions(+), 20 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index c2d294f95..f9ab128ed 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -101,6 +101,9 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     );
     expect(workspaceYaml).toContain("allowBuilds:");
     expect(workspaceYaml).toContain("better-sqlite3");
+    // Registry scaffolds resolve everything from npm — the yalc override
+    // block must never leak into them.
+    expect(workspaceYaml).not.toContain("overrides:");
 
     // The dev playground must boot with zero manual steps: without dev/.env
     // the dialect defaults to postgresql and `next dev` aborts in the
@@ -167,6 +170,40 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     expect(devConfig).not.toMatch(/\{\{\s*\w+\s*\}\}/);
   });
 
+  it("pins yalc scaffolds' nested resolutions to the local store", async () => {
+    workdir = await mkdtemp(path.join(tmpdir(), "nextly-plugin-yalc-"));
+    target = path.join(workdir, "my-plugin");
+
+    await copyTemplate({
+      projectName: "yalc-plugin",
+      projectType: "plugin",
+      targetDir: target,
+      database: { type: "sqlite" } as unknown as DatabaseConfig,
+      useYalc: true,
+      templateSource: {
+        basePath: path.join(templatesRoot, "base"),
+        templatePath: path.join(templatesRoot, "plugin"),
+      },
+    });
+
+    // Yalc rewrites workspace:* ranges to *, which semver treats as
+    // stable-only — without an overrides pin, pnpm resolves the packages'
+    // nested copies of each other from the registry's last stable release
+    // and the mixed versions crash at runtime.
+    const workspaceYaml = await readFile(
+      path.join(target, "pnpm-workspace.yaml"),
+      "utf-8"
+    );
+    expect(workspaceYaml).toContain("overrides:");
+    expect(workspaceYaml).toContain('"nextly": "file:.yalc/nextly"');
+    expect(workspaceYaml).toContain(
+      '"@nextlyhq/plugin-sdk": "file:.yalc/@nextlyhq/plugin-sdk"'
+    );
+    expect(workspaceYaml).toContain(
+      '"@nextlyhq/adapter-drizzle": "file:.yalc/@nextlyhq/adapter-drizzle"'
+    );
+  });
+
   it("restores .gitignore from the publish-safe bundled name", async () => {
     workdir = await mkdtemp(path.join(tmpdir(), "nextly-plugin-packed-"));
     target = path.join(workdir, "my-plugin");
diff --git a/packages/create-nextly-app/src/installers/dependencies.ts b/packages/create-nextly-app/src/installers/dependencies.ts
index 52979efb5..75997c37d 100644
--- a/packages/create-nextly-app/src/installers/dependencies.ts
+++ b/packages/create-nextly-app/src/installers/dependencies.ts
@@ -6,7 +6,10 @@ import type {
   ProjectInfo,
   ProjectType,
 } from "../types";
-import { projectUsesFormBuilder } from "../utils/template";
+import {
+  PLUGIN_YALC_PACKAGES,
+  projectUsesFormBuilder,
+} from "../utils/template";
 
 const INSTALL_COMMANDS: Record<PackageManager, string[]> = {
   npm: ["npm", "install"],
@@ -94,21 +97,24 @@ export async function installDependencies(
       // generatePackageJson(useYalc: true). Install npm-only deps first,
       // then layer yalc packages on top. Include ALL adapter packages because
       // yalc file: links cause Turbopack to resolve conditional dynamic imports.
-      const yalcPackages = [
-        ...new Set([
-          "nextly",
-          "@nextlyhq/admin",
-          "@nextlyhq/ui",
-          "@nextlyhq/adapter-drizzle",
-          ...ALL_ADAPTER_PACKAGES,
-          ...pluginPackages,
-          // A plugin scaffold imports @nextlyhq/plugin-sdk directly (its
-          // definePlugin surface + test harness). Linking it from the yalc
-          // store keeps it in lockstep with the other local packages instead
-          // of mixing the published SDK into a local-package scaffold.
-          ...(projectType === "plugin" ? ["@nextlyhq/plugin-sdk"] : []),
-        ]),
-      ];
+      // A plugin scaffold links the shared PLUGIN_YALC_PACKAGES set (which
+      // includes @nextlyhq/plugin-sdk — the scaffold imports it directly);
+      // the same list drives the pnpm-workspace.yaml overrides so every
+      // nested resolution pins to the local store. App scaffolds keep the
+      // app set: core packages + all adapters + template plugins.
+      const yalcPackages =
+        projectType === "plugin"
+          ? [...PLUGIN_YALC_PACKAGES]
+          : [
+              ...new Set([
+                "nextly",
+                "@nextlyhq/admin",
+                "@nextlyhq/ui",
+                "@nextlyhq/adapter-drizzle",
+                ...ALL_ADAPTER_PACKAGES,
+                ...pluginPackages,
+              ]),
+            ];
 
       if (projectType === "plugin") {
         // Plugin scaffolds declare Nextly peers with open ranges, and pnpm
diff --git a/packages/create-nextly-app/src/utils/template.ts b/packages/create-nextly-app/src/utils/template.ts
index 28d1fdacb..f9f015f16 100644
--- a/packages/create-nextly-app/src/utils/template.ts
+++ b/packages/create-nextly-app/src/utils/template.ts
@@ -637,6 +637,23 @@ export const NATIVE_BUILD_DEPENDENCIES = [
   "unrs-resolver",
 ] as const;
 
+/**
+ * The Nextly-family packages a plugin scaffold links from the local yalc
+ * store under --use-yalc. Single source of truth shared by the installer
+ * (which runs `yalc add` for each) and the pnpm-workspace.yaml generator
+ * (which pins every nested resolution to the same local copies).
+ */
+export const PLUGIN_YALC_PACKAGES = [
+  "nextly",
+  "@nextlyhq/admin",
+  "@nextlyhq/ui",
+  "@nextlyhq/adapter-drizzle",
+  "@nextlyhq/adapter-postgres",
+  "@nextlyhq/adapter-mysql",
+  "@nextlyhq/adapter-sqlite",
+  "@nextlyhq/plugin-sdk",
+] as const;
+
 /**
  * Generate the `pnpm-workspace.yaml` for a scaffolded project.
  *
@@ -649,8 +666,18 @@ export const NATIVE_BUILD_DEPENDENCIES = [
  * Both keys are emitted so native deps compile on any pnpm 10.6+/11. pnpm 9
  * runs build scripts by default and ignores this file; npm/yarn ignore it too,
  * so it is safe to ship in every scaffold regardless of package manager.
+ *
+ * `yalcOverrides` (yalc scaffolds only) additionally emits an `overrides`
+ * map pinning each named package to its `file:.yalc/<name>` copy. Yalc
+ * rewrites `workspace:*` inter-package ranges to `*`, and semver `*` never
+ * matches prereleases — so without the pin, pnpm resolves the packages'
+ * NESTED copies of each other from the registry's last stable release
+ * (0.0.1), and the scaffold crashes on APIs that old code lacks. Overrides
+ * apply to every resolution in the tree, forcing one consistent local set.
  */
-export function generatePnpmWorkspaceYaml(): string {
+export function generatePnpmWorkspaceYaml(options?: {
+  yalcOverrides?: readonly string[];
+}): string {
   const allowBuilds = NATIVE_BUILD_DEPENDENCIES.map(
     dep => `  ${dep}: true`
   ).join("\n");
@@ -658,6 +685,20 @@ export function generatePnpmWorkspaceYaml(): string {
     "\n"
   );
 
+  let overridesBlock = "";
+  if (options?.yalcOverrides && options.yalcOverrides.length > 0) {
+    const overrides = options.yalcOverrides
+      .map(pkg => `  "${pkg}": "file:.yalc/${pkg}"`)
+      .join("\n");
+    overridesBlock =
+      "\n# Pin every resolution (including nested ones) of the yalc-linked\n" +
+      "# packages to the local store. Yalc rewrites their workspace:* ranges\n" +
+      "# to *, which semver treats as stable-only — without this pin, pnpm\n" +
+      "# fetches ancient registry releases for the packages' internal copies\n" +
+      "# of each other and the mixed versions crash at runtime.\n" +
+      `overrides:\n${overrides}\n`;
+  }
+
   return (
     "# Allow native dependencies to run their build scripts. pnpm 10+ blocks\n" +
     "# dependency build scripts by default; without this better-sqlite3 has no\n" +
@@ -666,7 +707,8 @@ export function generatePnpmWorkspaceYaml(): string {
     "# pnpm 11+ reads `allowBuilds`; pnpm 10.6+ reads `onlyBuiltDependencies`.\n" +
     "# npm, yarn, and pnpm 9 ignore this file (they run build scripts by default).\n" +
     `allowBuilds:\n${allowBuilds}\n` +
-    `onlyBuiltDependencies:\n${onlyBuilt}\n`
+    `onlyBuiltDependencies:\n${onlyBuilt}\n` +
+    overridesBlock
   );
 }
 
@@ -971,10 +1013,14 @@ async function copyPluginTemplate(opts: {
   // pnpm 11 ignores the package.json `pnpm` field, and the embedded dev/
   // playground uses better-sqlite3 (native build) — so this file is what lets
   // `pnpm install` build it instead of aborting with ERR_PNPM_IGNORED_BUILDS.
-  // Harmless for npm/yarn/pnpm 9.
+  // Harmless for npm/yarn/pnpm 9. Yalc scaffolds additionally pin every
+  // nested resolution of the linked packages to the local store (see
+  // generatePnpmWorkspaceYaml).
   await fs.writeFile(
     path.join(targetDir, "pnpm-workspace.yaml"),
-    generatePnpmWorkspaceYaml(),
+    generatePnpmWorkspaceYaml(
+      useYalc ? { yalcOverrides: PLUGIN_YALC_PACKAGES } : undefined
+    ),
     "utf-8"
   );
 

From ef7c789a6a505a9725897825a32ca8de64b77e39 Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Tue, 28 Jul 2026 14:40:14 +0500
Subject: [PATCH 19/20] fix(create-nextly-app): scaffold plugins from inside an
 existing next.js app
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The plugin template always produces a standalone package, but a Next.js
project at cwd routed the run into the install-into-this-project flow —
which ignores the directory argument — so the guard cancelled even for
an explicit target like 'create-nextly-app my-plugin -t plugin' run from
inside an app repo. Plugin runs now always take the fresh-scaffold path
(making that guard unreachable, so it is removed); non-empty targets are
negotiated by the existing directory-conflict prompt, and non-plugin
behavior in existing projects is unchanged.

Also validates generated peer specs with an anchored full-range pattern
instead of a first-character check, which waved through hybrids like
'^latest'.
---
 .../src/__tests__/scaffold-plugin.test.ts     | 10 ++++++---
 .../create-nextly-app/src/create-nextly.ts    | 21 ++++++++-----------
 2 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index f9ab128ed..17c5b9459 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -83,12 +83,16 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     // (ERR_PNPM_INVALID_PEER_DEPENDENCY_SPECIFICATION) and then refuses to
     // run any script in the scaffold. This test runs with the registry
     // stubbed offline, so every version lookup exercises the fallback path —
-    // exactly where a dist-tag used to leak in. Semver ranges start with a
-    // digit or range operator; dist-tag names start with a letter.
+    // exactly where a dist-tag used to leak in. The generator only ever
+    // emits `^x.y.z(-prerelease)?` or the open `>=x.y.z` fallback, so the
+    // anchored pattern validates the complete spec — partial matches would
+    // wave through hybrids like `^latest` or `>=alpha`.
     for (const [peer, spec] of Object.entries(
       pkg.peerDependencies as Record<string, string>
     )) {
-      expect(spec, `peerDependencies.${peer}`).toMatch(/^[\d^~><=*]/);
+      expect(spec, `peerDependencies.${peer}`).toMatch(
+        /^(?:\^|>=)\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
+      );
     }
     // The native-build allowlist lives in pnpm-workspace.yaml, NOT the package.json
     // `pnpm` field (pnpm 11 ignores that field). Without this, `pnpm install` aborts
diff --git a/packages/create-nextly-app/src/create-nextly.ts b/packages/create-nextly-app/src/create-nextly.ts
index 275efae86..4238182d8 100644
--- a/packages/create-nextly-app/src/create-nextly.ts
+++ b/packages/create-nextly-app/src/create-nextly.ts
@@ -105,7 +105,15 @@ export async function createNextly(
 
   const existingProject = await isExistingNextProject(cwd);
 
-  if (existingProject) {
+  // The plugin template always scaffolds a standalone package — it never
+  // installs into an existing app. Running it from inside a Next.js repo
+  // (a natural place to build a plugin for that app) must therefore skip
+  // the install-into-this-project flow, which ignores the directory
+  // argument entirely; plugin runs take the fresh-scaffold path below and
+  // a non-empty target is negotiated by the directory-conflict prompt.
+  const isPluginScaffold = options.projectType === "plugin";
+
+  if (existingProject && !isPluginScaffold) {
     p.log.success(`${pc.green("Next.js")} project detected`);
 
     if (!defaults) {
@@ -218,17 +226,6 @@ export async function createNextly(
     projectType = isValidTemplateSelection(template) ? template : "blank";
   }
 
-  // The plugin template scaffolds a standalone publishable package. In an
-  // existing Next.js project the fresh-scaffold path is skipped entirely, so
-  // proceeding would install app dependencies and generate app config while
-  // never copying the plugin source — a broken hybrid. Fail fast instead.
-  if (projectType === "plugin" && !isFreshProject) {
-    p.cancel(
-      "The Plugin template creates a standalone package and cannot be installed into an existing Next.js project. Run create-nextly-app in an empty directory instead."
-    );
-    return;
-  }
-
   // --- Step 3: Schema approach (only for content templates with approaches) ---
 
   let approach: ProjectApproach | undefined;

From 0ec3970b969cf6cdafa12bf3195ec54f6bb1197b Mon Sep 17 00:00:00 2001
From: aqib-rx <aqib.revnix@gmail.com>
Date: Wed, 29 Jul 2026 14:45:28 +0500
Subject: [PATCH 20/20] fix(create-nextly-app): merge restored gitignores and
 validate registry versions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restoring a bundled gitignore now merges into an existing .gitignore
(overlay scaffolds can carry user rules at the destination; a rename
replaced them, silently un-ignoring whatever they covered) — the
template's rules are appended once, so user rules and the required
dev/.env exclusion both hold.

Registry dist-tag payloads are untrusted: fetchLatestVersion now wraps
only complete semver versions (a malformed tag became an invalid
"^not-a-version" install spec in every generated package.json), and the
plugin compat range validates the full caret range before trusting it.
The packing-time gitignore walk also skips node_modules and .git.
---
 .../src/__tests__/scaffold-plugin.test.ts     | 54 ++++++++++++++++++-
 .../src/__tests__/template-channel.test.ts    | 23 ++++++++
 .../create-nextly-app/src/utils/template.ts   | 38 +++++++++++--
 packages/create-nextly-app/tsup.config.ts     |  3 ++
 4 files changed, 112 insertions(+), 6 deletions(-)

diff --git a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
index 17c5b9459..9154b47f5 100644
--- a/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
+++ b/packages/create-nextly-app/src/__tests__/scaffold-plugin.test.ts
@@ -1,4 +1,13 @@
-import { cp, mkdtemp, readFile, rename, rm, stat } from "node:fs/promises";
+import {
+  cp,
+  mkdir,
+  mkdtemp,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -242,4 +251,47 @@ describe("scaffold --template plugin (D44/D45 smoke test)", () => {
     expect(gitignore).toContain(".env");
     expect(await exists(path.join(target, "gitignore"))).toBe(false);
   });
+
+  it("merges into a pre-existing .gitignore instead of replacing it", async () => {
+    workdir = await mkdtemp(path.join(tmpdir(), "nextly-plugin-overlay-"));
+    target = path.join(workdir, "my-plugin");
+
+    const packedTemplate = path.join(workdir, "packed-template");
+    await cp(path.join(templatesRoot, "plugin"), packedTemplate, {
+      recursive: true,
+    });
+    await rename(
+      path.join(packedTemplate, ".gitignore"),
+      path.join(packedTemplate, "gitignore")
+    );
+
+    // Overlay scenario: the user chose "ignore" on a non-empty directory
+    // that already carries their own ignore rules. Restoration must keep
+    // them — a rename would silently un-ignore whatever they covered.
+    await mkdir(target, { recursive: true });
+    await writeFile(
+      path.join(target, ".gitignore"),
+      "# user rules\nmy-secret.txt\n",
+      "utf-8"
+    );
+
+    await copyTemplate({
+      projectName: "overlay-plugin",
+      projectType: "plugin",
+      targetDir: target,
+      database: { type: "sqlite" } as unknown as DatabaseConfig,
+      allowExistingTarget: true,
+      templateSource: {
+        basePath: path.join(templatesRoot, "base"),
+        templatePath: packedTemplate,
+      },
+    });
+
+    const gitignore = await readFile(path.join(target, ".gitignore"), "utf-8");
+    // User rules survive AND the template's required rules (dev/.env!) land.
+    expect(gitignore).toContain("my-secret.txt");
+    expect(gitignore).toContain("node_modules");
+    expect(gitignore).toContain(".env");
+    expect(await exists(path.join(target, "gitignore"))).toBe(false);
+  });
 });
diff --git a/packages/create-nextly-app/src/__tests__/template-channel.test.ts b/packages/create-nextly-app/src/__tests__/template-channel.test.ts
index 15f7839ee..f2585e2c4 100644
--- a/packages/create-nextly-app/src/__tests__/template-channel.test.ts
+++ b/packages/create-nextly-app/src/__tests__/template-channel.test.ts
@@ -149,6 +149,29 @@ describe("alpha pin survives a registry lookup failure", () => {
     expect(pkg.dependencies["nextly"]).toBe("alpha");
   });
 
+  it("rejects a malformed registry version instead of wrapping it", async () => {
+    // The registry payload is untrusted: a dist-tag pointing at a
+    // non-semver value must fall back to the tag name (a valid npm spec),
+    // never become an invalid "^not-a-version" install spec.
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => ({
+        ok: true,
+        json: async () => ({ latest: "not-a-version", alpha: "also bad" }),
+      }))
+    );
+    const { generatePackageJson: gen, templateNextlyChannel: channelOf } =
+      await import("../utils/template");
+    const pkg = JSON.parse(await gen("my-plugin", pgDatabase, false, "plugin"));
+    expect(pkg.devDependencies["nextly"]).toBe(channelOf("plugin"));
+    expect(pkg.peerDependencies["nextly"]).toBe(">=0.0.0");
+
+    const blogPkg = JSON.parse(
+      await gen("blog-app", pgDatabase, false, "blog")
+    );
+    expect(blogPkg.dependencies["nextly"]).toBe(channelOf("blog"));
+  });
+
   it("keeps plugin devDeps on its channel tag but peers on a semver range when the registry fails", async () => {
     vi.stubGlobal(
       "fetch",
diff --git a/packages/create-nextly-app/src/utils/template.ts b/packages/create-nextly-app/src/utils/template.ts
index f9f015f16..76a509d86 100644
--- a/packages/create-nextly-app/src/utils/template.ts
+++ b/packages/create-nextly-app/src/utils/template.ts
@@ -223,7 +223,26 @@ export async function restoreBundledGitignores(dir: string): Promise<void> {
       if (entry.name === "node_modules" || entry.name === ".git") continue;
       await restoreBundledGitignores(fullPath);
     } else if (entry.isFile() && entry.name === "gitignore") {
-      await fs.rename(fullPath, path.join(dir, ".gitignore"));
+      const target = path.join(dir, ".gitignore");
+      if (await fs.pathExists(target)) {
+        // Overlay scaffolds ("ignore" on a non-empty directory) can already
+        // have user ignore rules at the destination. A rename would replace
+        // them — silently un-ignoring whatever they covered — so append the
+        // template's rules instead (duplicate patterns are harmless to
+        // git), unless a previous scaffold already appended them.
+        const existing = await fs.readFile(target, "utf-8");
+        const templateRules = await fs.readFile(fullPath, "utf-8");
+        if (!existing.includes(templateRules)) {
+          await fs.writeFile(
+            target,
+            `${existing.trimEnd()}\n\n${templateRules}`,
+            "utf-8"
+          );
+        }
+        await fs.remove(fullPath);
+      } else {
+        await fs.rename(fullPath, target);
+      }
     }
   }
 }
@@ -300,7 +319,13 @@ async function fetchLatestVersion(
     if (!res.ok) return channel;
     const data = (await res.json()) as Record<string, string>;
     const version = data[channel];
-    return version ? `^${version}` : channel;
+    // The registry payload is untrusted input: only wrap a value that is a
+    // complete semver version — anything else would become an invalid
+    // install spec (e.g. "^not-a-version") in every generated package.json.
+    // The dist-tag name is itself a valid npm spec, so it stays the fallback.
+    return version && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)
+      ? `^${version}`
+      : channel;
   } catch {
     return channel;
   }
@@ -494,11 +519,14 @@ async function resolvePluginNextlyRange(useYalc: boolean): Promise<string> {
   if (useYalc) return ">=0.0.0";
   // Plugin scaffolds track the alpha train (see templateNextlyChannel), so
   // the declared compat range comes from the same channel the devDeps
-  // install from. A failed lookup yields the dist-tag NAME, which is not a
-  // valid semver range — fall back to an open range instead.
+  // install from. The registry value is wrapped as `^version` upstream
+  // without being parsed, so validate the COMPLETE caret range here — a
+  // malformed dist-tags payload (or a failed lookup, which yields the bare
+  // dist-tag name) must fall back to an open range, never leak into the
+  // plugin's declared compat range.
   const versions = await resolveNextlyVersions(templateNextlyChannel("plugin"));
   const v = versions["nextly"];
-  return v && v.startsWith("^") ? v : ">=0.0.0";
+  return v && /^\^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(v) ? v : ">=0.0.0";
 }
 
 /**
diff --git a/packages/create-nextly-app/tsup.config.ts b/packages/create-nextly-app/tsup.config.ts
index b43aa7422..744a85cd9 100644
--- a/packages/create-nextly-app/tsup.config.ts
+++ b/packages/create-nextly-app/tsup.config.ts
@@ -24,6 +24,9 @@ function renameGitignoresForPacking(dir: string): void {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
+      // A template dir may carry a local node_modules from testing the dev/
+      // playground in place; recursing into it is pure waste.
+      if (entry.name === "node_modules" || entry.name === ".git") continue;
       renameGitignoresForPacking(full);
     } else if (entry.name === ".gitignore") {
       renameSync(full, path.join(dir, "gitignore"));