create-lacspace-app 2.7.0 → 2.9.0

package/README.md

@@ -20,6 +20,18 @@ npx create-lacspace-app my-app --template saas --fullstack
 
 You choose the *kind* of site you're building. It writes a **real Next.js 15 + React 19 + Tailwind v4 app** — not a hello-world, but a genuinely **polished, modern site**: a fluid `clamp()` type scale, tight display headings, a refined light **and** dark palette, glass chrome, soft layered shadows, a smooth logo marquee, animated counters, scroll reveals and a shimmering primary CTA — every page filled in, an SEO stack wired end-to-end, and a **26-component UI kit** you can drop in anywhere.
 
+> **New in v2.9 — guided & discoverable.** Made for newcomers:
+> - **Guided start** — the interactive prompt now offers a **recipe** first ("what are you building?"), so you can ship a whole product without knowing the flags.
+> - **`list`** — `npx create-lacspace-app list` shows every template, add-on and recipe. **`explain <name>`** describes what any add-on or recipe gives you (packages, next steps, docs link).
+> - **`--dry-run`** prints the exact files a command would create without writing anything. `--brand "#hex"` is an alias for `--theme`.
+
+> **New in v2.8 — recipes.** Scaffold a whole *kind of product* in one command with `--recipe <key>` (a curated template + full-stack mode + add-on stack):
+> - **`ai-saas`** → SaaS + accounts + payments + AI chat + analytics
+> - **`store`** → e-commerce + eSewa/Khalti checkout + email + analytics
+> - **`blog`** → blog + content + search · **`docs-ai`** → docs + RAG + search · **`internal-tool`** → dashboard + auth + analytics + email
+>
+> `npx create-lacspace-app my-app --recipe ai-saas`. Explicit `--template`/`--with`/`--fullstack` still merge on top. Also on the lib API: `listRecipes()` / `getRecipe()`.
+
 > **New in v2.7 — payments & email add-ons.**
 > - **`payments`** — a checkout wired to **eSewa & Khalti**: orders, integer-safe money (`@lacspace/money`), and the signed eSewa flow that **works end-to-end in test mode with NO credentials**. Khalti activates when you add `KHALTI_SECRET`.
 > - **`email`** — transactional email: a ready mail service (`@lacspace/mailer`) with beautiful templates (`@lacspace/email-templates`) + address validation. **Logs emails to the console until you add SMTP** — so it runs out-of-the-box, then delivers for real with one env change.

package/dist/index.js

@@ -29,14 +29,15 @@ var TEMPLATES = [
   { key: "marketplace", label: "Marketplace / commerce", description: "A real storefront wired to the Lacspace commerce packages \u2014 cart, checkout, tax, shipping, orders, invoices and Nepal payments.", accent: ["#0d9488", "#6366f1"], siteName: "LSBazaar", siteDescription: "A modern storefront \u2014 cart to checkout, wired end to end." }
 ];
 function resolveContext(options = {}) {
-  const base = TEMPLATES.find((t) => t.key === options.template) ?? TEMPLATES[0];
+  const recipe = options.recipe ? RECIPES.find((r) => r.key === String(options.recipe).toLowerCase()) : void 0;
+  const base = TEMPLATES.find((t) => t.key === (options.template ?? recipe?.template)) ?? TEMPLATES[0];
   const accent = resolveAccent(options.theme);
   const template = accent ? { ...base, accent } : base;
   const raw = options.name ?? "my-app";
   const seg = raw.split(/[\\/]/).filter(Boolean).pop() ?? "my-app";
   const name = seg.toLowerCase().replace(/[^a-z0-9-_]/g, "-").replace(/^-+|-+$/g, "") || "my-app";
-  const features = normalizeFeatures(options.features);
-  let mode = options.mode === "dynamic" ? "dynamic" : "static";
+  const features = normalizeFeatures([...recipe?.features ?? [], ...options.features ?? []]);
+  let mode = options.mode === "dynamic" ? "dynamic" : options.mode === "static" ? "static" : recipe?.mode ?? "static";
   if (mode === "static" && features.some((f) => f.requiresBackend)) mode = "dynamic";
   return { name, template, features, mode };
 }
@@ -5252,6 +5253,13 @@ var faqSection = (ctx) => {
         </div>
       </section>`;
 };
+var RECIPES = [
+  { key: "ai-saas", label: "AI SaaS", description: "SaaS landing + accounts + payments + a streaming AI chat + analytics.", template: "saas", mode: "dynamic", features: ["auth-pages", "payments", "ai-chat", "analytics"] },
+  { key: "store", label: "Online store", description: "E-commerce storefront + eSewa/Khalti checkout + transactional email + analytics.", template: "ecommerce", mode: "dynamic", features: ["payments", "email", "analytics"] },
+  { key: "blog", label: "Blog", description: "A blog with a Markdown content section, RSS/llms.txt and instant search.", template: "blog", features: ["content", "search"] },
+  { key: "internal-tool", label: "Internal tool", description: "An admin dashboard with accounts (2FA), analytics and email \u2014 full-stack.", template: "dashboard", mode: "dynamic", features: ["auth-pages", "analytics", "email"] },
+  { key: "docs-ai", label: "AI docs", description: "A documentation site with chat-with-your-docs RAG and instant search.", template: "docs", features: ["rag", "search"] }
+];
 var contentLib = () => `import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter, markdownToHtml, excerpt } from "@lacspace/markdown";
