@helloleo/plugins 0.2.4 → 0.2.5

package/dist/index.js

@@ -24900,19 +24900,25 @@ async function renderTemplate(templateId, vars, destDir) {
 }
 
 // src/tools/scaffold.ts
-var SCAFFOLD_VERSION = "tanstack-start-2026-06-18";
+var SCAFFOLD_TEMPLATES = {
+  "tanstack-start": "tanstack-start-2026-06-18",
+  "tanstack-router": "tanstack-router-2026-06-15"
+};
+var SCAFFOLD_VERSION = SCAFFOLD_TEMPLATES["tanstack-start"];
 function projectUuidFromDir(dir) {
   return path3.basename(dir);
 }
 var scaffoldOptionsSchema = exports_external2.object({
   name: exports_external2.string().describe("Human-readable name for SEO, e.g. 'Shipping Platform'"),
-  description: exports_external2.string().describe("One sentence describing the app. Used as the meta description.")
+  description: exports_external2.string().describe("One sentence describing the app. Used as the meta description."),
+  type: exports_external2.enum(["tanstack-start", "tanstack-router"]).optional().describe("Project type. 'tanstack-router': " + "client-only SPA with no server and no database \u2014 use it only for " + "pure frontends that talk to external APIs." + "'tanstack-start': SSR app with API routes and a " + "database, KV and bucket \u2014 use it whenever the app " + "needs to persist data or run server-side code (experimental, " + "use only if the user expresses a really complexe application idea).")
 });
 function slugify(name) {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "leo-project";
 }
