@agent-native/core 0.176.1 → 0.176.2-nightly-20260831184159

package/src/templates/chat/app/root.tsx

@@ -21,6 +21,7 @@ import {
   Outlet,
   Scripts,
   ScrollRestoration,
+  useLocation,
   useNavigate,
 } from "react-router";
 import type { LinksFunction } from "react-router";
@@ -153,11 +154,23 @@ function AppContent() {
 
 export default function Root() {
   const [queryClient] = useState(() => createAgentNativeQueryClient());
+  const location = useLocation();
+  const isMarketingPath = location.pathname === "/";
   return (
     <AppToolkitProvider>
-      <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
-        <DbSyncSetup />
-        <AppContent />
+      <AppProviders
+        queryClient={queryClient}
+        isPublicPath={isMarketingPath}
+        i18n={{ catalog: i18nCatalog }}
+      >
+        {isMarketingPath ? (
+          <Outlet />
+        ) : (
+          <>
+            <DbSyncSetup />
+            <AppContent />
+          </>
+        )}
       </AppProviders>
     </AppToolkitProvider>
   );

package/src/templates/chat/app/routes/_index.tsx

@@ -1,25 +1,16 @@
-import {
-  AgentChatSurface,
-  markAgentChatHomeHandoff,
-} from "@agent-native/core/client/agent-chat";
-import { useT } from "@agent-native/core/client/i18n";
-import { useEffect } from "react";
-import { useNavigate, useParams } from "react-router";
+import { appPath } from "@agent-native/core/client/api-path";
+import { MarketingHome } from "@agent-native/toolkit/marketing";
 
 import { APP_TITLE } from "@/lib/app-config";
-import { TAB_ID } from "@/lib/tab-id";
 
-const SEO_TITLE = `${APP_TITLE} - Open Source AI app starter with actions`;
+const SEO_TITLE = APP_TITLE + " - Open Source AI app starter with actions";
 const SEO_DESCRIPTION =
   "Open Source starter for agent-native apps with durable chat, shared actions, UI state, tools, and a backend your agent can extend.";
 
 export function meta() {
   return [
     { title: SEO_TITLE },
-    {
-      name: "description",
-      content: SEO_DESCRIPTION,
-    },
+    { name: "description", content: SEO_DESCRIPTION },
     { property: "og:title", content: SEO_TITLE },
     { property: "og:description", content: SEO_DESCRIPTION },
     { name: "twitter:card", content: "summary" },
@@ -28,67 +19,19 @@ export function meta() {
   ];
 }
 
-function chatThreadPath(threadId: string | null) {
-  return threadId ? `/chat/${encodeURIComponent(threadId)}` : "/";
-}
-
-export default function ChatRoute() {
-  const { threadId } = useParams();
-  const navigate = useNavigate();
-  const t = useT();
-  const threadUrlSync = threadId
-    ? {
-        routeThreadId: threadId,
-        getPath: chatThreadPath,
-        navigate,
-      }
-    : undefined;
-
-  useEffect(() => {
-    function handleChatRunning(event: Event) {
-      const detail = (event as CustomEvent).detail;
-      if (detail?.isRunning === true) markAgentChatHomeHandoff("chat");
-    }
-
-    window.addEventListener("agentNative.chatRunning", handleChatRunning);
-    return () =>
-      window.removeEventListener("agentNative.chatRunning", handleChatRunning);
-  }, []);
-
+export default function MarketingHomeRoute() {
   return (
-    <div className="flex h-full min-h-0 flex-col bg-background">
-      <AgentChatSurface
-        mode="page"
-        chatViewTransition
-        className="h-full"
-        defaultMode="chat"
-        storageKey="chat"
-        threadUrlSync={threadUrlSync}
-        browserTabId={TAB_ID}
-        showHeader={false}
-        showTabBar={false}
-        dynamicSuggestions={false}
-        suggestions={[
-          t("chat.suggestionCapabilities"),
-          t("chat.suggestionCustomize"),
-          t("chat.suggestionActions"),
-        ]}
-        emptyStateText={t("chat.emptyState")}
-        emptyStateDisplay="hidden"
-        centerComposerWhenEmpty
-        composerLayoutVariant="hero"
-        composerPlaceholder={t("chat.composerPlaceholder")}
-        composerSlot={
-          <div className="mx-auto mb-5 max-w-xl px-4 text-center">
-            <h1 className="text-2xl font-semibold tracking-normal text-foreground sm:text-3xl">
-              {t("chat.heroTitle")}
-            </h1>
-            <p className="mt-2 text-sm leading-6 text-muted-foreground">
-              {t("chat.heroDescription")}
-            </p>
-          </div>
-        }
-      />
-    </div>
+    <MarketingHome
+      appName={APP_TITLE}
+      tagline="Start from a chat-first agent-native app and add actions, screens, and workflows as you grow."
+      description={SEO_DESCRIPTION}
+      valueProps={[
+        "Full-page chat with durable threads and tool call history",
+        "Use shared actions from chat, UI, HTTP, MCP, A2A, and CLI",
+        "Plug in your own agent runtime or use the included app-agent loop",
+      ]}
+      primaryActionHref={appPath("/home")}
+      secondaryActionHref={appPath("/sign-in")}
+    />
   );
 }

package/src/templates/chat/app/routes/chat.$threadId.tsx

@@ -1 +1 @@
-export { default, meta } from "./_index";
+export { default, meta } from "./home";

package/src/templates/chat/app/routes/home.tsx

@@ -0,0 +1,94 @@
+import {
+  AgentChatSurface,
+  markAgentChatHomeHandoff,
+} from "@agent-native/core/client/agent-chat";
+import { useT } from "@agent-native/core/client/i18n";
+import { useEffect } from "react";
+import { useNavigate, useParams } from "react-router";
+
+import { APP_TITLE } from "@/lib/app-config";
+import { TAB_ID } from "@/lib/tab-id";
+
+const SEO_TITLE = `${APP_TITLE} - Open Source AI app starter with actions`;
+const SEO_DESCRIPTION =
+  "Open Source starter for agent-native apps with durable chat, shared actions, UI state, tools, and a backend your agent can extend.";
+
+export function meta() {
+  return [
+    { title: SEO_TITLE },
+    {
+      name: "description",
+      content: SEO_DESCRIPTION,
+    },
+    { property: "og:title", content: SEO_TITLE },
+    { property: "og:description", content: SEO_DESCRIPTION },
+    { name: "twitter:card", content: "summary" },
+    { name: "twitter:title", content: SEO_TITLE },
+    { name: "twitter:description", content: SEO_DESCRIPTION },
+  ];
+}
+
+function chatThreadPath(threadId: string | null) {
+  return threadId ? `/chat/${encodeURIComponent(threadId)}` : "/home";
+}
+
+export default function ChatRoute() {
+  const { threadId } = useParams();
+  const navigate = useNavigate();
+  const t = useT();
+  const threadUrlSync = threadId
+    ? {
+        routeThreadId: threadId,
+        getPath: chatThreadPath,
+        navigate,
+      }
+    : undefined;
+
+  useEffect(() => {
+    function handleChatRunning(event: Event) {
+      const detail = (event as CustomEvent).detail;
+      if (detail?.isRunning === true) markAgentChatHomeHandoff("chat");
+    }
+
+    window.addEventListener("agentNative.chatRunning", handleChatRunning);
+    return () =>
+      window.removeEventListener("agentNative.chatRunning", handleChatRunning);
+  }, []);
+
+  return (
+    <div className="flex h-full min-h-0 flex-col bg-background">
+      <AgentChatSurface
+        mode="page"
+        chatViewTransition
+        className="h-full"
+        defaultMode="chat"
+        storageKey="chat"
+        threadUrlSync={threadUrlSync}
+        browserTabId={TAB_ID}
+        showHeader={false}
+        showTabBar={false}
+        dynamicSuggestions={false}
+        suggestions={[
+          t("chat.suggestionCapabilities"),
+          t("chat.suggestionCustomize"),
+          t("chat.suggestionActions"),
+        ]}
+        emptyStateText={t("chat.emptyState")}
+        emptyStateDisplay="hidden"
+        centerComposerWhenEmpty
+        composerLayoutVariant="hero"
+        composerPlaceholder={t("chat.composerPlaceholder")}
+        composerSlot={
+          <div className="mx-auto mb-5 max-w-xl px-4 text-center">
+            <h1 className="text-2xl font-semibold tracking-normal text-foreground sm:text-3xl">
+              {t("chat.heroTitle")}
+            </h1>
+            <p className="mt-2 text-sm leading-6 text-muted-foreground">
+              {t("chat.heroDescription")}
+            </p>
+          </div>
+        }
+      />
+    </div>
+  );
+}

package/src/templates/chat/netlify.toml

@@ -1,6 +1,6 @@
 [build]
 ignore = "node ./scripts/netlify-ignore-build.mjs chat"
-command = "export DATABASE_URL=${NETLIFY_DATABASE_URL:-$DATABASE_URL} && pnpm install && NITRO_PRESET=netlify pnpm --filter chat build && if [ \"${CONTEXT:-}\" = \"production\" ] || [ \"${AGENT_NATIVE_RUN_RELEASE_MIGRATIONS:-}\" = \"1\" ]; then pnpm --filter chat migrate:production; fi"
+command = "if [ \"${agentNativePrebuiltBuild:-}\" = \"true\" ]; then export DATABASE_URL=\"${agentNativePrebuiltDatabaseUrl:?}\" BETTER_AUTH_SECRET=\"${agentNativePrebuiltAuthSecret:?}\"; else export DATABASE_URL=${NETLIFY_DATABASE_URL:-$DATABASE_URL}; fi && pnpm install && NITRO_PRESET=netlify pnpm --filter chat build && if { [ \"${CONTEXT:-}\" = \"production\" ] || [ \"${AGENT_NATIVE_RUN_RELEASE_MIGRATIONS:-}\" = \"1\" ]; } && [ \"${agentNativePrebuiltBuild:-}\" != \"true\" ]; then pnpm --filter chat migrate:production; fi"
 publish = "templates/chat/dist"
 functions = "templates/chat/.netlify/functions-internal"
 
@@ -14,6 +14,7 @@ NPM_CONFIG_PRODUCTION = "false"
 AGENT_NATIVE_HOSTED_HARNESS = "true"
 AGENT_NATIVE_ENABLE_KEEP_WARM = "1"
 AGENT_NATIVE_DISABLE_KEEP_WARM_BACKGROUND = "1"
+BETTER_AUTH_TRUSTED_ORIGINS = "https://starter.agent-native.com,https://chat.agent-native.com"
 # Production release migrations own schema setup; request functions must skip
 # migration probes on every serverless invocation.
 AGENT_NATIVE_RELEASE_MIGRATIONS = "1"

package/src/templates/chat/public/manifest.json

@@ -2,7 +2,7 @@
   "name": "Chat",
   "short_name": "Chat",
   "description": "Chat-first agent-native app ready to customize",
-  "start_url": ".",
+  "start_url": "./home",
   "background_color": "#111111",
   "theme_color": "#18181B",
   "icons": [

package/src/templates/chat/server/plugins/auth.ts

@@ -4,6 +4,7 @@ const rawAppTitle = "{{APP_TITLE}}";
 const appTitle = rawAppTitle === "{" + "{APP_TITLE}}" ? "Chat" : rawAppTitle;
 
 export default createAuthPlugin({
+  workspaceAppPublicPaths: ["/"],
   marketing: {
     appName: appTitle,
     tagline:

package/src/templates/default/.agents/skills/frontend-design/SKILL.md

@@ -68,6 +68,10 @@ is the target: a surface full of information and nearly empty of narration. So
 "make it minimal" is never satisfied by removing data or by burying it behind
 extra clicks, and never blocked by deleting a sentence.
 
+Keep on-screen text and badging minimal: show the shortest label needed for the
+next action, remove decorative or duplicate status chips, and put context in a
+tooltip or progressive disclosure when it is not needed to decide.
+
 Do not add, unless asked:
 
 - A page title that repeats the nav item or route the user just clicked, or a

package/src/templates/default/.agents/skills/secrets/SKILL.md

@@ -31,6 +31,53 @@ standard workspace connections and org/workspace vault scopes; never put them
 in `.env` or deployment environment variables, and never add a provider-specific
 action or startup bootstrap just to write a credential for one organization.
 
+## Google OAuth triage
+
+| Observation | Meaning | Next action |
+| --- | --- | --- |
+| `invalid_grant` from a deliberately fake code | Google accepted the client pair and rejected only the code | Do not rotate credentials; check flow state and callback registration |
+| `invalid_client` | Google rejected the client id/secret pair | Verify the exact pair and deployment source before rotating |
+| `redirect_uri_mismatch` | The client, host, callback path, and Google registration disagree | Compare that exact tuple in Google Cloud Console; publish a new deploy if site-scoped or build-time configuration changes |
+
+Do not reason about this from memory. The probe checks both contracts: the
+unqualified `/health/google` endpoint reports the sign-in contract, while
+`/health/google?client=managed` reports deployment-level managed OAuth. It asks
+Google directly whether each live `(client_id, redirect_uri)` pair is
+registered:
+
+```bash
+pnpm check:google-redirect-uris -- --env all
+```
+
+The sign-in health path calls `checkGoogleSignInCredential()`, which prefers
+the active Better Auth pair and otherwise uses `resolveGoogleSignInCredentials()`
+from `packages/core/src/server/google-oauth-credentials.ts`. Managed health
+calls `checkGoogleManagedCredential()`, which resolves
+`["GOOGLE_CLIENT_ID", "GOOGLE_CLIENT_SECRET"]` through `resolveSecretPair()` in
+`packages/core/src/server/credential-provider.ts`. App provider handlers use
+`resolveGoogleProviderCredentialCandidatesWithReader()` with `resolveSecret`
+under request context. These are separate flows and can intentionally land on
+different Google clients, so a clean result for one says nothing about the
+other. Read both contracts before changing anything:
+
+```bash
+curl -s https://HOST/_agent-native/health/google | jq '{clientId,mismatchedPairs,credentialSource}'
+curl -s "https://HOST/_agent-native/health/google?client=managed" | jq '{clientId,mismatchedPairs,credentialSource}'
+```
+
+Different `clientId` values across those two, or `mismatchedPairs: true`, is a
+divergence to understand, not damage to undo. Never repair it by rotating a
+secret: writing a fresh value into whichever namespace the failing flow does
+not read verifies clean and changes nothing. Do not collapse the namespaces
+without first confirming which flow uses which client; separate sign-in and
+managed clients on one host can be deliberate. For prebuilt Netlify deploys,
+uploaded Functions read site-scoped secrets at runtime, and the health route
+resolves them per request. The build may receive masked placeholder values.
+After changing a site-scoped env var, publish a new deploy before verifying
+live behavior. Call it a rebuild when the changed value is baked into build
+output or static assets; a runtime-only secret does not need to be baked into
+the bundle.
+
 ## Credential Modeling Preflight
 
 Before registering a provider's fields, inspect the workspace/provider connection

package/src/templates/default/AGENTS.md

@@ -24,12 +24,9 @@ cross-cutting work and `self-modifying-code` when changing app source.
   unauthenticated URLs, or non-JSON responses.
 - Keep database code provider-agnostic and migrations additive. Do not use
   adapter-only database methods or production schema push commands.
-- All user-facing AI work goes through the agent chat. UI and server code do
-  not call model providers or inline LLM APIs directly, or hide AI-shaped
-  multi-step work in one action.
-  Keep actions deterministic and focused; use the AgentSidebar for research,
-  analysis, generation, recommendation, synthesis, and follow-ups in the same
-  thread.
+- All AI work goes through agent chat. UI/server code must not call models or
+  hide multi-step AI in one action. Keep actions deterministic and focused; use
+  the AgentSidebar for research and follow-ups in the same thread.
 - Keep domain workflows on named routes and preserve the scaffold's full-page
   chat route. Use the right AgentSidebar for contextual AI and open it when a
   domain button hands work to the agent.
@@ -59,6 +56,13 @@ cross-cutting work and `self-modifying-code` when changing app source.
 - A missing or unreadable value must stay distinguishable from success. Throw or
   return an explicit error instead of silently falling back to an empty value.
 
+## Public and private routes
+
+`app/routes/_index.tsx` is the public SSR marketing page: no sessions, cookies,
+or private data. Use Toolkit `MarketingHome` with value props, backgrounds,
+action slots, or `children` for a custom hero. Keep the browser-gated app under
+`/home`; never server-redirect `/` based on authentication.
+
 ## Lightweight defaults
 
 Apps are English-only and do not generate changelog entries by default. If an

package/src/templates/default/DEVELOPING.md

@@ -4,7 +4,7 @@ This guide is for development-mode agents editing this app's source code. For ap
 
 ## Framework Basics
 
-**Client-side-first rendering:** This app uses React Router v8 framework mode with `ssr: true`, but all app content renders **client-side only**. The server renders only the HTML shell (meta tags, styles, scripts) plus a loading spinner. This is enforced by the `ClientOnly` wrapper in `root.tsx` — never remove it. Browser APIs (`window`, `localStorage`, `new Date()`) are safe to use anywhere in app code because components never run on the server.
+**Public SSR, private CSR:** This app uses React Router v8 framework mode with `ssr: true`. The `/` route is a public, server-rendered marketing page and must stay free of session, cookie, and private-data reads. Authenticated app routes start at `/home` and render client-side behind the `ClientOnly` session gate in `root.tsx`; browser APIs are safe there.
 
 **Do NOT fetch data server-side** in route loaders unless the page genuinely needs SEO/OG content. The standard pattern is: SSR renders the shell, client hydrates, and React reads/writes normal app data through actions with `useActionQuery` / `useActionMutation`.
 
@@ -14,6 +14,7 @@ Create a file in `app/routes/`. The filename determines the URL path:
 
 ```
 app/routes/_index.tsx              → /
+app/routes/home.tsx                → /home
 app/routes/settings.tsx            → /settings
 app/routes/inbox.tsx               → /inbox
 app/routes/inbox.$threadId.tsx     → /inbox/:threadId
@@ -27,6 +28,7 @@ In a workspace, this app can be mounted under `/<app-id>`. React Router already
 | Route file              | App-internal route | Mounted browser URL |
 | ----------------------- | ------------------ | ------------------- |
 | `app/routes/_index.tsx` | `/`                | `/<app-id>`         |
+| `app/routes/home.tsx`   | `/home`            | `/<app-id>/home`    |
 | `app/routes/review.tsx` | `/review`          | `/<app-id>/review`  |
 | `app/routes/$id.tsx`    | `/:id`             | `/<app-id>/:id`     |
 
@@ -46,6 +48,11 @@ export default function MyPageRoute() {
 }
 ```
 
+The root route is the public marketing surface. Use `MarketingHome` from
+`@agent-native/toolkit/marketing` for a reusable SSR page with value props,
+background visuals, action links, and a custom `children` escape hatch. Put
+authenticated app UI and data loads under `/home` or another private route.
+
 ## Adding App Data
 
 Normal app data starts as an action, not a custom route. Add `actions/<verb>-<resource>.ts` with `defineAction`, mark reads with `http: { method: "GET" }`, and call reads/writes from React with `useActionQuery` / `useActionMutation` from `@agent-native/core/client`. This keeps the UI and agent on one contract and lets mutating actions refresh action-backed queries automatically.

package/src/templates/default/app/hooks/use-navigation-state.ts

@@ -31,7 +31,7 @@ function viewFromPath(pathname: string): string {
 }
 
 function pathFromView(view: string | undefined): string {
-  if (!view || view === "home") return "/";
+  if (!view || view === "home") return "/home";
   return `/${view.replace(/^\/+/, "")}`;
 }
 

package/src/templates/default/app/root.tsx

@@ -20,6 +20,7 @@ import {
   ScrollRestoration,
   isRouteErrorResponse,
   Link,
+  useLocation,
   useRouteError,
 } from "react-router";
 
@@ -254,10 +255,16 @@ function DbSyncSetup() {
 
 export default function Root() {
   const [queryClient] = useState(() => createAgentNativeQueryClient());
+  const location = useLocation();
+  const isMarketingHome = location.pathname === "/";
   return (
-    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+    <AppProviders
+      queryClient={queryClient}
+      isPublicPath={isMarketingHome}
+      i18n={{ catalog: i18nCatalog }}
+    >
       <AppToolkitProvider>
-        <DbSyncSetup />
+        {isMarketingHome ? null : <DbSyncSetup />}
         <Outlet />
       </AppToolkitProvider>
     </AppProviders>
@@ -320,7 +327,7 @@ export function ErrorBoundary() {
         <h1 className="mt-3 text-2xl font-semibold">{title}</h1>
         <p className="mt-2 text-muted-foreground text-sm">{details}</p>
         <Link
-          to="/"
+          to="/home"
           className="mt-6 inline-flex items-center gap-1.5 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground shadow-sm hover:bg-primary/90 cursor-pointer"
         >
           {copy.goHome}

package/src/templates/default/app/routes/_index.tsx

@@ -1,94 +1,18 @@
-import { useActionQuery } from "@agent-native/core/client/hooks";
-import { useT } from "@agent-native/core/client/i18n";
-import { docsUrl } from "@agent-native/core/shared";
-import { useTheme } from "next-themes";
-import { Link } from "react-router";
+import { appPath } from "@agent-native/core/client/api-path";
+import { MarketingHome } from "@agent-native/toolkit/marketing";
 
 export function meta() {
   return [{ title: "{{APP_TITLE}}" }];
 }
 
-export default function IndexPage() {
-  const { resolvedTheme, setTheme } = useTheme();
-  const t = useT();
-  const isDark = resolvedTheme === "dark";
-  const { data } = useActionQuery("hello", { name: "{{APP_TITLE}}" });
-
+export default function MarketingHomeRoute() {
   return (
-    <div className="flex flex-col items-center justify-center min-h-screen px-6">
-      <div className="max-w-md w-full space-y-8 text-center">
-        <div className="space-y-3">
-          <h1 className="text-2xl font-semibold tracking-tight text-foreground">
-            {t("home.title")}
-          </h1>
-          <p className="text-[14px] text-muted-foreground leading-relaxed">
-            {t("home.intro")}{" "}
-            <code className="text-[13px] bg-muted px-1.5 py-0.5 rounded font-mono">
-              app/routes/_index.tsx
-            </code>
-          </p>
-        </div>
-
-        <div className="h-px bg-border" />
-
-        <div className="rounded-lg border border-border/50 px-4 py-3 text-left">
-          <p className="text-[13px] font-medium text-foreground">
-            {t("home.actionCardTitle")}
-          </p>
-          <p className="text-[12px] text-muted-foreground mt-0.5">
-            {data?.message ?? t("home.loadingAction")}
-          </p>
-        </div>
-
-        <div className="grid grid-cols-2 gap-3 text-left">
-          <a
-            href={docsUrl("getting-started")}
-            target="_blank"
-            rel="noopener noreferrer"
-            className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
-          >
-            <p className="text-[13px] font-medium text-foreground">
-              {t("home.docsTitle")}
-            </p>
-            <p className="text-[12px] text-muted-foreground mt-0.5">
-              {t("home.docsDescription")}
-            </p>
-          </a>
-          <button
-            onClick={() => setTheme(isDark ? "light" : "dark")}
-            className="rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors text-left"
-          >
-            <p className="text-[13px] font-medium text-foreground">
-              {t("home.themeTitle")}
-            </p>
-            <p className="text-[12px] text-muted-foreground mt-0.5">
-              {t("home.themeDescription")}
-            </p>
-          </button>
-          <Link
-            to="/settings"
-            className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
-          >
-            <p className="text-[13px] font-medium text-foreground">
-              {t("home.settingsTitle")}
-            </p>
-            <p className="text-[12px] text-muted-foreground mt-0.5">
-              {t("home.settingsDescription")}
-            </p>
-          </Link>
-          <Link
-            to="/settings/agent"
-            className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
-          >
-            <p className="text-[13px] font-medium text-foreground">
-              {t("settings.agentTitle")}
-            </p>
-            <p className="text-[12px] text-muted-foreground mt-0.5">
-              {t("settings.agentDescription")}
-            </p>
-          </Link>
-        </div>
-      </div>
-    </div>
+    <MarketingHome
+      appName="{{APP_TITLE}}"
+      tagline="Build with your AI agent."
+      description="A starter app for building Agent-Native workflows."
+      primaryActionHref={appPath("/home")}
+      secondaryActionHref={appPath("/sign-in")}
+    />
   );
 }

package/src/templates/default/app/routes/home.tsx

@@ -0,0 +1,94 @@
+import { useActionQuery } from "@agent-native/core/client/hooks";
+import { useT } from "@agent-native/core/client/i18n";
+import { docsUrl } from "@agent-native/core/shared";
+import { useTheme } from "next-themes";
+import { Link } from "react-router";
+
+export function meta() {
+  return [{ title: "{{APP_TITLE}}" }];
+}
+
+export default function HomePage() {
+  const { resolvedTheme, setTheme } = useTheme();
+  const t = useT();
+  const isDark = resolvedTheme === "dark";
+  const { data } = useActionQuery("hello", { name: "{{APP_TITLE}}" });
+
+  return (
+    <div className="flex flex-col items-center justify-center min-h-screen px-6">
+      <div className="max-w-md w-full space-y-8 text-center">
+        <div className="space-y-3">
+          <h1 className="text-2xl font-semibold tracking-tight text-foreground">
+            {t("home.title")}
+          </h1>
+          <p className="text-[14px] text-muted-foreground leading-relaxed">
+            {t("home.intro")}{" "}
+            <code className="text-[13px] bg-muted px-1.5 py-0.5 rounded font-mono">
+              app/routes/home.tsx
+            </code>
+          </p>
+        </div>
+
+        <div className="h-px bg-border" />
+
+        <div className="rounded-lg border border-border/50 px-4 py-3 text-left">
+          <p className="text-[13px] font-medium text-foreground">
+            {t("home.actionCardTitle")}
+          </p>
+          <p className="text-[12px] text-muted-foreground mt-0.5">
+            {data?.message ?? t("home.loadingAction")}
+          </p>
+        </div>
+
+        <div className="grid grid-cols-2 gap-3 text-left">
+          <a
+            href={docsUrl("getting-started")}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
+          >
+            <p className="text-[13px] font-medium text-foreground">
+              {t("home.docsTitle")}
+            </p>
+            <p className="text-[12px] text-muted-foreground mt-0.5">
+              {t("home.docsDescription")}
+            </p>
+          </a>
+          <button
+            onClick={() => setTheme(isDark ? "light" : "dark")}
+            className="rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors text-left"
+          >
+            <p className="text-[13px] font-medium text-foreground">
+              {t("home.themeTitle")}
+            </p>
+            <p className="text-[12px] text-muted-foreground mt-0.5">
+              {t("home.themeDescription")}
+            </p>
+          </button>
+          <Link
+            to="/settings"
+            className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
+          >
+            <p className="text-[13px] font-medium text-foreground">
+              {t("home.settingsTitle")}
+            </p>
+            <p className="text-[12px] text-muted-foreground mt-0.5">
+              {t("home.settingsDescription")}
+            </p>
+          </Link>
+          <Link
+            to="/settings/agent"
+            className="group rounded-lg border border-border/50 px-4 py-3 hover:bg-accent/50 transition-colors"
+          >
+            <p className="text-[13px] font-medium text-foreground">
+              {t("settings.agentTitle")}
+            </p>
+            <p className="text-[12px] text-muted-foreground mt-0.5">
+              {t("settings.agentDescription")}
+            </p>
+          </Link>
+        </div>
+      </div>
+    </div>
+  );
+}