create-lacspace-app 2.2.2 → 2.4.0

package/dist/lib.js

@@ -36,7 +36,25 @@ function resolveContext(options = {}) {
   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";
-  return { name, template };
+  const features = normalizeFeatures(options.features);
+  const mode = options.mode === "dynamic" ? "dynamic" : "static";
+  return { name, template, features, mode };
+}
+function normalizeFeatures(requested) {
+  if (!requested || requested.length === 0) return [];
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  const unknown = [];
+  for (const raw of requested) {
+    const key = String(raw).toLowerCase().trim();
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    const def = FEATURES.find((f) => f.key === key);
+    if (def) out.push(def);
+    else unknown.push(key);
+  }
+  if (unknown.length) console.warn(`create-lacspace-app: ignoring unknown feature(s): ${unknown.join(", ")}`);
+  return out;
 }
 var pkgJson = (ctx) => JSON.stringify({
   name: ctx.name,
@@ -1893,6 +1911,10 @@ Because posts are just Markdown files, you can:
 Check the [first post](/blog/welcome) for the full Markdown reference.
 `;
 function buildFiles(ctx) {
+  if (ctx.mode === "dynamic") return buildFullStack(ctx);
+  return buildApp(ctx);
+}
+function buildApp(ctx) {
   const isBlog = ctx.template.key === "blog";
   const isDocs = ctx.template.key === "docs";
   const files = {
@@ -1963,8 +1985,529 @@ function buildFiles(ctx) {
     files["content/docs/installation.md"] = sampleDocInstall();
     files["content/docs/writing-content.md"] = sampleDocWriting();
   }
+  applyFeatures(files, ctx);
   return files;
 }
+function applyFeatures(files, ctx) {
+  const features = ctx.features;
+  if (!features.length) return;
+  for (const feat of features) {
+    for (const [rel, content] of Object.entries(feat.files(ctx))) {
+      files[rel] = content;
+    }
+  }
+  const addDeps = {};
+  const addScripts = {};
+  for (const feat of features) {
+    Object.assign(addDeps, feat.deps);
+    if (feat.scripts) Object.assign(addScripts, feat.scripts);
+  }
+  if (files["package.json"]) {
+    const pkg = JSON.parse(files["package.json"]);
+    pkg.dependencies = { ...pkg.dependencies ?? {}, ...addDeps };
+    if (Object.keys(addScripts).length) pkg.scripts = { ...pkg.scripts ?? {}, ...addScripts };
+    files["package.json"] = JSON.stringify(pkg, null, 2) + "\n";
+  }
+  const existingEnv = new Set(
+    (files[".env.example"] ?? "").split("\n").map((l) => l.match(/^\s*#?\s*([A-Z0-9_]+)=/)?.[1]).filter(Boolean)
+  );
+  const envLines = [];
+  for (const feat of features) {
+    if (!feat.env || Object.keys(feat.env).length === 0) continue;
+    const fresh = Object.entries(feat.env).filter(([name]) => !existingEnv.has(name));
+    if (fresh.length === 0) continue;
+    envLines.push("", `# --- ${feat.label} (${feat.key}) ---`);
+    for (const [name, comment] of fresh) {
+      if (comment) envLines.push(`# ${comment}`);
+      envLines.push(`${name}=`);
+      existingEnv.add(name);
+    }
+  }
+  if (envLines.length) {
+    const base = files[".env.example"] ?? "";
+    files[".env.example"] = (base.endsWith("\n") || base === "" ? base : base + "\n") + envLines.join("\n") + "\n";
+  }
+  files["LEARN.md"] = learnMd(ctx, features);
+}
+function learnMd(ctx, features) {
+  const blocks = features.map((f) => {
+    const steps = f.nextSteps.map((s) => `- [ ] ${s}`).join("\n");
+    const learn = f.learn ? `
+
+Learn more \u2192 ${f.learn}` : "";
+    return `## ${f.label} \`(${f.key})\`
+
+${f.description}
+
+${steps}${learn}`;
+  }).join("\n\n");
+  return `# \u{1F9ED} Learn ${ctx.name}
+
+You scaffolded **${ctx.template.label}** with ${features.length} feature add-on${features.length === 1 ? "" : "s"}:
+${features.map((f) => `\`${f.key}\``).join(" \xB7 ")}.
+
+Work through the checklist below \u2014 each item is a real next step.
+
+${blocks}
+
+---
+
+Every add-on is built from zero-dependency \`@lacspace/*\` packages. Browse them all \u2192 https://lacspace.com/packages
+`;
+}
+var FEATURES = [
+  {
+    key: "ai-chat",
+    label: "AI chat",
+    description: "A streaming AI chat route + UI \u2014 free & local by default (Ollama), keyless.",
+    deps: {
+      "@lacspace/ai": "^1.1.0",
+      "@lacspace/prompt": "^1.1.0",
+      "@lacspace/stream": "^1.1.0",
+      "@lacspace/providers": "^1.0.0",
+      "@lacspace/memory": "^1.0.0",
+      "@lacspace/moderation": "^1.0.0"
+    },
+    env: {
+      LACSPACE_AI_PROVIDER: "Which provider preset to use (default: ollama \u2014 free & local, no key).",
+      LACSPACE_AI_BASE_URL: "Override the provider base URL (default Ollama: http://localhost:11434).",
+      LACSPACE_AI_MODEL: "Chat model id (default: llama3.2).",
+      LACSPACE_AI_API_KEY: "Only needed for a hosted provider \u2014 leave blank for local Ollama."
+    },
+    files: (ctx) => ({
+      "app/api/chat/route.ts": aiChatRoute(),
+      "app/chat/page.tsx": aiChatPage(ctx)
+    }),
+    nextSteps: [
+      "\u{1F193} Free local AI \u2014 install Ollama (https://ollama.com), then run `ollama pull llama3.2`.",
+      "Run `npm run dev` and open http://localhost:3000/chat.",
+      "Prefer a hosted model? Set LACSPACE_AI_* in .env (e.g. LACSPACE_AI_PROVIDER=groq + LACSPACE_AI_API_KEY=\u2026)."
+    ],
+    learn: "https://developer.lacspace.com/packages/ai"
+  },
+  {
+    key: "rag",
+    label: "RAG \u2014 chat with your docs",
+    description: "Index your markdown/text and answer grounded questions with cited sources. Keyless & local (Ollama).",
+    deps: {
+      "@lacspace/rag": "^1.0.0",
+      "@lacspace/embeddings": "^1.0.0",
+      "@lacspace/vector": "^1.0.0",
+      "@lacspace/chunk": "^1.1.0",
+      "@lacspace/rerank": "^1.0.0",
+      "@lacspace/providers": "^1.0.0",
+      "@lacspace/ai": "^1.1.0"
+    },
+    scripts: { "rag:index": "node scripts/index-content.mjs" },
+    env: {
+      LACSPACE_AI_PROVIDER: "Which provider preset to use (default: ollama \u2014 free & local, no key).",
+      LACSPACE_AI_BASE_URL: "Override the provider base URL (default Ollama: http://localhost:11434).",
+      LACSPACE_AI_MODEL: "Chat model id used to answer (default: llama3.2).",
+      LACSPACE_AI_API_KEY: "Only needed for a hosted provider \u2014 leave blank for local Ollama.",
+      LACSPACE_EMBED_MODEL: "Embedding model id (default: nomic-embed-text)."
+    },
+    files: (ctx) => ({
+      "content/welcome.md": ragSampleDoc(ctx),
+      "scripts/index-content.mjs": ragIndexScript(),
+      "app/api/ask/route.ts": ragAskRoute(),
+      "app/ask/page.tsx": ragAskPage(ctx)
+    }),
+    nextSteps: [
+      "\u{1F193} Free & local \u2014 install Ollama (https://ollama.com), then `ollama pull nomic-embed-text` and `ollama pull llama3.2`.",
+      "Add markdown/text files to content/, then run `npm run rag:index` to build .rag-index.json.",
+      "Run `npm run dev` and open http://localhost:3000/ask."
+    ],
+    learn: "https://developer.lacspace.com/packages/rag"
+  }
+];
+var aiChatRoute = (_ctx) => `import { resolveConfig } from "@lacspace/providers";
+import { stream } from "@lacspace/ai";
+import type { Message } from "@lacspace/ai";
+import { detectPromptInjection } from "@lacspace/moderation";
+import { toReadableStream } from "@lacspace/stream";
+
+// This route runs on Node (it talks to your local Ollama / a hosted LLM).
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function POST(req: Request) {
+  // 1. Read the conversation the <ChatUI/> sent us.
+  const { messages } = (await req.json()) as { messages: Message[] };
+
+  // 2. Guard the newest user turn against prompt-injection / jailbreak attempts.
+  //    Learn more \u2192 https://developer.lacspace.com/packages/moderation
+  const lastUser = [...messages].reverse().find((m) => m.role === "user");
+  const userText = typeof lastUser?.content === "string" ? lastUser.content : "";
+  const check = detectPromptInjection(userText);
+  if (check.flagged) {
+    return new Response(JSON.stringify({ error: "That message was blocked by the safety guard." }), {
+      status: 400,
+      headers: { "Content-Type": "application/json" },
+    });
+  }
+
+  // 3. Resolve provider config from env \u2014 KEYLESS by default (local Ollama).
+  //    Learn more \u2192 https://developer.lacspace.com/packages/providers
+  const cfg = resolveConfig(process.env.LACSPACE_AI_PROVIDER ?? "ollama", {
+    baseUrl: process.env.LACSPACE_AI_BASE_URL,        // default: http://localhost:11434
+    model: process.env.LACSPACE_AI_MODEL,             // default: llama3.2
+    apiKey: process.env.LACSPACE_AI_API_KEY,          // only for hosted providers
+  });
+
+  // Ollama speaks its own dialect but also exposes an OpenAI-compatible surface
+  // at /v1 \u2014 so we always call it (and any hosted provider) as "openai-compatible".
+  const baseUrl = cfg.apiStyle === "ollama" ? cfg.baseUrl.replace(/\\/+$/, "") + "/v1" : cfg.baseUrl;
+  const model = cfg.model ?? "llama3.2";
+
+  // 4. Stream the reply. @lacspace/ai yields unified {type:"text", delta} chunks;
+  //    we encode each token and hand the stream to the browser via @lacspace/stream.
+  //    Learn more \u2192 https://developer.lacspace.com/packages/ai
+  const encoder = new TextEncoder();
+  async function* tokens() {
+    for await (const chunk of stream({
+      provider: "openai-compatible",
+      baseUrl,
+      apiKey: cfg.apiKey,
+      model,
+      headers: cfg.headers,
+      messages,
+    })) {
+      if (chunk.type === "text") yield encoder.encode(chunk.delta);
+    }
+  }
+
+  // Learn more \u2192 https://developer.lacspace.com/packages/stream
+  return new Response(toReadableStream(tokens()), {
+    headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-cache" },
+  });
+}
+`;
+var aiChatPage = (ctx) => `"use client";
+
+import { useState, useRef, useEffect } from "react";
+
+interface Msg { role: "user" | "assistant"; content: string; }
+
+export default function ChatPage() {
+  const [messages, setMessages] = useState<Msg[]>([]);
+  const [input, setInput] = useState("");
+  const [busy, setBusy] = useState(false);
+  const scroller = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    scroller.current?.scrollTo({ top: scroller.current.scrollHeight, behavior: "smooth" });
+  }, [messages]);
+
+  async function send(e: React.FormEvent) {
+    e.preventDefault();
+    const text = input.trim();
+    if (!text || busy) return;
+    setInput("");
+    setBusy(true);
+
+    const next: Msg[] = [...messages, { role: "user", content: text }];
+    setMessages([...next, { role: "assistant", content: "" }]);
+
+    try {
+      const res = await fetch("/api/chat", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ messages: next }),
+      });
+      if (!res.ok || !res.body) throw new Error("The chat endpoint returned an error.");
+
+      // Read the streamed reply token-by-token and append it live.
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder();
+      let acc = "";
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        acc += decoder.decode(value, { stream: true });
+        setMessages([...next, { role: "assistant", content: acc }]);
+      }
+    } catch {
+      setMessages([...next, { role: "assistant", content: "\u26A0\uFE0F Couldn't reach the model. Is Ollama running? (ollama.com)" }]);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <section className="mx-auto flex min-h-[calc(100vh-4rem)] max-w-2xl flex-col px-6 py-10">
+      <header className="mb-6">
+        <p className="text-sm font-semibold uppercase tracking-widest gradient-text">AI \xB7 ${ctx.template.siteName}</p>
+        <h1 className="mt-2 text-3xl font-bold sm:text-4xl">Chat</h1>
+        <p className="mt-2 text-muted">Free &amp; local by default \u2014 powered by Ollama and the Lacspace AI Kit. No key required.</p>
+      </header>
+
+      <div ref={scroller} className="flex-1 space-y-4 overflow-y-auto rounded-2xl border border-hairline bg-surface p-4">
+        {messages.length === 0 && (
+          <p className="py-16 text-center text-muted">Ask me anything to get started.</p>
+        )}
+        {messages.map((m, i) => (
+          <div key={i} className={m.role === "user" ? "flex justify-end" : "flex justify-start"}>
+            <div className={
+              "max-w-[85%] whitespace-pre-wrap rounded-2xl px-4 py-2.5 text-sm leading-relaxed " +
+              (m.role === "user" ? "gradient-bg on-accent" : "border border-hairline bg-app")
+            }>
+              {m.content || (busy ? "\u2026" : "")}
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <form onSubmit={send} className="mt-4 flex gap-2">
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder="Type a message\u2026"
+          className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none focus:border-hairline"
+        />
+        <button
+          type="submit"
+          disabled={busy || !input.trim()}
+          className="rounded-xl gradient-bg on-accent px-5 py-3 text-sm font-semibold shimmer disabled:opacity-50"
+        >
+          {busy ? "\u2026" : "Send"}
+        </button>
+      </form>
+    </section>
+  );
+}
+`;
+var ragSampleDoc = (ctx) => `# Welcome to ${ctx.template.siteName}
+
+This markdown file lives in \`content/\`. Run \`npm run rag:index\` to chunk and embed
+everything under \`content/\` into a local vector index (\`.rag-index.json\`), then open
+\`/ask\` to ask grounded questions about it.
+
+## How this works
+
+- **Chunking** \u2014 \`@lacspace/chunk\` splits each document into overlapping passages.
+- **Embeddings** \u2014 \`@lacspace/embeddings\` turns each passage into a vector using a
+  local Ollama model (\`nomic-embed-text\`) \u2014 no API key needed.
+- **Retrieval** \u2014 \`@lacspace/vector\` + \`@lacspace/rag\` find the passages closest to
+  your question, and \`@lacspace/rerank\` re-orders them for relevance.
+- **Answering** \u2014 \`@lacspace/ai\` writes a grounded answer and cites its sources.
+
+## Tips
+
+Add your own \`.md\` or \`.txt\` files here, re-run \`npm run rag:index\`, and ask away.
+Everything runs on your machine \u2014 free, keyless and private.
+`;
+var ragIndexScript = (_ctx) => `// Build a local vector index from everything under content/.
+// Run: npm run rag:index   (needs Ollama: \`ollama pull nomic-embed-text\`)
+import { readdir, readFile, writeFile, stat } from "node:fs/promises";
+import { join, extname, relative } from "node:path";
+import { splitText } from "@lacspace/chunk";
+import { embed } from "@lacspace/embeddings";
+import { createVectorStore } from "@lacspace/vector";
+
+const ROOT = process.cwd();
+const CONTENT_DIR = join(ROOT, "content");
+const OUT = join(ROOT, ".rag-index.json");
+
+// Which files to index (add more extensions if you like).
+const EXTS = new Set([".md", ".markdown", ".txt", ".mdx"]);
+
+// Recursively collect readable files under content/.
+async function walk(dir) {
+  const out = [];
+  let entries = [];
+  try { entries = await readdir(dir, { withFileTypes: true }); }
+  catch { return out; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) out.push(...(await walk(full)));
+    else if (EXTS.has(extname(e.name).toLowerCase())) out.push(full);
+  }
+  return out;
+}
+
+async function main() {
+  const files = await walk(CONTENT_DIR);
+  if (files.length === 0) {
+    console.error("No content found. Add .md/.txt files under content/ and re-run.");
+    process.exit(1);
+  }
+
+  // 1. Chunk every document into overlapping passages via @lacspace/chunk.
+  const records = [];
+  for (const file of files) {
+    const raw = await readFile(file, "utf8");
+    const source = relative(CONTENT_DIR, file);
+    const chunks = splitText(raw, { chunkSize: 900, chunkOverlap: 150 });
+    chunks.forEach((chunk, i) => {
+      records.push({ id: \`\${source}#\${i}\`, text: chunk.text, source });
+    });
+  }
+
+  // 2. Embed all passages with a local Ollama model (keyless) via @lacspace/embeddings.
+  const model = process.env.LACSPACE_EMBED_MODEL ?? "nomic-embed-text";
+  const baseUrl = process.env.LACSPACE_AI_BASE_URL ?? "http://localhost:11434";
+  console.log(\`Embedding \${records.length} chunks with \${model}\u2026\`);
+  const vectors = await embed(records.map((r) => r.text), { provider: "ollama", model, baseUrl });
+
+  // 3. Store them in an in-memory vector store, then serialise to .rag-index.json.
+  const store = createVectorStore({ metric: "cosine" });
+  store.upsert(records.map((r, i) => ({ id: r.id, vector: vectors[i], text: r.text, metadata: { source: r.source } })));
+
+  await writeFile(OUT, JSON.stringify(store.toJSON()));
+  console.log(\`\u2713 Wrote \${OUT} (\${records.length} chunks from \${files.length} files).\`);
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });
+`;
+var ragAskRoute = (_ctx) => `import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fromJSON } from "@lacspace/vector";
+import { createEmbedder } from "@lacspace/embeddings";
+import { createRag } from "@lacspace/rag";
+import { rerank } from "@lacspace/rerank";
+import { resolveConfig } from "@lacspace/providers";
+import { chat } from "@lacspace/ai";
+import type { Message } from "@lacspace/ai";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function POST(req: Request) {
+  const { question } = (await req.json()) as { question: string };
+  if (!question || !question.trim()) {
+    return Response.json({ error: "Ask a question." }, { status: 400 });
+  }
+
+  // 1. Load the local index built by \`npm run rag:index\`.
+  let store;
+  try {
+    const raw = await readFile(join(process.cwd(), ".rag-index.json"), "utf8");
+    store = fromJSON(JSON.parse(raw));
+  } catch {
+    return Response.json({ error: "No index found. Run \`npm run rag:index\` first." }, { status: 503 });
+  }
+
+  // 2. Config \u2014 keyless local Ollama by default.
+  //    Learn more \u2192 https://developer.lacspace.com/packages/providers
+  const cfg = resolveConfig(process.env.LACSPACE_AI_PROVIDER ?? "ollama", {
+    baseUrl: process.env.LACSPACE_AI_BASE_URL,
+    model: process.env.LACSPACE_AI_MODEL,
+    apiKey: process.env.LACSPACE_AI_API_KEY,
+  });
+  const embedModel = process.env.LACSPACE_EMBED_MODEL ?? "nomic-embed-text";
+  const embedBaseUrl = cfg.apiStyle === "ollama" ? cfg.baseUrl : (process.env.LACSPACE_AI_BASE_URL ?? "http://localhost:11434");
+
+  // 3. Retrieve the closest passages via @lacspace/rag + @lacspace/embeddings.
+  //    Learn more \u2192 https://developer.lacspace.com/packages/rag
+  const embedder = createEmbedder({ provider: "ollama", model: embedModel, baseUrl: embedBaseUrl });
+  const rag = createRag({ embed: embedder, store });
+  const hits = await rag.retrieve(question, { k: 8 });
+
+  // 4. Re-rank for relevance and keep the best few. @lacspace/rerank blends the
+  //    vector score with a lexical match \u2014 no second model call needed.
+  //    Learn more \u2192 https://developer.lacspace.com/packages/rerank
+  const ranked = await rerank(question, hits.map((h) => ({ id: h.id, text: h.text, score: h.score })), { k: 4 });
+
+  // 5. Build a grounded prompt and answer with @lacspace/ai.
+  //    Learn more \u2192 https://developer.lacspace.com/packages/ai
+  const context = ranked.map((d, i) => \`[\${i + 1}] \${d.text}\`).join("\\n\\n");
+  const messages: Message[] = [
+    { role: "system", content: "You answer strictly from the provided context. If the answer isn't there, say you don't know. Cite sources as [n]." },
+    { role: "user", content: \`Context:\\n\${context}\\n\\nQuestion: \${question}\` },
+  ];
+
+  const baseUrl = cfg.apiStyle === "ollama" ? cfg.baseUrl.replace(/\\/+$/, "") + "/v1" : cfg.baseUrl;
+  const res = await chat({
+    provider: "openai-compatible",
+    baseUrl,
+    apiKey: cfg.apiKey,
+    model: cfg.model ?? "llama3.2",
+    headers: cfg.headers,
+    messages,
+  });
+
+  const sources = ranked.map((d, i) => ({ n: i + 1, id: d.id }));
+  return Response.json({ answer: res.text, sources });
+}
+`;
+var ragAskPage = (ctx) => `"use client";
+
+import { useState } from "react";
+
+interface Source { n: number; id: string; }
+
+export default function AskPage() {
+  const [question, setQuestion] = useState("");
+  const [answer, setAnswer] = useState("");
+  const [sources, setSources] = useState<Source[]>([]);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+
+  async function ask(e: React.FormEvent) {
+    e.preventDefault();
+    const q = question.trim();
+    if (!q || busy) return;
+    setBusy(true); setError(""); setAnswer(""); setSources([]);
+    try {
+      const res = await fetch("/api/ask", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ question: q }),
+      });
+      const data = await res.json();
+      if (!res.ok) throw new Error(data.error || "Something went wrong.");
+      setAnswer(data.answer);
+      setSources(data.sources ?? []);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Something went wrong.");
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <section className="mx-auto max-w-2xl px-6 py-16">
+      <p className="text-sm font-semibold uppercase tracking-widest gradient-text">RAG \xB7 ${ctx.template.siteName}</p>
+      <h1 className="mt-2 text-3xl font-bold sm:text-4xl">Ask your content</h1>
+      <p className="mt-2 text-muted">Grounded answers from your own docs \u2014 indexed and answered locally. Run <code className="rounded bg-panel px-1.5 py-0.5 text-sm">npm run rag:index</code> first.</p>
+
+      <form onSubmit={ask} className="mt-8 flex gap-2">
+        <input
+          value={question}
+          onChange={(e) => setQuestion(e.target.value)}
+          placeholder="What is this project about?"
+          className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none focus:border-hairline"
+        />
+        <button
+          type="submit"
+          disabled={busy || !question.trim()}
+          className="rounded-xl gradient-bg on-accent px-5 py-3 text-sm font-semibold shimmer disabled:opacity-50"
+        >
+          {busy ? "\u2026" : "Ask"}
+        </button>
+      </form>
+
+      {error && <p className="mt-6 rounded-xl border border-red-400/40 bg-red-400/10 px-4 py-3 text-sm text-red-400">{error}</p>}
+
+      {answer && (
+        <div className="mt-8 card p-6">
+          <p className="whitespace-pre-wrap leading-relaxed">{answer}</p>
+          {sources.length > 0 && (
+            <div className="mt-5 border-t border-hairline pt-4">
+              <p className="text-xs font-semibold uppercase tracking-widest text-muted">Sources</p>
+              <ul className="mt-2 space-y-1 text-sm text-muted">
+                {sources.map((s) => (
+                  <li key={s.n}>[{s.n}] <code className="text-fg">{s.id}</code></li>
+                ))}
+              </ul>
+            </div>
+          )}
+        </div>
+      )}
+    </section>
+  );
+}
+`;
 function pagesFor(ctx) {
   const k = ctx.template.key;
   if (k === "dashboard") {
@@ -4553,8 +5096,921 @@ var faqSection = (ctx) => {
         </div>
       </section>`;
 };
+var scope = (ctx) => `@${ctx.name}`;
+var typesPkgJson = (ctx) => JSON.stringify({
+  name: `${scope(ctx)}/types`,
+  version: "0.1.0",
+  private: true,
+  // Type-only package: it ships a single .d.ts (no runtime code, nothing to build).
+  types: "./index.d.ts",
+  exports: { ".": { types: "./index.d.ts" } }
+}, null, 2) + "\n";
+var sharedTypes = () => `// Shared API contract \u2014 imported by BOTH the frontend and the backend, so the two
+// can never drift. These are TYPE-ONLY (no runtime code), so importing them adds
+// nothing to either bundle. Edit here once; both sides update. Use \`import type\`.
+
+/** A user, as returned by the API (no password; dates are ISO strings). */
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  createdAt: string;
+}
+
+/** The response from POST /auth/register and POST /auth/login. */
+export interface AuthResponse {
+  token: string;
+  user: User;
+}
+
+/** The shape of an error response from the API. */
+export interface ApiError {
+  error: string;
+  fields?: Record<string, string>;
+}
+
+/** The example CRUD resource. Rename "Note" to your real domain object. */
+export interface Note {
+  id: string;
+  title: string;
+  body: string;
+  userId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateNoteInput {
+  title: string;
+  body?: string;
+}
+
+export interface UpdateNoteInput {
+  title?: string;
+  body?: string;
+}
+`;
+var rootPkgJson = (ctx) => JSON.stringify({
+  name: ctx.name,
+  version: "0.1.0",
+  private: true,
+  workspaces: ["types", "backend", "frontend"],
+  scripts: {
+    // Run the API and the frontend together (concurrently), colourised + kill-all.
+    dev: 'concurrently -k -n api,web -c blue,magenta "npm:dev:api" "npm:dev:web"',
+    "dev:api": `npm run dev --workspace ${scope(ctx)}/backend`,
+    "dev:web": `npm run dev --workspace ${scope(ctx)}/frontend`,
+    build: `npm run build --workspace ${scope(ctx)}/backend && npm run build --workspace ${scope(ctx)}/frontend`,
+    start: 'concurrently -k -n api,web -c blue,magenta "npm:start:api" "npm:start:web"',
+    "start:api": `npm run start --workspace ${scope(ctx)}/backend`,
+    "start:web": `npm run start --workspace ${scope(ctx)}/frontend`,
+    typecheck: `npm run typecheck --workspace ${scope(ctx)}/backend`
+  },
+  devDependencies: { concurrently: "^9.1.0" },
+  engines: { node: ">=18" }
+}, null, 2) + "\n";
+var dockerCompose = (ctx) => `# Local infrastructure for ${ctx.name}. Start it with:  docker compose up -d
+# Optional \u2014 the API also runs with NO Redis, and against any MongoDB (e.g. Atlas).
+services:
+  mongo:
+    image: mongo:7
+    restart: unless-stopped
+    ports:
+      - "27017:27017"
+    volumes:
+      - mongo-data:/data/db
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    ports:
+      - "6379:6379"
+
+volumes:
+  mongo-data:
+`;
+var rootGitignore = () => `node_modules
+.env
+.env.local
+*.log
+.DS_Store
+dist
+.next
+`;
+var rootEnvExample = (ctx) => `# ${ctx.name} \u2014 ONE .env for the whole monorepo.  Copy it:  cp .env.example .env
+# The defaults below let the app run locally with zero changes.
+
+# --- Backend ---
+NODE_ENV=development
+PORT=4000
+
+# MongoDB. With Docker (docker compose up -d) the default just works. Or paste a
+# free MongoDB Atlas connection string here.
+MONGODB_URI=mongodb://localhost:27017/${ctx.name}
+
+# Signs JWTs. In production generate a strong value:  openssl rand -hex 32
+JWT_SECRET=dev-secret-change-me
+
+# Redis is OPTIONAL \u2014 leave empty to use the in-memory cache fallback.
+# With Docker, set it to:  redis://localhost:6379
+REDIS_URL=
+
+# Who may call the API (the frontend origin). Comma-separate for multiple.
+CORS_ORIGIN=http://localhost:3000
+
+# --- Frontend ---
+# Where the browser calls the API. Unset = http://localhost:4000 (local default).
+# NEXT_PUBLIC_API_URL=http://localhost:4000
+`;
+var rootReadme = (ctx) => `# ${ctx.name}
+
+A full-stack app scaffolded with [create-lacspace-app](https://www.npmjs.com/package/create-lacspace-app) \u2014 a **${ctx.template.label}** frontend + a real backend, wired together.
+
+\`\`\`
+${ctx.name}/
+\u251C\u2500 frontend/   Next.js 15 app (your UI) \u2014 talks to the API
+\u251C\u2500 backend/    Node \xB7 Express \xB7 MongoDB \xB7 Redis \xB7 TypeScript API
+\u251C\u2500 types/      Shared API types \u2014 imported by BOTH sides, so they can't drift
+\u2514\u2500 docker-compose.yml   Mongo + Redis for local dev (optional)
+\`\`\`
+
+## Quick start
+
+\`\`\`bash
+cp .env.example .env         # one env file for everything (sensible defaults)
+docker compose up -d         # optional: starts MongoDB + Redis locally
+npm install                  # installs all three workspaces at once
+npm run dev                  # runs the API (:4000) and the frontend (:3000) together
+\`\`\`
+
+Then open **http://localhost:3000** \u2192 visit **/register**, create an account, and you'll land on **/account** \u2014 a protected page that reads/writes the example "notes" resource through the API.
+
+**No Docker?** Point \`MONGODB_URI\` at any MongoDB (a free [Atlas](https://www.mongodb.com/atlas) cluster works). Redis is optional \u2014 leave \`REDIS_URL\` empty and the API uses an in-memory cache instead.
+
+## What's already built
+
+- **Auth** \u2014 \`POST /auth/register\`, \`POST /auth/login\` (JWT), \`GET /auth/me\`. Passwords hashed with \`@lacspace/password\`, tokens signed/verified with \`@lacspace/jwt\`.
+- **Example CRUD** \u2014 \`/notes\` (list \xB7 create \xB7 read \xB7 update \xB7 delete), protected, per-user, with a per-user cache (Redis or in-memory) that busts on writes.
+- **Validation** \u2014 request bodies validated with \`@lacspace/validate\`; failures return a clean 400.
+- **Rate limiting** \u2014 auth endpoints throttled with \`@lacspace/rate-limit\`.
+- **Typed env** \u2014 \`@lacspace/env\` fails fast at boot if config is wrong.
+
+Everything on the backend is built from zero-dependency \`@lacspace/*\` packages \u2192 https://lacspace.com/packages
+
+## Make it yours
+
+Rename the \`Note\` resource (in \`types/index.d.ts\`, \`backend/src/models/note.ts\`, \`backend/src/routes/notes.ts\`) to your real domain object, then follow the same pattern for more resources. The shared \`types/\` package keeps the frontend and backend in lock-step.
+`;
+var frontendApiClient = (ctx) => `import type { AuthResponse, User, Note, CreateNoteInput, ApiError } from "${scope(ctx)}/types";
+
+// how this works: a tiny typed fetch wrapper around the backend API. The response
+// shapes come from the shared "${scope(ctx)}/types" package \u2014 the SAME types the
+// backend uses \u2014 so the client and server can never disagree about the contract.
+const BASE = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:4000";
+const TOKEN_KEY = "${ctx.name}_token";
+
+export function getToken(): string | null {
+  if (typeof window === "undefined") return null;
+  try { return localStorage.getItem(TOKEN_KEY); } catch { return null; }
+}
+export function setToken(token: string | null): void {
+  if (typeof window === "undefined") return;
+  try { token ? localStorage.setItem(TOKEN_KEY, token) : localStorage.removeItem(TOKEN_KEY); } catch {}
+}
+
+async function request<T>(path: string, init?: RequestInit): Promise<T> {
+  const token = getToken();
+  const res = await fetch(\`\${BASE}\${path}\`, {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      ...(token ? { Authorization: \`Bearer \${token}\` } : {}),
+      ...(init?.headers ?? {}),
+    },
+  });
+  if (!res.ok) {
+    let message = "Request failed";
+    try { message = ((await res.json()) as ApiError).error ?? message; } catch {}
+    throw new Error(message);
+  }
+  if (res.status === 204) return undefined as T;
+  return (await res.json()) as T;
+}
+
+export const api = {
+  register: (input: { name: string; email: string; password: string }) =>
+    request<AuthResponse>("/auth/register", { method: "POST", body: JSON.stringify(input) }),
+  login: (input: { email: string; password: string }) =>
+    request<AuthResponse>("/auth/login", { method: "POST", body: JSON.stringify(input) }),
+  me: () => request<User>("/auth/me"),
+  listNotes: () => request<Note[]>("/notes"),
+  createNote: (input: CreateNoteInput) =>
+    request<Note>("/notes", { method: "POST", body: JSON.stringify(input) }),
+  deleteNote: (id: string) => request<void>(\`/notes/\${id}\`, { method: "DELETE" }),
+};
+`;
+var frontendLoginPage = () => `"use client";
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import Link from "next/link";
+import { api, setToken } from "@/lib/api";
+
+// how this works: posts to the backend /auth/login, stores the returned JWT, then
+// redirects to /account. Every request after this sends the token automatically.
+export default function LoginPage() {
+  const router = useRouter();
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true); setError(null);
+    try {
+      const { token } = await api.login({ email, password });
+      setToken(token);
+      router.push("/account");
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Something went wrong");
+    } finally { setBusy(false); }
+  }
+
+  return (
+    <main className="mx-auto flex min-h-[70vh] max-w-sm flex-col justify-center px-6">
+      <h1 className="text-2xl font-bold">Welcome back</h1>
+      <p className="mt-1 text-muted">Sign in to your account.</p>
+      <form onSubmit={onSubmit} className="mt-6 space-y-4">
+        <input value={email} onChange={(e) => setEmail(e.target.value)} type="email" required placeholder="you@example.com" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        <input value={password} onChange={(e) => setPassword(e.target.value)} type="password" required placeholder="Password" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        {error && <p className="text-sm text-red-400">{error}</p>}
+        <button disabled={busy} className="w-full rounded-full gradient-bg px-4 py-3 font-semibold on-accent transition hover:opacity-90 disabled:opacity-60">{busy ? "Signing in\u2026" : "Sign in"}</button>
+      </form>
+      <p className="mt-4 text-sm text-muted">No account? <Link href="/register" className="underline">Create one</Link></p>
+    </main>
+  );
+}
+`;
+var frontendRegisterPage = () => `"use client";
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import Link from "next/link";
+import { api, setToken } from "@/lib/api";
+
+// how this works: posts to /auth/register, stores the JWT, redirects to /account.
+export default function RegisterPage() {
+  const router = useRouter();
+  const [name, setName] = useState("");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function onSubmit(e: React.FormEvent) {
+    e.preventDefault();
+    setBusy(true); setError(null);
+    try {
+      const { token } = await api.register({ name, email, password });
+      setToken(token);
+      router.push("/account");
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Something went wrong");
+    } finally { setBusy(false); }
+  }
+
+  return (
+    <main className="mx-auto flex min-h-[70vh] max-w-sm flex-col justify-center px-6">
+      <h1 className="text-2xl font-bold">Create your account</h1>
+      <p className="mt-1 text-muted">It takes a few seconds.</p>
+      <form onSubmit={onSubmit} className="mt-6 space-y-4">
+        <input value={name} onChange={(e) => setName(e.target.value)} required placeholder="Your name" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        <input value={email} onChange={(e) => setEmail(e.target.value)} type="email" required placeholder="you@example.com" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        <input value={password} onChange={(e) => setPassword(e.target.value)} type="password" required minLength={8} placeholder="Password (min 8 chars)" className="w-full rounded-xl border border-hairline bg-surface px-4 py-3 outline-none" />
+        {error && <p className="text-sm text-red-400">{error}</p>}
+        <button disabled={busy} className="w-full rounded-full gradient-bg px-4 py-3 font-semibold on-accent transition hover:opacity-90 disabled:opacity-60">{busy ? "Creating\u2026" : "Create account"}</button>
+      </form>
+      <p className="mt-4 text-sm text-muted">Already have one? <Link href="/login" className="underline">Sign in</Link></p>
+    </main>
+  );
+}
+`;
+var frontendAccountPage = (ctx) => `"use client";
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { api, getToken, setToken } from "@/lib/api";
+import type { User, Note } from "${scope(ctx)}/types";
+
+// how this works: a PROTECTED page. On mount it calls /auth/me with the stored
+// token; if that fails it bounces to /login. Notes are the example CRUD resource.
+export default function AccountPage() {
+  const router = useRouter();
+  const [user, setUser] = useState<User | null>(null);
+  const [notes, setNotes] = useState<Note[]>([]);
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!getToken()) { router.push("/login"); return; }
+    (async () => {
+      try {
+        setUser(await api.me());
+        setNotes(await api.listNotes());
+      } catch { setToken(null); router.push("/login"); }
+    })();
+  }, [router]);
+
+  async function addNote(e: React.FormEvent) {
+    e.preventDefault();
+    setError(null);
+    try {
+      const note = await api.createNote({ title, body });
+      setNotes((prev) => [note, ...prev]);
+      setTitle(""); setBody("");
+    } catch (err) { setError(err instanceof Error ? err.message : "Failed to save"); }
+  }
+  async function remove(id: string) {
+    await api.deleteNote(id);
+    setNotes((prev) => prev.filter((n) => n.id !== id));
+  }
+  function signOut() { setToken(null); router.push("/login"); }
+
+  if (!user) return <main className="mx-auto max-w-2xl px-6 py-16 text-muted">Loading\u2026</main>;
+
+  return (
+    <main className="mx-auto max-w-2xl px-6 py-16">
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="text-2xl font-bold">Hi, {user.name}</h1>
+          <p className="text-muted">{user.email}</p>
+        </div>
+        <button onClick={signOut} className="rounded-full border border-hairline px-4 py-2 text-sm transition hover:bg-surface">Sign out</button>
+      </div>
+
+      <form onSubmit={addNote} className="mt-8 space-y-3 rounded-2xl border border-hairline bg-surface p-5">
+        <h2 className="font-semibold">Add a note</h2>
+        <input value={title} onChange={(e) => setTitle(e.target.value)} required placeholder="Title" className="w-full rounded-xl border border-hairline bg-app px-4 py-2 outline-none" />
+        <textarea value={body} onChange={(e) => setBody(e.target.value)} placeholder="Write something\u2026" rows={3} className="w-full rounded-xl border border-hairline bg-app px-4 py-2 outline-none" />
+        {error && <p className="text-sm text-red-400">{error}</p>}
+        <button className="rounded-full gradient-bg px-4 py-2 text-sm font-semibold on-accent">Save note</button>
+      </form>
+
+      <ul className="mt-6 space-y-3">
+        {notes.length === 0 && <li className="text-muted">No notes yet \u2014 add your first above.</li>}
+        {notes.map((n) => (
+          <li key={n.id} className="flex items-start justify-between rounded-2xl border border-hairline p-4">
+            <div>
+              <p className="font-medium">{n.title}</p>
+              {n.body && <p className="mt-1 text-sm text-muted">{n.body}</p>}
+            </div>
+            <button onClick={() => remove(n.id)} className="shrink-0 text-sm text-muted transition hover:text-red-400">Delete</button>
+          </li>
+        ))}
+      </ul>
+    </main>
+  );
+}
+`;
+function buildFullStack(ctx) {
+  const out = {};
+  const s = scope(ctx);
+  const app = buildApp(ctx);
+  for (const [rel, content] of Object.entries(app)) out[`frontend/${rel}`] = content;
+  const fpkg = JSON.parse(out["frontend/package.json"]);
+  fpkg.name = `${s}/frontend`;
+  fpkg.dependencies[`${s}/types`] = "*";
+  out["frontend/package.json"] = JSON.stringify(fpkg, null, 2) + "\n";
+  const fts = JSON.parse(out["frontend/tsconfig.json"]);
+  fts.compilerOptions.paths[`${s}/types`] = ["../types/index.d.ts"];
+  out["frontend/tsconfig.json"] = JSON.stringify(fts, null, 2) + "\n";
+  const fenv = out["frontend/.env.example"] ?? "";
+  out["frontend/.env.example"] = (fenv.endsWith("\n") || fenv === "" ? fenv : fenv + "\n") + "\n# The backend API base URL. Unset = http://localhost:4000 (local default).\n# NEXT_PUBLIC_API_URL=http://localhost:4000\n";
+  out["frontend/lib/api.ts"] = frontendApiClient(ctx);
+  out["frontend/app/login/page.tsx"] = frontendLoginPage();
+  out["frontend/app/register/page.tsx"] = frontendRegisterPage();
+  out["frontend/app/account/page.tsx"] = frontendAccountPage(ctx);
+  Object.assign(out, backendFiles(ctx));
+  out["types/package.json"] = typesPkgJson(ctx);
+  out["types/index.d.ts"] = sharedTypes();
+  out["package.json"] = rootPkgJson(ctx);
+  out["docker-compose.yml"] = dockerCompose(ctx);
+  out[".gitignore"] = rootGitignore();
+  out[".env.example"] = rootEnvExample(ctx);
+  out["README.md"] = rootReadme(ctx);
+  return out;
+}
+var backendPkgJson = (ctx) => JSON.stringify({
+  name: `${scope(ctx)}/backend`,
+  version: "0.1.0",
+  private: true,
+  type: "module",
+  main: "dist/index.js",
+  scripts: {
+    dev: "tsx watch src/index.ts",
+    build: "tsc -p tsconfig.json",
+    start: "node dist/index.js",
+    typecheck: "tsc -p tsconfig.json --noEmit"
+  },
+  dependencies: {
+    express: "^4.21.2",
+    cors: "^2.8.5",
+    mongoose: "^8.9.0",
+    ioredis: "^5.4.2",
+    dotenv: "^16.4.7",
+    // ✨ Backend built on zero-dep @lacspace/* packages instead of the usual grab-bag.
+    "@lacspace/env": "^1.1.0",
+    "@lacspace/jwt": "^1.4.0",
+    "@lacspace/password": "^1.1.0",
+    "@lacspace/validate": "^1.1.0",
+    "@lacspace/id": "^1.1.0",
+    "@lacspace/rate-limit": "^1.2.0",
+    "@lacspace/cache": "^1.1.0",
+    [`${scope(ctx)}/types`]: "*"
+  },
+  devDependencies: {
+    typescript: "^5.7.0",
+    tsx: "^4.19.2",
+    "@types/node": "^22.10.0",
+    "@types/express": "^4.17.21",
+    "@types/cors": "^2.8.17"
+  }
+}, null, 2) + "\n";
+var backendTsconfig = (ctx) => JSON.stringify({
+  compilerOptions: {
+    target: "ES2022",
+    module: "NodeNext",
+    moduleResolution: "NodeNext",
+    lib: ["ES2022"],
+    esModuleInterop: true,
+    allowSyntheticDefaultImports: true,
+    strict: true,
+    skipLibCheck: true,
+    resolveJsonModule: true,
+    outDir: "dist",
+    rootDir: "src",
+    sourceMap: true,
+    types: ["node"],
+    baseUrl: ".",
+    paths: { [`${scope(ctx)}/types`]: ["../types/index.d.ts"] }
+  },
+  include: ["src/**/*"],
+  exclude: ["node_modules", "dist"]
+}, null, 2) + "\n";
+var backendGitignore = () => `node_modules
+dist
+.env
+*.log
+`;
+var backendReadme = (ctx) => `# ${ctx.name} \u2014 API
+
+Node \xB7 Express \xB7 MongoDB \xB7 Redis (optional) \xB7 TypeScript. Built on zero-dependency \`@lacspace/*\` packages.
+
+Run it from the repo root with \`npm run dev\` (starts this API + the frontend). Standalone: \`npm run dev\` inside this folder.
+
+## Endpoints
+
+| Method | Path             | Auth | Description                    |
+|--------|------------------|------|--------------------------------|
+| GET    | \`/health\`        | \u2014    | Liveness check                 |
+| POST   | \`/auth/register\` | \u2014    | Create an account \u2192 JWT + user |
+| POST   | \`/auth/login\`    | \u2014    | Log in \u2192 JWT + user            |
+| GET    | \`/auth/me\`       | \u2713    | The current user               |
+| GET    | \`/notes\`         | \u2713    | List your notes (cached)       |
+| POST   | \`/notes\`         | \u2713    | Create a note                  |
+| GET    | \`/notes/:id\`     | \u2713    | Read one note                  |
+| PATCH  | \`/notes/:id\`     | \u2713    | Update a note                  |
+| DELETE | \`/notes/:id\`     | \u2713    | Delete a note                  |
+
+Send \`Authorization: Bearer <token>\` for the \u2713 routes (you get the token from register/login).
+
+## Layout
+
+\`\`\`
+src/
+\u251C\u2500 index.ts        boot: load env \u2192 connect Mongo \u2192 listen
+\u251C\u2500 load-env.ts     loads the root .env (imported first)
+\u251C\u2500 env.ts          typed, validated env (@lacspace/env)
+\u251C\u2500 app.ts          the Express app (CORS, routes, error handler)
+\u251C\u2500 db.ts           Mongoose connection
+\u251C\u2500 cache.ts        Redis, or an in-memory fallback (@lacspace/cache)
+\u251C\u2500 http.ts         HttpError + asyncHandler
+\u251C\u2500 validation.ts   request schemas (@lacspace/validate)
+\u251C\u2500 middleware/     auth (@lacspace/jwt) + error handling
+\u251C\u2500 models/         Mongoose models (User, Note)
+\u2514\u2500 routes/         auth + notes (the example CRUD resource)
+\`\`\`
+`;
+var backendLoadEnv = () => `import { config } from "dotenv";
+import { resolve } from "node:path";
+
+// how this works: the whole monorepo shares ONE .env at the repo root. When this
+// API runs via \`npm run dev\` its working directory is backend/, so the root .env
+// is one level up. This module is imported FIRST (before env.ts) so the variables
+// exist by the time anything reads them.
+config({ path: resolve(process.cwd(), "../.env") });
+config(); // also load backend/.env if you keep one (root values already set win)
+`;
+var backendEnv = (ctx) => `import { createEnv, str, port, oneOf } from "@lacspace/env";
+
+// how this works: fail-fast, TYPED environment variables (@lacspace/env). Bad or
+// missing values throw at boot with a clear message. Sensible dev defaults mean it
+// runs with zero config against a local MongoDB; set real values in the root .env.
+export const env = createEnv({
+  NODE_ENV: oneOf(["development", "production", "test"], { default: "development" }),
+  PORT: port({ default: 4000 }),
+  MONGODB_URI: str({ default: "mongodb://localhost:27017/${ctx.name}" }),
+  JWT_SECRET: str({ default: "dev-secret-change-me" }),
+  REDIS_URL: str({ optional: true }),
+  CORS_ORIGIN: str({ default: "http://localhost:3000" }),
+});
+
+if (env.NODE_ENV === "production" && env.JWT_SECRET === "dev-secret-change-me") {
+  throw new Error("Set a strong JWT_SECRET in production (see .env.example).");
+}
+`;
+var backendIndex = (ctx) => `import "./load-env.js"; // MUST be first: fills process.env before anything reads it
+import { env } from "./env.js";
+import { connectDb } from "./db.js";
+import { createApp } from "./app.js";
+
+// how this works: connect to MongoDB, build the Express app, then listen.
+async function main(): Promise<void> {
+  await connectDb(env.MONGODB_URI);
+  const app = createApp();
+  app.listen(env.PORT, () => {
+    console.log(\`\u{1F680} ${ctx.name} API ready on http://localhost:\${env.PORT}\`);
+  });
+}
+
+main().catch((err) => {
+  console.error("Failed to start the API:", err);
+  process.exit(1);
+});
+`;
+var backendDb = () => `import mongoose from "mongoose";
+
+// how this works: opens the Mongoose connection. Call once at boot.
+export async function connectDb(uri: string): Promise<void> {
+  mongoose.set("strictQuery", true);
+  await mongoose.connect(uri);
+  console.log("\u2714 MongoDB connected");
+}
+`;
+var backendCache = () => `import { createCache } from "@lacspace/cache";
+import { Redis } from "ioredis";
+import { env } from "./env.js";
+
+// how this works: one cache interface, TWO backends. If REDIS_URL is set we use
+// Redis; otherwise we fall back to @lacspace/cache (zero-dep, in-memory) so the app
+// runs with NO Redis at all. The rest of the code doesn't care which is active.
+export interface Cache {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+  del(key: string): Promise<void>;
+  readonly kind: "redis" | "memory";
+}
+
+function redisCache(url: string): Cache {
+  const client = new Redis(url, { maxRetriesPerRequest: 2 });
+  client.on("error", (e: Error) => console.warn("\u26A0 Redis error:", e.message));
+  return {
+    kind: "redis",
+    async get(key) { return client.get(key); },
+    async set(key, value, ttl) { if (ttl) await client.set(key, value, "EX", ttl); else await client.set(key, value); },
+    async del(key) { await client.del(key); },
+  };
+}
+
+function memoryCache(): Cache {
+  const mem = createCache<string>({ max: 5000 });
+  return {
+    kind: "memory",
+    async get(key) { return mem.get(key) ?? null; },
+    async set(key, value, ttl) { mem.set(key, value, ttl ? ttl * 1000 : undefined); },
+    async del(key) { mem.delete(key); },
+  };
+}
+
+export const cache: Cache = env.REDIS_URL ? redisCache(env.REDIS_URL) : memoryCache();
+console.log(\`\u2714 Cache: \${cache.kind}\${cache.kind === "memory" ? " (no REDIS_URL \u2014 in-memory fallback)" : ""}\`);
+`;
+var backendHttp = () => `import type { Request, Response, NextFunction, RequestHandler } from "express";
+
+/** A simple HTTP error with a status code \u2014 throw it from any handler. */
+export class HttpError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+    this.name = "HttpError";
+  }
+}
+
+// how this works: Express v4 doesn't catch rejected Promises from async handlers,
+// so wrap them \u2014 any thrown error is forwarded to the error middleware.
+export const asyncHandler =
+  (fn: (req: Request, res: Response, next: NextFunction) => Promise<unknown>): RequestHandler =>
+  (req, res, next) => { fn(req, res, next).catch(next); };
+`;
+var backendExpressTypes = () => `// Adds req.user (populated by requireAuth) to Express's Request type.
+import "express";
+
+declare global {
+  namespace Express {
+    interface Request {
+      user?: { sub: string; email: string; iat?: number; exp?: number; iss?: string };
+    }
+  }
+}
+
+export {};
+`;
+var backendErrorMw = () => `import type { Request, Response, NextFunction } from "express";
+import { ValidationError } from "@lacspace/validate";
+import { HttpError } from "../http.js";
+
+// how this works: ONE place that turns thrown errors into clean JSON responses.
+// Register it LAST (after all routes). Express identifies it by its 4 arguments.
+export function errorHandler(err: unknown, _req: Request, res: Response, _next: NextFunction): void {
+  if (err instanceof ValidationError) {
+    res.status(400).json({ error: "Validation failed", fields: err.flatten() });
+    return;
+  }
+  if (err instanceof HttpError) {
+    res.status(err.status).json({ error: err.message });
+    return;
+  }
+  console.error(err);
+  res.status(500).json({ error: "Internal server error" });
+}
+`;
+var backendAuthMw = (ctx) => `import type { RequestHandler } from "express";
+import { expressJwt } from "@lacspace/jwt";
+import { env } from "../env.js";
+
+// how this works: verifies the "Authorization: Bearer <token>" header with
+// @lacspace/jwt and attaches the decoded payload to req.user (see express.d.ts).
+// Missing/invalid token \u2192 it responds 401 automatically. Put it on any route you
+// want protected:  router.get("/secret", requireAuth, handler)
+// (@lacspace/jwt's middleware is framework-agnostic, so we cast it to Express's
+//  RequestHandler \u2014 it's a standard (req, res, next) function underneath.)
+export const requireAuth = expressJwt(env.JWT_SECRET, { issuer: "${ctx.name}-api" }) as unknown as RequestHandler;
+`;
+var backendUserModel = () => `import mongoose from "mongoose";
+import { uuidv7 } from "@lacspace/id";
+
+// how this works: the User fields. _id is a time-sortable UUID (@lacspace/id)
+// instead of an ObjectId, so ids are readable and orderable. We store only a
+// password HASH, never the raw password. (We DON'T extend mongoose.Document \u2014 that
+// would force _id to be an ObjectId; a plain interface lets _id be our string.)
+export interface UserDoc {
+  _id: string;
+  email: string;
+  name: string;
+  passwordHash: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const userSchema = new mongoose.Schema<UserDoc>(
+  {
+    _id: { type: String, default: () => uuidv7() },
+    email: { type: String, required: true, unique: true, lowercase: true, trim: true },
+    name: { type: String, required: true, trim: true },
+    passwordHash: { type: String, required: true },
+  },
+  { timestamps: true },
+);
+
+export const User =
+  (mongoose.models.User as mongoose.Model<UserDoc>) ?? mongoose.model<UserDoc>("User", userSchema);
+`;
+var backendNoteModel = () => `import mongoose from "mongoose";
+import { uuidv7 } from "@lacspace/id";
+
+// how this works: the example CRUD resource. Rename "Note" to your real domain
+// object (Task, Post, Product\u2026) and add fields \u2014 the routes follow the same shape.
+// (Plain interface, not mongoose.Document, so _id can be our string UUID.)
+export interface NoteDoc {
+  _id: string;
+  title: string;
+  body: string;
+  userId: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const noteSchema = new mongoose.Schema<NoteDoc>(
+  {
+    _id: { type: String, default: () => uuidv7() },
+    title: { type: String, required: true, trim: true },
+    body: { type: String, default: "" },
+    userId: { type: String, required: true, index: true },
+  },
+  { timestamps: true },
+);
+
+export const Note =
+  (mongoose.models.Note as mongoose.Model<NoteDoc>) ?? mongoose.model<NoteDoc>("Note", noteSchema);
+`;
+var backendValidation = () => `import { v, type Infer } from "@lacspace/validate";
+
+// how this works: Zod-like schemas (@lacspace/validate). .parse(body) throws a
+// ValidationError on bad input, which the error middleware turns into a clean 400
+// with per-field messages.
+export const RegisterInput = v.object({
+  name: v.string().min(2).max(80),
+  email: v.string().email(),
+  password: v.string().min(8).max(200),
+});
+
+export const LoginInput = v.object({
+  email: v.string().email(),
+  password: v.string().min(1),
+});
+
+export const NoteInput = v.object({
+  title: v.string().min(1).max(200),
+  body: v.string().max(10_000).default(""),
+});
+
+export type RegisterBody = Infer<typeof RegisterInput>;
+export type LoginBody = Infer<typeof LoginInput>;
+export type NoteBody = Infer<typeof NoteInput>;
+`;
+var backendAuthRoutes = (ctx) => `import express from "express";
+import { hash, verify as verifyPassword } from "@lacspace/password";
+import { sign } from "@lacspace/jwt";
+import { asyncHandler, HttpError } from "../http.js";
+import { requireAuth } from "../middleware/auth.js";
+import { User, type UserDoc } from "../models/user.js";
+import { env } from "../env.js";
+import { RegisterInput, LoginInput } from "../validation.js";
+import type { AuthResponse, User as UserDTO } from "${scope(ctx)}/types";
+
+const ISSUER = "${ctx.name}-api";
+const WEEK = 60 * 60 * 24 * 7; // token lifetime, in seconds
+const router = express.Router();
+
+function toDTO(u: UserDoc): UserDTO {
+  return { id: String(u._id), email: u.email, name: u.name, createdAt: u.createdAt.toISOString() };
+}
+function tokenFor(u: UserDoc): Promise<string> {
+  return sign({ sub: String(u._id), email: u.email }, env.JWT_SECRET, { expiresIn: WEEK, issuer: ISSUER });
+}
+
+// POST /auth/register \u2014 create an account, return a JWT + the user.
+router.post("/register", asyncHandler(async (req, res) => {
+  const { name, email, password } = RegisterInput.parse(req.body);
+  if (await User.findOne({ email })) throw new HttpError(409, "That email is already registered");
+  const passwordHash = await hash(password); // PBKDF2 via @lacspace/password
+  const user = await User.create({ name, email, passwordHash });
+  const out: AuthResponse = { token: await tokenFor(user), user: toDTO(user) };
+  res.status(201).json(out);
+}));
+
+// POST /auth/login \u2014 verify credentials, return a JWT + the user.
+router.post("/login", asyncHandler(async (req, res) => {
+  const { email, password } = LoginInput.parse(req.body);
+  const user = await User.findOne({ email });
+  if (!user || !(await verifyPassword(password, user.passwordHash))) {
+    throw new HttpError(401, "Invalid email or password");
+  }
+  const out: AuthResponse = { token: await tokenFor(user), user: toDTO(user) };
+  res.json(out);
+}));
+
+// GET /auth/me \u2014 the current user (requires a valid token).
+router.get("/me", requireAuth, asyncHandler(async (req, res) => {
+  const user = await User.findById(req.user!.sub);
+  if (!user) throw new HttpError(404, "User not found");
+  res.json(toDTO(user));
+}));
+
+export default router;
+`;
+var backendNoteRoutes = (ctx) => `import express from "express";
+import { asyncHandler, HttpError } from "../http.js";
+import { requireAuth } from "../middleware/auth.js";
+import { Note, type NoteDoc } from "../models/note.js";
+import { cache } from "../cache.js";
+import { NoteInput } from "../validation.js";
+import type { Note as NoteDTO } from "${scope(ctx)}/types";
+
+const router = express.Router();
+router.use(requireAuth); // every /notes route requires a valid token
+
+function toDTO(n: NoteDoc): NoteDTO {
+  return {
+    id: String(n._id),
+    title: n.title,
+    body: n.body,
+    userId: String(n.userId),
+    createdAt: n.createdAt.toISOString(),
+    updatedAt: n.updatedAt.toISOString(),
+  };
+}
+const listKey = (userId: string): string => \`notes:\${userId}\`;
+
+// GET /notes \u2014 this user's notes. Cached for 30s (Redis or in-memory); every write
+// below busts the cache, so reads are fast but never stale after a change.
+router.get("/", asyncHandler(async (req, res) => {
+  const userId = req.user!.sub;
+  const cached = await cache.get(listKey(userId));
+  if (cached) { res.json(JSON.parse(cached) as NoteDTO[]); return; }
+  const notes = await Note.find({ userId }).sort({ createdAt: -1 });
+  const dto = notes.map(toDTO);
+  await cache.set(listKey(userId), JSON.stringify(dto), 30);
+  res.json(dto);
+}));
+
+// POST /notes \u2014 create a note.
+router.post("/", asyncHandler(async (req, res) => {
+  const userId = req.user!.sub;
+  const { title, body } = NoteInput.parse(req.body);
+  const note = await Note.create({ title, body, userId });
+  await cache.del(listKey(userId));
+  res.status(201).json(toDTO(note));
+}));
+
+// GET /notes/:id \u2014 one note (only if it's yours).
+router.get("/:id", asyncHandler(async (req, res) => {
+  const note = await Note.findOne({ _id: req.params.id, userId: req.user!.sub });
+  if (!note) throw new HttpError(404, "Note not found");
+  res.json(toDTO(note));
+}));
+
+// PATCH /notes/:id \u2014 update a note.
+router.patch("/:id", asyncHandler(async (req, res) => {
+  const patch = NoteInput.partial().parse(req.body);
+  const note = await Note.findOneAndUpdate({ _id: req.params.id, userId: req.user!.sub }, { $set: patch }, { new: true });
+  if (!note) throw new HttpError(404, "Note not found");
+  await cache.del(listKey(req.user!.sub));
+  res.json(toDTO(note));
+}));
+
+// DELETE /notes/:id \u2014 delete a note.
+router.delete("/:id", asyncHandler(async (req, res) => {
+  const note = await Note.findOneAndDelete({ _id: req.params.id, userId: req.user!.sub });
+  if (!note) throw new HttpError(404, "Note not found");
+  await cache.del(listKey(req.user!.sub));
+  res.status(204).end();
+}));
+
+export default router;
+`;
+var backendApp = (ctx) => `import express from "express";
+import type { RequestHandler } from "express";
+import cors from "cors";
+import { rateLimit, expressRateLimit } from "@lacspace/rate-limit";
+import { env } from "./env.js";
+import { errorHandler } from "./middleware/error.js";
+import authRoutes from "./routes/auth.js";
+import noteRoutes from "./routes/notes.js";
+
+// how this works: assembles the Express app \u2014 CORS for the frontend, JSON parsing,
+// a health check, the auth + notes routers, then the error handler LAST.
+export function createApp(): express.Express {
+  const app = express();
+
+  app.use(cors({ origin: env.CORS_ORIGIN.split(",").map((o) => o.trim()), credentials: true }));
+  app.use(express.json());
+
+  // Brute-force protection on auth: 20 requests / minute / IP (@lacspace/rate-limit).
+  const authLimiter = expressRateLimit(rateLimit({ limit: 20, windowMs: 60_000 })) as unknown as RequestHandler;
+
+  app.get("/health", (_req, res) => { res.json({ ok: true, service: "${ctx.name}-api" }); });
+  app.use("/auth", authLimiter, authRoutes);
+  app.use("/notes", noteRoutes);
+
+  app.use(errorHandler);
+  return app;
+}
+`;
+function backendFiles(ctx) {
+  return {
+    "backend/package.json": backendPkgJson(ctx),
+    "backend/tsconfig.json": backendTsconfig(ctx),
+    "backend/.gitignore": backendGitignore(),
+    "backend/README.md": backendReadme(ctx),
+    "backend/src/index.ts": backendIndex(ctx),
+    "backend/src/load-env.ts": backendLoadEnv(),
+    "backend/src/env.ts": backendEnv(ctx),
+    "backend/src/db.ts": backendDb(),
+    "backend/src/cache.ts": backendCache(),
+    "backend/src/app.ts": backendApp(ctx),
+    "backend/src/http.ts": backendHttp(),
+    "backend/src/express.d.ts": backendExpressTypes(),
+    "backend/src/validation.ts": backendValidation(),
+    "backend/src/middleware/auth.ts": backendAuthMw(ctx),
+    "backend/src/middleware/error.ts": backendErrorMw(),
+    "backend/src/models/user.ts": backendUserModel(),
+    "backend/src/models/note.ts": backendNoteModel(),
+    "backend/src/routes/auth.ts": backendAuthRoutes(ctx),
+    "backend/src/routes/notes.ts": backendNoteRoutes(ctx)
+  };
+}
+var splitList = (s) => s.split(",").map((x) => x.trim()).filter(Boolean);
 function parseArgs(list) {
-  const a = { yes: false, install: true, git: true, pm: "npm", help: false };
+  const a = { features: [], yes: false, install: true, git: true, pm: "npm", help: false };
   for (let i = 0; i < list.length; i++) {
     const arg = list[i];
     const next = () => list[++i] ?? "";
@@ -4564,10 +6020,21 @@ function parseArgs(list) {
     else if (arg === "--no-git") a.git = false;
     else if (arg === "--pm") a.pm = next();
     else if (arg === "--theme" || arg === "--accent") a.theme = next();
-    else if (arg === "-h" || arg === "--help") a.help = true;
+    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";
+    else if (arg === "--mode") {
+      const m = next().toLowerCase();
+      a.mode = m === "dynamic" ? "dynamic" : "static";
+    } 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.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("--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;
   }
   return a;
@@ -4662,6 +6129,10 @@ ${TEMPLATES.map((t) => `  ${t.key.padEnd(10)} ${t.description}`).join("\n")}
 
 ${c("bold", "Options")}
   -t, --template <key>   Template (${TEMPLATES.map((t) => t.key).join(" | ")})
+  --fullstack            Full-stack monorepo: Next.js frontend + Node/Express/
+                         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)
   --pm <npm|pnpm|yarn|bun>  Package manager (default npm)
   --no-install           Skip installing dependencies
@@ -4669,13 +6140,18 @@ ${c("bold", "Options")}
   -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")}
+  ${c("dim", "e.g. npx create-lacspace-app my-app --template saas --with ai-chat,rag")}
+
 ${c("bold", "Themes")} ${c("dim", "(--theme)")}
   ${Object.keys(THEMES).join(" \xB7 ")}
   ${c("dim", 'or a custom colour: --theme "#ff6a00"  \xB7  --theme "#0bb9d9,#7c3aed"')}
 
-${c("bold", "Add sections to an existing app")}
-  npx create-lacspace-app add pricing faq testimonials
-  ${c("dim", "Drops prebuilt, themed sections into components/sections/ (and the UI kit if missing).")}
+${c("bold", "Grow an existing app")}
+  npx create-lacspace-app add pricing faq testimonials   ${c("dim", "# prebuilt sections")}
+  npx create-lacspace-app add ai-chat                    ${c("dim", "# a feature add-on")}
+  ${c("dim", "Drops themed sections / feature files into your project (and the UI kit if missing).")}
 `;
 var SECTIONS = {
   hero: `import Link from "next/link";
@@ -4915,7 +6391,7 @@ function ensureUiKit(root) {
 var pascal = (s) => s.split(/[-_]/).map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
 function runAdd(rawNames) {
   stdout.write(`
-${c("bold", c("magenta", "\u25C6 create-lacspace-app add"))} ${c("dim", "\u2014 drop prebuilt sections into your app")}
+${c("bold", c("magenta", "\u25C6 create-lacspace-app add"))} ${c("dim", "\u2014 drop prebuilt sections or a feature into your app")}
 
 `);
   const root = cwd();
@@ -4926,56 +6402,108 @@ ${c("bold", c("magenta", "\u25C6 create-lacspace-app add"))} ${c("dim", "\u2014
   }
   const wanted = rawNames.filter((n) => !n.startsWith("-")).map((n) => n.toLowerCase());
   if (wanted.length === 0 || rawNames.includes("--help") || rawNames.includes("-h")) {
-    stdout.write(`Usage: ${c("cyan", "npx create-lacspace-app add <section...>")}
+    stdout.write(`Usage: ${c("cyan", "npx create-lacspace-app add <section|feature...>")}
 
 ${c("bold", "Available sections")}
 `);
     stdout.write("  " + Object.keys(SECTIONS).map((k) => c("cyan", k)).join("  ") + "\n");
     stdout.write(`
-Example: ${c("cyan", "npx create-lacspace-app add pricing faq testimonials")}
+${c("bold", "Available features")}
+`);
+    stdout.write("  " + FEATURES.map((f) => c("cyan", f.key)).join("  ") + "\n");
+    stdout.write(`
+Example: ${c("cyan", "npx create-lacspace-app add pricing faq")}  ${c("dim", "or")}  ${c("cyan", "add ai-chat")}
 
 `);
     return;
   }
-  const unknown = wanted.filter((n) => !(n in SECTIONS));
+  const featKeys = wanted.filter((n) => FEATURES.some((f) => f.key === n));
+  const sectionNames = wanted.filter((n) => n in SECTIONS);
+  const unknown = wanted.filter((n) => !featKeys.includes(n) && !(n in SECTIONS));
   if (unknown.length) stdout.write(c("yellow", `! Unknown: ${unknown.join(", ")} ${c("dim", "(run with no args to list)")}
 `));
-  const toAdd = wanted.filter((n) => n in SECTIONS);
-  if (toAdd.length === 0) {
-    exit(1);
-    return;
-  }
-  const kitAdded = ensureUiKit(root);
-  if (kitAdded.length) stdout.write(`  ${c("green", "\u2714")} Added the UI kit ${c("dim", "(" + kitAdded.length + " components)")}
+  const addedFeatures = featKeys.map((k) => FEATURES.find((f) => f.key === k));
+  if (addedFeatures.length) {
+    const ctx = resolveContext({ name: basename(root), features: featKeys });
+    for (const feat of addedFeatures) {
+      stdout.write(`
+${c("bold", `+ ${feat.label}`)} ${c("dim", `(${feat.key})`)}
 `);
-  const created = [];
-  for (const name of toAdd) {
-    const rel = `components/sections/${name}.tsx`;
-    const full = join(root, rel);
-    if (existsSync(full)) {
-      stdout.write(c("yellow", `  ~ ${rel} exists \u2014 skipped
+      for (const [rel, content] of Object.entries(feat.files(ctx))) {
+        const full = join(root, rel);
+        if (existsSync(full)) {
+          stdout.write(c("yellow", `  ~ ${rel} exists \u2014 skipped
 `));
-      continue;
-    }
-    mkdirSync(dirname(full), { recursive: true });
-    writeFileSync(full, SECTIONS[name]);
-    created.push(name);
-    stdout.write(`  ${c("green", "\u2714")} ${c("dim", "+ " + rel)}
+          continue;
+        }
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, content);
+        stdout.write(`  ${c("green", "\u2714")} ${c("dim", "+ " + rel)}
+`);
+      }
+      stdout.write(`
+  ${c("bold", "Add these dependencies")}:
+    ${c("cyan", "npm i " + Object.entries(feat.deps).map(([n, v]) => `${n}@${v}`).join(" "))}
+`);
+      if (feat.scripts && Object.keys(feat.scripts).length) {
+        stdout.write(`
+  ${c("bold", "Add to package.json scripts")}:
+`);
+        for (const [n, v] of Object.entries(feat.scripts)) stdout.write(`    ${c("cyan", `"${n}": "${v}"`)}
 `);
+      }
+      if (feat.env && Object.keys(feat.env).length) {
+        stdout.write(`
+  ${c("bold", "Add to .env")}:
+`);
+        for (const [n, comment] of Object.entries(feat.env)) stdout.write(`    ${c("cyan", n + "=")}  ${c("dim", "# " + comment)}
+`);
+      }
+      stdout.write(`
+  ${c("bold", "Next steps")}:
+`);
+      for (const s of feat.nextSteps) stdout.write(`    ${c("dim", "\u2022")} ${s}
+`);
+    }
+    stdout.write("\n");
   }
-  if (created.length) {
-    stdout.write(`
+  if (sectionNames.length) {
+    const kitAdded = ensureUiKit(root);
+    if (kitAdded.length) stdout.write(`  ${c("green", "\u2714")} Added the UI kit ${c("dim", "(" + kitAdded.length + " components)")}
+`);
+    const created = [];
+    for (const name of sectionNames) {
+      const rel = `components/sections/${name}.tsx`;
+      const full = join(root, rel);
+      if (existsSync(full)) {
+        stdout.write(c("yellow", `  ~ ${rel} exists \u2014 skipped
+`));
+        continue;
+      }
+      mkdirSync(dirname(full), { recursive: true });
+      writeFileSync(full, SECTIONS[name]);
+      created.push(name);
+      stdout.write(`  ${c("green", "\u2714")} ${c("dim", "+ " + rel)}
+`);
+    }
+    if (created.length) {
+      stdout.write(`
 ${c("bold", "Use them")} \u2014 import into any page:
 `);
-    for (const n of created) stdout.write(`  ${c("cyan", `import { ${pascal(n)}Section } from "@/components/sections/${n}";`)}
+      for (const n of created) stdout.write(`  ${c("cyan", `import { ${pascal(n)}Section } from "@/components/sections/${n}";`)}
 `);
-    stdout.write(`
+      stdout.write(`
   Then drop ${c("cyan", "<" + pascal(created[0]) + "Section />")} into your JSX.
 `);
-    stdout.write(`
+      stdout.write(`
   ${c("dim", "Sections use the @lacspace UI kit + design tokens \u2014 best inside a create-lacspace-app project.")}
 
 `);
+    }
+  }
+  if (!addedFeatures.length && !sectionNames.length) {
+    exit(1);
+    return;
   }
 }
 async function main() {
@@ -4995,7 +6523,9 @@ ${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 a go
 `);
   let name = args.name;
   let templateKey = args.template;
-  if (!args.yes) {
+  let mode = args.mode ?? "static";
+  const featureKeys = [...args.features];
+  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";
@@ -5010,6 +6540,34 @@ ${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) {
+        stdout.write(`
+  What kind of app?
+`);
+        stdout.write(`   ${c("cyan", "1")}. ${c("bold", "Static / frontend only")} ${c("dim", "\u2014 a single Next.js app (SEO site, marketing, blog, docs). Fast, deploy anywhere.")}
+`);
+        stdout.write(`   ${c("cyan", "2")}. ${c("bold", "Dynamic / full-stack")} ${c("dim", "\u2014 frontend + a Node\xB7Express\xB7MongoDB\xB7Redis API with working auth & CRUD, wired together.")}
+`);
+        const ans = (await rl.question(`
+${c("green", "?")} Type ${c("dim", "(1)")}: `)).trim() || "1";
+        mode = ans === "2" || ans.toLowerCase().startsWith("dyn") || ans.toLowerCase().startsWith("full") ? "dynamic" : "static";
+      }
+      if (featureKeys.length === 0) {
+        stdout.write(`
+  Add feature add-ons? ${c("dim", "(free & keyless \u2014 local AI by default)")}
+`);
+        FEATURES.forEach((f, i) => stdout.write(`   ${c("cyan", String(i + 1))}. ${c("bold", f.label)} ${c("dim", "\u2014 " + f.description)}
+`));
+        const ans = (await rl.question(`
+${c("green", "?")} Add features? ${c("dim", "(comma-separated numbers, or Enter for none)")}: `)).trim();
+        if (ans) {
+          for (const tok of splitList(ans)) {
+            const idx = /^\d+$/.test(tok) ? parseInt(tok, 10) - 1 : FEATURES.findIndex((f) => f.key === tok);
+            const feat = FEATURES[idx];
+            if (feat && !featureKeys.includes(feat.key)) featureKeys.push(feat.key);
+          }
+        }
+      }
     } finally {
       rl.close();
     }
@@ -5034,14 +6592,18 @@ ${c("green", "?")} Template ${c("dim", "(1)")}: `)).trim() || "1";
     exit(1);
     return;
   }
-  const files = buildFiles({ name: projectName, template });
+  const features = normalizeFeatures(featureKeys);
+  const files = buildFiles({ name: projectName, template, features, mode });
   for (const [rel, content] of Object.entries(files)) {
     const full = join(dir, rel);
     mkdirSync(dirname(full), { recursive: true });
     writeFileSync(full, content);
   }
+  const shape = mode === "dynamic" ? " \xB7 full-stack" : "";
   stdout.write(`
-  ${c("green", "\u2714")} Created ${c("bold", name)} ${c("dim", `(${template.label})`)}
+  ${c("green", "\u2714")} Created ${c("bold", name)} ${c("dim", `(${template.label}${shape})`)}
+`);
+  if (features.length) stdout.write(`  ${c("green", "\u2714")} Feature add-ons: ${features.map((f) => c("cyan", f.key)).join(", ")}
 `);
   for (const rel of Object.keys(files)) stdout.write(`    ${c("dim", "+ " + rel)}
 `);
@@ -5069,11 +6631,40 @@ ${c("bold", "Done! Next steps")}
 `);
   if (!args.install) stdout.write(`  ${c("cyan", `${args.pm} install`)}
 `);
-  stdout.write(`  ${c("cyan", run)}
+  if (mode === "dynamic") {
+    stdout.write(`  ${c("cyan", "cp .env.example .env")} ${c("dim", "\u2014 then, optionally:")} ${c("cyan", "docker compose up -d")} ${c("dim", "(Mongo + Redis)")}
 `);
-  stdout.write(`
+    stdout.write(`  ${c("cyan", run)} ${c("dim", "\u2014 runs the API (:4000) and the frontend (:3000) together")}
+`);
+    stdout.write(`
+  ${c("dim", "backend \u2192")} ${c("cyan", "backend/src/")} ${c("dim", "(Express \xB7 MongoDB \xB7 Redis \xB7 JWT auth \xB7 example CRUD)")}
+`);
+    stdout.write(`  ${c("dim", "frontend \u2192")} ${c("cyan", "frontend/app/")} ${c("dim", "\xB7 shared API types \u2192")} ${c("cyan", "types/src/")}
+`);
+    stdout.write(`  ${c("dim", "No Docker? Point")} ${c("cyan", "MONGODB_URI")} ${c("dim", "at any MongoDB (e.g. free Atlas); Redis is optional.")}
+`);
+  } else {
+    stdout.write(`  ${c("cyan", run)}
+`);
+    stdout.write(`
   Edit ${c("cyan", "lib/site.ts")} (your SEO config) and ${c("cyan", "app/page.tsx")}.
 `);
+  }
+  if (features.length) {
+    const hasAi = features.some((f) => f.key === "ai-chat" || f.key === "rag");
+    stdout.write(`
+${c("bold", "Your feature add-ons")} ${c("dim", "\u2014 details in LEARN.md")}
+`);
+    if (hasAi) stdout.write(`  ${c("green", "\u{1F193} Free & local AI")} ${c("dim", "\u2014 install Ollama (https://ollama.com); no API key required.")}
+`);
+    for (const f of features) {
+      stdout.write(`
+  ${c("bold", f.label)} ${c("dim", `(${f.key})`)}
+`);
+      for (const s of f.nextSteps) stdout.write(`    ${c("dim", "\u2022")} ${s}
+`);
+    }
+  }
   stdout.write(`
   ${c("green", "Happy building!")} ${c("dim", "https://lacspace.com/packages")}
 
@@ -5106,6 +6697,13 @@ function listSections() {
 function getSection(name) {
   return SECTIONS[name];
 }
+function listFeatures() {
+  return FEATURES.map((f) => ({ ...f }));
+}
+function getFeature(key) {
+  const f = FEATURES.find((x) => x.key === key);
+  return f ? { ...f } : void 0;
+}
 function generateProject(options = {}) {
   return buildFiles(resolveContext(options));
 }
@@ -5121,4 +6719,4 @@ async function scaffold(options = {}) {
   return { dir: target, files: Object.keys(files) };
 }
 
-export { generateProject, getSection, getTemplate, listSections, listTemplates, scaffold, templateKeys, templates };
+export { generateProject, getFeature, getSection, getTemplate, listFeatures, listSections, listTemplates, scaffold, templateKeys, templates };