-async function writeBaseScaffold({ name, description }, dir) {
-  const created = await renderTemplate(SCAFFOLD_VERSION, {
+async function writeBaseScaffold({ name, description, type }, dir) {
+  const templateId = SCAFFOLD_TEMPLATES[type ?? "tanstack-start"];
+  const created = await renderTemplate(templateId, {
     LEO_NAME: name,
     LEO_SLUG: slugify(name),
     LEO_DESCRIPTION: description,
@@ -24920,36 +24926,49 @@ async function writeBaseScaffold({ name, description }, dir) {
   }, dir);
   await mkdir(path3.join(dir, ".leo"), { recursive: true });
   const leoPath = path3.join(".leo", "project.json");
-  await Bun.write(path3.join(dir, leoPath), JSON.stringify({ $schema: 1, scaffold: SCAFFOLD_VERSION }, null, 2));
+  await Bun.write(path3.join(dir, leoPath), JSON.stringify({ $schema: 1, scaffold: templateId }, null, 2));
   return [...created, leoPath];
 }
 var scaffold = tool({
-  description: "Scaffold a new TanStack Start project with React 19, SSR, file-based " + "routing, Tailwind v4, shadcn/ui, react-query, and a database, KV and " + "bucket via @helloleo/runtime. Call this first for any new project, " + "before writing routes or components.",
+  description: "Scaffold a new project with React 19, file-based routing (TanStack), " + "Tailwind v4, shadcn/ui, and react-query. Two types: 'tanstack-start' " + "(SSR, API routes, and a database, KV and bucket via @helloleo/runtime) " + "or 'tanstack-router' (client-only SPA, no server, no database). Call " + "this first for any new project, before writing routes or components.",
   args: {
     name: scaffoldOptionsSchema.shape.name,
-    description: scaffoldOptionsSchema.shape.description
+    description: scaffoldOptionsSchema.shape.description,
+    type: scaffoldOptionsSchema.shape.type
   },
   async execute(args, context) {
+    const type = args.type ?? "tanstack-start";
     const created = await writeBaseScaffold(args, context.directory);
     const uiComponents = created.filter((f) => f.startsWith("src/components/ui/"));
     const rest = created.filter((f) => !f.startsWith("src/components/ui/"));
+    const typeNotes = type === "tanstack-start" ? [
+      "- This is a TanStack Start project. The server entry is src/server.ts. There is no index.html or client entrypoint.",
+      "- For JSON/CRUD APIs, add server routes under src/routes/api/. Read src/routes/api/health.ts first, add routes as needed.",
+      "- The database schema lives in src/db/schema.ts. Migrations run automatically."
+    ] : [
+      "- This is a TanStack Router SPA. The client entry is index.html -> src/main.tsx. There is no server: no API routes, no server functions, no database.",
+      "- Fetch data from external APIs only. If the app needs its own persistence or server-side code, it should have been scaffolded as tanstack-start."
+    ];
+    const nextSteps = type === "tanstack-start" ? [
+      "Next: read src/routes/index.tsx and continue with the user's request.",
+      "For authentication (password and/or OAuth), call setup_authentication.",
+      "For NetSuite projects, call setup_netsuite."
+    ] : [
+      "Next: read src/routes/index.tsx and continue with the user's request."
+    ];
     return [
       `Scaffolded ${created.length} files:`,
       ...rest.map((f) => `  - ${f}`),
       `  - src/components/ui/ (${uiComponents.length} shadcn/ui components)`,
       "",
       "Notes:",
-      "- This is a TanStack Start project. The server entry is src/server.ts. There is no index.html or client entrypoint.",
+      ...typeNotes,
       "- Add routes as files in src/routes/. Do not default export route components. Routing and layout conventions are documented in src/routes/README.md, read it before adding routes.",
-      "- For JSON/CRUD APIs, add server routes under src/routes/api/. Read src/routes/api/health.ts first, add routes as needed.",
       "- shadcn/ui components are already in src/components/ui.",
       "- Design system: style exclusively with the token utilities, never hardcoded colors. To change the look, edit the token values in src/styles.css (light and dark blocks).",
-      "- The database schema lives in src/db/schema.ts. Migrations run automatically.",
       "- Always fetch data with react-query (useQuery and useMutation).",
       "",
-      "Next: read src/routes/index.tsx and continue with the user's request.",
-      "For authentication (password and/or OAuth), call setup_authentication.",
-      "For NetSuite projects, call setup_netsuite."
+      ...nextSteps
     ].join(`
 `);
   }

package/dist/templates/tanstack-router-2026-06-15/index.html

@@ -5,6 +5,10 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{{LEO_NAME}}</title>
+    <meta name="description" content="{{LEO_DESCRIPTION}}" />
+    <meta property="og:title" content="{{LEO_NAME}}" />
+    <meta property="og:description" content="{{LEO_DESCRIPTION}}" />
+    <meta property="og:type" content="website" />
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">

package/dist/templates/tanstack-router-2026-06-15/src/components/error-component.tsx

@@ -0,0 +1,47 @@
+import { useState } from 'react'
+import { useRouterState } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+
+// Rendered by the router's defaultErrorComponent for any uncaught render or
+// loader error. Per-route `errorComponent` options override it. Keep this
+// component free of app dependencies (toasts, auth, etc.) -- it must still
+// render when the rest of the app is broken.
+export function DefaultErrorComponent({ error }: { error: Error }) {
+  const pathname = useRouterState({ select: (s) => s.location.pathname })
+  const [copied, setCopied] = useState(false)
+
+  async function copyForLeo() {
+    // Blank lines + fenced stack so the report keeps its structure when
+    // pasted into a markdown-rendering chat.
+    const report = [
+      'My app threw an error, please fix it:',
+      `Page: ${pathname}`,
+      `Error: ${error.message}`,
+      ['Stack:', '```', error.stack ?? '(no stack trace)', '```'].join('\n'),
+    ].join('\n\n')
+
+    await navigator.clipboard.writeText(report)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-background p-4">
+      <Card className="w-full max-w-lg">
+        <CardHeader>
+          <CardTitle>Something went wrong</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <pre className="text-sm text-destructive whitespace-pre-wrap break-words rounded-md bg-muted p-3">
+            {error.message}
+          </pre>
+          <Button onClick={copyForLeo}>{copied ? 'Copied!' : 'Copy error'}</Button>
+          <p className="text-sm text-muted-foreground">
+            Paste the copied error to Leo and it will help you fix it.
+          </p>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}

package/dist/templates/tanstack-router-2026-06-15/src/main.tsx

@@ -2,6 +2,7 @@ import ReactDOM from 'react-dom/client'
 import { RouterProvider, createRouter } from '@tanstack/react-router'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { routeTree } from './routeTree.gen'
+import { DefaultErrorComponent } from '@/components/error-component'
 
 const queryClient = new QueryClient()
 
@@ -12,6 +13,9 @@ const router = createRouter({
   // on every preload/visit and React Query owns caching from there.
   defaultPreloadStaleTime: 0,
   scrollRestoration: true,
+  // Catches uncaught render/loader errors on any route. Routes can still
+  // set their own `errorComponent` to override this.
+  defaultErrorComponent: DefaultErrorComponent,
   context: { queryClient },
 })
 

package/dist/templates/tanstack-router-2026-06-15/src/routes/README.md

@@ -0,0 +1,85 @@
+# Routes
+
+TanStack Router uses file-based routing. Every `.ts` and `.tsx` file in this directory is a route. Do not create `src/pages/`, `app/layout.tsx`, or similar, those are Next.js / Remix conventions. The only root layout is `src/routes/__root.tsx`.
+
+## Conventions
+
+| File | URL |
+| --- | --- |
+| `index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `users/index.tsx` | `/users` |
+| `users/$id.tsx` | `/users/:id` (dynamic — bare `$`, no curly braces) |
+| `posts.$postId.tsx` | `/posts/:postId` (dots nest without folders) |
+| `admin/route.tsx` | layout for every `/admin/*` page; must render `<Outlet />` |
+| `admin_.login.tsx` | `/admin/login`, but outside the admin layout (trailing `_` escapes it) |
+| `_auth.tsx` | pathless layout; wraps `_auth/*` files without adding a URL segment |
+| `__root.tsx` | app shell, wraps every page; preserve `<Outlet />` |
+
+## Rules
+
+- A layout route without `<Outlet />` renders its children nowhere.
+- Do not `export default` route components, it breaks code splitting. Use a named function passed as `component:`.
+- `routeTree.gen.ts` is auto-generated. Don't edit it by hand.
+- This is a client-only SPA — there are no server routes or server functions. Fetch data from external APIs with React Query.
+
+## Authenticated routes
+
+Put protected pages inside a pathless `_authed` layout and keep login/signup
+at the top level, outside it. Never special-case the login pathname inside
+the layout guard.
+
+```
+routes/
+  __root.tsx          loads the session into router context (context.user)
+  _authed.tsx         pathless guard — no URL segment of its own
+  _authed/
+    dashboard.tsx     /dashboard (protected)
+    posts.tsx         /posts     (protected)
+  index.tsx           /          (public)
+  login.tsx           /login     (public)
+  logout.tsx          /logout
+```
+
+`_authed.tsx` does the guarding, all children inherit it:
+
+```tsx _authed.tsx
+export const Route = createFileRoute('/_authed')({
+  beforeLoad: ({ context }) => {
+    if (!context.user) {
+      throw redirect({ to: '/login' })
+    }
+  },
+})
+```
+
+The session is loaded once in `__root.tsx`'s `beforeLoad` and returned into
+the router context so every route can read `context.user`. `getUser()` is
+whatever your auth uses (e.g. verify a JWT from localStorage) and resolves to
+the user or null:
+
+```tsx __root.tsx
+// (keep the existing component, add this)
+export const Route = createRootRouteWithContext<{ queryClient: QueryClient }>()({
+  beforeLoad: async () => {
+    const user = await getUser()
+    return { user }
+  },
+  // ...component unchanged
+})
+```
+
+Components read it with `Route.useRouteContext()` (e.g. to swap a Login link
+for a Logout button in the shell):
+
+```tsx
+function Route() {
+  const { user } = Route.useRouteContext()
+  
+  return (
+    <nav>
+      {user ? <Link to="/logout">Logout</Link> : <Link to="/login">Login</Link>}
+    </nav>
+  )
+}
+```

package/dist/templates/tanstack-router-2026-06-15/src/routes/__root.tsx

@@ -1,5 +1,6 @@
 import { Outlet, createRootRouteWithContext } from '@tanstack/react-router'
 import type { QueryClient } from '@tanstack/react-query'
+import { Toaster } from '@/components/ui/sonner'
 
 import '../styles.css'
 
@@ -11,6 +12,7 @@ function RootComponent() {
   return (
     <>
       <Outlet />
+      <Toaster richColors position="top-right" />
     </>
   )
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helloleo/plugins",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "OpenCode plugins for HelloLeo",
   "license": "UNLICENSED",
   "type": "module",

package/src/templates/tanstack-router-2026-06-15/index.html

@@ -5,6 +5,10 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{{LEO_NAME}}</title>
+    <meta name="description" content="{{LEO_DESCRIPTION}}" />
+    <meta property="og:title" content="{{LEO_NAME}}" />
+    <meta property="og:description" content="{{LEO_DESCRIPTION}}" />
+    <meta property="og:type" content="website" />
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet">

package/src/templates/tanstack-router-2026-06-15/src/components/error-component.tsx

@@ -0,0 +1,47 @@
+import { useState } from 'react'
+import { useRouterState } from '@tanstack/react-router'
+import { Button } from '@/components/ui/button'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+
+// Rendered by the router's defaultErrorComponent for any uncaught render or
+// loader error. Per-route `errorComponent` options override it. Keep this
+// component free of app dependencies (toasts, auth, etc.) -- it must still
+// render when the rest of the app is broken.
+export function DefaultErrorComponent({ error }: { error: Error }) {
+  const pathname = useRouterState({ select: (s) => s.location.pathname })
+  const [copied, setCopied] = useState(false)
+
+  async function copyForLeo() {
+    // Blank lines + fenced stack so the report keeps its structure when
+    // pasted into a markdown-rendering chat.
+    const report = [
+      'My app threw an error, please fix it:',
+      `Page: ${pathname}`,
+      `Error: ${error.message}`,
+      ['Stack:', '```', error.stack ?? '(no stack trace)', '```'].join('\n'),
+    ].join('\n\n')
+
+    await navigator.clipboard.writeText(report)
+    setCopied(true)
+    setTimeout(() => setCopied(false), 2000)
+  }
+
+  return (
+    <div className="min-h-screen flex items-center justify-center bg-background p-4">
+      <Card className="w-full max-w-lg">
+        <CardHeader>
+          <CardTitle>Something went wrong</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <pre className="text-sm text-destructive whitespace-pre-wrap break-words rounded-md bg-muted p-3">
+            {error.message}
+          </pre>
+          <Button onClick={copyForLeo}>{copied ? 'Copied!' : 'Copy error'}</Button>
+          <p className="text-sm text-muted-foreground">
+            Paste the copied error to Leo and it will help you fix it.
+          </p>
+        </CardContent>
+      </Card>
+    </div>
+  )
+}

package/src/templates/tanstack-router-2026-06-15/src/main.tsx

@@ -2,6 +2,7 @@ import ReactDOM from 'react-dom/client'
 import { RouterProvider, createRouter } from '@tanstack/react-router'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { routeTree } from './routeTree.gen'
+import { DefaultErrorComponent } from '@/components/error-component'
 
 const queryClient = new QueryClient()
 
@@ -12,6 +13,9 @@ const router = createRouter({
   // on every preload/visit and React Query owns caching from there.
   defaultPreloadStaleTime: 0,
   scrollRestoration: true,
+  // Catches uncaught render/loader errors on any route. Routes can still
+  // set their own `errorComponent` to override this.
+  defaultErrorComponent: DefaultErrorComponent,
   context: { queryClient },
 })
 

package/src/templates/tanstack-router-2026-06-15/src/routes/README.md

@@ -0,0 +1,85 @@
+# Routes
+
+TanStack Router uses file-based routing. Every `.ts` and `.tsx` file in this directory is a route. Do not create `src/pages/`, `app/layout.tsx`, or similar, those are Next.js / Remix conventions. The only root layout is `src/routes/__root.tsx`.
+
+## Conventions
+
+| File | URL |
+| --- | --- |
+| `index.tsx` | `/` |
+| `about.tsx` | `/about` |
+| `users/index.tsx` | `/users` |
+| `users/$id.tsx` | `/users/:id` (dynamic — bare `$`, no curly braces) |
+| `posts.$postId.tsx` | `/posts/:postId` (dots nest without folders) |
+| `admin/route.tsx` | layout for every `/admin/*` page; must render `<Outlet />` |
+| `admin_.login.tsx` | `/admin/login`, but outside the admin layout (trailing `_` escapes it) |
+| `_auth.tsx` | pathless layout; wraps `_auth/*` files without adding a URL segment |
+| `__root.tsx` | app shell, wraps every page; preserve `<Outlet />` |
+
+## Rules
+
+- A layout route without `<Outlet />` renders its children nowhere.
+- Do not `export default` route components, it breaks code splitting. Use a named function passed as `component:`.
+- `routeTree.gen.ts` is auto-generated. Don't edit it by hand.
+- This is a client-only SPA — there are no server routes or server functions. Fetch data from external APIs with React Query.
+
+## Authenticated routes
+
+Put protected pages inside a pathless `_authed` layout and keep login/signup
+at the top level, outside it. Never special-case the login pathname inside
+the layout guard.
+
+```
+routes/
+  __root.tsx          loads the session into router context (context.user)
+  _authed.tsx         pathless guard — no URL segment of its own
+  _authed/
+    dashboard.tsx     /dashboard (protected)
+    posts.tsx         /posts     (protected)
+  index.tsx           /          (public)
+  login.tsx           /login     (public)
+  logout.tsx          /logout
+```
+
+`_authed.tsx` does the guarding, all children inherit it:
+
+```tsx _authed.tsx
+export const Route = createFileRoute('/_authed')({
+  beforeLoad: ({ context }) => {
+    if (!context.user) {
+      throw redirect({ to: '/login' })
+    }
+  },
+})
+```
+
+The session is loaded once in `__root.tsx`'s `beforeLoad` and returned into
+the router context so every route can read `context.user`. `getUser()` is
+whatever your auth uses (e.g. verify a JWT from localStorage) and resolves to
+the user or null:
+
+```tsx __root.tsx
+// (keep the existing component, add this)
+export const Route = createRootRouteWithContext<{ queryClient: QueryClient }>()({
+  beforeLoad: async () => {
+    const user = await getUser()
+    return { user }
+  },
+  // ...component unchanged
+})
+```
+
+Components read it with `Route.useRouteContext()` (e.g. to swap a Login link
+for a Logout button in the shell):
+
+```tsx
+function Route() {
+  const { user } = Route.useRouteContext()
+  
+  return (
+    <nav>
+      {user ? <Link to="/logout">Logout</Link> : <Link to="/login">Login</Link>}
+    </nav>
+  )
+}
+```

package/src/templates/tanstack-router-2026-06-15/src/routes/__root.tsx

@@ -1,5 +1,6 @@
 import { Outlet, createRootRouteWithContext } from '@tanstack/react-router'
 import type { QueryClient } from '@tanstack/react-query'
+import { Toaster } from '@/components/ui/sonner'
 
 import '../styles.css'
 
@@ -11,6 +12,7 @@ function RootComponent() {
   return (
     <>
       <Outlet />
+      <Toaster richColors position="top-right" />
     </>
   )
 }

package/src/tools/scaffold.ts

@@ -6,14 +6,26 @@ import { z } from "zod/v4";
 import { renderTemplate } from "../template-render.ts";
 
 /**
- * Identifier for the scaffold template a project was generated from. It is
- * also the directory name under src/templates/. Written to .leo/project.json
- * so the webapp / leo-core can tell which template (and therefore which
- * conventions: TanStack Start file routing + SSR, Tailwind v4, shadcn/ui) a
- * workspace was bootstrapped with. Bump this (and add a new templates/<id>/
- * dir) when the scaffold's shape changes.
+ * Scaffold template identifiers, keyed by project type. Each value is the
+ * directory name under src/templates/ and is written to .leo/project.json so
+ * the webapp / leo-core can tell which template (and therefore which
+ * conventions) a workspace was bootstrapped with. Bump a value (and add a new
+ * templates/<id>/ dir) when that scaffold's shape changes.
+ *
+ * - tanstack-start: SSR Worker with file routing, API routes, and a database,
+ *   KV and bucket via @helloleo/runtime.
+ * - tanstack-router: client-only SPA (Vite + index.html entry), no server and
+ *   no database.
  */
-export const SCAFFOLD_VERSION = "tanstack-start-2026-06-18";
+export const SCAFFOLD_TEMPLATES = {
+	"tanstack-start": "tanstack-start-2026-06-18",
+	"tanstack-router": "tanstack-router-2026-06-15",
+} as const;
+
+export type ScaffoldType = keyof typeof SCAFFOLD_TEMPLATES;
+
+/** Default template id, kept for callers that predate the `type` param. */
+export const SCAFFOLD_VERSION = SCAFFOLD_TEMPLATES["tanstack-start"];
 
 /**
  * The project workspace directory is named after the project UUID -- the
@@ -33,6 +45,18 @@ const scaffoldOptionsSchema = z.object({
 	description: z
 		.string()
 		.describe("One sentence describing the app. Used as the meta description."),
+	type: z
+		.enum(["tanstack-start", "tanstack-router"])
+		.optional()
+		.describe(
+			"Project type. 'tanstack-router': " +
+				"client-only SPA with no server and no database — use it only for " +
+				"pure frontends that talk to external APIs." +
+				"'tanstack-start': SSR app with API routes and a " +
+				"database, KV and bucket — use it whenever the app " +
+				"needs to persist data or run server-side code (experimental, " +
+				"use only if the user expresses a really complexe application idea).",
+		),
 });
 
 /** Kebab-case slug of the product name, for package.json. */
@@ -46,16 +70,17 @@ function slugify(name: string): string {
 }
 
 /**
- * Write the base scaffold by rendering the TanStack Start template into dir,
- * then adding .leo/project.json (template metadata the tool owns, not part of
- * the template tree). Returns the relative paths written.
+ * Write the base scaffold by rendering the template for the requested type
+ * into dir, then adding .leo/project.json (template metadata the tool owns,
+ * not part of the template tree). Returns the relative paths written.
  */
 export async function writeBaseScaffold(
-	{ name, description }: z.infer<typeof scaffoldOptionsSchema>,
+	{ name, description, type }: z.infer<typeof scaffoldOptionsSchema>,
 	dir: string,
 ): Promise<string[]> {
+	const templateId = SCAFFOLD_TEMPLATES[type ?? "tanstack-start"];
 	const created = await renderTemplate(
-		SCAFFOLD_VERSION,
+		templateId,
 		{
 			LEO_NAME: name,
 			LEO_SLUG: slugify(name),
@@ -69,7 +94,7 @@ export async function writeBaseScaffold(
 	const leoPath = path.join(".leo", "project.json");
 	await Bun.write(
 		path.join(dir, leoPath),
-		JSON.stringify({ $schema: 1, scaffold: SCAFFOLD_VERSION }, null, 2),
+		JSON.stringify({ $schema: 1, scaffold: templateId }, null, 2),
 	);
 
 	return [...created, leoPath];
@@ -77,37 +102,60 @@ export async function writeBaseScaffold(
 
 export const scaffold = tool({
 	description:
-		"Scaffold a new TanStack Start project with React 19, SSR, file-based " +
-		"routing, Tailwind v4, shadcn/ui, react-query, and a database, KV and " +
-		"bucket via @helloleo/runtime. Call this first for any new project, " +
-		"before writing routes or components.",
+		"Scaffold a new project with React 19, file-based routing (TanStack), " +
+		"Tailwind v4, shadcn/ui, and react-query. Two types: 'tanstack-start' " +
+		"(SSR, API routes, and a database, KV and bucket via @helloleo/runtime) " +
+		"or 'tanstack-router' (client-only SPA, no server, no database). Call " +
+		"this first for any new project, before writing routes or components.",
 	args: {
 		name: scaffoldOptionsSchema.shape.name,
 		description: scaffoldOptionsSchema.shape.description,
+		type: scaffoldOptionsSchema.shape.type,
 	},
 	async execute(args, context) {
+		const type: ScaffoldType = args.type ?? "tanstack-start";
 		const created = await writeBaseScaffold(args, context.directory);
 		const uiComponents = created.filter((f) =>
 			f.startsWith("src/components/ui/"),
 		);
 		const rest = created.filter((f) => !f.startsWith("src/components/ui/"));
+
+		const typeNotes =
+			type === "tanstack-start"
+				? [
+						"- This is a TanStack Start project. The server entry is src/server.ts. There is no index.html or client entrypoint.",
+						"- For JSON/CRUD APIs, add server routes under src/routes/api/. Read src/routes/api/health.ts first, add routes as needed.",
+						"- The database schema lives in src/db/schema.ts. Migrations run automatically.",
+					]
+				: [
+						"- This is a TanStack Router SPA. The client entry is index.html -> src/main.tsx. There is no server: no API routes, no server functions, no database.",
+						"- Fetch data from external APIs only. If the app needs its own persistence or server-side code, it should have been scaffolded as tanstack-start.",
+					];
+
+		const nextSteps =
+			type === "tanstack-start"
+				? [
+						"Next: read src/routes/index.tsx and continue with the user's request.",
+						"For authentication (password and/or OAuth), call setup_authentication.",
+						"For NetSuite projects, call setup_netsuite.",
+					]
+				: [
+						"Next: read src/routes/index.tsx and continue with the user's request.",
+					];
+
 		return [
 			`Scaffolded ${created.length} files:`,
 			...rest.map((f) => `  - ${f}`),
 			`  - src/components/ui/ (${uiComponents.length} shadcn/ui components)`,
 			"",
 			"Notes:",
-			"- This is a TanStack Start project. The server entry is src/server.ts. There is no index.html or client entrypoint.",
+			...typeNotes,
 			"- Add routes as files in src/routes/. Do not default export route components. Routing and layout conventions are documented in src/routes/README.md, read it before adding routes.",
-			"- For JSON/CRUD APIs, add server routes under src/routes/api/. Read src/routes/api/health.ts first, add routes as needed.",
 			"- shadcn/ui components are already in src/components/ui.",
 			"- Design system: style exclusively with the token utilities, never hardcoded colors. To change the look, edit the token values in src/styles.css (light and dark blocks).",
-			"- The database schema lives in src/db/schema.ts. Migrations run automatically.",
 			"- Always fetch data with react-query (useQuery and useMutation).",
 			"",
-			"Next: read src/routes/index.tsx and continue with the user's request.",
-			"For authentication (password and/or OAuth), call setup_authentication.",
-			"For NetSuite projects, call setup_netsuite.",
+			...nextSteps,
 		].join("\n");
 	},
 });