kitcn 0.12.4 → 0.12.6

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as isColorEnabled, c as EnableRLS, d as TableName, f as createSystemFields, i as highlighter, l as OrmSchemaExtensions, n as getConvexConfig, o as getSchemaRelations, r as logger, s as Columns, t as generateMeta, u as RlsPolicies } from "./codegen-lF80HSWu.mjs";
+import { a as isColorEnabled, c as EnableRLS, d as TableName, f as createSystemFields, i as highlighter, l as OrmSchemaExtensions, n as getConvexConfig, o as getSchemaRelations, r as logger, s as Columns, t as generateMeta, u as RlsPolicies } from "./codegen-B60fOYhd.mjs";
 import { createRequire } from "node:module";
 import fs, { existsSync, readFileSync } from "node:fs";
 import path, { basename, delimiter, dirname, isAbsolute, join, posix, relative, resolve } from "node:path";
@@ -2330,10 +2330,10 @@ function mapFrameworkToScaffoldMode(framework) {
 }
 function resolveProjectScaffoldContext(params = {}) {
 	const cwd = params.cwd ?? process.cwd();
-	const detectedFramework = detectProjectFramework(cwd) ?? (params.template === "next" ? "next-app" : params.template === "vite" ? "vite" : null);
+	const detectedFramework = (params.template === "next" ? "next-app" : params.template === "start" ? "tanstack-start" : params.template === "vite" ? "vite" : null) ?? detectProjectFramework(cwd);
 	if (!detectedFramework) {
 		if (params.allowMissing) return null;
-		throw new Error("Could not detect a supported app scaffold. Supported modes currently start from `next` or `vite`.");
+		throw new Error("Could not detect a supported app scaffold. Supported modes currently start from `next`, `start`, or `vite`.");
 	}
 	let mode;
 	try {
@@ -2451,6 +2451,8 @@ const INIT_TEMPLATE_DEPENDENCY_INSTALL_SPECS = ["superjson"];
 
 //#endregion
 //#region src/cli/registry/dependencies.ts
+const BUN_LOCK_PATH = "bun.lock";
+const BETTER_AUTH_CORE_LOCK_MARKER = "@better-auth/core";
 const findNearestPackageJsonPath$1 = (startDir) => {
 	let current = resolve(startDir);
 	while (true) {
@@ -2479,6 +2481,26 @@ const resolvePackageJsonInstallTarget = () => {
 		packageJson: packageJsonPath ? JSON.parse(fs.readFileSync(packageJsonPath, "utf8")) : null
 	};
 };
+const resolveBunPeerWarningPreinstallSpecs = () => {
+	const { packageJsonPath, packageJson } = resolvePackageJsonInstallTarget();
+	if (!packageJsonPath || !packageJson) return [];
+	if (!(hasDependency(packageJson, "kitcn") || hasDependency(packageJson, "better-auth") || hasDependency(packageJson, "@convex-dev/better-auth"))) return [];
+	if (hasDependency(packageJson, getPackageNameFromInstallSpec(OPENTELEMETRY_API_INSTALL_SPEC))) return [];
+	const bunLockPath = join(dirname(packageJsonPath), BUN_LOCK_PATH);
+	if (!fs.existsSync(bunLockPath)) return [];
+	if (!fs.readFileSync(bunLockPath, "utf8").includes(BETTER_AUTH_CORE_LOCK_MARKER)) return [];
+	return [OPENTELEMETRY_API_INSTALL_SPEC];
+};
+const applyBunPeerWarningPreinstall = async (execaFn) => {
+	const dependencySpecs = resolveBunPeerWarningPreinstallSpecs();
+	if (dependencySpecs.length === 0) return [];
+	const { packageJsonPath } = resolvePackageJsonInstallTarget();
+	await execaFn("bun", ["add", ...dependencySpecs], {
+		cwd: dirname(packageJsonPath),
+		stdio: "inherit"
+	});
+	return dependencySpecs;
+};
 const inspectPluginDependencyInstall = async (params) => {
 	const packageName = params.descriptor.packageName;
 	const packageSpec = resolveSupportedDependencyInstallSpec(params.descriptor.packageInstallSpec ?? params.descriptor.packageName);
@@ -2512,27 +2534,30 @@ const resolveMissingDependencyHints = (dependencyHints) => {
 	return dependencyHints.filter((dependencyHint) => !hasDependency(packageJson, getPackageNameFromInstallSpec(dependencyHint)));
 };
 const applyDependencyHintsInstall = async (dependencyHints, execaFn) => {
-	const missingDependencyHints = resolveMissingDependencyHints(dependencyHints);
-	if (missingDependencyHints.length === 0) return [];
+	const preinstalledSpecs = await applyBunPeerWarningPreinstall(execaFn);
+	const missingDependencyHints = resolveMissingDependencyHints(dependencyHints).filter((dependencyHint) => !preinstalledSpecs.includes(dependencyHint));
+	if (missingDependencyHints.length === 0) return preinstalledSpecs;
 	const { packageJsonPath } = resolvePackageJsonInstallTarget();
 	await execaFn("bun", ["add", ...missingDependencyHints], {
 		cwd: dirname(packageJsonPath),
 		stdio: "inherit"
 	});
-	return missingDependencyHints;
+	return [...preinstalledSpecs, ...missingDependencyHints];
 };
 const applyPlanningDependencyInstall = async (dependencySpecs, execaFn) => {
-	const missingDependencySpecs = resolveMissingDependencyHints(dependencySpecs);
-	if (missingDependencySpecs.length === 0) return [];
+	const preinstalledSpecs = await applyBunPeerWarningPreinstall(execaFn);
+	const missingDependencySpecs = resolveMissingDependencyHints(dependencySpecs).filter((dependencySpec) => !preinstalledSpecs.includes(dependencySpec));
+	if (missingDependencySpecs.length === 0) return preinstalledSpecs;
 	const { packageJsonPath } = resolvePackageJsonInstallTarget();
 	await execaFn("bun", ["add", ...missingDependencySpecs], {
 		cwd: dirname(packageJsonPath),
 		stdio: "inherit"
 	});
-	return missingDependencySpecs;
+	return [...preinstalledSpecs, ...missingDependencySpecs];
 };
 const applyPluginDependencyInstall = async (install, execaFn) => {
 	if (install.skipped || !install.packageName || !install.packageJsonPath) return install;
+	await applyBunPeerWarningPreinstall(execaFn);
 	const packageSpec = install.packageSpec ?? install.packageName;
 	await execaFn("bun", ["add", packageSpec], {
 		cwd: dirname(install.packageJsonPath),
@@ -2723,6 +2748,53 @@ function QueryProvider({ children }: { children: ReactNode }) {
 }
 `;
 
+//#endregion
+//#region src/cli/registry/init/start/init-start-convex-provider.template.ts
+const INIT_START_CONVEX_PROVIDER_TEMPLATE = `'use client';
+
+import { QueryClientProvider as TanstackQueryClientProvider } from '@tanstack/react-query';
+import {
+  ConvexProvider,
+  ConvexReactClient,
+  getConvexQueryClientSingleton,
+  getQueryClientSingleton,
+} from 'kitcn/react';
+import type { ReactNode } from 'react';
+
+import { CRPCProvider } from '@/lib/convex/crpc';
+import { createQueryClient } from '@/lib/convex/query-client';
+
+const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL!);
+
+export function AppConvexProvider({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  return (
+    <ConvexProvider client={convex}>
+      <QueryProvider>{children}</QueryProvider>
+    </ConvexProvider>
+  );
+}
+
+function QueryProvider({ children }: { children: ReactNode }) {
+  const queryClient = getQueryClientSingleton(createQueryClient);
+  const convexQueryClient = getConvexQueryClientSingleton({
+    convex,
+    queryClient,
+  });
+
+  return (
+    <TanstackQueryClientProvider client={queryClient}>
+      <CRPCProvider convexClient={convex} convexQueryClient={convexQueryClient}>
+        {children}
+      </CRPCProvider>
+    </TanstackQueryClientProvider>
+  );
+}
+`;
+
 //#endregion
 //#region src/cli/utils/content-compare.ts
 const AST_COMPARABLE_EXTENSIONS = new Set([
@@ -3195,10 +3267,10 @@ const resolvePluginScaffoldFiles = (templates, roots, functionsDir, existingTemp
 	if (template.target === "lib") rootDir = roots.libRootDir;
 	else if (template.target === "functions") rootDir = roots.functionsRootDir;
 	else if (template.target === "app") {
-		if (!roots.appRootDir) throw new Error(`${descriptor.label} scaffolding requires a supported app baseline. Run \`kitcn init --yes\` in a supported app, or bootstrap one with \`kitcn init -t <next|vite>\` first.`);
+		if (!roots.appRootDir) throw new Error(`${descriptor.label} scaffolding requires a supported app baseline. Run \`kitcn init --yes\` in a supported app, or bootstrap one with \`kitcn init -t <next|start|vite>\` first.`);
 		rootDir = roots.appRootDir;
 	} else {
-		if (!roots.clientLibRootDir) throw new Error(`${descriptor.label} scaffolding requires a supported app baseline. Run \`kitcn init --yes\` in a supported app, or bootstrap one with \`kitcn init -t <next|vite>\` first.`);
+		if (!roots.clientLibRootDir) throw new Error(`${descriptor.label} scaffolding requires a supported app baseline. Run \`kitcn init --yes\` in a supported app, or bootstrap one with \`kitcn init -t <next|start|vite>\` first.`);
 		rootDir = roots.clientLibRootDir;
 	}
 	const mappedLockfilePath = existingTemplatePathMap?.[template.id];
@@ -4159,6 +4231,24 @@ export const authClient = createAuthClient({
   plugins: [convexClient()],
 });
 
+export const {
+  useSignInMutationOptions,
+  useSignOutMutationOptions,
+  useSignUpMutationOptions,
+} = createAuthMutations(authClient);
+`;
+const AUTH_START_CLIENT_TEMPLATE = `import { createAuthClient } from 'better-auth/react';
+import { convexClient } from 'kitcn/auth/client';
+import { createAuthMutations } from 'kitcn/react';
+
+export const authClient = createAuthClient({
+  baseURL:
+    typeof window === 'undefined'
+      ? (import.meta.env.VITE_SITE_URL as string | undefined)
+      : window.location.origin,
+  plugins: [convexClient()],
+});
+
 export const {
   useSignInMutationOptions,
   useSignOutMutationOptions,
@@ -4712,6 +4802,295 @@ export const authSchema = {
 };
 `;
 
+//#endregion
+//#region src/cli/registry/items/auth/auth-start-convex-provider.template.ts
+const AUTH_START_CONVEX_PROVIDER_TEMPLATE = `'use client';
+
+import { QueryClientProvider as TanstackQueryClientProvider } from '@tanstack/react-query';
+import { ConvexAuthProvider } from 'kitcn/auth/client';
+import {
+  ConvexReactClient,
+  getConvexQueryClientSingleton,
+  getQueryClientSingleton,
+  useAuthStore,
+} from 'kitcn/react';
+import type { ReactNode } from 'react';
+
+import { authClient } from '@/lib/convex/auth-client';
+import { CRPCProvider } from '@/lib/convex/crpc';
+import { createQueryClient } from '@/lib/convex/query-client';
+
+const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL!);
+
+export function AppConvexProvider({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  return (
+    <ConvexAuthProvider authClient={authClient} client={convex}>
+      <QueryProvider>{children}</QueryProvider>
+    </ConvexAuthProvider>
+  );
+}
+
+function QueryProvider({ children }: { children: ReactNode }) {
+  const authStore = useAuthStore();
+  const queryClient = getQueryClientSingleton(createQueryClient);
+  const convexQueryClient = getConvexQueryClientSingleton({
+    authStore,
+    convex,
+    queryClient,
+  });
+
+  return (
+    <TanstackQueryClientProvider client={queryClient}>
+      <CRPCProvider convexClient={convex} convexQueryClient={convexQueryClient}>
+        {children}
+      </CRPCProvider>
+    </TanstackQueryClientProvider>
+  );
+}
+`;
+
+//#endregion
+//#region src/cli/registry/items/auth/auth-start-page.template.ts
+const AUTH_START_PAGE_TEMPLATE = `'use client';
+
+import { useMutation } from '@tanstack/react-query';
+import { createFileRoute } from '@tanstack/react-router';
+import { useAuth } from 'kitcn/react';
+import { useState } from 'react';
+
+import {
+  authClient,
+  useSignInMutationOptions,
+  useSignOutMutationOptions,
+  useSignUpMutationOptions,
+} from '@/lib/convex/auth-client';
+
+export const Route = createFileRoute('/auth' as never)({
+  component: AuthPage,
+});
+
+function AuthPage() {
+  const { hasSession, isLoading } = useAuth();
+  const authSession = authClient.useSession();
+  const session = authSession.data;
+  const user = session?.user ?? null;
+  const hasSignedInUser = hasSession || Boolean(user);
+  const [mode, setMode] = useState<'signin' | 'signup'>('signin');
+  const [name, setName] = useState('');
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  const signIn = useMutation(useSignInMutationOptions());
+  const signUp = useMutation(useSignUpMutationOptions());
+  const signOut = useMutation(useSignOutMutationOptions());
+
+  const errorMessage =
+    signIn.error?.message ??
+    signUp.error?.message ??
+    signOut.error?.message ??
+    null;
+  const isPending =
+    signIn.isPending || signUp.isPending || signOut.isPending;
+
+  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+
+    if (mode === 'signup') {
+      signUp.mutate({
+        email,
+        name,
+        password,
+      });
+      return;
+    }
+
+    signIn.mutate({
+      email,
+      password,
+    });
+  }
+
+  if (isLoading && !hasSignedInUser) {
+    return (
+      <main className="mx-auto flex min-h-[60vh] max-w-md items-center px-6 py-16">
+        <p className="text-sm text-muted-foreground">Loading auth…</p>
+      </main>
+    );
+  }
+
+  if (hasSignedInUser) {
+    return (
+      <main className="mx-auto flex min-h-[60vh] max-w-md flex-col justify-center gap-6 px-6 py-16">
+        <div className="space-y-2">
+          <p className="text-sm font-medium text-muted-foreground">Signed in</p>
+          <h1 className="text-3xl font-semibold tracking-tight">
+            {user?.name || user?.email || email}
+          </h1>
+          <p className="text-sm text-muted-foreground">
+            {user?.email || email}
+          </p>
+        </div>
+        <button
+          className="rounded-md bg-foreground px-4 py-2 text-sm font-medium text-background transition hover:opacity-90 disabled:opacity-60"
+          disabled={isPending}
+          onClick={() => signOut.mutate()}
+          type="button"
+        >
+          {signOut.isPending ? 'Signing out…' : 'Sign out'}
+        </button>
+      </main>
+    );
+  }
+
+  return (
+    <main className="mx-auto flex min-h-[60vh] max-w-md flex-col justify-center gap-6 px-6 py-16">
+      <div className="space-y-2">
+        <p className="text-sm font-medium text-muted-foreground">Auth demo</p>
+        <h1 className="text-3xl font-semibold tracking-tight">
+          {mode === 'signup' ? 'Create an account' : 'Sign in'}
+        </h1>
+        <p className="text-sm text-muted-foreground">
+          Minimal Better Auth wiring on top of the init baseline.
+        </p>
+      </div>
+
+      <form className="space-y-3" onSubmit={handleSubmit}>
+        {mode === 'signup' ? (
+          <input
+            autoComplete="name"
+            className="w-full rounded-md border bg-background px-3 py-2 text-sm"
+            onChange={(event) => setName(event.target.value)}
+            placeholder="Name"
+            required
+            type="text"
+            value={name}
+          />
+        ) : null}
+        <input
+          autoComplete="email"
+          className="w-full rounded-md border bg-background px-3 py-2 text-sm"
+          onChange={(event) => setEmail(event.target.value)}
+          placeholder="Email"
+          required
+          type="email"
+          value={email}
+        />
+        <input
+          autoComplete={mode === 'signup' ? 'new-password' : 'current-password'}
+          className="w-full rounded-md border bg-background px-3 py-2 text-sm"
+          minLength={8}
+          onChange={(event) => setPassword(event.target.value)}
+          placeholder="Password"
+          required
+          type="password"
+          value={password}
+        />
+        <button
+          className="w-full rounded-md bg-foreground px-4 py-2 text-sm font-medium text-background transition hover:opacity-90 disabled:opacity-60"
+          disabled={isPending}
+          type="submit"
+        >
+          {isPending
+            ? 'Working…'
+            : mode === 'signup'
+              ? 'Create account'
+              : 'Sign in'}
+        </button>
+      </form>
+
+      <button
+        className="text-left text-sm text-muted-foreground underline-offset-4 hover:underline"
+        onClick={() => setMode(mode === 'signin' ? 'signup' : 'signin')}
+        type="button"
+      >
+        {mode === 'signin'
+          ? "Don't have an account? Sign up"
+          : 'Already have an account? Sign in'}
+      </button>
+
+      {errorMessage ? (
+        <p className="text-sm text-destructive">{errorMessage}</p>
+      ) : null}
+    </main>
+  );
+}
+`;
+
+//#endregion
+//#region src/cli/registry/items/auth/auth-start-route.template.ts
+const AUTH_START_ROUTE_TEMPLATE = `import { createFileRoute } from '@tanstack/react-router';
+
+import { handler } from '@/lib/convex/auth-server';
+
+export const Route = createFileRoute('/api/auth/$' as never)({
+  server: {
+    handlers: {
+      GET: ({ request }) => handler(request),
+      POST: ({ request }) => handler(request),
+    },
+  },
+});
+`;
+
+//#endregion
+//#region src/cli/registry/items/auth/auth-start-server.template.ts
+const AUTH_START_SERVER_TEMPLATE = `import { convexBetterAuthReactStart } from 'kitcn/auth/start';
+
+export const {
+  handler,
+  getToken,
+  fetchAuthQuery,
+  fetchAuthMutation,
+  fetchAuthAction,
+} = convexBetterAuthReactStart({
+  convexUrl: import.meta.env.VITE_CONVEX_URL!,
+  convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
+});
+`;
+
+//#endregion
+//#region src/cli/registry/items/auth/auth-start-server-call.template.ts
+const AUTH_START_SERVER_CALL_TEMPLATE = `import { api } from '@convex/api';
+import { getRequestHeaders } from '@tanstack/react-start/server';
+import { createCallerFactory } from 'kitcn/server';
+
+import { getToken } from '@/lib/convex/auth-server';
+
+const { createContext, createCaller } = createCallerFactory({
+  api,
+  convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
+  auth: {
+    getToken: async () => {
+      return {
+        token: await getToken(),
+      };
+    },
+  },
+});
+
+type ServerCaller = ReturnType<typeof createCaller>;
+
+async function makeContext() {
+  const headers = await getRequestHeaders();
+  return createContext({ headers });
+}
+
+function createServerCaller(): ServerCaller {
+  return createCaller(async () => {
+    return await makeContext();
+  });
+}
+
+export function runServerCall<T>(fn: (caller: ServerCaller) => Promise<T> | T) {
+  const caller = createServerCaller();
+  return fn(caller);
+}
+`;
+
 //#endregion
 //#region src/auth/auth-config.ts
 const createPublicJwks = (jwks, options) => {
@@ -5493,11 +5872,21 @@ app.use(
 		updateReason: "Register auth middleware in http.ts.",
 		skipReason: "Auth middleware is already registered in http.ts."
 	});
-}
-function buildAuthProviderPlanFile(params) {
-	if (!params.roots.projectContext) throw new Error("Auth scaffolding requires a supported app baseline. Run `kitcn init --yes` in a supported app, or bootstrap one with `kitcn init -t <next|vite>` first.");
-	const providerPath = resolve(process.cwd(), params.roots.projectContext.convexClientDir, "convex-provider.tsx");
-	const isNextApp = params.roots.projectContext.mode === "next-app";
+}
+function buildAuthProviderPlanFile(params) {
+	const projectContext = params.roots.projectContext;
+	if (!projectContext) throw new Error("Auth scaffolding requires a supported app baseline. Run `kitcn init --yes` in a supported app, or bootstrap one with `kitcn init -t <next|start|vite>` first.");
+	if (projectContext.framework === "tanstack-start") return createPlanFile({
+		kind: "scaffold",
+		filePath: resolve(process.cwd(), projectContext.convexClientDir, "convex-provider.tsx"),
+		content: AUTH_START_CONVEX_PROVIDER_TEMPLATE,
+		managedBaselineContent: INIT_START_CONVEX_PROVIDER_TEMPLATE,
+		createReason: "Create auth-aware kitcn provider for the app scaffold.",
+		updateReason: "Update kitcn provider with auth-aware client wiring.",
+		skipReason: "kitcn provider already matches the auth scaffold."
+	});
+	const providerPath = resolve(process.cwd(), projectContext.convexClientDir, "convex-provider.tsx");
+	const isNextApp = projectContext.mode === "next-app";
 	return createPlanFile({
 		kind: "scaffold",
 		filePath: providerPath,
@@ -5533,6 +5922,54 @@ function buildAuthNextRoutePlanFile(params) {
 		skipReason: "The Next auth proxy route already exists."
 	});
 }
+function buildAuthStartServerPlanFile(params) {
+	const projectContext = params.roots.projectContext;
+	if (!projectContext || projectContext.framework !== "tanstack-start") throw new Error("Auth scaffolding requires a supported TanStack Start shell.");
+	return createPlanFile({
+		kind: "scaffold",
+		filePath: resolve(process.cwd(), projectContext.convexClientDir, "auth-server.ts"),
+		content: AUTH_START_SERVER_TEMPLATE,
+		createReason: "Create auth-aware Start server helpers.",
+		updateReason: "Update Start server helpers with auth route support.",
+		skipReason: "Start server helpers already include auth route support."
+	});
+}
+function buildAuthStartRoutePlanFile(params) {
+	const projectContext = params.roots.projectContext;
+	if (!projectContext || projectContext.framework !== "tanstack-start") throw new Error("Auth scaffolding requires a supported TanStack Start shell.");
+	return createPlanFile({
+		kind: "scaffold",
+		filePath: resolve(process.cwd(), projectContext.usesSrc ? "src" : "", "routes", "api", "auth", "$.ts"),
+		content: AUTH_START_ROUTE_TEMPLATE,
+		createReason: "Create the Start auth proxy route.",
+		updateReason: "Update the Start auth proxy route.",
+		skipReason: "The Start auth proxy route already exists."
+	});
+}
+function buildAuthStartServerCallPlanFile(params) {
+	const projectContext = params.roots.projectContext;
+	if (!projectContext || projectContext.framework !== "tanstack-start") throw new Error("Auth scaffolding requires a supported TanStack Start shell.");
+	return createPlanFile({
+		kind: "scaffold",
+		filePath: resolve(process.cwd(), projectContext.convexClientDir, "server.ts"),
+		content: AUTH_START_SERVER_CALL_TEMPLATE,
+		createReason: "Create auth-aware Start server caller helpers.",
+		updateReason: "Update Start server caller helpers with auth token wiring.",
+		skipReason: "Start server caller helpers already include auth token wiring."
+	});
+}
+function buildAuthStartPagePlanFile(params) {
+	const projectContext = params.roots.projectContext;
+	if (!projectContext || projectContext.framework !== "tanstack-start") throw new Error("Auth scaffolding requires a supported TanStack Start shell.");
+	return createPlanFile({
+		kind: "scaffold",
+		filePath: resolve(process.cwd(), projectContext.usesSrc ? "src" : "", "routes", "auth.tsx"),
+		content: AUTH_START_PAGE_TEMPLATE,
+		createReason: "Create the Start auth demo route.",
+		updateReason: "Update the Start auth demo route.",
+		skipReason: "The Start auth demo route already exists."
+	});
+}
 function buildAuthConvexLocalEnvPlanFile(params) {
 	const envPath = resolve(params.functionsDir, ".env");
 	return createPlanFile({
@@ -5669,6 +6106,13 @@ const authRegistryItem = defineInternalRegistryItem({
 			})),
 			resolveTemplates: ({ roots, templates }) => {
 				if (!roots.projectContext || roots.projectContext.mode === "next-app") return templates;
+				if (roots.projectContext.framework === "tanstack-start") return templates.filter((template) => template.id !== "auth-page" && template.id !== "auth-page-convex").map((template) => {
+					if (template.id === "auth-client") return {
+						...template,
+						content: AUTH_START_CLIENT_TEMPLATE
+					};
+					return template;
+				});
 				return templates.filter((template) => template.id !== "auth-page" && template.id !== "auth-page-convex").map((template) => {
 					if (template.id === "auth-client") return {
 						...template,
@@ -5694,6 +6138,7 @@ const authRegistryItem = defineInternalRegistryItem({
 					buildAuthProviderPlanFile(params)
 				];
 				if (roots.projectContext?.mode === "next-app") files.push(buildAuthNextServerPlanFile(params), buildAuthNextRoutePlanFile(params));
+				else if (roots.projectContext?.framework === "tanstack-start") files.push(buildAuthStartServerPlanFile(params), buildAuthStartRoutePlanFile(params), buildAuthStartServerCallPlanFile(params), buildAuthStartPagePlanFile(params));
 				return files;
 			},
 			buildSchemaRegistrationPlanFile: ({ applyScope, config, functionsDir, lockfile, overwrite, preset, preview, promptAdapter, roots, yes }) => buildAuthSchemaRegistrationPlanFile({
@@ -7379,6 +7824,8 @@ function renderInitConvexTsconfigTemplate(functionsDirRelative = "convex/functio
 			forceConsistentCasingInFileNames: true,
 			isolatedModules: true,
 			skipLibCheck: true,
+			noUnusedLocals: false,
+			noUnusedParameters: false,
 			noEmit: true,
 			jsx: "react-jsx",
 			lib: ["esnext", "dom"],
@@ -7577,7 +8024,10 @@ const INIT_NEXT_CONVEX_DEV_SCRIPT_NAME = "convex:dev";
 const INIT_NEXT_CONVEX_DEV_SCRIPT = "kitcn dev";
 const INIT_NEXT_CONVEX_TYPECHECK_SCRIPT_NAME = "typecheck:convex";
 const getInitNextConvexTypecheckScript = (functionsDirRelative = "convex/functions") => `tsc --noEmit --project ${functionsDirRelative}/tsconfig.json`;
-const INIT_NEXT_PACKAGE_JSON_DEPENDENCIES = { superjson: "2.2.6" };
+const INIT_NEXT_PACKAGE_JSON_DEPENDENCIES = {
+	"@opentelemetry/api": SUPPORTED_DEPENDENCY_VERSIONS.opentelemetryApi.exact,
+	superjson: "2.2.6"
+};
 const INIT_NEXT_PACKAGE_JSON_DEV_DEPENDENCIES = { "@types/bun": "latest" };
 const getInitNextPackageJsonDevDependencies = (options) => ({
 	...INIT_NEXT_PACKAGE_JSON_DEV_DEPENDENCIES,
@@ -7786,7 +8236,10 @@ const INIT_REACT_CONVEX_DEV_SCRIPT_NAME = "convex:dev";
 const INIT_REACT_CONVEX_DEV_SCRIPT = "kitcn dev";
 const INIT_REACT_CONVEX_TYPECHECK_SCRIPT_NAME = "typecheck:convex";
 const getInitReactConvexTypecheckScript = (functionsDirRelative = "convex/functions") => `tsc --noEmit --project ${functionsDirRelative}/tsconfig.json`;
-const INIT_REACT_PACKAGE_JSON_DEPENDENCIES = { superjson: "2.2.6" };
+const INIT_REACT_PACKAGE_JSON_DEPENDENCIES = {
+	"@opentelemetry/api": SUPPORTED_DEPENDENCY_VERSIONS.opentelemetryApi.exact,
+	superjson: "2.2.6"
+};
 const INIT_REACT_PACKAGE_JSON_DEV_DEPENDENCIES = { "@types/bun": "latest" };
 const getInitReactPackageJsonDevDependencies = (options) => ({
 	...INIT_REACT_PACKAGE_JSON_DEV_DEPENDENCIES,
@@ -7827,6 +8280,203 @@ export function Providers({ children }: { children: ReactNode }) {
 }
 `;
 
+//#endregion
+//#region src/cli/registry/init/start/init-start-crpc.template.ts
+const INIT_START_CRPC_TEMPLATE = `import { api } from '@convex/api';
+import { createCRPCContext } from 'kitcn/react';
+
+export const { CRPCProvider, useCRPC, useCRPCClient } = createCRPCContext({
+  api,
+  convexSiteUrl: import.meta.env.VITE_CONVEX_SITE_URL!,
+});
+`;
+
+//#endregion
+//#region src/cli/registry/init/start/init-start-messages-page.template.ts
+const INIT_START_MESSAGES_PAGE_TEMPLATE = `'use client';
+
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { createFileRoute } from '@tanstack/react-router';
+import { type FormEvent, useState } from 'react';
+
+import { Button } from '@/components/ui/button';
+import { useCRPC } from '@/lib/convex/crpc';
+
+export const Route = createFileRoute('/')({
+  component: ConvexMessagesPage,
+});
+
+function ConvexMessagesPage() {
+  const crpc = useCRPC();
+  const [draft, setDraft] = useState('');
+  const messagesQuery = useQuery(crpc.messages.list.queryOptions());
+  const createMessage = useMutation(crpc.messages.create.mutationOptions());
+
+  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const body = draft.trim();
+    if (!body) return;
+
+    try {
+      await createMessage.mutateAsync({ body });
+      setDraft('');
+    } catch {}
+  }
+
+  return (
+    <main className="mx-auto flex min-h-svh w-full max-w-2xl flex-col gap-6 px-6 py-10 text-sm">
+      <header className="space-y-2">
+        <p className="font-mono text-xs uppercase tracking-[0.2em] text-muted-foreground">
+          kitcn
+        </p>
+        <h1 className="font-medium text-2xl tracking-tight">Messages</h1>
+        <p className="max-w-xl text-muted-foreground leading-6">
+          This page is a tiny live query and mutation over kitcn. Start the
+          backend, send a message, and watch the list update.
+        </p>
+      </header>
+
+      <form className="flex flex-col gap-3 sm:flex-row" onSubmit={handleSubmit}>
+        <input
+          className="min-h-10 flex-1 rounded-md border border-border bg-background px-3 py-2 outline-none transition-colors focus:border-primary"
+          maxLength={120}
+          onChange={(event) => setDraft(event.target.value)}
+          placeholder="Write a message"
+          value={draft}
+        />
+        <Button disabled={createMessage.isPending || draft.trim().length === 0} type="submit">
+          {createMessage.isPending ? 'Saving...' : 'Add message'}
+        </Button>
+      </form>
+
+      {messagesQuery.isPending ? (
+        <p className="text-muted-foreground">Loading messages...</p>
+      ) : messagesQuery.isError ? (
+        <div className="rounded-md border border-dashed border-border px-4 py-3 text-muted-foreground leading-6">
+          Backend not ready. Start <code>kitcn dev</code> and refresh.
+        </div>
+      ) : messagesQuery.data.length === 0 ? (
+        <div className="rounded-md border border-dashed border-border px-4 py-6 text-muted-foreground">
+          No messages yet. Add the first one.
+        </div>
+      ) : (
+        <ul className="space-y-3">
+          {messagesQuery.data.map((message) => (
+            <li
+              className="rounded-md border border-border bg-background px-4 py-3"
+              key={message.id}
+            >
+              <div className="flex items-start justify-between gap-3">
+                <p className="leading-6">{message.body}</p>
+                <time className="shrink-0 font-mono text-xs text-muted-foreground">
+                  {message.createdAt.toLocaleTimeString()}
+                </time>
+              </div>
+            </li>
+          ))}
+        </ul>
+      )}
+    </main>
+  );
+}
+`;
+
+//#endregion
+//#region src/cli/registry/init/start/init-start-root.template.ts
+const INIT_START_ROOT_TEMPLATE = `import {
+  HeadContent,
+  Outlet,
+  Scripts,
+  createRootRoute,
+} from '@tanstack/react-router';
+import { TanStackDevtools } from '@tanstack/react-devtools';
+import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools';
+
+import { Providers } from '@/components/providers';
+import appCss from '../styles.css?url';
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      {
+        charSet: 'utf-8',
+      },
+      {
+        name: 'viewport',
+        content: 'width=device-width, initial-scale=1',
+      },
+      {
+        title: 'TanStack Start Starter',
+      },
+    ],
+    links: [
+      {
+        rel: 'stylesheet',
+        href: appCss,
+      },
+    ],
+  }),
+  component: RootComponent,
+  shellComponent: RootDocument,
+});
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <TanStackDevtools
+          config={{
+            position: 'bottom-right',
+          }}
+          plugins={[
+            {
+              name: 'Tanstack Router',
+              render: <TanStackRouterDevtoolsPanel />,
+            },
+          ]}
+        />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+function RootComponent() {
+  return (
+    <Providers>
+      <Outlet />
+    </Providers>
+  );
+}
+`;
+
+//#endregion
+//#region src/cli/registry/init/start/init-start-router.template.ts
+const INIT_START_ROUTER_TEMPLATE = `import { createRouter } from '@tanstack/react-router';
+import { routeTree } from './routeTree.gen';
+
+export function getRouter() {
+  const router = createRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreload: 'intent',
+    defaultPreloadStaleTime: 0,
+  });
+
+  return router;
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>;
+  }
+}
+`;
+
 //#endregion
 //#region src/cli/registry/selection.ts
 const getPluginDisplayHint = (descriptor) => descriptor.presets[0]?.description;
@@ -8288,6 +8938,7 @@ const realConvex = join(dirname(require.resolve("convex/package.json")), "bin/ma
 const MISSING_BACKFILL_FUNCTION_RE = /could not find function|function .* was not found|unknown function/i;
 const GITIGNORE_RUNTIME_ENTRIES = [".convex/", ".concave/"];
 const TS_EXTENSION_RE = /\.ts$/;
+const LEADING_SLASHES_RE = /^\/+/;
 const AGGREGATE_STATE_RELATIVE_PATH = join(".convex", "kitcn", "aggregate-backfill-state.json");
 const AGGREGATE_STATE_VERSION = 1;
 const INIT_SHADCN_PACKAGE_SPEC = "shadcn@4.0.1";
@@ -8323,7 +8974,11 @@ const VALID_SCOPES = new Set([
 const VALID_BACKENDS = new Set(["convex", "concave"]);
 const SUPPORTED_PLUGINS = new Set(getSupportedPluginKeys());
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const SUPPORTED_INIT_TEMPLATES = ["next", "vite"];
+const SUPPORTED_INIT_TEMPLATES = [
+	"next",
+	"start",
+	"vite"
+];
 const REACT_APP_MOUNT_RE = /<App\s*\/>/;
 const DOCS_BASE_URL = "https://kitcn.vercel.app/docs";
 const CORE_DOC_TOPICS = {
@@ -8918,9 +9573,129 @@ function buildInitReactOwnedScaffoldFiles(context, functionsDirRelative, backend
 		}
 	];
 }
+function buildInitStartOwnedScaffoldFiles(context, functionsDirRelative, backend, includeDemoFiles) {
+	const rootPrefix = context.usesSrc ? "src" : "";
+	const files = [
+		{
+			kind: "config",
+			relativePath: "package.json",
+			requiresExplicitOverwrite: false,
+			content: ({ existingContent }) => renderInitReactPackageJsonTemplate(existingContent, {
+				backend,
+				functionsDirRelative
+			}),
+			createReason: "Create baseline package.json scripts for the Start scaffold.",
+			updateReason: "Update package.json scripts for the Start scaffold.",
+			skipReason: "package.json scripts already match the Start scaffold."
+		},
+		{
+			kind: "env",
+			relativePath: ".env.local",
+			requiresExplicitOverwrite: false,
+			content: ({ existingContent }) => renderInitReactEnvLocalTemplate(existingContent),
+			createReason: "Create baseline .env.local for the Start scaffold.",
+			updateReason: "Update baseline .env.local for the Start scaffold.",
+			skipReason: ".env.local already matches the Start scaffold."
+		},
+		{
+			kind: "scaffold",
+			relativePath: `${context.componentsDir}/providers.tsx`,
+			requiresExplicitOverwrite: true,
+			content: INIT_REACT_PROVIDERS_TEMPLATE,
+			createReason: `Create baseline ${context.componentsDir}/providers.tsx for the Start scaffold.`,
+			updateReason: `Update ${context.componentsDir}/providers.tsx for the Start scaffold.`,
+			skipReason: `${context.componentsDir}/providers.tsx already matches the Start scaffold.`
+		},
+		{
+			kind: "scaffold",
+			relativePath: `${context.convexClientDir}/query-client.ts`,
+			requiresExplicitOverwrite: true,
+			content: INIT_NEXT_QUERY_CLIENT_TEMPLATE,
+			createReason: `Create baseline ${context.convexClientDir}/query-client.ts for the Start scaffold.`,
+			updateReason: `Update ${context.convexClientDir}/query-client.ts for the Start scaffold.`,
+			skipReason: `${context.convexClientDir}/query-client.ts already matches the Start scaffold.`
+		},
+		{
+			kind: "scaffold",
+			relativePath: `${context.convexClientDir}/crpc.tsx`,
+			requiresExplicitOverwrite: true,
+			content: INIT_START_CRPC_TEMPLATE,
+			createReason: `Create baseline ${context.convexClientDir}/crpc.tsx for the Start scaffold.`,
+			updateReason: `Update ${context.convexClientDir}/crpc.tsx for the Start scaffold.`,
+			skipReason: `${context.convexClientDir}/crpc.tsx already matches the Start scaffold.`
+		},
+		{
+			kind: "scaffold",
+			relativePath: `${context.convexClientDir}/convex-provider.tsx`,
+			requiresExplicitOverwrite: true,
+			content: INIT_START_CONVEX_PROVIDER_TEMPLATE,
+			preserveManagedContent: [AUTH_START_CONVEX_PROVIDER_TEMPLATE],
+			createReason: `Create baseline ${context.convexClientDir}/convex-provider.tsx for the Start scaffold.`,
+			updateReason: `Update ${context.convexClientDir}/convex-provider.tsx for the Start scaffold.`,
+			skipReason: `${context.convexClientDir}/convex-provider.tsx already matches the Start scaffold.`
+		},
+		{
+			kind: "scaffold",
+			relativePath: trimLeadingSlashes(posix.join(rootPrefix, "router.tsx")),
+			requiresExplicitOverwrite: true,
+			content: INIT_START_ROUTER_TEMPLATE,
+			createReason: `Create baseline ${trimLeadingSlashes(posix.join(rootPrefix, "router.tsx"))} for the Start scaffold.`,
+			updateReason: `Update ${trimLeadingSlashes(posix.join(rootPrefix, "router.tsx"))} for the Start scaffold.`,
+			skipReason: `${trimLeadingSlashes(posix.join(rootPrefix, "router.tsx"))} already matches the Start scaffold.`
+		},
+		{
+			kind: "scaffold",
+			relativePath: trimLeadingSlashes(posix.join(rootPrefix, "routes", "__root.tsx")),
+			requiresExplicitOverwrite: true,
+			content: INIT_START_ROOT_TEMPLATE,
+			createReason: `Create baseline ${trimLeadingSlashes(posix.join(rootPrefix, "routes", "__root.tsx"))} for the Start scaffold.`,
+			updateReason: `Update ${trimLeadingSlashes(posix.join(rootPrefix, "routes", "__root.tsx"))} for the Start scaffold.`,
+			skipReason: `${trimLeadingSlashes(posix.join(rootPrefix, "routes", "__root.tsx"))} already matches the Start scaffold.`
+		},
+		{
+			kind: "config",
+			relativePath: join(functionsDirRelative, "tsconfig.json"),
+			managedBaselineContent: getManagedConvexTsconfigBaselines(functionsDirRelative),
+			requiresExplicitOverwrite: true,
+			content: ({ existingContent }) => typeof existingContent === "string" ? patchInitConvexTsconfigContent(existingContent, functionsDirRelative) : renderInitConvexTsconfigTemplate(functionsDirRelative),
+			createReason: `Create ${join(functionsDirRelative, "tsconfig.json")} for kitcn functions.`,
+			updateReason: `Patch ${join(functionsDirRelative, "tsconfig.json")} for kitcn functions.`,
+			skipReason: `${join(functionsDirRelative, "tsconfig.json")} already matches the kitcn functions project.`
+		}
+	];
+	if (includeDemoFiles) files.push({
+		kind: "scaffold",
+		relativePath: trimLeadingSlashes(posix.join(rootPrefix, "routes", "index.tsx")),
+		requiresExplicitOverwrite: false,
+		content: INIT_START_MESSAGES_PAGE_TEMPLATE,
+		createReason: `Create ${trimLeadingSlashes(posix.join(rootPrefix, "routes", "index.tsx"))} as the minimal kitcn demo route.`,
+		updateReason: `Update ${trimLeadingSlashes(posix.join(rootPrefix, "routes", "index.tsx"))} for the kitcn demo route.`,
+		skipReason: `${trimLeadingSlashes(posix.join(rootPrefix, "routes", "index.tsx"))} already matches the kitcn demo route.`
+	}, {
+		kind: "schema",
+		relativePath: `${functionsDirRelative}/schema.ts`,
+		requiresExplicitOverwrite: true,
+		content: INIT_NEXT_SCHEMA_TEMPLATE,
+		createReason: `Create ${functionsDirRelative}/schema.ts with the minimal kitcn demo schema.`,
+		updateReason: `Update ${functionsDirRelative}/schema.ts with the minimal kitcn demo schema.`,
+		skipReason: `${functionsDirRelative}/schema.ts already matches the kitcn demo schema.`
+	}, {
+		kind: "scaffold",
+		relativePath: `${functionsDirRelative}/messages.ts`,
+		requiresExplicitOverwrite: true,
+		content: renderInitNextMessagesTemplate(functionsDirRelative),
+		createReason: `Create ${functionsDirRelative}/messages.ts for the kitcn demo route.`,
+		updateReason: `Update ${functionsDirRelative}/messages.ts for the kitcn demo route.`,
+		skipReason: `${functionsDirRelative}/messages.ts already matches the kitcn demo route.`
+	});
+	return files;
+}
 function detectImportQuote(source) {
 	return source.match(INIT_NEXT_IMPORT_QUOTE_RE)?.[1] === "'" ? "'" : "\"";
 }
+function trimLeadingSlashes(value) {
+	return value.replace(LEADING_SLASHES_RE, "");
+}
 function detectStatementTerminator(source) {
 	return INIT_NEXT_IMPORT_SEMICOLON_RE.test(source) ? ";" : "";
 }
@@ -8963,6 +9738,25 @@ function patchInitTsconfigContent(source, context) {
 		}
 	}, null, 2)}\n`;
 }
+function patchInitStartTsconfigContent(source, context) {
+	const parsedResult = ts.parseConfigFileTextToJson("tsconfig.json", source);
+	if (parsedResult.error || parsedResult.config === void 0) throw new Error("Could not patch tsconfig.json: expected valid JSON or JSONC scaffold output.");
+	const parsed = parsedResult.config;
+	if (!isPlainObject(parsed)) throw new Error("Could not patch tsconfig.json: expected a top-level JSON object.");
+	const compilerOptions = isPlainObject(parsed.compilerOptions) ? { ...parsed.compilerOptions } : {};
+	const paths = isPlainObject(compilerOptions.paths) ? { ...compilerOptions.paths } : {};
+	if (!("@/*" in paths)) paths["@/*"] = [context.tsconfigAliasPath];
+	paths["@convex/*"] = ["./convex/shared/*"];
+	return `${JSON.stringify({
+		...parsed,
+		compilerOptions: {
+			...compilerOptions,
+			strictFunctionTypes: false,
+			paths
+		},
+		...context.usesSrc ? { include: ["src"] } : {}
+	}, null, 2)}\n`;
+}
 function patchInitConvexTsconfigContent(source, functionsDirRelative) {
 	const parsedResult = ts.parseConfigFileTextToJson("tsconfig.json", source);
 	if (parsedResult.error || parsedResult.config === void 0) throw new Error("Could not patch Convex tsconfig.json: expected valid JSON or JSONC scaffold output.");
@@ -9074,6 +9868,7 @@ function patchInitReactMainContent(source) {
 }
 function patchInitReactViteConfigContent(source) {
 	if (source.includes("'@convex'") || source.includes("\"@convex\"")) return source.endsWith("\n") ? source : `${source}\n`;
+	if (source.includes("viteTsConfigPaths(") || source.includes("tsConfigPaths(")) return source.endsWith("\n") ? source : `${source}\n`;
 	if (!source.includes("alias: {")) throw new Error("Could not patch vite.config.ts: expected a resolve.alias block.");
 	const nextSource = source.replace("alias: {", `alias: {\n      '@convex': path.resolve(__dirname, './convex/shared'),`);
 	return nextSource.endsWith("\n") ? nextSource : `${nextSource}\n`;
@@ -9133,7 +9928,7 @@ function buildInitReactRootTsconfigPlanFile(context) {
 		kind: "config",
 		filePath,
 		requiresExplicitOverwrite: false,
-		content: patchInitTsconfigContent(fs.readFileSync(filePath, "utf8"), context),
+		content: context.framework === "tanstack-start" ? patchInitStartTsconfigContent(fs.readFileSync(filePath, "utf8"), context) : patchInitTsconfigContent(fs.readFileSync(filePath, "utf8"), context),
 		updateReason: "Patch tsconfig.json to keep the app alias and add @convex/*.",
 		createReason: "Patch tsconfig.json to keep the app alias and add @convex/*.",
 		skipReason: "tsconfig.json already includes the kitcn alias."
@@ -9225,7 +10020,7 @@ function buildTemplateInitializationPlanFiles(params) {
 		allowUnsupported: true
 	});
 	if (!projectContext) return [];
-	const plannedOwnedFiles = (projectContext.mode === "next-app" ? buildInitNextOwnedScaffoldFiles(projectContext, params.functionsDirRelative, params.backend, params.includeDemoFiles) : buildInitReactOwnedScaffoldFiles(projectContext, params.functionsDirRelative, params.backend)).map((file) => {
+	const plannedOwnedFiles = (projectContext.mode === "next-app" ? buildInitNextOwnedScaffoldFiles(projectContext, params.functionsDirRelative, params.backend, params.includeDemoFiles) : projectContext.framework === "tanstack-start" ? buildInitStartOwnedScaffoldFiles(projectContext, params.functionsDirRelative, params.backend, params.includeDemoFiles) : buildInitReactOwnedScaffoldFiles(projectContext, params.functionsDirRelative, params.backend)).map((file) => {
 		const filePath = resolve(process.cwd(), file.relativePath);
 		const existingContent = fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf8") : void 0;
 		const nextContent = typeof file.content === "function" ? file.content({ existingContent }) : file.content;
@@ -9255,6 +10050,11 @@ function buildTemplateInitializationPlanFiles(params) {
 			buildInitNextLayoutPlanFile(projectContext)
 		];
 	}
+	if (projectContext.framework === "tanstack-start") return [
+		...plannedOwnedFiles,
+		buildInitReactRootTsconfigPlanFile(projectContext),
+		...buildInitReactViteConfigPlanFile(projectContext)
+	];
 	return [
 		...plannedOwnedFiles,
 		buildInitReactRootTsconfigPlanFile(projectContext),
@@ -9483,7 +10283,7 @@ async function runScaffoldCommandFlow(params) {
 			template: params.template
 		});
 		const applyResult = await applyPluginInstallPlanFiles(initPlan.files, {
-			overwrite: Boolean(params.overwrite),
+			overwrite: Boolean(params.overwrite) || params.template !== void 0,
 			yes: params.yes || Boolean(params.defaults),
 			promptAdapter: params.promptAdapter
 		});
@@ -9533,7 +10333,7 @@ async function runInitCommandFlow(params) {
 		allowUnsupported: true
 	});
 	if (template !== void 0 || params.initArgs.defaults || params.initArgs.name !== void 0) {
-		if (!template) throw new Error("Fresh app scaffolding requires `kitcn init -t <next|vite>`.");
+		if (!template) throw new Error("Fresh app scaffolding requires `kitcn init -t <next|start|vite>`.");
 		if (existingProjectContext) throw new Error(`Existing supported app scaffold detected. Run \`kitcn init --yes\` in ${normalizePath(relative(process.cwd(), projectDir) || ".")} to adopt the current project.`);
 		return runScaffoldCommandFlow({
 			allowCodegenBootstrapFallback: !params.initArgs.json,
@@ -9555,7 +10355,7 @@ async function runInitCommandFlow(params) {
 			realConcavePath: params.realConcavePath
 		});
 	}
-	if (!existingProjectContext) throw new Error("Could not detect a supported app scaffold. Use `kitcn init -t <next|vite>` for a fresh app.");
+	if (!existingProjectContext) throw new Error("Could not detect a supported app scaffold. Use `kitcn init -t <next|start|vite>` for a fresh app.");
 	return runScaffoldCommandFlow({
 		allowCodegenBootstrapFallback: !params.initArgs.json,
 		projectDir,
@@ -10008,7 +10808,7 @@ async function runConvexInitIfNeeded(params) {
 		stdout: "",
 		stderr: ""
 	};
-	const shouldUseAnonymousAgentMode = params.yes && !hasRemoteConvexInitTargetArgs(params.targetArgs);
+	const agentModeOverride = params.yes && !hasRemoteConvexInitTargetArgs(params.targetArgs) ? "anonymous" : params.env?.CONVEX_AGENT_MODE;
 	const result = normalizeConvexCommandResult(await params.execaFn(params.backendAdapter.command, [
 		...params.backendAdapter.argsPrefix,
 		"init",
@@ -10017,7 +10817,7 @@ async function runConvexInitIfNeeded(params) {
 		cwd: process.cwd(),
 		env: createBackendCommandEnv({
 			...params.env,
-			CONVEX_AGENT_MODE: shouldUseAnonymousAgentMode ? "anonymous" : params.env?.CONVEX_AGENT_MODE
+			...agentModeOverride ? { CONVEX_AGENT_MODE: agentModeOverride } : {}
 		}),
 		reject: false,
 		stdio: "pipe"
@@ -11953,6 +12753,7 @@ const handleAddCommand = async (argv, deps = {}) => {
 			templates: selectedTemplates
 		})) throw new Error(AUTH_SCHEMA_ONLY_MISSING_ERROR);
 	}
+	if (rawConvexAuthPreset && !addArgs.dryRun) assertRawConvexAuthDeploymentReady();
 	if (!addArgs.dryRun) await applyPlanningDependencyInstall(pluginDescriptor.planningDependencies ?? [], execaFn);
 	const plan = filterPluginInstallPlanForAddScope({
 		plan: await buildPluginInstallPlan({
@@ -11995,7 +12796,6 @@ const handleAddCommand = async (argv, deps = {}) => {
 		else logger.write(formatPlanSummary(plan));
 		return 0;
 	}
-	if (rawConvexAuthPreset) assertRawConvexAuthDeploymentReady();
 	const applyResult = await applyPluginInstallPlanFiles(plan.files, {
 		overwrite: addArgs.overwrite,
 		yes: addArgs.yes,
@@ -12618,7 +13418,7 @@ const INIT_LOCAL_BOOTSTRAP_PROMPT = "Run one-shot local Convex bootstrap after i
 const INIT_HELP_TEXT = `Usage: kitcn init [options]
 
 Options:
-  --template, -t    App template ("next" or "vite") for fresh app scaffolding
+  --template, -t    App template ("next", "start", or "vite") for fresh app scaffolding
   --cwd             Target directory (or parent when used with --name)
   --name            Project name when scaffolding a fresh app
   --prod            Forward to \`convex init\`
@@ -13088,7 +13888,7 @@ const __filename = fileURLToPath(import.meta.url);
 const HELP_FLAGS = new Set(["--help", "-h"]);
 const VERSION_FLAGS = new Set(["--version", "-v"]);
 const packageJson = readOwnPackageJson(import.meta.url);
-const REMOVED_CREATE_MESSAGE = "Removed `kitcn create`. Use `kitcn init -t <next|vite>` for fresh app scaffolding.";
+const REMOVED_CREATE_MESSAGE = "Removed `kitcn create`. Use `kitcn init -t <next|start|vite>` for fresh app scaffolding.";
 const LOCAL_NODE_REEXEC_ENV = "KITCN_NODE_REEXEC";
 const LOCAL_NODE_REEXEC_COMMANDS = new Set([
 	"add",