@@ -7209,7 +7217,7 @@ function backendFiles(ctx) {
 }
 var splitList = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 function parseArgs(list) {
-  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false };
+  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false, dryRun: false };
   for (let i = 0; i < list.length; i++) {
     const arg = list[i];
     const next = () => list[++i] ?? "";
@@ -7217,8 +7225,9 @@ function parseArgs(list) {
     else if (arg === "-y" || arg === "--yes") a.yes = true;
     else if (arg === "--no-install") a.install = false;
     else if (arg === "--no-git") a.git = false;
+    else if (arg === "--dry-run" || arg === "--dry") a.dryRun = true;
     else if (arg === "--pm") a.pm = next();
-    else if (arg === "--theme" || arg === "--accent") a.theme = next();
+    else if (arg === "--theme" || arg === "--accent" || arg === "--brand") a.theme = next();
     else if (arg === "--with" || arg === "--features") a.features.push(...splitList(next()));
     else if (arg === "--fullstack" || arg === "--full-stack" || arg === "--dynamic") a.mode = "dynamic";
     else if (arg === "--static") a.mode = "static";
@@ -7228,10 +7237,13 @@ function parseArgs(list) {
     } else if (arg.startsWith("--mode=")) {
       const m = arg.slice(7).toLowerCase();
       a.mode = m === "dynamic" ? "dynamic" : "static";
-    } else if (arg === "-h" || arg === "--help") a.help = true;
+    } else if (arg === "--recipe") a.recipe = next();
+    else if (arg.startsWith("--recipe=")) a.recipe = arg.slice(9);
+    else if (arg === "-h" || arg === "--help") a.help = true;
     else if (arg.startsWith("--template=")) a.template = arg.slice(11);
     else if (arg.startsWith("--theme=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--accent=")) a.theme = arg.slice(9);
+    else if (arg.startsWith("--brand=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--with=")) a.features.push(...splitList(arg.slice(7)));
     else if (arg.startsWith("--features=")) a.features.push(...splitList(arg.slice(11)));
     else if (!arg.startsWith("-") && !a.name) a.name = arg;
@@ -7322,6 +7334,8 @@ ${c("bold", "Usage")}
   npm create lacspace-app@latest <name> [options]
   npx create-lacspace-app <name> --template <key>
   npx create-lacspace-app add <section...>   ${c("dim", "# grow an existing app")}
+  npx create-lacspace-app list                ${c("dim", "# templates, add-ons & recipes")}
+  npx create-lacspace-app explain <name>      ${c("dim", "# what an add-on/recipe gives you")}
 
 ${c("bold", "Templates")}
 ${TEMPLATES.map((t) => `  ${t.key.padEnd(10)} ${t.description}`).join("\n")}
@@ -7332,17 +7346,23 @@ ${c("bold", "Options")}
                          MongoDB/Redis backend (JWT auth + CRUD) + shared types
                          ${c("dim", "(alias --dynamic; default is --static, a single Next.js app)")}
   --with <a,b>           Feature add-ons, comma-separated (alias --features)
-  --theme <name|hex>     Accent: a preset, a "#hex", or "from,to" (e.g. --theme lacspace)
+  --recipe <key>         Start from a curated stack (${RECIPES.map((r) => r.key).join(" | ")})
+  --theme <name|hex>     Accent: a preset, a "#hex", or "from,to" (alias --brand)
   --pm <npm|pnpm|yarn|bun>  Package manager (default npm)
+  --dry-run              Print the files that would be created; write nothing
   --no-install           Skip installing dependencies
   --no-git               Skip git init
   -y, --yes              Accept defaults (needs <name>)
   -h, --help             Show this help
 
 ${c("bold", "Feature add-ons")} ${c("dim", "(--with) \u2014 free & keyless, local by default")}
-${FEATURES.map((f) => `  ${f.key.padEnd(10)} ${f.description}`).join("\n")}
+${FEATURES.map((f) => `  ${f.key.padEnd(11)} ${f.description}`).join("\n")}
   ${c("dim", "e.g. npx create-lacspace-app my-app --template saas --with ai-chat,rag")}
 
+${c("bold", "Recipes")} ${c("dim", "(--recipe) \u2014 a whole product in one command")}
+${RECIPES.map((r) => `  ${r.key.padEnd(14)} ${r.description}`).join("\n")}
+  ${c("dim", "e.g. npx create-lacspace-app my-app --recipe ai-saas")}
+
 ${c("bold", "Themes")} ${c("dim", "(--theme)")}
   ${Object.keys(THEMES).join(" \xB7 ")}
   ${c("dim", 'or a custom colour: --theme "#ff6a00"  \xB7  --theme "#0bb9d9,#7c3aed"')}
@@ -7705,12 +7725,103 @@ ${c("bold", "Use them")} \u2014 import into any page:
     return;
   }
 }
