From 1807f400f9fecf412ed0ef65c7d2512207967304 Mon Sep 17 00:00:00 2001
From: Abhin Rustagi <abhin@thesys.dev>
Date: Thu, 8 Oct 2026 14:22:13 +0530
Subject: [PATCH 1/5] feat(cli): show featured examples beside frameworks and
 browse the full catalog

---
 docs/content/docs/api-reference/cli.mdx       |  6 ++++-
 examples/README.md                            |  8 ++++++
 examples/examples.json                        | 12 ++++++---
 packages/openui-cli/README.md                 |  6 ++++-
 .../commands/create/lib/examples-catalog.ts   | 12 +++++++++
 .../src/commands/create/lib/help.ts           |  3 ++-
 .../src/commands/create/lib/resolve.ts        | 26 ++++++++++++++++---
 7 files changed, 62 insertions(+), 11 deletions(-)

diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdx
index a7a15872f..ec168fee5 100644
--- a/docs/content/docs/api-reference/cli.mdx
+++ b/docs/content/docs/api-reference/cli.mdx
@@ -104,7 +104,7 @@ Every framework overlay includes a `get_weather` example backed by Open-Meteo. A
 
 **OpenUI examples**
 
-Interactive `openui create` lists starter templates, and option to create an app from listed [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). `--example <name>` skips both menus. `--example` cannot be combined with `--template` or `--backend-framework`. Any other folder name in the catalog works the same way.
+Interactive `openui create` lists starter templates and up to five featured [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). `--example <name>` skips both menus. `--example` cannot be combined with `--template` or `--backend-framework`. Any other folder name in the catalog works the same way.
 
 **Conversation storage**
 
@@ -545,3 +545,7 @@ collection.
     `createLibrary`, `PromptOptions`, and the `Library` interface that `openui generate` read.
   </Card>
 </Cards>
+
+The backend framework picker shows up to five examples marked `featured: true`
+in `examples/examples.json`, in catalog order. Select “More examples…” for the
+complete catalog, or pass any catalog name through `--example`.
diff --git a/examples/README.md b/examples/README.md
index ec1ecadce..f514411b0 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -17,6 +17,14 @@ Each example has one primary home. Complete workflows with a companion tutorial
 
 `miscellaneous` is intentionally flat. If several examples develop the same stable integration seam, promote that seam to a top-level category instead of adding nested miscellaneous taxonomies.
 
+## CLI selection
+
+Set `"featured": true` on an entry in `examples.json` to show it in the CLI's
+backend framework picker. It shows up to five featured examples in catalog
+order beside the backend choices. “More examples…” opens the complete catalog,
+including entries with omitted or false flags. Every example is also available
+through `openui create --example <name>`.
+
 ## Catalog
 
 ### Agent frameworks
diff --git a/examples/examples.json b/examples/examples.json
index fbc631ca6..e19961d21 100644
--- a/examples/examples.json
+++ b/examples/examples.json
@@ -16,7 +16,8 @@
       "title": "Mastra",
       "description": "A Mastra agent connected to OpenUI through AG-UI.",
       "path": "agent-frameworks/mastra",
