@guuey/create-agentic-app 0.9.0 → 0.10.0

package/README.md

@@ -7,9 +7,11 @@ MCP servers, and generative UI, in one workspace.
 npx @guuey/create-agentic-app my-agent
 cd my-agent
 pnpm install
-pnpm dev            # local: your agent + your MCP servers, hot reload
+pnpm bootstrap      # brand, theme, copy → guuey.app.json + AGENTS.md (local, no account)
+pnpm dev            # local: your agent + MCP servers + the web app, hot reload
 guuey login
 guuey deploy        # hosted: agent + MCP servers live on guuey
+pnpm bootstrap -- --link   # bind the deployed app into the frontend
 ```
 
 ## What you get
@@ -27,9 +29,27 @@ guuey deploy        # hosted: agent + MCP servers live on guuey
 ## Options
 
 ```
-npx @guuey/create-agentic-app <dir> [--framework claude-agent-sdk|openai-agents-sdk] [--skip-install]
+npx @guuey/create-agentic-app <dir> [--template base|agentic-app] [--framework claude-agent-sdk|openai-agents-sdk|google-adk] [--install]
 ```
 
+- `--template base` (default) — a three-page app: landing (with the guuey
+  widget), login (guest + BYO-OIDC seam), home (live status + the
+  three-ways distribution guide), plus an embedded-chat page on
+  [`@guuey/chat`](https://www.npmjs.com/package/@guuey/chat).
+- `--template agentic-app` — everything in base, plus a split-sidebar
+  product shell: upper sidebar = your menus, lower sidebar = the agent
+  dock; activating the dock swaps the main canvas to a fullscreen agent
+  (generative-UI cards get the whole width), and "Talk on mobile" shows a
+  QR to the same agent in the guuey portal.
+- `--install` — run `pnpm install` after scaffolding (off by default).
+- `--example <vertical>` — instead of a blank template, extract one of the
+  open-source demo apps from
+  [`withguuey/demos`](https://github.com/withguuey/demos) (e.g.
+  `--example trimly`) — the exact app behind the live demo, already wired
+  end to end. Re-brand it with `pnpm bootstrap` (which also turns the demo
+  chrome off). Mutually exclusive with `--template`/`--framework`. Manual
+  alternative: `npx degit withguuey/demos/<vertical>`.
+
 ## Binding to an existing app
 
 `guuey deploy` (above) creates a new app on first run. To bind this

package/dist/{chunk-JD4RAKEG.js → chunk-5V2IFXD4.js}

@@ -57,27 +57,33 @@ var execFileAsync = promisify(execFile);
 var here = dirname(fileURLToPath(import.meta.url));
 var packageRoot = join(here, "..");
 var defaultTemplatesDir = join(packageRoot, "dist", "templates");
-async function listAvailableFrameworks(templatesDir) {
+async function listDirs(root) {
   try {
-    const entries = await fs2.readdir(templatesDir, { withFileTypes: true });
+    const entries = await fs2.readdir(root, { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   } catch (err) {
     if (isErrnoException(err) && err.code === "ENOENT") return [];
     throw err;
   }
 }
-async function resolveTemplateDir(templatesDir, framework) {
-  const dir = join(templatesDir, framework);
+async function resolveTemplateDir(templatesDir, template, framework) {
+  const dir = join(templatesDir, template, framework);
   if (await pathExists(dir)) return dir;
-  const available = await listAvailableFrameworks(templatesDir);
-  const list = available.length > 0 ? available.join(", ") : `(none found under ${templatesDir})`;
+  const templates = (await listDirs(templatesDir)).filter((name) => name !== "mcp-base");
+  if (!templates.includes(template)) {
+    const list2 = templates.length > 0 ? templates.join(", ") : `(none found under ${templatesDir})`;
+    throw new Error(`No template "${template}". Available templates: ${list2}`);
+  }
+  const frameworks = await listDirs(join(templatesDir, template));
+  const list = frameworks.length > 0 ? frameworks.join(", ") : `(none found under ${join(templatesDir, template)})`;
   throw new Error(`No template for framework "${framework}". Available frameworks: ${list}`);
 }
 async function copyTree(src, dest, name, scope) {
   await fs2.mkdir(dest, { recursive: true });
   const entries = await fs2.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
-    const destName = renameContent(entry.name, name, scope);
+    const rawName = entry.name === "gitignore" ? ".gitignore" : entry.name;
+    const destName = renameContent(rawName, name, scope);
     const srcPath = join(src, entry.name);
     const destPath = join(dest, destName);
     if (entry.isDirectory()) {
@@ -139,7 +145,7 @@ async function scaffold(opts) {
   assertNpmSafeName(opts.name, "project");
   const scope = opts.scope ?? opts.name;
   const templatesDir = opts.templatesDir ?? defaultTemplatesDir;
-  const templateDir = await resolveTemplateDir(templatesDir, opts.framework);
+  const templateDir = await resolveTemplateDir(templatesDir, opts.template ?? "base", opts.framework);
   const projectDir = resolve(opts.targetDir);
   await ensureTargetDir(projectDir, opts.force);
   await copyTree(templateDir, projectDir, opts.name, scope);
@@ -153,31 +159,99 @@ async function scaffold(opts) {
   return { projectDir };
 }
 
+// src/scaffold-example.ts
+import { promises as fs3, createWriteStream } from "fs";
+import { join as join2, resolve as resolve2 } from "path";
+import { pipeline } from "stream/promises";
+import { Readable } from "stream";
+import { tmpdir } from "os";
+import { x, t } from "tar";
+var EXAMPLES_REPO = "withguuey/demos";
+var EXAMPLES_REF = "main";
+var TARBALL_URL = `https://codeload.github.com/${EXAMPLES_REPO}/tar.gz/${EXAMPLES_REF}`;
+async function defaultFetchTarball() {
+  const res = await fetch(TARBALL_URL);
+  if (!res.ok) {
+    throw new Error(
+      `Could not download ${EXAMPLES_REPO} (${res.status} from codeload.github.com). Check your network; the manual alternative is: npx degit ${EXAMPLES_REPO}/<example>`
+    );
+  }
+  return Readable.from(Buffer.from(await res.arrayBuffer()));
+}
+async function saveTarball(fetchTarball) {
+  const file = join2(await fs3.mkdtemp(join2(tmpdir(), "guuey-example-")), "demos.tar.gz");
+  await pipeline(await fetchTarball(), createWriteStream(file));
+  return file;
+}
+async function listTarball(file) {
+  let root = null;
+  const examples = /* @__PURE__ */ new Set();
+  await t({
+    file,
+    onReadEntry: (entry) => {
+      const segments = entry.path.split("/").filter(Boolean);
+      const first = segments[0];
+      if (first === void 0) return;
+      root ??= first;
+      const second = segments[1];
+      if (second !== void 0 && segments[2] === "guuey.json") examples.add(second);
+    }
+  });
+  if (root === null) throw new Error(`The ${EXAMPLES_REPO} tarball was empty.`);
+  return { root, examples: [...examples].sort() };
+}
+async function scaffoldExample(opts) {
+  const tarball = await saveTarball(opts.fetchTarball ?? defaultFetchTarball);
+  const { root, examples } = await listTarball(tarball);
+  if (!examples.includes(opts.example)) {
+    const list = examples.length > 0 ? examples.join(", ") : "(none published yet)";
+    throw new Error(`No example "${opts.example}" in ${EXAMPLES_REPO}. Available: ${list}`);
+  }
+  const projectDir = resolve2(opts.targetDir);
+  await ensureTargetDir(projectDir, opts.force);
+  const prefix = `${root}/${opts.example}/`;
+  await x({
+    file: tarball,
+    cwd: projectDir,
+    strip: 2,
+    filter: (path) => path.startsWith(prefix)
+  });
+  if (!await pathExists(join2(projectDir, "guuey.json"))) {
+    throw new Error(
+      `Extraction produced no guuey.json in ${projectDir} \u2014 the "${opts.example}" example looks malformed; please report this.`
+    );
+  }
+  await seedEnvLocal(projectDir);
+  if (opts.git !== false) await initGit(projectDir);
+  if (opts.install) await runInstall(projectDir);
+  return { projectDir };
+}
+
 // src/scaffold-mcp.ts
