create-lacspace-app 2.2.1 → 2.3.0

package/dist/index.js

@@ -35,7 +35,24 @@ 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);
+  return { name, template, features };
+}
+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,
@@ -1962,8 +1979,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") {
@@ -4552,8 +5090,9 @@ var faqSection = (ctx) => {
         </div>
       </section>`;
 };
+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] ?? "";
@@ -4563,10 +5102,13 @@ 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 === "--with" || arg === "--features") a.features.push(...splitList(next()));
     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;
@@ -4661,6 +5203,7 @@ ${TEMPLATES.map((t) => `  ${t.key.padEnd(10)} ${t.description}`).join("\n")}
 
 ${c("bold", "Options")}
   -t, --template <key>   Template (${TEMPLATES.map((t) => t.key).join(" | ")})
+  --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
@@ -4668,13 +5211,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";
@@ -4914,7 +5462,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();
@@ -4925,56 +5473,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() {
@@ -4994,7 +5594,8 @@ ${c("bold", c("magenta", "\u25C6 create-lacspace-app"))} ${c("dim", "\u2014 a go
 `);
   let name = args.name;
   let templateKey = args.template;
-  if (!args.yes) {
+  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";
@@ -5009,6 +5610,22 @@ ${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 (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();
     }
@@ -5033,7 +5650,8 @@ ${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 });
   for (const [rel, content] of Object.entries(files)) {
     const full = join(dir, rel);
     mkdirSync(dirname(full), { recursive: true });
@@ -5041,6 +5659,8 @@ ${c("green", "?")} Template ${c("dim", "(1)")}: `)).trim() || "1";
   }
   stdout.write(`
   ${c("green", "\u2714")} Created ${c("bold", name)} ${c("dim", `(${template.label})`)}
+`);
+  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)}
 `);
@@ -5073,6 +5693,21 @@ ${c("bold", "Done! Next steps")}
   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")}
 
@@ -5089,4 +5724,4 @@ if (invokedAsCli) {
   });
 }
 
-export { SECTIONS, TEMPLATES, buildFiles, resolveContext };
+export { FEATURES, SECTIONS, TEMPLATES, applyFeatures, buildFiles, normalizeFeatures, resolveContext };