-      "envKey": "THESYS_API_KEY"
+      "envKey": "THESYS_API_KEY",
+      "featured": true
     },
     {
       "title": "Vercel AI SDK",
@@ -82,13 +83,15 @@
       "title": "Material UI",
       "description": "A broad Material UI component library for generated interfaces.",
       "path": "design-systems/material-ui",
-      "envKey": "THESYS_API_KEY"
+      "envKey": "THESYS_API_KEY",
+      "featured": true
     },
     {
       "title": "shadcn/ui",
       "description": "A broad shadcn/ui component library for generated interfaces.",
       "path": "design-systems/shadcn",
-      "envKey": "THESYS_API_KEY"
+      "envKey": "THESYS_API_KEY",
+      "featured": true
     },
     {
       "title": "Grok Build",
@@ -100,7 +103,8 @@
       "title": "Pi",
       "description": "A Pi coding-agent session on OpenUI Cloud.",
       "path": "harnesses/pi",
-      "envKey": "THESYS_API_KEY"
+      "envKey": "THESYS_API_KEY",
+      "featured": true
     },
     {
       "title": "Autofix",
diff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.md
index a2c3011f6..2e532684b 100644
--- a/packages/openui-cli/README.md
+++ b/packages/openui-cli/README.md
@@ -150,7 +150,7 @@ Every framework overlay includes `get_weather` as its example app-owned function
 
 #### OpenUI examples
 
-Interactive `openui create` offers to scaffold [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). Pass `--example <name>` to skip the menus. `--example` cannot be combined with `--template` or `--backend-framework`.
+Interactive `openui create` offers up to five featured [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). Pass `--example <name>` to skip the menus. `--example` cannot be combined with `--template` or `--backend-framework`.
 
 ```bash
 openui create --example shadcn
@@ -379,3 +379,7 @@ openui create --no-telemetry
 ## License
 
 [MIT](https://github.com/thesysdev/openui/blob/main/LICENSE)
+
+The backend framework picker shows up to five examples marked `featured: true`
+in `examples/examples.json`, in catalog order. Select “More examples…” for the
+complete catalog, or pass any catalog name through `--example`.
diff --git a/packages/openui-cli/src/commands/create/lib/examples-catalog.ts b/packages/openui-cli/src/commands/create/lib/examples-catalog.ts
index 5fc9e1e84..e5d51a407 100644
--- a/packages/openui-cli/src/commands/create/lib/examples-catalog.ts
+++ b/packages/openui-cli/src/commands/create/lib/examples-catalog.ts
@@ -15,6 +15,8 @@ export type ExampleProject = {
   envFile: ".env";
   /** Primary env var to prompt for. Omit when the example needs several keys. */
   envKey?: string;
+  /** Show this example in the curated interactive picker. */
+  featured?: boolean;
 };
 
 function catalogError(message: string): CreateError {
@@ -27,6 +29,7 @@ function parseCatalogEntry(item: unknown): ExampleProject {
     description?: unknown;
     path?: unknown;
     envKey?: unknown;
+    featured?: unknown;
   };
   if (
     typeof entry.title !== "string" ||
@@ -37,6 +40,9 @@ function parseCatalogEntry(item: unknown): ExampleProject {
       `${EXAMPLES_CATALOG_PATH} has an example missing title, description, or path.`,
     );
   }
+  if (entry.featured !== undefined && typeof entry.featured !== "boolean") {
+    throw catalogError(`${EXAMPLES_CATALOG_PATH} has an example with an invalid featured flag.`);
+  }
   const relative = entry.path.replace(/^\/+/, "");
   const name = relative.split("/").filter(Boolean).at(-1);
   if (!name) {
@@ -53,6 +59,7 @@ function parseCatalogEntry(item: unknown): ExampleProject {
     description: entry.description,
     path: relative.startsWith("examples/") ? relative : `examples/${relative}`,
     envFile: ".env",
+    featured: entry.featured === true,
     envKey: typeof entry.envKey === "string" ? entry.envKey : undefined,
   };
 }
@@ -75,6 +82,11 @@ export async function loadExamplesCatalog(
   return parseExamplesCatalog(content);
 }
 
+/** Keep catalog order so curators control which five examples are shown. */
+export function featuredExamples(examples: ExampleProject[]): ExampleProject[] {
+  return examples.filter((example) => example.featured === true).slice(0, 5);
+}
+
 export function findExample(name: string, examples: ExampleProject[]): ExampleProject {
   const normalized = name.toLowerCase();
   const match = examples.find((entry) => entry.name.toLowerCase() === normalized);
diff --git a/packages/openui-cli/src/commands/create/lib/help.ts b/packages/openui-cli/src/commands/create/lib/help.ts
index 1450bbe17..6e827a699 100644
--- a/packages/openui-cli/src/commands/create/lib/help.ts
+++ b/packages/openui-cli/src/commands/create/lib/help.ts
@@ -83,7 +83,8 @@ async function loadCreateHelpText(): Promise<string> {
 
   sections.push(`OpenUI examples:
   Loaded at runtime from examples/examples.json in the OpenUI repo.
-  Pick "Scaffold from OpenUI Examples" in the interactive prompt, or pass
+  Pick a featured example beside the backend choices, choose "More examples…"
+  for the complete list, or pass
   --example <name> with any catalog folder name.`);
 
   return `\n${sections.join("\n\n")}\n`;
diff --git a/packages/openui-cli/src/commands/create/lib/resolve.ts b/packages/openui-cli/src/commands/create/lib/resolve.ts
index 3e1e12a4e..c4965f6e0 100644
--- a/packages/openui-cli/src/commands/create/lib/resolve.ts
+++ b/packages/openui-cli/src/commands/create/lib/resolve.ts
@@ -3,6 +3,7 @@ import { resolveArgs } from "../../../lib/resolve-args";
 import type { RetryAttemptInfo } from "../../../lib/retry";
 import type { OverlayName, TemplateName } from "./create-types";
 import {
+  featuredExamples,
   findExample,
   groupedExampleChoices,
   loadExamplesCatalog,
@@ -111,6 +112,7 @@ export async function resolveProjectIdentity(
 
 const OPENUI_EXAMPLES_CHOICE = "openui-examples";
 const GO_BACK_CHOICE = "__back__";
+const EXAMPLE_CHOICE_PREFIX = "example:";
 
 export async function resolveCreateSelection(params: {
   backendFramework?: OverlayName;
@@ -126,6 +128,7 @@ export async function resolveCreateSelection(params: {
   if (backendFramework) return { kind: "overlay", overlay: backendFramework };
   if (!interactive) return { kind: "overlay", overlay: "default" };
 
+  const featured = featuredExamples(examples);
   const { select, Separator } = await import("@inquirer/prompts");
   const prompt = async <T extends string>(
     message: string,
@@ -154,20 +157,35 @@ export async function resolveCreateSelection(params: {
       name: overlay.name,
       description: overlay.description,
     }));
+    if (featured.length > 0) {
+      starterChoices.push(new Separator("Featured examples"));
+      starterChoices.push(
+        ...featured.map((example) => ({
+          value: `${EXAMPLE_CHOICE_PREFIX}${example.name}`,
+          name: example.label,
+          description: example.description,
+        })),
+      );
+    }
     if (examples.length > 0) {
-      starterChoices.push(new Separator());
       starterChoices.push({
         value: OPENUI_EXAMPLES_CHOICE,
-        name: "Scaffold from OpenUI Examples",
-        description: "Browse examples from the OpenUI repo",
+        name: "More examples…",
+        description: "Browse the complete OpenUI example catalog",
       });
     }
 
     const selected = await prompt<string>(
-      "Choose your backend framework",
+      "Choose your backend framework or example",
       starterChoices,
       starterChoices.length,
     );
+    if (selected.startsWith(EXAMPLE_CHOICE_PREFIX)) {
+      return {
+        kind: "example",
+        example: findExample(selected.slice(EXAMPLE_CHOICE_PREFIX.length), examples),
+      };
+    }
     if (selected !== OPENUI_EXAMPLES_CHOICE) {
       return { kind: "overlay", overlay: selected as OverlayName };
     }

From e8b6504d13d7a3271733b3b4ae3e0b2e09c87e00 Mon Sep 17 00:00:00 2001
From: Abhin Rustagi <abhin@thesys.dev>
Date: Thu, 8 Oct 2026 17:22:33 +0530
Subject: [PATCH 2/5] fix(cli): match featured example picker and more
 navigation

---
 docs/content/docs/api-reference/cli.mdx            |  2 +-
 examples/examples.json                             | 14 +++++++-------
 packages/openui-cli/README.md                      |  2 +-
 .../openui-cli/src/commands/create/lib/resolve.ts  |  6 +++---
 4 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdx
index d2c3e06b5..754bd85c0 100644
--- a/docs/content/docs/api-reference/cli.mdx
+++ b/docs/content/docs/api-reference/cli.mdx
@@ -546,5 +546,5 @@ collection.
 </Cards>
 
 The backend framework picker shows up to five examples marked `featured: true`
-in `examples/examples.json`, in catalog order. Select “More examples…” for the
+in `examples/examples.json`, in catalog order. Select “More OpenUI Examples →” for the
 complete catalog, or pass any catalog name through `--example`.
diff --git a/examples/examples.json b/examples/examples.json
index e19961d21..e02970b06 100644
--- a/examples/examples.json
+++ b/examples/examples.json
@@ -80,16 +80,16 @@
       "envKey": "THESYS_API_KEY"
     },
     {
-      "title": "Material UI",
-      "description": "A broad Material UI component library for generated interfaces.",
-      "path": "design-systems/material-ui",
+      "title": "ShadCN",
+      "description": "A broad shadcn/ui component library for generated interfaces.",
+      "path": "design-systems/shadcn",
       "envKey": "THESYS_API_KEY",
       "featured": true
     },
     {
-      "title": "shadcn/ui",
-      "description": "A broad shadcn/ui component library for generated interfaces.",
-      "path": "design-systems/shadcn",
+      "title": "Material UI",
+      "description": "A broad Material UI component library for generated interfaces.",
+      "path": "design-systems/material-ui",
       "envKey": "THESYS_API_KEY",
       "featured": true
     },
@@ -100,7 +100,7 @@
       "envKey": "XAI_API_KEY"
     },
     {
-      "title": "Pi",
+      "title": "Pi Harness",
       "description": "A Pi coding-agent session on OpenUI Cloud.",
       "path": "harnesses/pi",
       "envKey": "THESYS_API_KEY",
diff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.md
index 0dff2069d..dc012ce92 100644
--- a/packages/openui-cli/README.md
+++ b/packages/openui-cli/README.md
@@ -379,5 +379,5 @@ openui create --no-telemetry
 [MIT](https://github.com/thesysdev/openui/blob/main/LICENSE)
 
 The backend framework picker shows up to five examples marked `featured: true`
-in `examples/examples.json`, in catalog order. Select “More examples…” for the
+in `examples/examples.json`, in catalog order. Select “More OpenUI Examples →” for the
 complete catalog, or pass any catalog name through `--example`.
diff --git a/packages/openui-cli/src/commands/create/lib/resolve.ts b/packages/openui-cli/src/commands/create/lib/resolve.ts
index 20c2f6d2b..c5d8a615b 100644
--- a/packages/openui-cli/src/commands/create/lib/resolve.ts
+++ b/packages/openui-cli/src/commands/create/lib/resolve.ts
@@ -158,7 +158,7 @@ export async function resolveCreateSelection(params: {
       description: overlay.description,
     }));
     if (featured.length > 0) {
-      starterChoices.push(new Separator("Featured examples"));
+      starterChoices.push(new Separator());
       starterChoices.push(
         ...featured.map((example) => ({
           value: `${EXAMPLE_CHOICE_PREFIX}${example.name}`,
@@ -170,13 +170,13 @@ export async function resolveCreateSelection(params: {
     if (examples.length > 0) {
       starterChoices.push({
         value: OPENUI_EXAMPLES_CHOICE,
-        name: "More examples…",
+        name: "More OpenUI Examples →",
         description: "Browse the complete OpenUI example catalog",
       });
     }
 
     const selected = await prompt<string>(
-      "Choose your backend framework or example",
+      "Choose your backend framework",
       starterChoices,
       starterChoices.length,
     );

From ef5622024add56b7e06e6bf0b6fb8e00e31972cc Mon Sep 17 00:00:00 2001
From: Abhin Rustagi <abhin@thesys.dev>
Date: Thu, 8 Oct 2026 17:23:05 +0530
Subject: [PATCH 3/5] chore: preserve existing example catalog order

---
 examples/examples.json | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/examples/examples.json b/examples/examples.json
index e02970b06..eac950c14 100644
--- a/examples/examples.json
+++ b/examples/examples.json
@@ -80,16 +80,16 @@
       "envKey": "THESYS_API_KEY"
     },
     {
-      "title": "ShadCN",
-      "description": "A broad shadcn/ui component library for generated interfaces.",
-      "path": "design-systems/shadcn",
+      "title": "Material UI",
+      "description": "A broad Material UI component library for generated interfaces.",
+      "path": "design-systems/material-ui",
       "envKey": "THESYS_API_KEY",
       "featured": true
     },
     {
-      "title": "Material UI",
-      "description": "A broad Material UI component library for generated interfaces.",
-      "path": "design-systems/material-ui",
+      "title": "ShadCN",
+      "description": "A broad shadcn/ui component library for generated interfaces.",
+      "path": "design-systems/shadcn",
       "envKey": "THESYS_API_KEY",
       "featured": true
     },

From 0965229dcd72223edacaab22b5ac226bdf535569 Mon Sep 17 00:00:00 2001
From: AB <55152006+AbhinRustagi@users.noreply.github.com>
Date: Thu, 8 Oct 2026 17:23:50 +0530
Subject: [PATCH 4/5] Update cli.mdx

---
 docs/content/docs/api-reference/cli.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/content/docs/api-reference/cli.mdx b/docs/content/docs/api-reference/cli.mdx
index 754bd85c0..3ed9c1074 100644
--- a/docs/content/docs/api-reference/cli.mdx
+++ b/docs/content/docs/api-reference/cli.mdx
@@ -103,7 +103,7 @@ Every framework overlay includes a `get_weather` example backed by Open-Meteo. A
 
 **OpenUI examples**
 
-Interactive `openui create` lists starter templates and up to five featured [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). `--example <name>` skips both menus. `--example` cannot be combined with `--template` or `--backend-framework`. Any other folder name in the catalog works the same way.
+Interactive `openui create` lists starter templates and featured [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). `--example <name>` skips both menus. `--example` cannot be combined with `--template` or `--backend-framework`. Any other folder name in the catalog works the same way.
 
 **Conversation storage**
 
@@ -545,6 +545,6 @@ collection.
   </Card>
 </Cards>
 
-The backend framework picker shows up to five examples marked `featured: true`
+The backend framework picker shows examples marked `featured: true`
 in `examples/examples.json`, in catalog order. Select “More OpenUI Examples →” for the
 complete catalog, or pass any catalog name through `--example`.

From 76fd65f6e25888959d1a035a5d60ac0797cadac5 Mon Sep 17 00:00:00 2001
From: AB <55152006+AbhinRustagi@users.noreply.github.com>
Date: Thu, 8 Oct 2026 17:24:50 +0530
Subject: [PATCH 5/5] Update README.md

---
 packages/openui-cli/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/openui-cli/README.md b/packages/openui-cli/README.md
index dc012ce92..3df1ac1d6 100644
--- a/packages/openui-cli/README.md
+++ b/packages/openui-cli/README.md
@@ -149,7 +149,7 @@ Every framework overlay includes `get_weather` as its example app-owned function
 
 #### OpenUI examples
 
-Interactive `openui create` offers up to five featured [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). Pass `--example <name>` to skip the menus. `--example` cannot be combined with `--template` or `--backend-framework`.
+Interactive `openui create` offers featured [OpenUI examples](https://github.com/thesysdev/openui/blob/main/examples). Pass `--example <name>` to skip the menus. `--example` cannot be combined with `--template` or `--backend-framework`.
 
 ```bash
 openui create --example shadcn
@@ -378,6 +378,6 @@ openui create --no-telemetry
 
 [MIT](https://github.com/thesysdev/openui/blob/main/LICENSE)
 
-The backend framework picker shows up to five examples marked `featured: true`
+The backend framework picker shows examples marked `featured: true`
 in `examples/examples.json`, in catalog order. Select “More OpenUI Examples →” for the
 complete catalog, or pass any catalog name through `--example`.