-import { promises as fs3 } from "fs";
-import { join as join2, dirname as dirname2, resolve as resolve2 } from "path";
+import { promises as fs4 } from "fs";
+import { join as join3, dirname as dirname2, resolve as resolve3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var here2 = dirname2(fileURLToPath2(import.meta.url));
-var packageRoot2 = join2(here2, "..");
-var defaultTemplatesDir2 = join2(packageRoot2, "dist", "templates");
+var packageRoot2 = join3(here2, "..");
+var defaultTemplatesDir2 = join3(packageRoot2, "dist", "templates");
 function renameMcpTokens(content, name, scope) {
   return renameContent(content.replaceAll("NAME_PLACEHOLDER", name), scope, scope);
 }
 async function copyMcpTree(src, dest, name, scope) {
-  await fs3.mkdir(dest, { recursive: true });
-  const entries = await fs3.readdir(src, { withFileTypes: true });
+  await fs4.mkdir(dest, { recursive: true });
+  const entries = await fs4.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     const destName = renameMcpTokens(entry.name, name, scope);
-    const srcPath = join2(src, entry.name);
-    const destPath = join2(dest, destName);
+    const srcPath = join3(src, entry.name);
+    const destPath = join3(dest, destName);
     if (entry.isDirectory()) {
       await copyMcpTree(srcPath, destPath, name, scope);
     } else {
-      const buf = await fs3.readFile(srcPath);
+      const buf = await fs4.readFile(srcPath);
       if (isProbablyText(buf)) {
-        await fs3.writeFile(destPath, renameMcpTokens(buf.toString("utf8"), name, scope), "utf8");
+        await fs4.writeFile(destPath, renameMcpTokens(buf.toString("utf8"), name, scope), "utf8");
       } else {
-        await fs3.writeFile(destPath, buf);
+        await fs4.writeFile(destPath, buf);
       }
     }
   }
@@ -186,11 +260,11 @@ async function scaffoldMcp(opts) {
   assertNpmSafeName(opts.name, "MCP");
   const scope = opts.scope ?? opts.name;
   const templatesDir = opts.templatesDir ?? defaultTemplatesDir2;
-  const templateDir = join2(templatesDir, "mcp-base");
+  const templateDir = join3(templatesDir, "mcp-base");
   if (!await pathExists(templateDir)) {
     throw new Error(`No mcp-base template found at ${templateDir}.`);
   }
-  const mcpDir = resolve2(opts.targetDir);
+  const mcpDir = resolve3(opts.targetDir);
   await ensureTargetDir(mcpDir, void 0);
   await copyMcpTree(templateDir, mcpDir, opts.name, scope);
   return { mcpDir };
@@ -199,5 +273,6 @@ async function scaffoldMcp(opts) {
 export {
   isNpmSafeName,
   scaffold,
+  scaffoldExample,
   scaffoldMcp
 };

package/dist/cli.cjs

@@ -2,7 +2,7 @@
 "use strict";
 
 // src/cli.ts
-var import_promises = require("readline/promises");
+var import_promises2 = require("readline/promises");
 var import_node_process = require("process");
 
 // src/scaffold.ts
@@ -65,27 +65,33 @@ var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.ex
 var here = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
 var packageRoot = (0, import_node_path.join)(here, "..");
 var defaultTemplatesDir = (0, import_node_path.join)(packageRoot, "dist", "templates");
-async function listAvailableFrameworks(templatesDir) {
+async function listDirs(root) {
   try {
-    const entries = await import_node_fs2.promises.readdir(templatesDir, { withFileTypes: true });
+    const entries = await import_node_fs2.promises.readdir(root, { withFileTypes: true });
     return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
   } catch (err) {
     if (isErrnoException(err) && err.code === "ENOENT") return [];
     throw err;
   }
 }
-async function resolveTemplateDir(templatesDir, framework) {
-  const dir = (0, import_node_path.join)(templatesDir, framework);
+async function resolveTemplateDir(templatesDir, template, framework) {
+  const dir = (0, import_node_path.join)(templatesDir, template, framework);
   if (await pathExists(dir)) return dir;
-  const available = await listAvailableFrameworks(templatesDir);
-  const list = available.length > 0 ? available.join(", ") : `(none found under ${templatesDir})`;
+  const templates = (await listDirs(templatesDir)).filter((name) => name !== "mcp-base");
+  if (!templates.includes(template)) {
+    const list2 = templates.length > 0 ? templates.join(", ") : `(none found under ${templatesDir})`;
+    throw new Error(`No template "${template}". Available templates: ${list2}`);
+  }
+  const frameworks = await listDirs((0, import_node_path.join)(templatesDir, template));
+  const list = frameworks.length > 0 ? frameworks.join(", ") : `(none found under ${(0, import_node_path.join)(templatesDir, template)})`;
   throw new Error(`No template for framework "${framework}". Available frameworks: ${list}`);
 }
 async function copyTree(src, dest, name, scope) {
   await import_node_fs2.promises.mkdir(dest, { recursive: true });
   const entries = await import_node_fs2.promises.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
-    const destName = renameContent(entry.name, name, scope);
+    const rawName = entry.name === "gitignore" ? ".gitignore" : entry.name;
+    const destName = renameContent(rawName, name, scope);
     const srcPath = (0, import_node_path.join)(src, entry.name);
     const destPath = (0, import_node_path.join)(dest, destName);
     if (entry.isDirectory()) {
@@ -147,7 +153,7 @@ async function scaffold(opts) {
   assertNpmSafeName(opts.name, "project");
   const scope = opts.scope ?? opts.name;
   const templatesDir = opts.templatesDir ?? defaultTemplatesDir;
-  const templateDir = await resolveTemplateDir(templatesDir, opts.framework);
+  const templateDir = await resolveTemplateDir(templatesDir, opts.template ?? "base", opts.framework);
   const projectDir = (0, import_node_path.resolve)(opts.targetDir);
   await ensureTargetDir(projectDir, opts.force);
   await copyTree(templateDir, projectDir, opts.name, scope);
@@ -161,20 +167,92 @@ async function scaffold(opts) {
   return { projectDir };
 }
 
-// src/scaffold-mcp.ts
+// src/scaffold-example.ts
 var import_node_fs3 = require("fs");
 var import_node_path2 = require("path");
+var import_promises = require("stream/promises");
+var import_node_stream = require("stream");
+var import_node_os = require("os");
+var import_tar = require("tar");
+var EXAMPLES_REPO = "withguuey/demos";
+var EXAMPLES_REF = "main";
+var TARBALL_URL = `https://codeload.github.com/${EXAMPLES_REPO}/tar.gz/${EXAMPLES_REF}`;
+async function defaultFetchTarball() {
+  const res = await fetch(TARBALL_URL);
+  if (!res.ok) {
+    throw new Error(
+      `Could not download ${EXAMPLES_REPO} (${res.status} from codeload.github.com). Check your network; the manual alternative is: npx degit ${EXAMPLES_REPO}/<example>`
+    );
+  }
+  return import_node_stream.Readable.from(Buffer.from(await res.arrayBuffer()));
+}
+async function saveTarball(fetchTarball) {
+  const file = (0, import_node_path2.join)(await import_node_fs3.promises.mkdtemp((0, import_node_path2.join)((0, import_node_os.tmpdir)(), "guuey-example-")), "demos.tar.gz");
+  await (0, import_promises.pipeline)(await fetchTarball(), (0, import_node_fs3.createWriteStream)(file));
+  return file;
+}
+async function listTarball(file) {
+  let root = null;
+  const examples = /* @__PURE__ */ new Set();
+  await (0, import_tar.t)({
+    file,
+    onReadEntry: (entry) => {
+      const segments = entry.path.split("/").filter(Boolean);
+      const first = segments[0];
+      if (first === void 0) return;
+      root ??= first;
+      const second = segments[1];
+      if (second !== void 0 && segments[2] === "guuey.json") examples.add(second);
+    }
+  });
+  if (root === null) throw new Error(`The ${EXAMPLES_REPO} tarball was empty.`);
+  return { root, examples: [...examples].sort() };
+}
+async function scaffoldExample(opts) {
+  const tarball = await saveTarball(opts.fetchTarball ?? defaultFetchTarball);
+  const { root, examples } = await listTarball(tarball);
+  if (!examples.includes(opts.example)) {
+    const list = examples.length > 0 ? examples.join(", ") : "(none published yet)";
+    throw new Error(`No example "${opts.example}" in ${EXAMPLES_REPO}. Available: ${list}`);
+  }
+  const projectDir = (0, import_node_path2.resolve)(opts.targetDir);
+  await ensureTargetDir(projectDir, opts.force);
+  const prefix = `${root}/${opts.example}/`;
+  await (0, import_tar.x)({
+    file: tarball,
+    cwd: projectDir,
+    strip: 2,
+    filter: (path) => path.startsWith(prefix)
+  });
+  if (!await pathExists((0, import_node_path2.join)(projectDir, "guuey.json"))) {
+    throw new Error(
+      `Extraction produced no guuey.json in ${projectDir} \u2014 the "${opts.example}" example looks malformed; please report this.`
+    );
+  }
+  await seedEnvLocal(projectDir);
+  if (opts.git !== false) await initGit(projectDir);
+  if (opts.install) await runInstall(projectDir);
+  return { projectDir };
+}
+
+// src/scaffold-mcp.ts
+var import_node_fs4 = require("fs");
+var import_node_path3 = require("path");
 var import_node_url2 = require("url");
 var import_meta2 = {};
-var here2 = (0, import_node_path2.dirname)((0, import_node_url2.fileURLToPath)(import_meta2.url));
-var packageRoot2 = (0, import_node_path2.join)(here2, "..");
-var defaultTemplatesDir2 = (0, import_node_path2.join)(packageRoot2, "dist", "templates");
+var here2 = (0, import_node_path3.dirname)((0, import_node_url2.fileURLToPath)(import_meta2.url));
+var packageRoot2 = (0, import_node_path3.join)(here2, "..");
+var defaultTemplatesDir2 = (0, import_node_path3.join)(packageRoot2, "dist", "templates");
 
 // src/cli.ts
 var FRAMEWORKS = ["claude-agent-sdk", "openai-agents-sdk", "google-adk"];
+var TEMPLATES = ["base", "agentic-app"];
 function isFramework(value) {
   return FRAMEWORKS.includes(value);
 }
+function isTemplate(value) {
+  return TEMPLATES.includes(value);
+}
 function parseArgs(argv) {
   const positional = [];
   const flags = {};
@@ -206,8 +284,15 @@ Arguments:
 Options:
   --name <name>         Project name (default: derived from target)
   --scope <scope>       npm scope for @<scope>/* packages (default: name)
+  --template <t>        App template: ${TEMPLATES.join(" | ")} (default: base)
+                        base = landing + login + home + chat;
+                        agentic-app = base + split-sidebar product shell with
+                        a fullscreen agent canvas and "talk on mobile" QR
   --framework <f>       Framework: ${FRAMEWORKS.join(" | ")}
   --agent <f>           Alias for --framework
+  --example <vertical>  Extract a demo app from github.com/withguuey/demos
+                        instead of a blank template (mutually exclusive with
+                        --template/--framework; re-brand via pnpm bootstrap)
   --install             Run "pnpm install" after scaffolding
   --no-git              Skip "git init" + initial commit
   --force               Scaffold into a non-empty target directory
@@ -224,8 +309,12 @@ function deriveName(target) {
   const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+/, "");
   return slug || "agentic-app";
 }
-async function promptFor(question) {
-  const rl = (0, import_promises.createInterface)({ input: import_node_process.stdin, output: import_node_process.stdout });
+async function promptFor(question, missingFlagHint) {
+  if (import_node_process.stdin.isTTY !== true) {
+    console.error(`Non-interactive run: pass ${missingFlagHint} explicitly.`);
+    process.exit(1);
+  }
+  const rl = (0, import_promises2.createInterface)({ input: import_node_process.stdin, output: import_node_process.stdout });
   try {
     return (await rl.question(question)).trim();
   } finally {
@@ -244,17 +333,53 @@ async function main() {
   }
   let target = positional[0];
   if (!target) {
-    target = await promptFor("Project directory: ");
+    target = await promptFor("Project directory: ", "the target directory as the first argument");
   }
   if (!target) {
     console.error("A target directory is required.");
     process.exit(1);
     return;
   }
+  if (flags.example !== void 0) {
+    if (flags.template !== void 0 || flags.framework !== void 0 || flags.agent !== void 0) {
+      console.error("--example is mutually exclusive with --template/--framework (an example is already a complete app).");
+      process.exit(1);
+      return;
+    }
+    if (typeof flags.example !== "string") {
+      console.error("--example needs a value, e.g. --example trimly");
+      process.exit(1);
+      return;
+    }
+    const { projectDir: projectDir2 } = await scaffoldExample({
+      targetDir: target,
+      example: flags.example,
+      install: flags.install === true,
+      git: flags["no-git"] !== true,
+      force: flags.force === true
+    });
+    console.log(`
+Extracted the "${flags.example}" example into ${projectDir2}
+`);
+    console.log("Next steps:");
+    console.log(`  cd ${projectDir2}`);
+    if (flags.install !== true) console.log("  pnpm install");
+    console.log("  pnpm bootstrap        # re-brand it as yours (also turns the demo chrome off)");
+    console.log("  pnpm dev");
+    return;
+  }
+  const templateFlag = flags.template;
+  const templateInput = typeof templateFlag === "string" ? templateFlag : "base";
+  if (!isTemplate(templateInput)) {
+    console.error(`Unknown template "${templateInput}". Available: ${TEMPLATES.join(", ")}`);
+    process.exit(1);
+    return;
+  }
+  const template = templateInput;
   const frameworkFlag = flags.framework ?? flags.agent;
   let frameworkInput = typeof frameworkFlag === "string" ? frameworkFlag : void 0;
   if (!frameworkInput) {
-    frameworkInput = await promptFor(`Framework (${FRAMEWORKS.join(" | ")}): `);
+    frameworkInput = await promptFor(`Framework (${FRAMEWORKS.join(" | ")}): `, "--framework <f>");
   }
   if (!isFramework(frameworkInput)) {
     console.error(`Unknown framework "${frameworkInput}". Available: ${FRAMEWORKS.join(", ")}`);
@@ -269,6 +394,7 @@ async function main() {
     targetDir: target,
     name,
     framework,
+    template,
     scope,
     install,
     git: flags["no-git"] !== true,
@@ -280,8 +406,10 @@ Scaffolded "${name}" in ${projectDir}
   console.log("Next steps:");
   console.log(`  cd ${projectDir}`);
   if (!install) console.log("  pnpm install");
+  console.log("  pnpm bootstrap        # brand, theme, copy \u2014 the web app is gated on this");
   console.log("  pnpm dev");
   console.log("  guuey login && guuey deploy");
+  console.log("  pnpm bootstrap -- --link   # bind the deployed app into the frontend");
 }
 main().catch((err) => {
   if (err instanceof Error) {

package/dist/cli.js

@@ -1,15 +1,20 @@
 #!/usr/bin/env node
 import {
-  scaffold
-} from "./chunk-JD4RAKEG.js";
+  scaffold,
+  scaffoldExample
+} from "./chunk-5V2IFXD4.js";
 
 // src/cli.ts
 import { createInterface } from "readline/promises";
 import { stdin, stdout } from "process";
 var FRAMEWORKS = ["claude-agent-sdk", "openai-agents-sdk", "google-adk"];
+var TEMPLATES = ["base", "agentic-app"];
 function isFramework(value) {
   return FRAMEWORKS.includes(value);
 }
+function isTemplate(value) {
+  return TEMPLATES.includes(value);
+}
 function parseArgs(argv) {
   const positional = [];
   const flags = {};
@@ -41,8 +46,15 @@ Arguments:
 Options:
   --name <name>         Project name (default: derived from target)
   --scope <scope>       npm scope for @<scope>/* packages (default: name)
+  --template <t>        App template: ${TEMPLATES.join(" | ")} (default: base)
+                        base = landing + login + home + chat;
+                        agentic-app = base + split-sidebar product shell with
+                        a fullscreen agent canvas and "talk on mobile" QR
   --framework <f>       Framework: ${FRAMEWORKS.join(" | ")}
   --agent <f>           Alias for --framework
+  --example <vertical>  Extract a demo app from github.com/withguuey/demos
+                        instead of a blank template (mutually exclusive with
+                        --template/--framework; re-brand via pnpm bootstrap)
   --install             Run "pnpm install" after scaffolding
   --no-git              Skip "git init" + initial commit
   --force               Scaffold into a non-empty target directory
@@ -59,7 +71,11 @@ function deriveName(target) {
   const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+/, "");
   return slug || "agentic-app";
 }
-async function promptFor(question) {
+async function promptFor(question, missingFlagHint) {
+  if (stdin.isTTY !== true) {
+    console.error(`Non-interactive run: pass ${missingFlagHint} explicitly.`);
+    process.exit(1);
+  }
   const rl = createInterface({ input: stdin, output: stdout });
   try {
     return (await rl.question(question)).trim();
@@ -79,17 +95,53 @@ async function main() {
   }
   let target = positional[0];
   if (!target) {
-    target = await promptFor("Project directory: ");
+    target = await promptFor("Project directory: ", "the target directory as the first argument");
   }
   if (!target) {
     console.error("A target directory is required.");
     process.exit(1);
     return;
   }
+  if (flags.example !== void 0) {
+    if (flags.template !== void 0 || flags.framework !== void 0 || flags.agent !== void 0) {
+      console.error("--example is mutually exclusive with --template/--framework (an example is already a complete app).");
+      process.exit(1);
+      return;
+    }
+    if (typeof flags.example !== "string") {
+      console.error("--example needs a value, e.g. --example trimly");
+      process.exit(1);
+      return;
+    }
+    const { projectDir: projectDir2 } = await scaffoldExample({
+      targetDir: target,
+      example: flags.example,
+      install: flags.install === true,
+      git: flags["no-git"] !== true,
+      force: flags.force === true
+    });
+    console.log(`
+Extracted the "${flags.example}" example into ${projectDir2}
+`);
+    console.log("Next steps:");
+    console.log(`  cd ${projectDir2}`);
+    if (flags.install !== true) console.log("  pnpm install");
+    console.log("  pnpm bootstrap        # re-brand it as yours (also turns the demo chrome off)");
+    console.log("  pnpm dev");
+    return;
+  }
+  const templateFlag = flags.template;
+  const templateInput = typeof templateFlag === "string" ? templateFlag : "base";
+  if (!isTemplate(templateInput)) {
+    console.error(`Unknown template "${templateInput}". Available: ${TEMPLATES.join(", ")}`);
+    process.exit(1);
+    return;
+  }
+  const template = templateInput;
   const frameworkFlag = flags.framework ?? flags.agent;
   let frameworkInput = typeof frameworkFlag === "string" ? frameworkFlag : void 0;
   if (!frameworkInput) {
-    frameworkInput = await promptFor(`Framework (${FRAMEWORKS.join(" | ")}): `);
+    frameworkInput = await promptFor(`Framework (${FRAMEWORKS.join(" | ")}): `, "--framework <f>");
   }
   if (!isFramework(frameworkInput)) {
     console.error(`Unknown framework "${frameworkInput}". Available: ${FRAMEWORKS.join(", ")}`);
@@ -104,6 +156,7 @@ async function main() {
     targetDir: target,
     name,
     framework,
+    template,
     scope,
     install,
     git: flags["no-git"] !== true,
@@ -115,8 +168,10 @@ Scaffolded "${name}" in ${projectDir}
   console.log("Next steps:");
   console.log(`  cd ${projectDir}`);
   if (!install) console.log("  pnpm install");
+  console.log("  pnpm bootstrap        # brand, theme, copy \u2014 the web app is gated on this");
   console.log("  pnpm dev");
   console.log("  guuey login && guuey deploy");
+  console.log("  pnpm bootstrap -- --link   # bind the deployed app into the frontend");
 }
 main().catch((err) => {
   if (err instanceof Error) {