+function runList() {
+  stdout.write(`
+${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 what you can build")}
+`);
+  stdout.write(`
+${c("bold", "Templates")} ${c("dim", "(-t / --template)")}
+`);
+  for (const t of TEMPLATES) stdout.write(`  ${c("cyan", t.key.padEnd(12))} ${c("dim", t.description)}
+`);
+  stdout.write(`
+${c("bold", "Add-ons")} ${c("dim", "(--with) \u2014 free & keyless")}
+`);
+  for (const f of FEATURES) stdout.write(`  ${c("cyan", f.key.padEnd(12))} ${c("dim", f.description)}${f.requiresBackend ? c("green", "  [full-stack]") : ""}
+`);
+  stdout.write(`
+${c("bold", "Recipes")} ${c("dim", "(--recipe) \u2014 a whole product in one command")}
+`);
+  for (const r of RECIPES) stdout.write(`  ${c("cyan", r.key.padEnd(14))} ${c("dim", r.description)}
+`);
+  stdout.write(`
+  ${c("dim", "Learn one:")} ${c("cyan", "npx create-lacspace-app explain <name>")}
+
+`);
+}
+function runExplain(rawNames) {
+  const name = rawNames.find((n) => !n.startsWith("-"))?.toLowerCase();
+  if (!name) {
+    stdout.write(`Usage: ${c("cyan", "npx create-lacspace-app explain <template|add-on|recipe>")}
+
+`);
+    runList();
+    return;
+  }
+  const feat = FEATURES.find((f) => f.key === name);
+  const recipe = RECIPES.find((r) => r.key === name);
+  const tmpl = TEMPLATES.find((t) => t.key === name);
+  stdout.write("\n");
+  if (feat) {
+    stdout.write(`${c("bold", c("magenta", "add-on: " + feat.key))} ${feat.requiresBackend ? c("green", "[full-stack]") : c("dim", "[frontend]")}
+
+${feat.description}
+`);
+    const deps = { ...feat.deps, ...feat.backend?.({ name: "app", template: TEMPLATES[0], features: [], mode: "dynamic" })?.deps ?? {} };
+    if (Object.keys(deps).length) stdout.write(`
+${c("bold", "Packages")}: ${Object.keys(deps).map((d) => c("cyan", d)).join(", ")}
+`);
+    stdout.write(`
+${c("bold", "Next steps")}:
+`);
+    for (const s of feat.nextSteps) stdout.write(`  ${c("dim", "\u2022")} ${s}
+`);
+    if (feat.learn) stdout.write(`
+Learn more \u2192 ${c("cyan", feat.learn)}
+`);
+    stdout.write(`
+Add it: ${c("cyan", "npx create-lacspace-app my-app --with " + feat.key)}
+
+`);
+  } else if (recipe) {
+    stdout.write(`${c("bold", c("magenta", "recipe: " + recipe.key))}
+
+${recipe.description}
+
+${c("bold", "Template")}: ${c("cyan", recipe.template)}${recipe.mode ? c("dim", " \xB7 " + recipe.mode) : ""}
+${c("bold", "Add-ons")}: ${recipe.features.map((f) => c("cyan", f)).join(", ")}
+
+Use it: ${c("cyan", "npx create-lacspace-app my-app --recipe " + recipe.key)}
+
+`);
+  } else if (tmpl) {
+    stdout.write(`${c("bold", c("magenta", "template: " + tmpl.key))}
+
+${tmpl.description}
+
+Use it: ${c("cyan", "npx create-lacspace-app my-app --template " + tmpl.key)}
+
+`);
+  } else {
+    stdout.write(c("yellow", `Unknown "${name}".
+`));
+    runList();
+  }
+}
 async function main() {
   const raw = argv.slice(2);
   if (raw[0] === "add") {
     runAdd(raw.slice(1));
     return;
   }
+  if (raw[0] === "list" || raw[0] === "ls") {
+    runList();
+    return;
+  }
+  if (raw[0] === "explain" || raw[0] === "info") {
+    runExplain(raw.slice(1));
+    return;
+  }
   const args = parseArgs(raw);
   if (args.help) {
     stdout.write(HELP + "\n");
@@ -7719,15 +7830,42 @@ async function main() {
   stdout.write(`
 ${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 a gorgeous Next.js starter, batteries wired")}
 
+`);
+  const recipe = args.recipe ? RECIPES.find((r) => r.key === args.recipe.toLowerCase()) : void 0;
+  if (args.recipe && !recipe) stdout.write(c("yellow", `  ! Unknown recipe "${args.recipe}" \u2014 ignoring. Try: ${RECIPES.map((r) => r.key).join(", ")}
+`));
+  if (recipe) stdout.write(`  ${c("green", "\u2714")} Recipe ${c("cyan", recipe.key)} ${c("dim", "\u2014 " + recipe.description)}
 `);
   let name = args.name;
-  let templateKey = args.template;
-  let mode = args.mode ?? "static";
-  const featureKeys = [...args.features];
+  let templateKey = args.template ?? recipe?.template;
+  let mode = args.mode ?? recipe?.mode ?? "static";
+  const featureKeys = [...recipe?.features ?? [], ...args.features];
+  let usedRecipe = Boolean(recipe);
   if (!args.yes && stdin.isTTY) {
     const rl = createInterface({ input: stdin, output: stdout });
     try {
       if (!name) name = (await rl.question(`${c("green", "?")} Project name ${c("dim", "(my-app)")}: `)).trim() || "my-app";
+      if (!usedRecipe && !templateKey && featureKeys.length === 0) {
+        stdout.write(`
+  Start from a recipe? ${c("dim", "(a template + add-ons, ready to go)")}
+`);
+        RECIPES.forEach((r, i) => stdout.write(`   ${c("cyan", String(i + 1))}. ${c("bold", r.label)} ${c("dim", "\u2014 " + r.description)}
+`));
+        stdout.write(`   ${c("cyan", "0")}. ${c("dim", "No recipe \u2014 I'll choose a template myself")}
+`);
+        const ans = (await rl.question(`
+${c("green", "?")} Recipe ${c("dim", "(0)")}: `)).trim() || "0";
+        const idx = /^\d+$/.test(ans) ? parseInt(ans, 10) - 1 : RECIPES.findIndex((r) => r.key === ans);
+        const chosen = ans === "0" ? void 0 : RECIPES[idx];
+        if (chosen) {
+          usedRecipe = true;
+          templateKey = chosen.template;
+          mode = chosen.mode ?? mode;
+          for (const k of chosen.features) if (!featureKeys.includes(k)) featureKeys.push(k);
+          stdout.write(`  ${c("green", "\u2714")} Recipe ${c("cyan", chosen.key)}
+`);
+        }
+      }
       if (!templateKey) {
         stdout.write(`
   Choose a template:
@@ -7739,7 +7877,7 @@ ${c("green", "?")} Template ${c("dim", "(1)")}: `)).trim() || "1";
         const idx = /^\d+$/.test(ans) ? parseInt(ans, 10) - 1 : TEMPLATES.findIndex((t) => t.key === ans);
         templateKey = TEMPLATES[idx]?.key ?? "personal";
       }
-      if (args.mode === void 0) {
+      if (args.mode === void 0 && !usedRecipe) {
         stdout.write(`
   What kind of app?
 `);
@@ -7792,7 +7930,25 @@ ${c("green", "?")} Add features? ${c("dim", "(comma-separated numbers, or Enter
     return;
   }
   const features = normalizeFeatures(featureKeys);
+  if (mode === "static" && features.some((f) => f.requiresBackend)) {
+    mode = "dynamic";
+    stdout.write(`  ${c("dim", "\u2191 a selected add-on needs a backend \u2014 building full-stack")}
+`);
+  }
   const files = buildFiles({ name: projectName, template, features, mode });
+  if (args.dryRun) {
+    const keys = Object.keys(files).sort();
+    stdout.write(`
+  ${c("bold", "Dry run")} ${c("dim", `\u2014 ${keys.length} files (${mode}${features.length ? ", +" + features.map((f) => f.key).join(",") : ""}), nothing written`)}
+`);
+    for (const rel of keys) stdout.write(`    ${c("dim", "+ " + rel)}
+`);
+    stdout.write(`
+  ${c("dim", "Remove --dry-run to create the project.")}
+
+`);
+    return;
+  }
   for (const [rel, content] of Object.entries(files)) {
     const full = join(dir, rel);
     mkdirSync(dirname(full), { recursive: true });
@@ -7880,4 +8036,4 @@ if (invokedAsCli) {
   });
 }
 
-export { FEATURES, SECTIONS, TEMPLATES, applyFeatures, buildFiles, normalizeFeatures, resolveContext };
+export { FEATURES, RECIPES, SECTIONS, TEMPLATES, applyFeatures, buildFiles, normalizeFeatures, resolveContext };

package/dist/lib.cjs

@@ -33,14 +33,15 @@ var TEMPLATES = [
   { key: "marketplace", label: "Marketplace / commerce", description: "A real storefront wired to the Lacspace commerce packages \u2014 cart, checkout, tax, shipping, orders, invoices and Nepal payments.", accent: ["#0d9488", "#6366f1"], siteName: "LSBazaar", siteDescription: "A modern storefront \u2014 cart to checkout, wired end to end." }
 ];
 function resolveContext(options = {}) {
-  const base = TEMPLATES.find((t) => t.key === options.template) ?? TEMPLATES[0];
+  const recipe = options.recipe ? RECIPES.find((r) => r.key === String(options.recipe).toLowerCase()) : void 0;
+  const base = TEMPLATES.find((t) => t.key === (options.template ?? recipe?.template)) ?? TEMPLATES[0];
   const accent = resolveAccent(options.theme);
   const template = accent ? { ...base, accent } : base;
   const raw = options.name ?? "my-app";
   const seg = raw.split(/[\\/]/).filter(Boolean).pop() ?? "my-app";
   const name = seg.toLowerCase().replace(/[^a-z0-9-_]/g, "-").replace(/^-+|-+$/g, "") || "my-app";
-  const features = normalizeFeatures(options.features);
-  let mode = options.mode === "dynamic" ? "dynamic" : "static";
+  const features = normalizeFeatures([...recipe?.features ?? [], ...options.features ?? []]);
+  let mode = options.mode === "dynamic" ? "dynamic" : options.mode === "static" ? "static" : recipe?.mode ?? "static";
   if (mode === "static" && features.some((f) => f.requiresBackend)) mode = "dynamic";
   return { name, template, features, mode };
 }
@@ -5256,6 +5257,13 @@ var faqSection = (ctx) => {
         </div>
       </section>`;
 };
+var RECIPES = [
+  { key: "ai-saas", label: "AI SaaS", description: "SaaS landing + accounts + payments + a streaming AI chat + analytics.", template: "saas", mode: "dynamic", features: ["auth-pages", "payments", "ai-chat", "analytics"] },
+  { key: "store", label: "Online store", description: "E-commerce storefront + eSewa/Khalti checkout + transactional email + analytics.", template: "ecommerce", mode: "dynamic", features: ["payments", "email", "analytics"] },
+  { key: "blog", label: "Blog", description: "A blog with a Markdown content section, RSS/llms.txt and instant search.", template: "blog", features: ["content", "search"] },
+  { key: "internal-tool", label: "Internal tool", description: "An admin dashboard with accounts (2FA), analytics and email \u2014 full-stack.", template: "dashboard", mode: "dynamic", features: ["auth-pages", "analytics", "email"] },
+  { key: "docs-ai", label: "AI docs", description: "A documentation site with chat-with-your-docs RAG and instant search.", template: "docs", features: ["rag", "search"] }
+];
 var contentLib = () => `import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter, markdownToHtml, excerpt } from "@lacspace/markdown";
@@ -7213,7 +7221,7 @@ function backendFiles(ctx) {
 }
 var splitList = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 function parseArgs(list) {
-  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false };
+  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false, dryRun: false };
   for (let i = 0; i < list.length; i++) {
     const arg = list[i];
     const next = () => list[++i] ?? "";
@@ -7221,8 +7229,9 @@ function parseArgs(list) {
     else if (arg === "-y" || arg === "--yes") a.yes = true;
     else if (arg === "--no-install") a.install = false;
     else if (arg === "--no-git") a.git = false;
+    else if (arg === "--dry-run" || arg === "--dry") a.dryRun = true;
     else if (arg === "--pm") a.pm = next();
-    else if (arg === "--theme" || arg === "--accent") a.theme = next();
+    else if (arg === "--theme" || arg === "--accent" || arg === "--brand") a.theme = next();
     else if (arg === "--with" || arg === "--features") a.features.push(...splitList(next()));
     else if (arg === "--fullstack" || arg === "--full-stack" || arg === "--dynamic") a.mode = "dynamic";
     else if (arg === "--static") a.mode = "static";
@@ -7232,10 +7241,13 @@ function parseArgs(list) {
     } else if (arg.startsWith("--mode=")) {
       const m = arg.slice(7).toLowerCase();
       a.mode = m === "dynamic" ? "dynamic" : "static";
-    } else if (arg === "-h" || arg === "--help") a.help = true;
+    } else if (arg === "--recipe") a.recipe = next();
+    else if (arg.startsWith("--recipe=")) a.recipe = arg.slice(9);
+    else if (arg === "-h" || arg === "--help") a.help = true;
     else if (arg.startsWith("--template=")) a.template = arg.slice(11);
     else if (arg.startsWith("--theme=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--accent=")) a.theme = arg.slice(9);
+    else if (arg.startsWith("--brand=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--with=")) a.features.push(...splitList(arg.slice(7)));
     else if (arg.startsWith("--features=")) a.features.push(...splitList(arg.slice(11)));
     else if (!arg.startsWith("-") && !a.name) a.name = arg;
@@ -7326,6 +7338,8 @@ ${c("bold", "Usage")}
   npm create lacspace-app@latest <name> [options]
   npx create-lacspace-app <name> --template <key>
   npx create-lacspace-app add <section...>   ${c("dim", "# grow an existing app")}
+  npx create-lacspace-app list                ${c("dim", "# templates, add-ons & recipes")}
+  npx create-lacspace-app explain <name>      ${c("dim", "# what an add-on/recipe gives you")}
 
 ${c("bold", "Templates")}
 ${TEMPLATES.map((t) => `  ${t.key.padEnd(10)} ${t.description}`).join("\n")}
@@ -7336,17 +7350,23 @@ ${c("bold", "Options")}
                          MongoDB/Redis backend (JWT auth + CRUD) + shared types
                          ${c("dim", "(alias --dynamic; default is --static, a single Next.js app)")}
   --with <a,b>           Feature add-ons, comma-separated (alias --features)
-  --theme <name|hex>     Accent: a preset, a "#hex", or "from,to" (e.g. --theme lacspace)
+  --recipe <key>         Start from a curated stack (${RECIPES.map((r) => r.key).join(" | ")})
+  --theme <name|hex>     Accent: a preset, a "#hex", or "from,to" (alias --brand)
   --pm <npm|pnpm|yarn|bun>  Package manager (default npm)
+  --dry-run              Print the files that would be created; write nothing
   --no-install           Skip installing dependencies
   --no-git               Skip git init
   -y, --yes              Accept defaults (needs <name>)
   -h, --help             Show this help
 
 ${c("bold", "Feature add-ons")} ${c("dim", "(--with) \u2014 free & keyless, local by default")}
-${FEATURES.map((f) => `  ${f.key.padEnd(10)} ${f.description}`).join("\n")}
+${FEATURES.map((f) => `  ${f.key.padEnd(11)} ${f.description}`).join("\n")}
   ${c("dim", "e.g. npx create-lacspace-app my-app --template saas --with ai-chat,rag")}
 
+${c("bold", "Recipes")} ${c("dim", "(--recipe) \u2014 a whole product in one command")}
+${RECIPES.map((r) => `  ${r.key.padEnd(14)} ${r.description}`).join("\n")}
+  ${c("dim", "e.g. npx create-lacspace-app my-app --recipe ai-saas")}
+
 ${c("bold", "Themes")} ${c("dim", "(--theme)")}
   ${Object.keys(THEMES).join(" \xB7 ")}
   ${c("dim", 'or a custom colour: --theme "#ff6a00"  \xB7  --theme "#0bb9d9,#7c3aed"')}
@@ -7709,12 +7729,103 @@ ${c("bold", "Use them")} \u2014 import into any page:
     return;
   }
 }
+function runList() {
+  process$1.stdout.write(`
+${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 what you can build")}
+`);
+  process$1.stdout.write(`
+${c("bold", "Templates")} ${c("dim", "(-t / --template)")}
+`);
+  for (const t of TEMPLATES) process$1.stdout.write(`  ${c("cyan", t.key.padEnd(12))} ${c("dim", t.description)}
+`);
+  process$1.stdout.write(`
+${c("bold", "Add-ons")} ${c("dim", "(--with) \u2014 free & keyless")}
+`);
+  for (const f of FEATURES) process$1.stdout.write(`  ${c("cyan", f.key.padEnd(12))} ${c("dim", f.description)}${f.requiresBackend ? c("green", "  [full-stack]") : ""}
+`);
+  process$1.stdout.write(`
+${c("bold", "Recipes")} ${c("dim", "(--recipe) \u2014 a whole product in one command")}
+`);
+  for (const r of RECIPES) process$1.stdout.write(`  ${c("cyan", r.key.padEnd(14))} ${c("dim", r.description)}
+`);
+  process$1.stdout.write(`
+  ${c("dim", "Learn one:")} ${c("cyan", "npx create-lacspace-app explain <name>")}
+
+`);
+}
+function runExplain(rawNames) {
+  const name = rawNames.find((n) => !n.startsWith("-"))?.toLowerCase();
+  if (!name) {
+    process$1.stdout.write(`Usage: ${c("cyan", "npx create-lacspace-app explain <template|add-on|recipe>")}
+
+`);
+    runList();
+    return;
+  }
+  const feat = FEATURES.find((f) => f.key === name);
+  const recipe = RECIPES.find((r) => r.key === name);
+  const tmpl = TEMPLATES.find((t) => t.key === name);
+  process$1.stdout.write("\n");
+  if (feat) {
+    process$1.stdout.write(`${c("bold", c("magenta", "add-on: " + feat.key))} ${feat.requiresBackend ? c("green", "[full-stack]") : c("dim", "[frontend]")}
+
+${feat.description}
+`);
+    const deps = { ...feat.deps, ...feat.backend?.({ name: "app", template: TEMPLATES[0], features: [], mode: "dynamic" })?.deps ?? {} };
+    if (Object.keys(deps).length) process$1.stdout.write(`
+${c("bold", "Packages")}: ${Object.keys(deps).map((d) => c("cyan", d)).join(", ")}
+`);
+    process$1.stdout.write(`
+${c("bold", "Next steps")}:
+`);
+    for (const s of feat.nextSteps) process$1.stdout.write(`  ${c("dim", "\u2022")} ${s}
+`);
+    if (feat.learn) process$1.stdout.write(`
+Learn more \u2192 ${c("cyan", feat.learn)}
+`);
+    process$1.stdout.write(`
+Add it: ${c("cyan", "npx create-lacspace-app my-app --with " + feat.key)}
+
+`);
+  } else if (recipe) {
+    process$1.stdout.write(`${c("bold", c("magenta", "recipe: " + recipe.key))}
+
+${recipe.description}
+
+${c("bold", "Template")}: ${c("cyan", recipe.template)}${recipe.mode ? c("dim", " \xB7 " + recipe.mode) : ""}
+${c("bold", "Add-ons")}: ${recipe.features.map((f) => c("cyan", f)).join(", ")}
+
+Use it: ${c("cyan", "npx create-lacspace-app my-app --recipe " + recipe.key)}
+
+`);
+  } else if (tmpl) {
+    process$1.stdout.write(`${c("bold", c("magenta", "template: " + tmpl.key))}
+
+${tmpl.description}
+
+Use it: ${c("cyan", "npx create-lacspace-app my-app --template " + tmpl.key)}
+
+`);
+  } else {
+    process$1.stdout.write(c("yellow", `Unknown "${name}".
+`));
+    runList();
+  }
+}
 async function main() {
   const raw = process$1.argv.slice(2);
   if (raw[0] === "add") {
     runAdd(raw.slice(1));
     return;
   }
+  if (raw[0] === "list" || raw[0] === "ls") {
+    runList();
+    return;
+  }
+  if (raw[0] === "explain" || raw[0] === "info") {
+    runExplain(raw.slice(1));
+    return;
+  }
   const args = parseArgs(raw);
   if (args.help) {
     process$1.stdout.write(HELP + "\n");
@@ -7723,15 +7834,42 @@ async function main() {
   process$1.stdout.write(`
 ${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 a gorgeous Next.js starter, batteries wired")}
 
+`);
+  const recipe = args.recipe ? RECIPES.find((r) => r.key === args.recipe.toLowerCase()) : void 0;
+  if (args.recipe && !recipe) process$1.stdout.write(c("yellow", `  ! Unknown recipe "${args.recipe}" \u2014 ignoring. Try: ${RECIPES.map((r) => r.key).join(", ")}
+`));
+  if (recipe) process$1.stdout.write(`  ${c("green", "\u2714")} Recipe ${c("cyan", recipe.key)} ${c("dim", "\u2014 " + recipe.description)}
 `);
   let name = args.name;
-  let templateKey = args.template;
-  let mode = args.mode ?? "static";
-  const featureKeys = [...args.features];
+  let templateKey = args.template ?? recipe?.template;
+  let mode = args.mode ?? recipe?.mode ?? "static";
+  const featureKeys = [...recipe?.features ?? [], ...args.features];
+  let usedRecipe = Boolean(recipe);
   if (!args.yes && process$1.stdin.isTTY) {
     const rl = promises.createInterface({ input: process$1.stdin, output: process$1.stdout });
     try {
       if (!name) name = (await rl.question(`${c("green", "?")} Project name ${c("dim", "(my-app)")}: `)).trim() || "my-app";
+      if (!usedRecipe && !templateKey && featureKeys.length === 0) {
+        process$1.stdout.write(`
+  Start from a recipe? ${c("dim", "(a template + add-ons, ready to go)")}
+`);
+        RECIPES.forEach((r, i) => process$1.stdout.write(`   ${c("cyan", String(i + 1))}. ${c("bold", r.label)} ${c("dim", "\u2014 " + r.description)}
+`));
+        process$1.stdout.write(`   ${c("cyan", "0")}. ${c("dim", "No recipe \u2014 I'll choose a template myself")}
+`);
+        const ans = (await rl.question(`
+${c("green", "?")} Recipe ${c("dim", "(0)")}: `)).trim() || "0";
+        const idx = /^\d+$/.test(ans) ? parseInt(ans, 10) - 1 : RECIPES.findIndex((r) => r.key === ans);
+        const chosen = ans === "0" ? void 0 : RECIPES[idx];
+        if (chosen) {
+          usedRecipe = true;
+          templateKey = chosen.template;
+          mode = chosen.mode ?? mode;
+          for (const k of chosen.features) if (!featureKeys.includes(k)) featureKeys.push(k);
+          process$1.stdout.write(`  ${c("green", "\u2714")} Recipe ${c("cyan", chosen.key)}
+`);
+        }
+      }
       if (!templateKey) {
         process$1.stdout.write(`
   Choose a template:
@@ -7743,7 +7881,7 @@ ${c("green", "?")} Template ${c("dim", "(1)")}: `)).trim() || "1";
         const idx = /^\d+$/.test(ans) ? parseInt(ans, 10) - 1 : TEMPLATES.findIndex((t) => t.key === ans);
         templateKey = TEMPLATES[idx]?.key ?? "personal";
       }
-      if (args.mode === void 0) {
+      if (args.mode === void 0 && !usedRecipe) {
         process$1.stdout.write(`
   What kind of app?
 `);
@@ -7796,7 +7934,25 @@ ${c("green", "?")} Add features? ${c("dim", "(comma-separated numbers, or Enter
     return;
   }
   const features = normalizeFeatures(featureKeys);
+  if (mode === "static" && features.some((f) => f.requiresBackend)) {
+    mode = "dynamic";
+    process$1.stdout.write(`  ${c("dim", "\u2191 a selected add-on needs a backend \u2014 building full-stack")}
+`);
+  }
   const files = buildFiles({ name: projectName, template, features, mode });
+  if (args.dryRun) {
+    const keys = Object.keys(files).sort();
+    process$1.stdout.write(`
+  ${c("bold", "Dry run")} ${c("dim", `\u2014 ${keys.length} files (${mode}${features.length ? ", +" + features.map((f) => f.key).join(",") : ""}), nothing written`)}
+`);
+    for (const rel of keys) process$1.stdout.write(`    ${c("dim", "+ " + rel)}
+`);
+    process$1.stdout.write(`
+  ${c("dim", "Remove --dry-run to create the project.")}
+
+`);
+    return;
+  }
   for (const [rel, content] of Object.entries(files)) {
     const full = path.join(dir, rel);
     fs.mkdirSync(path.dirname(full), { recursive: true });
@@ -7907,6 +8063,13 @@ function getFeature(key) {
   const f = FEATURES.find((x) => x.key === key);
   return f ? { ...f } : void 0;
 }
+function listRecipes() {
+  return RECIPES.map((r) => ({ ...r, features: [...r.features] }));
+}
+function getRecipe(key) {
+  const r = RECIPES.find((x) => x.key === key);
+  return r ? { ...r, features: [...r.features] } : void 0;
+}
 function generateProject(options = {}) {
   return buildFiles(resolveContext(options));
 }
@@ -7924,9 +8087,11 @@ async function scaffold(options = {}) {
 
 exports.generateProject = generateProject;
 exports.getFeature = getFeature;
+exports.getRecipe = getRecipe;
 exports.getSection = getSection;
 exports.getTemplate = getTemplate;
 exports.listFeatures = listFeatures;
+exports.listRecipes = listRecipes;
 exports.listSections = listSections;
 exports.listTemplates = listTemplates;
 exports.scaffold = scaffold;

package/dist/lib.d.cts

@@ -104,6 +104,28 @@ interface GenerateOptions {
      * changes.
      */
     mode?: "static" | "dynamic";
+    /**
+     * A one-shot **recipe** (see {@link RECIPES}) — a curated bundle of template +
+     * mode + feature add-ons for a whole kind of product, e.g. `"ai-saas"` or
+     * `"store"`. Explicit `template`/`features`/`mode` still win and are merged on
+     * top. Omit for no recipe.
+     */
+    recipe?: string;
+}
+/**
+ * A one-command **recipe**: a curated template + mode + add-on stack for a whole
+ * kind of product. `npx create-lacspace-app my-app --recipe ai-saas`.
+ */
+interface RecipeDef {
+    key: string;
+    label: string;
+    description: string;
+    /** The template this recipe starts from. */
+    template: string;
+    /** Force full-stack when the stack needs a backend (add-ons can also force it). */
+    mode?: "static" | "dynamic";
+    /** The add-ons this recipe layers on. */
+    features: string[];
 }
 
 /** A project file map: relative path → file contents. */
@@ -131,6 +153,13 @@ declare function getSection(name: string): string | undefined;
 declare function listFeatures(): FeatureDef[];
 /** Look up one feature add-on's definition by key, or `undefined`. */
 declare function getFeature(key: string): FeatureDef | undefined;
+/**
+ * The built-in one-shot recipes (see {@link RecipeDef}) — curated template + mode +
+ * add-on bundles you can pass as `options.recipe` or request with `--recipe <key>`.
+ */
+declare function listRecipes(): RecipeDef[];
+/** Look up one recipe's definition by key, or `undefined`. */
+declare function getRecipe(key: string): RecipeDef | undefined;
 /**
  * Generate a full project as an in-memory file map (relative path → contents).
  *
@@ -162,4 +191,4 @@ interface ScaffoldResult {
  */
 declare function scaffold(options?: ScaffoldOptions): Promise<ScaffoldResult>;
 
-export { type FeatureBackend, type FeatureDef, type FeatureRoute, type GenerateOptions, type ProjectFiles, type ScaffoldOptions, type ScaffoldResult, type TemplateDef, generateProject, getFeature, getSection, getTemplate, listFeatures, listSections, listTemplates, scaffold, templateKeys, templates };
+export { type FeatureBackend, type FeatureDef, type FeatureRoute, type GenerateOptions, type ProjectFiles, type RecipeDef, type ScaffoldOptions, type ScaffoldResult, type TemplateDef, generateProject, getFeature, getRecipe, getSection, getTemplate, listFeatures, listRecipes, listSections, listTemplates, scaffold, templateKeys, templates };

package/dist/lib.d.ts

@@ -104,6 +104,28 @@ interface GenerateOptions {
      * changes.
      */
     mode?: "static" | "dynamic";
+    /**
+     * A one-shot **recipe** (see {@link RECIPES}) — a curated bundle of template +
+     * mode + feature add-ons for a whole kind of product, e.g. `"ai-saas"` or
+     * `"store"`. Explicit `template`/`features`/`mode` still win and are merged on
+     * top. Omit for no recipe.
+     */
+    recipe?: string;
+}
+/**
+ * A one-command **recipe**: a curated template + mode + add-on stack for a whole
+ * kind of product. `npx create-lacspace-app my-app --recipe ai-saas`.
+ */
+interface RecipeDef {
+    key: string;
+    label: string;
+    description: string;
+    /** The template this recipe starts from. */
+    template: string;
+    /** Force full-stack when the stack needs a backend (add-ons can also force it). */
+    mode?: "static" | "dynamic";
+    /** The add-ons this recipe layers on. */
+    features: string[];
 }
 
 /** A project file map: relative path → file contents. */
@@ -131,6 +153,13 @@ declare function getSection(name: string): string | undefined;
 declare function listFeatures(): FeatureDef[];
 /** Look up one feature add-on's definition by key, or `undefined`. */
 declare function getFeature(key: string): FeatureDef | undefined;
+/**
+ * The built-in one-shot recipes (see {@link RecipeDef}) — curated template + mode +
+ * add-on bundles you can pass as `options.recipe` or request with `--recipe <key>`.
+ */
+declare function listRecipes(): RecipeDef[];
+/** Look up one recipe's definition by key, or `undefined`. */
+declare function getRecipe(key: string): RecipeDef | undefined;
 /**
  * Generate a full project as an in-memory file map (relative path → contents).
  *
@@ -162,4 +191,4 @@ interface ScaffoldResult {
  */
 declare function scaffold(options?: ScaffoldOptions): Promise<ScaffoldResult>;
 
-export { type FeatureBackend, type FeatureDef, type FeatureRoute, type GenerateOptions, type ProjectFiles, type ScaffoldOptions, type ScaffoldResult, type TemplateDef, generateProject, getFeature, getSection, getTemplate, listFeatures, listSections, listTemplates, scaffold, templateKeys, templates };
+export { type FeatureBackend, type FeatureDef, type FeatureRoute, type GenerateOptions, type ProjectFiles, type RecipeDef, type ScaffoldOptions, type ScaffoldResult, type TemplateDef, generateProject, getFeature, getRecipe, getSection, getTemplate, listFeatures, listRecipes, listSections, listTemplates, scaffold, templateKeys, templates };

package/dist/lib.js

@@ -30,14 +30,15 @@ var TEMPLATES = [
   { key: "marketplace", label: "Marketplace / commerce", description: "A real storefront wired to the Lacspace commerce packages \u2014 cart, checkout, tax, shipping, orders, invoices and Nepal payments.", accent: ["#0d9488", "#6366f1"], siteName: "LSBazaar", siteDescription: "A modern storefront \u2014 cart to checkout, wired end to end." }
 ];
 function resolveContext(options = {}) {
-  const base = TEMPLATES.find((t) => t.key === options.template) ?? TEMPLATES[0];
+  const recipe = options.recipe ? RECIPES.find((r) => r.key === String(options.recipe).toLowerCase()) : void 0;
+  const base = TEMPLATES.find((t) => t.key === (options.template ?? recipe?.template)) ?? TEMPLATES[0];
   const accent = resolveAccent(options.theme);
   const template = accent ? { ...base, accent } : base;
   const raw = options.name ?? "my-app";
   const seg = raw.split(/[\\/]/).filter(Boolean).pop() ?? "my-app";
   const name = seg.toLowerCase().replace(/[^a-z0-9-_]/g, "-").replace(/^-+|-+$/g, "") || "my-app";
-  const features = normalizeFeatures(options.features);
-  let mode = options.mode === "dynamic" ? "dynamic" : "static";
+  const features = normalizeFeatures([...recipe?.features ?? [], ...options.features ?? []]);
+  let mode = options.mode === "dynamic" ? "dynamic" : options.mode === "static" ? "static" : recipe?.mode ?? "static";
   if (mode === "static" && features.some((f) => f.requiresBackend)) mode = "dynamic";
   return { name, template, features, mode };
 }
@@ -5253,6 +5254,13 @@ var faqSection = (ctx) => {
         </div>
       </section>`;
 };
+var RECIPES = [
+  { key: "ai-saas", label: "AI SaaS", description: "SaaS landing + accounts + payments + a streaming AI chat + analytics.", template: "saas", mode: "dynamic", features: ["auth-pages", "payments", "ai-chat", "analytics"] },
+  { key: "store", label: "Online store", description: "E-commerce storefront + eSewa/Khalti checkout + transactional email + analytics.", template: "ecommerce", mode: "dynamic", features: ["payments", "email", "analytics"] },
+  { key: "blog", label: "Blog", description: "A blog with a Markdown content section, RSS/llms.txt and instant search.", template: "blog", features: ["content", "search"] },
+  { key: "internal-tool", label: "Internal tool", description: "An admin dashboard with accounts (2FA), analytics and email \u2014 full-stack.", template: "dashboard", mode: "dynamic", features: ["auth-pages", "analytics", "email"] },
+  { key: "docs-ai", label: "AI docs", description: "A documentation site with chat-with-your-docs RAG and instant search.", template: "docs", features: ["rag", "search"] }
+];
 var contentLib = () => `import fs from "node:fs";
 import path from "node:path";
 import { parseFrontmatter, markdownToHtml, excerpt } from "@lacspace/markdown";
@@ -7210,7 +7218,7 @@ function backendFiles(ctx) {
 }
 var splitList = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 function parseArgs(list) {
-  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false };
+  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false, dryRun: false };
   for (let i = 0; i < list.length; i++) {
     const arg = list[i];
     const next = () => list[++i] ?? "";
@@ -7218,8 +7226,9 @@ function parseArgs(list) {
     else if (arg === "-y" || arg === "--yes") a.yes = true;
     else if (arg === "--no-install") a.install = false;
     else if (arg === "--no-git") a.git = false;
+    else if (arg === "--dry-run" || arg === "--dry") a.dryRun = true;
     else if (arg === "--pm") a.pm = next();
-    else if (arg === "--theme" || arg === "--accent") a.theme = next();
+    else if (arg === "--theme" || arg === "--accent" || arg === "--brand") a.theme = next();
     else if (arg === "--with" || arg === "--features") a.features.push(...splitList(next()));
     else if (arg === "--fullstack" || arg === "--full-stack" || arg === "--dynamic") a.mode = "dynamic";
     else if (arg === "--static") a.mode = "static";
@@ -7229,10 +7238,13 @@ function parseArgs(list) {
     } else if (arg.startsWith("--mode=")) {
       const m = arg.slice(7).toLowerCase();
       a.mode = m === "dynamic" ? "dynamic" : "static";
-    } else if (arg === "-h" || arg === "--help") a.help = true;
+    } else if (arg === "--recipe") a.recipe = next();
+    else if (arg.startsWith("--recipe=")) a.recipe = arg.slice(9);
+    else if (arg === "-h" || arg === "--help") a.help = true;
     else if (arg.startsWith("--template=")) a.template = arg.slice(11);
     else if (arg.startsWith("--theme=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--accent=")) a.theme = arg.slice(9);
+    else if (arg.startsWith("--brand=")) a.theme = arg.slice(8);
     else if (arg.startsWith("--with=")) a.features.push(...splitList(arg.slice(7)));
     else if (arg.startsWith("--features=")) a.features.push(...splitList(arg.slice(11)));
     else if (!arg.startsWith("-") && !a.name) a.name = arg;
@@ -7323,6 +7335,8 @@ ${c("bold", "Usage")}
   npm create lacspace-app@latest <name> [options]
   npx create-lacspace-app <name> --template <key>
   npx create-lacspace-app add <section...>   ${c("dim", "# grow an existing app")}
+  npx create-lacspace-app list                ${c("dim", "# templates, add-ons & recipes")}
+  npx create-lacspace-app explain <name>      ${c("dim", "# what an add-on/recipe gives you")}
 
 ${c("bold", "Templates")}
 ${TEMPLATES.map((t) => `  ${t.key.padEnd(10)} ${t.description}`).join("\n")}
@@ -7333,17 +7347,23 @@ ${c("bold", "Options")}
                          MongoDB/Redis backend (JWT auth + CRUD) + shared types
                          ${c("dim", "(alias --dynamic; default is --static, a single Next.js app)")}
   --with <a,b>           Feature add-ons, comma-separated (alias --features)
-  --theme <name|hex>     Accent: a preset, a "#hex", or "from,to" (e.g. --theme lacspace)
+  --recipe <key>         Start from a curated stack (${RECIPES.map((r) => r.key).join(" | ")})
+  --theme <name|hex>     Accent: a preset, a "#hex", or "from,to" (alias --brand)
   --pm <npm|pnpm|yarn|bun>  Package manager (default npm)
+  --dry-run              Print the files that would be created; write nothing
   --no-install           Skip installing dependencies
   --no-git               Skip git init
   -y, --yes              Accept defaults (needs <name>)
   -h, --help             Show this help
 
 ${c("bold", "Feature add-ons")} ${c("dim", "(--with) \u2014 free & keyless, local by default")}
-${FEATURES.map((f) => `  ${f.key.padEnd(10)} ${f.description}`).join("\n")}
+${FEATURES.map((f) => `  ${f.key.padEnd(11)} ${f.description}`).join("\n")}
   ${c("dim", "e.g. npx create-lacspace-app my-app --template saas --with ai-chat,rag")}
 
+${c("bold", "Recipes")} ${c("dim", "(--recipe) \u2014 a whole product in one command")}
+${RECIPES.map((r) => `  ${r.key.padEnd(14)} ${r.description}`).join("\n")}
+  ${c("dim", "e.g. npx create-lacspace-app my-app --recipe ai-saas")}
+
 ${c("bold", "Themes")} ${c("dim", "(--theme)")}
   ${Object.keys(THEMES).join(" \xB7 ")}
   ${c("dim", 'or a custom colour: --theme "#ff6a00"  \xB7  --theme "#0bb9d9,#7c3aed"')}
@@ -7706,12 +7726,103 @@ ${c("bold", "Use them")} \u2014 import into any page:
     return;
   }
 }
+function runList() {
+  stdout.write(`
+${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 what you can build")}
+`);
+  stdout.write(`
+${c("bold", "Templates")} ${c("dim", "(-t / --template)")}
+`);
+  for (const t of TEMPLATES) stdout.write(`  ${c("cyan", t.key.padEnd(12))} ${c("dim", t.description)}
+`);
+  stdout.write(`
+${c("bold", "Add-ons")} ${c("dim", "(--with) \u2014 free & keyless")}
+`);
+  for (const f of FEATURES) stdout.write(`  ${c("cyan", f.key.padEnd(12))} ${c("dim", f.description)}${f.requiresBackend ? c("green", "  [full-stack]") : ""}
+`);
+  stdout.write(`
+${c("bold", "Recipes")} ${c("dim", "(--recipe) \u2014 a whole product in one command")}
+`);
+  for (const r of RECIPES) stdout.write(`  ${c("cyan", r.key.padEnd(14))} ${c("dim", r.description)}
+`);
+  stdout.write(`
+  ${c("dim", "Learn one:")} ${c("cyan", "npx create-lacspace-app explain <name>")}
+
+`);
+}
+function runExplain(rawNames) {
+  const name = rawNames.find((n) => !n.startsWith("-"))?.toLowerCase();
+  if (!name) {
+    stdout.write(`Usage: ${c("cyan", "npx create-lacspace-app explain <template|add-on|recipe>")}
+
+`);
+    runList();
+    return;
+  }
+  const feat = FEATURES.find((f) => f.key === name);
+  const recipe = RECIPES.find((r) => r.key === name);
+  const tmpl = TEMPLATES.find((t) => t.key === name);
+  stdout.write("\n");
+  if (feat) {
+    stdout.write(`${c("bold", c("magenta", "add-on: " + feat.key))} ${feat.requiresBackend ? c("green", "[full-stack]") : c("dim", "[frontend]")}
+
+${feat.description}
+`);
+    const deps = { ...feat.deps, ...feat.backend?.({ name: "app", template: TEMPLATES[0], features: [], mode: "dynamic" })?.deps ?? {} };
+    if (Object.keys(deps).length) stdout.write(`
+${c("bold", "Packages")}: ${Object.keys(deps).map((d) => c("cyan", d)).join(", ")}
+`);
+    stdout.write(`
+${c("bold", "Next steps")}:
+`);
+    for (const s of feat.nextSteps) stdout.write(`  ${c("dim", "\u2022")} ${s}
+`);
+    if (feat.learn) stdout.write(`
+Learn more \u2192 ${c("cyan", feat.learn)}
+`);
+    stdout.write(`
+Add it: ${c("cyan", "npx create-lacspace-app my-app --with " + feat.key)}
+
+`);
+  } else if (recipe) {
+    stdout.write(`${c("bold", c("magenta", "recipe: " + recipe.key))}
+
+${recipe.description}
+
+${c("bold", "Template")}: ${c("cyan", recipe.template)}${recipe.mode ? c("dim", " \xB7 " + recipe.mode) : ""}
+${c("bold", "Add-ons")}: ${recipe.features.map((f) => c("cyan", f)).join(", ")}
+
+Use it: ${c("cyan", "npx create-lacspace-app my-app --recipe " + recipe.key)}
+
+`);
+  } else if (tmpl) {
+    stdout.write(`${c("bold", c("magenta", "template: " + tmpl.key))}
+
+${tmpl.description}
+
+Use it: ${c("cyan", "npx create-lacspace-app my-app --template " + tmpl.key)}
+
+`);
+  } else {
+    stdout.write(c("yellow", `Unknown "${name}".
+`));
+    runList();
+  }
+}
 async function main() {
   const raw = argv.slice(2);
   if (raw[0] === "add") {
     runAdd(raw.slice(1));
     return;
   }
+  if (raw[0] === "list" || raw[0] === "ls") {
+    runList();
+    return;
+  }
+  if (raw[0] === "explain" || raw[0] === "info") {
+    runExplain(raw.slice(1));
+    return;
+  }
   const args = parseArgs(raw);
   if (args.help) {
     stdout.write(HELP + "\n");
@@ -7720,15 +7831,42 @@ async function main() {
   stdout.write(`
 ${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 a gorgeous Next.js starter, batteries wired")}
 
+`);
+  const recipe = args.recipe ? RECIPES.find((r) => r.key === args.recipe.toLowerCase()) : void 0;
+  if (args.recipe && !recipe) stdout.write(c("yellow", `  ! Unknown recipe "${args.recipe}" \u2014 ignoring. Try: ${RECIPES.map((r) => r.key).join(", ")}
+`));
+  if (recipe) stdout.write(`  ${c("green", "\u2714")} Recipe ${c("cyan", recipe.key)} ${c("dim", "\u2014 " + recipe.description)}
 `);
   let name = args.name;
-  let templateKey = args.template;
-  let mode = args.mode ?? "static";
-  const featureKeys = [...args.features];
+  let templateKey = args.template ?? recipe?.template;
+  let mode = args.mode ?? recipe?.mode ?? "static";
+  const featureKeys = [...recipe?.features ?? [], ...args.features];
+  let usedRecipe = Boolean(recipe);
   if (!args.yes && stdin.isTTY) {
     const rl = createInterface({ input: stdin, output: stdout });
     try {
       if (!name) name = (await rl.question(`${c("green", "?")} Project name ${c("dim", "(my-app)")}: `)).trim() || "my-app";
+      if (!usedRecipe && !templateKey && featureKeys.length === 0) {
+        stdout.write(`
+  Start from a recipe? ${c("dim", "(a template + add-ons, ready to go)")}
+`);
+        RECIPES.forEach((r, i) => stdout.write(`   ${c("cyan", String(i + 1))}. ${c("bold", r.label)} ${c("dim", "\u2014 " + r.description)}
+`));
+        stdout.write(`   ${c("cyan", "0")}. ${c("dim", "No recipe \u2014 I'll choose a template myself")}
+`);
+        const ans = (await rl.question(`
+${c("green", "?")} Recipe ${c("dim", "(0)")}: `)).trim() || "0";
+        const idx = /^\d+$/.test(ans) ? parseInt(ans, 10) - 1 : RECIPES.findIndex((r) => r.key === ans);
+        const chosen = ans === "0" ? void 0 : RECIPES[idx];
+        if (chosen) {
+          usedRecipe = true;
+          templateKey = chosen.template;
+          mode = chosen.mode ?? mode;
+          for (const k of chosen.features) if (!featureKeys.includes(k)) featureKeys.push(k);
+          stdout.write(`  ${c("green", "\u2714")} Recipe ${c("cyan", chosen.key)}
+`);
+        }
+      }
       if (!templateKey) {
         stdout.write(`
   Choose a template:
@@ -7740,7 +7878,7 @@ ${c("green", "?")} Template ${c("dim", "(1)")}: `)).trim() || "1";
         const idx = /^\d+$/.test(ans) ? parseInt(ans, 10) - 1 : TEMPLATES.findIndex((t) => t.key === ans);
         templateKey = TEMPLATES[idx]?.key ?? "personal";
       }
-      if (args.mode === void 0) {
+      if (args.mode === void 0 && !usedRecipe) {
         stdout.write(`
   What kind of app?
 `);
@@ -7793,7 +7931,25 @@ ${c("green", "?")} Add features? ${c("dim", "(comma-separated numbers, or Enter
     return;
   }
   const features = normalizeFeatures(featureKeys);
+  if (mode === "static" && features.some((f) => f.requiresBackend)) {
+    mode = "dynamic";
+    stdout.write(`  ${c("dim", "\u2191 a selected add-on needs a backend \u2014 building full-stack")}
+`);
+  }
   const files = buildFiles({ name: projectName, template, features, mode });
+  if (args.dryRun) {
+    const keys = Object.keys(files).sort();
+    stdout.write(`
+  ${c("bold", "Dry run")} ${c("dim", `\u2014 ${keys.length} files (${mode}${features.length ? ", +" + features.map((f) => f.key).join(",") : ""}), nothing written`)}
+`);
+    for (const rel of keys) stdout.write(`    ${c("dim", "+ " + rel)}
+`);
+    stdout.write(`
+  ${c("dim", "Remove --dry-run to create the project.")}
+
+`);
+    return;
+  }
   for (const [rel, content] of Object.entries(files)) {
     const full = join(dir, rel);
     mkdirSync(dirname(full), { recursive: true });
@@ -7904,6 +8060,13 @@ function getFeature(key) {
   const f = FEATURES.find((x) => x.key === key);
   return f ? { ...f } : void 0;
 }
+function listRecipes() {
+  return RECIPES.map((r) => ({ ...r, features: [...r.features] }));
+}
+function getRecipe(key) {
+  const r = RECIPES.find((x) => x.key === key);
+  return r ? { ...r, features: [...r.features] } : void 0;
+}
 function generateProject(options = {}) {
   return buildFiles(resolveContext(options));
 }
@@ -7919,4 +8082,4 @@ async function scaffold(options = {}) {
   return { dir: target, files: Object.keys(files) };
 }
 
-export { generateProject, getFeature, getSection, getTemplate, listFeatures, listSections, listTemplates, scaffold, templateKeys, templates };
+export { generateProject, getFeature, getRecipe, getSection, getTemplate, listFeatures, listRecipes, listSections, listTemplates, scaffold, templateKeys, templates };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lacspace-app",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "description": "Scaffold a beautiful, production-ready Next.js app from a Lacspace template — portfolio, business, e-commerce, SaaS, blog, docs, dashboard, restaurant or marketplace — pre-wired with SEO, security headers, sitemap and robots. Use it as a CLI (like create-next-app, but you start gorgeous) or import it as a library to generate projects programmatically.",
   "type": "module",
   "bin": {