@agent-native/core 0.207.0-nightly-20261011124220 → 0.207.0

package/docs/content/environment-variables.mdx

@@ -15,9 +15,11 @@ most apps need.
 For a normal app, start with the [Agent-Native app configuration guide](/docs/agent-native-config),
 then use [Deployment: Environment Variables](/docs/deployment-environment-variables)
 and [Authentication](/docs/authentication) for the deliberate environment-only
-parts. Keep user-, organization-, and workspace-scoped credentials in the
-database-backed secret or connection store; use environment variables for
-deploy-level configuration.
+parts. LLM provider keys can be app-wide fallbacks on self-hosted deployments;
+production Hosted-workspace runtimes block that fallback. See [LLM provider
+keys](#llm-provider-keys) for local setup, scoped keys, and deployment sharing
+and billing. Keep user-, organization-, and workspace-scoped credentials in the
+database-backed secret or connection store.
 
 For committed, non-secret app defaults, use `agent-native.config.ts` first. If a
 public config value must vary by deployment, use its deterministic
@@ -79,7 +81,7 @@ public app behavior, use the config paths above instead.
 | `SECRETS_ENCRYPTION_KEY`                       | Legacy app-local/shared encryption fallback.                                                                                                                                   | A stable encryption key; prefer the workspace key for new shared vaults.                                                |
 | `WORKSPACE_SECRETS_ENCRYPTION_KEY`             | Stable encryption key for a workspace-shared secrets vault.                                                                                                                    | The same stable key in every app that reads the vault.                                                                  |
 | `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS`    | Previous workspace key during rotation.                                                                                                                                        | The old key only; remove it after migration.                                                                            |
-| `ANTHROPIC_API_KEY`                            | Optional deploy-level fallback for the embedded production agent.                                                                                                              | An API key; prefer scoped credentials for multi-tenant apps.                                                            |
+| `ANTHROPIC_API_KEY`                            | Shared fallback for self-hosted apps, including remote databases.                                                                                                              | An Anthropic API key; saved personal, organization, or workspace-scoped keys take precedence.                           |
 | `AGENT_ENGINE`                                 | Explicitly selects the agent engine instead of auto-detecting from provider keys.                                                                                              | A registered engine name such as `anthropic`, `ai-sdk:openai`, `builder`, or `codex-cli`.                               |
 | `AGENT_BUILT_IN_ENGINES`                       | Restricts which built-in engines are registered at all, so the rest never appear in the model picker or resolve by name.                                                       | A comma-separated list of built-in engine names such as `ai-sdk:openai`; unset registers every built-in.                |
 | `AGENT_SOURCE_SWEEP_TOOL_CALL_THRESHOLD`       | Read-only source/search tool calls one turn may make before the agent is told to converge and answer from what it gathered.                                                    | A positive integer; defaults to 24. Raise it for research-shaped apps that legitimately inspect many records.           |
@@ -169,8 +171,38 @@ specific Google API integrations; they are not required for browser sign-in.
 
 ## Optional AI, search, and email fallbacks
 
-These are deploy-level fallbacks for single-tenant or local use. Hosted,
-multi-user apps should prefer the scoped credential and connection store.
+### LLM provider keys {#llm-provider-keys}
+
+For local development, put a supported provider key in the app's `.env` file
+before starting `pnpm dev`. For example:
+
+```dotenv
+ANTHROPIC_API_KEY=replace-with-your-key
+```
+
+For an app-wide fallback, set a supported provider key in the server-side
+environment of a self-hosted app. This also works with a remote PostgreSQL
+database. Any signed-in user without a personal, organization-scoped, or
+workspace-scoped provider key can use the deployment's provider account, and
+usage is billed to that account. Anonymous public runs and synthetic traffic do
+not receive this fallback. Personal, organization, and workspace-scoped keys
+take precedence. Setting a deployment key opts in to
+app-wide access and billing; no extra shared-key flag is needed. Production
+Hosted-workspace runtimes block deployment provider-key fallbacks.
+
+To keep a key scoped, select **Custom keys** in the app's LLM setup. In a
+PostgreSQL app, a personal key stays with its user; organization scope shares a
+key with the active organization and is available to admins. The app stores
+these saved keys in its encrypted database-backed credential store.
+
+To use Builder's managed provider, connect with **Use Builder.io** in the app's
+LLM setup. This uses the Builder connection instead of a provider API key from
+the table below.
+
+The table below lists optional deployment-level fallbacks for self-hosted apps.
+See the LLM guidance above for which users can use the deployment provider key
+and how usage is billed. Production Hosted-workspace runtimes block deployment
+provider-key fallbacks.
 
 Every provider key below selects its engine on its own: dropping one in is
 enough, and `AGENT_ENGINE` is only needed to pick between several.

package/docs/content/getting-started.mdx

@@ -20,8 +20,7 @@ In this guide, you'll create an agent with a chat UI and call its included
 - [Node.js](https://nodejs.org) 22.22 or later
 - [pnpm](https://pnpm.io) available on your `PATH` (run `corepack enable` in
   the generated app if it is not)
-- An LLM connection for the agent: Builder.io, an Anthropic or OpenAI API key,
-  or a local Ollama model
+- Optional while setting up; required to run the agent: Builder.io, an Anthropic/OpenAI key, or local Ollama
 
 ## Create an agent
 
@@ -64,11 +63,12 @@ enter an email or password for local development.
 
 </Callout>
 
-## Connect an LLM
+## Connect an LLM (optional) {#connect-an-llm}
 
-Next, connect an LLM. Select **Use Builder.io** to use free credits, or
-select **Custom keys**, choose a provider, and enter the requested connection
-details.
+Connect with **Use Builder.io**, add a personal or organization key through
+**Custom keys**, or set a provider key in `.env` for local development and in
+the deployment environment for app-wide use on self-hosted apps. See the [LLM
+provider setup](/docs/environment-variables#llm-provider-keys).
 
 ## Run the action from the agent
 
@@ -76,7 +76,7 @@ An action is a typed function that your React UI can call from code and agents
 can use as a tool. The Chat template includes a simple `hello` action so you
 can try the pattern before writing one yourself.
 
-In the agent panel, ask:
+In the prompt on the **Get started** page, ask:
 
 > Call the hello action for Alex.
 

package/docs/content/multi-app-workspace.mdx

@@ -260,7 +260,10 @@ By default every workspace can reach the hosted first-party apps (Mail, Calendar
     "workspaceCore": "@my-company-platform/shared",
     "builtinAgents": {
       "mode": "selected",
-      "include": ["mail", "calendar"]
+      "include": ["mail", "calendar", "design"],
+      "urls": {
+        "design": "https://design.example.test"
+      }
     }
   }
 }
@@ -268,10 +271,11 @@ By default every workspace can reach the hosted first-party apps (Mail, Calendar
 
 - `mode`: `"all"` (default, every public first-party app), `"none"` (no built-ins), or `"selected"` (only `include`).
 - `include`: the built-ins this workspace offers when `mode` is `"selected"`. Anything else stays unknown to the workspace.
+- `urls` (optional): maps built-in IDs to HTTPS base URL overrides for offered built-ins without changing the offered agents. It replaces the canonical hosted URL, including in a seeded manifest that still uses that default, while custom connected remote-agent URLs and workspace-app overlays retain priority. Unknown IDs and invalid URLs fail parsing. Each value must be a trimmed absolute HTTPS URL with no credentials, query, or fragment. Local-development routing keeps priority and uses local URLs.
 
-Unknown ids log a warning and are ignored. A standalone app can use the same key in its own `package.json`. `agent-native dev` and workspace deploys pass the value to every app as `AGENT_NATIVE_BUILTIN_AGENTS_JSON`.
+Unknown IDs in `include` log a warning and are ignored. A standalone app can use the same key in its own `package.json`. `agent-native dev` and workspace deploys pass the value to every app as `AGENT_NATIVE_BUILTIN_AGENTS_JSON`.
 
-This config controls the app list, agent discovery, and agent-to-agent calls. Mounted workspace apps and connected remote agents are unaffected, and MCP app access stays a separate routing permission.
+This config controls the app list, agent discovery, and agent-to-agent calls. Mounted workspace apps and custom connected remote-agent URLs retain priority, and MCP app access stays a separate routing permission.
 
 ## Shared MCP servers {#shared-mcp}
 

package/docs/content/template-chat-first-edits.mdx

@@ -1,18 +1,20 @@
 ---
 title: "Chat: Your First Feature"
-description: "The one file that renders Chat's starter screen, what its real props do, and a full walkthrough of adding a feature end to end."
+description: "The files that render Chat's starter screens, what their real props do, and a full walkthrough of adding a feature end to end."
 ---
 
 # Your First Feature
 
-This page is for developers extending the [Chat template](/docs/template-chat). It covers the single file that renders the starter chat screen, then walks through everything the agent typically touches when you ask for a real feature.
+This page is for developers extending the [Chat template](/docs/template-chat). It covers the files that render the starter screens, then walks through everything the agent typically touches when you ask for a real feature.
 
 ## First code to inspect {#first-code}
 
 - `actions/hello.ts` is the starter behavior the agent can call. Replace it or
   add actions beside it.
-- `app/routes/_index.tsx` renders the full-page chat surface. Adjust the
-  suggestions, empty state, composer, or surrounding layout here.
+- `app/components/chat/ChatRouteContent.tsx` renders the full-page chat surface
+  at `/chat/<threadId>`. Adjust the empty state, composer, or message slots here.
+- `app/components/home/HomePage.tsx` is the editable Get started landing page at
+  `/home`. `/chat` starts a new chat.
 - `AGENTS.md` tells the built-in agent how to work inside this app.
 
 <FileTree
@@ -32,12 +34,28 @@ This page is for developers extending the [Chat template](/docs/template-chat).
       note: "standard navigation action",
     },
     {
-      path: "app/routes/_index.tsx",
-      note: "renders the full-page chat surface; edit suggestions, empty state, composer",
+      path: "app/routes/home.tsx",
+      note: "/home: the Get started landing page; /chat: starts a new chat",
+    },
+    {
+      path: "app/routes/chat._index.tsx",
+      note: "/chat: starts a new chat and hands off to /chat/:threadId",
     },
     {
       path: "app/routes/chat.$threadId.tsx",
-      note: "re-exports _index.tsx so /chat/:threadId renders the same surface with a thread id in the URL",
+      note: "/chat/:threadId: renders ChatRouteContent for that thread",
+    },
+    {
+      path: "app/components/chat/ChatRouteContent.tsx",
+      note: "the full-page chat surface; edit the empty state, composer, and message slots",
+    },
+    {
+      path: "app/components/home/HomePage.tsx",
+      note: "the editable Get started home page",
+    },
+    {
+      path: "app/lib/chat-paths.ts",
+      note: "Chat path helpers",
     },
     {
       path: "AGENTS.md",
@@ -46,46 +64,41 @@ This page is for developers extending the [Chat template](/docs/template-chat).
   ]}
 />
 
-The real starter file is more than a bare `<AgentChatSurface />` — it wires thread-URL sync, a tab identity for multi-tab runs, and a hero composer layout, and its copy comes from i18n keys rather than literal strings:
+The chat surface is assembled from AgentKit pieces: a transport, a thread root, and the chat view. Its copy comes from i18n keys rather than literal strings:
 
 <AnnotatedCode
   id="doc-block-chat4"
-  title="app/routes/_index.tsx (trimmed)"
-  filename="app/routes/_index.tsx"
+  title="app/components/chat/ChatRouteContent.tsx (trimmed)"
+  filename="app/components/chat/ChatRouteContent.tsx"
   language="tsx"
   code={
-    'import {\n  AgentChatSurface,\n  markAgentChatHomeHandoff,\n} from "@agent-native/core/client/agent-chat";\nimport { useT } from "@agent-native/core/client/i18n";\nimport { useEffect } from "react";\nimport { useNavigate, useParams } from "react-router";\n\nimport { TAB_ID } from "@/lib/tab-id";\n\nfunction chatThreadPath(threadId: string | null) {\n  return threadId ? `/chat/${encodeURIComponent(threadId)}` : "/";\n}\n\nexport default function ChatRoute() {\n  const { threadId } = useParams();\n  const navigate = useNavigate();\n  const t = useT();\n  const threadUrlSync = threadId\n    ? { routeThreadId: threadId, getPath: chatThreadPath, navigate }\n    : undefined;\n\n  useEffect(() => {\n    function handleChatRunning(event: Event) {\n      const detail = (event as CustomEvent).detail;\n      if (detail?.isRunning === true) markAgentChatHomeHandoff("chat");\n    }\n    window.addEventListener("agentNative.chatRunning", handleChatRunning);\n    return () =>\n      window.removeEventListener("agentNative.chatRunning", handleChatRunning);\n  }, []);\n\n  return (\n    <AgentChatSurface\n      mode="page"\n      chatViewTransition\n      threadUrlSync={threadUrlSync}\n      browserTabId={TAB_ID}\n      dynamicSuggestions={false}\n      suggestions={[\n        t("chat.suggestionCapabilities"),\n        t("chat.suggestionCustomize"),\n        t("chat.suggestionActions"),\n      ]}\n      emptyStateText={t("chat.emptyState")}\n      centerComposerWhenEmpty\n      composerLayoutVariant="hero"\n      composerPlaceholder={t("chat.composerPlaceholder")}\n      composerSlot={\n        <div className="mx-auto mb-5 max-w-xl px-4 text-center">\n          <h1>{t("chat.heroTitle")}</h1>\n          <p>{t("chat.heroDescription")}</p>\n        </div>\n      }\n    />\n  );\n}'
+    'import { createAgentNativeAgentKitTransport } from "@agent-native/core/client/agentkit-chat/transport";\nimport { useT } from "@agent-native/core/client/i18n";\nimport { AgentKitChat } from "@agent-native/toolkit/app/agentkit/react/components";\nimport { CoreAgentKitRoot } from "@agent-native/toolkit/app/chat/agentkit-chat/index";\nimport { useState } from "react";\nimport { useNavigate, useParams } from "react-router";\n\nimport { chatThreadPath } from "@/lib/chat-paths";\nimport { TAB_ID } from "@/lib/tab-id";\n\nexport default function ChatRouteContent() {\n  const { threadId } = useParams();\n  const navigate = useNavigate();\n  const t = useT();\n  const [transport] = useState(() =>\n    createAgentNativeAgentKitTransport({\n      browserTabId: TAB_ID,\n      surface: "app",\n      adapter: { textFormat: "markdown" },\n    }),\n  );\n  if (!threadId) return null;\n\n  return (\n    <CoreAgentKitRoot\n      transport={transport}\n      threadId={threadId}\n      labels={{ composerPlaceholder: t("chat.composerPlaceholder") }}\n      slots={{ emptyState: ChatEmptyState }}\n      onThreadForked={(thread) => navigate(chatThreadPath(thread.id))}\n    >\n      <AgentKitChat\n        emptyComposerPlacement="center"\n        composerProps={{ requireAgentEngine: true, voiceEnabled: true }}\n      />\n    </CoreAgentKitRoot>\n  );\n}\n\nfunction ChatEmptyState() {\n  const t = useT();\n  return (\n    <div className="agentkit-chat-empty-copy">\n      <h1>{t("chat.heroTitle")}</h1>\n    </div>\n  );\n}'
   }
   annotations={[
     {
-      lines: "19-21",
-      label: "Thread URL sync",
-      note: "`/chat/:threadId` (`chat.$threadId.tsx`) re-exports this same component. When the route has a thread id, `threadUrlSync` keeps the URL and the active thread in lock-step: switching threads pushes `/chat/<id>`, and opening that URL restores the thread.",
-    },
-    {
-      lines: "38",
-      label: "Tab identity",
-      note: "`TAB_ID` (`app/lib/tab-id.ts`, a random id generated once per browser tab) lets the shared chat runtime tell multiple open tabs of the same app apart, so a run started in one tab isn't mistaken for one in another.",
+      lines: "15-21",
+      label: "Transport",
+      note: "`createAgentNativeAgentKitTransport` connects the chat view to the app's agent runtime. `TAB_ID` (`app/lib/tab-id.ts`, a random id generated once per browser tab) lets the runtime tell open tabs of the same app apart, so a run started in one tab isn't mistaken for one in another.",
     },
     {
-      lines: "39-44",
-      label: "Suggestions are i18n keys",
-      note: 'Suggestion copy comes from `t("chat.suggestionCapabilities")` etc. (see `app/i18n/en-US.ts`), not literal English strings, and `dynamicSuggestions={false}` turns off the runtime\'s own suggestion generation in favor of these three.',
+      lines: "25-30",
+      label: "Thread root",
+      note: "`CoreAgentKitRoot` loads the thread named in `/chat/:threadId` (`chat.$threadId.tsx`). Visiting `/chat` creates a new thread id and hands off here. When a thread is forked, `chatThreadPath` moves the URL to the new thread.",
     },
     {
-      lines: "46-47",
-      label: "Hero composer layout",
-      note: '`composerLayoutVariant="hero"` plus `centerComposerWhenEmpty` centers the composer with a title/description above it, instead of the plain bottom-docked composer other `mode="page"` chat routes use.',
+      lines: "29",
+      label: "Slots",
+      note: "Slots replace parts of the chat view. The real file also passes `message`, `runFailure`, `connectionRequest`, and `footer` slots for recovery messages, MCP connection cards, and the agent footer.",
     },
     {
-      lines: "49-54",
-      label: "composerSlot",
-      note: 'Arbitrary JSX rendered above the composer only while it\'s centered — this is where the "How can I help?" heading lives. Edit this to change the empty-state pitch without touching the runtime.',
+      lines: "32-35",
+      label: "Centered composer",
+      note: '`emptyComposerPlacement="center"` centers the composer until the thread has a message. `requireAgentEngine` shows the Connect AI card until a model is connected.',
     },
     {
-      lines: "23-31",
-      label: "Home handoff",
-      note: 'When a run starts on this page, `markAgentChatHomeHandoff("chat")` records that the home surface owns the active run, so navigating away and back reattaches to it instead of losing it.',
+      lines: "40-47",
+      label: "Empty state",
+      note: "The heading above the centered composer. Its copy is `chat.heroTitle` in `app/i18n/en-US.ts`: edit the catalog to change the pitch, or add elements here.",
     },
   ]}
 />
@@ -126,10 +139,10 @@ The rest of the feature follows from there:
 - `actions/create-note.ts` — a `defineAction` with a Zod schema (`title`, `body`), shaped like `actions/hello.ts`.
 - `actions/list-notes.ts` — a read-only action (`readOnly: true`, like `actions/view-screen.ts`) that queries the new table through `accessFilter`.
 - `app/routes/notes.tsx` — a new route; the app uses file-system routing (`flatRoutes()` in `app/routes.ts`), so adding the file is enough to mount `/notes`.
-- A new entry in the `navItems` array in `app/components/layout/Sidebar.tsx` pointing at `/notes`.
+- A link in `app/components/layout/Sidebar.tsx`, added before `ChatThreadsSection` and pointing at `/notes`.
 - An `AGENTS.md` addition telling the agent notes exist and which actions manage them.
 
-A new action is callable by chat as soon as it exists — every `defineAction` is a tool by default unless it sets `agentTool: false`. It won't necessarily be in the model's very first request, though: `server/plugins/agent-chat.ts` sets `INITIAL_TOOL_NAMES = ["view-screen", "navigate", "hello"]`, which controls only which tool schemas are sent on the first turn. Everything else, including a brand-new `create-note`, stays reachable through `tool-search` and loads on demand — add a name to that list only if you want it in the model's default toolset from message one.
+A new action is callable by chat as soon as it exists — every `defineAction` is a tool by default unless it sets `agentTool: false`. It won't necessarily be in the model's very first request, though: `server/plugins/agent-chat.ts` sets `INITIAL_TOOL_NAMES = ["view-screen", "navigate", "hello", "provider-api-request"]`, which controls only which tool schemas are sent on the first turn. Everything else, including a brand-new `create-note`, stays reachable through `tool-search` and loads on demand — add a name to that list only if you want it in the model's default toolset from message one.
 
 ## Use your own agent backend {#own-agent-backend}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.207.0-nightly-20261011124220",
+  "version": "0.207.0",
   "description": "The agentic application framework for building autonomous agents with intuitive UIs",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -694,8 +694,8 @@
     "yaml": "^2.9.0",
     "yjs": "^13.6.33",
     "zod": "^4.3.6",
-    "@agent-native/agentkit": "^0.207.0-nightly-20261011124220",
-    "@agent-native/recap-cli": "^0.5.68"
+    "@agent-native/recap-cli": "^0.5.69",
+    "@agent-native/agentkit": "^0.207.0"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",
@@ -765,7 +765,7 @@
     "xlsx": "^0.18.5"
   },
   "peerDependencies": {
-    "@agent-native/core-corpus": "0.207.0-nightly-20261011124220",
+    "@agent-native/core-corpus": ">=0.196.0",
     "@ai-sdk/anthropic": ">=3",
     "@ai-sdk/cohere": ">=3",
     "@ai-sdk/google": ">=3",

package/src/templates/builder-code-starter/.agents/skills/adding-a-feature/SKILL.md.patch

@@ -1,7 +1,7 @@
 ===================================================================
 --- a/.agents/skills/adding-a-feature/SKILL.md
 +++ b/.agents/skills/adding-a-feature/SKILL.md
-@@ -129,11 +129,12 @@
+@@ -131,11 +131,12 @@
  Instruction examples may name secret keys like `SLACK_WEBHOOK`, but must use
  placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
  real keys, internal data, or customer data into instructions as examples.

package/src/templates/builder-code-starter/AGENTS.md.patch

@@ -5,7 +5,7 @@
 -# Chat — Agent Guide
 +# App — Agent Guide
  
--Chat is the minimal chat-first agent-native app. `/` redirects to shared sign-in; authenticated chat starts at `/home`. Actions carry capabilities; screens exist only for durable workflows.
+-Chat is the minimal chat-first agent-native app. `/` redirects to shared sign-in, then `/home`, the editable Get started page. Chat lives at `/chat`; new chats start there. Actions carry capabilities; screens exist only for durable workflows.
 +This starter ships as a blank Agent-Native app canvas — that describes its
 +initial state, not necessarily its current one. See `DEVELOPING.md` before
 +making any source code change.
@@ -30,7 +30,7 @@
  
  ## Application state
  
--- `navigation` describes the view and selected ids. Chat is `chat` at `/home`; `/` opens shared sign-in/signup.
+-- `navigation` describes the view and selected ids. Chat is `chat` at `/chat` and `/chat/<threadId>`; the Get started page is `home` at `/home`; `/` opens shared sign-in/signup.
 +- `navigation` describes the view and selected ids. The default home view is
 +  `home` at `/` (blank app canvas). No agent rail or chat is mounted by
 +  default; add one only when the user asks.
@@ -38,7 +38,7 @@
  
  ## Building a domain app
  
--Choose the primary workflow and route before editing. Add a domain route under `app/routes/` and set `app.homePath` in `server/plugins/agent-native-email-branding.ts` with `defineAppConfig`. Keep `/home` as Chat. Add a static link in `app/components/layout/Sidebar.tsx` before `ChatThreadsSection`; `Header.tsx` maps `/home` to Chat and uses `APP_TITLE` elsewhere. Shared sidebar and AgentInspector remain.
+-Choose the primary workflow and route before editing. Add a domain route under `app/routes/` and set `app.homePath` in `server/plugins/agent-native-email-branding.ts` with `defineAppConfig`. The default Get started page lives at `/home`, and Chat stays at `/chat`; edit `app/routes/home.tsx` when replacing that page with a domain-specific home. Add a static link in `app/components/layout/Sidebar.tsx` before `ChatThreadsSection`; `Header.tsx` uses `APP_TITLE` elsewhere. Shared sidebar and AgentInspector remain.
 +Choose the primary workflow and route before editing. Build on the blank canvas in `app/routes/_index.tsx` or add domain routes under `app/routes/`. This starter has no Chat route, sidebar, header, or agent rail; add only the navigation the product needs. Set `app.homePath` in the existing `defineAppConfig` in `server/plugins/config.ts` as `DEVELOPING.md` describes.
  
 -Use `adding-a-feature` for functional parity and `frontend-design` for a user-facing screen. Keep feature guidance here; do not rewrite `README.md` or `DESIGN.md`. After all edits, run one typecheck, one doctor check, and one browser smoke of the primary workflow, including overlap rejection, cancellation freeing the slot, and authenticated landing. Skip production build and extra test suites.

package/src/templates/builder-code-starter/app/components/layout/Layout.tsx.patch

@@ -1,7 +1,7 @@
 ===================================================================
 --- a/app/components/layout/Layout.tsx
 +++ b/app/components/layout/Layout.tsx
-@@ -1,189 +1,28 @@
+@@ -1,188 +1,28 @@
 -import { useT } from "@agent-native/core/client/i18n";
 -import { HeaderActionsProvider } from "@agent-native/toolkit/app-shell/header-actions";
 -import {
@@ -23,6 +23,7 @@
 -  SheetTitle,
 -} from "@/components/ui/sheet";
 -import { APP_TITLE } from "@/lib/app-config";
+-import { HOME_PATH, isChatPathname } from "@/lib/chat-paths";
 -
 -import { Sidebar } from "./Sidebar";
 -
@@ -43,8 +44,8 @@
 -
 -function routeOwnsToolbar(pathname: string): boolean {
 -  return (
--    pathname === "/home" ||
--    pathname.startsWith("/chat/") ||
+-    pathname === HOME_PATH ||
+-    isChatPathname(pathname) ||
 -    pathname === "/database" ||
 -    pathname.startsWith("/extensions")
 -  );
@@ -66,8 +67,7 @@
 -  const t = useT();
 -  const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
 -  const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
--  const isChatRoute =
--    location.pathname === "/home" || location.pathname.startsWith("/chat/");
+-  const isChatRoute = isChatPathname(location.pathname);
 -  // Settings brings its own navigation, header, and agent toggle, so it
 -  // renders full width.
 -  const settingsOwnsChrome = isSettingsPathname(location.pathname);
@@ -79,8 +79,7 @@
 -  const chatHomeHandoffPending = isAgentChatHomeHandoffActive("chat");
 -  useAgentChatHomeHandoffLinks({
 -    storageKey: "chat",
--    isChatPath: (pathname) =>
--      pathname === "/home" || pathname.startsWith("/chat/"),
+-    isChatPath: isChatPathname,
 -    requireActiveHandoff: true,
 -  });
 -

package/src/templates/builder-code-starter/app/hooks/use-navigation-state.ts.patch

@@ -1,7 +1,18 @@
 ===================================================================
 --- a/app/hooks/use-navigation-state.ts
 +++ b/app/hooks/use-navigation-state.ts
-@@ -5,83 +5,37 @@
+@@ -1,85 +1,41 @@
+ import { appBasePath, appPath } from "@agent-native/core/client/api-path";
+ import { useAgentRouteState } from "@agent-native/core/client/navigation";
+ 
+-import {
+-  chatThreadPath,
+-  HOME_PATH,
+-  isChatPathname,
+-  NEW_CHAT_PATH,
+-  threadIdFromPath,
+-} from "@/lib/chat-paths";
+ import { TAB_ID } from "@/lib/tab-id";
  
  export interface NavigationState {
    view: string;
@@ -31,19 +42,9 @@
    });
  }
  
--function threadIdFromPath(pathname: string): string | null {
--  const match = pathname.match(/^\/chat\/([^/]+)/);
--  if (!match) return null;
--  try {
--    const value = decodeURIComponent(match[1]).trim();
--    return value || null;
--  } catch {
--    return null;
--  }
--}
--
  function viewForPath(pathname: string): string {
--  if (isChatPath(pathname)) return "chat";
+-  if (isChatPathname(pathname)) return "chat";
+-  if (pathname === HOME_PATH) return "home";
 -  if (pathname.startsWith("/database")) return "database";
 -  if (pathname.startsWith("/extensions")) return "extensions";
 -  if (pathname.startsWith("/observability")) return "observability";
@@ -60,9 +61,10 @@
  function pathForView(view?: string): string {
    switch (view) {
 -    case "chat":
-     case "home":
 -    case "ask":
--      return "/home";
+-      return NEW_CHAT_PATH;
+     case "home":
+-      return HOME_PATH;
 -    case "database":
 -      return "/database";
 -    case "extensions":
@@ -77,29 +79,20 @@
 -      return "/settings/organization";
 +      return "/";
      default:
--      return "/home";
+-      return HOME_PATH;
 +      return "/";
    }
  }
  
--function pathForCommand(command: any): string {
+-export function pathForCommand(command: any): string {
 -  const path = pathForView(command?.view);
--  if (path !== "/home") return path;
+-  if (command?.view !== "chat" && command?.view !== "ask") return path;
 -  const threadId =
 -    typeof command?.threadId === "string" ? command.threadId.trim() : "";
--  return threadId ? `/chat/${encodeURIComponent(threadId)}` : path;
+-  return threadId ? chatThreadPath(threadId) : path;
 -}
 -
  function routerPath(path: string): string {
    const basePath = appBasePath();
    if (!basePath) return path;
    if (path === basePath) return "/";
-@@ -89,8 +43,4 @@
-     return path.slice(basePath.length) || "/";
-   }
-   return path;
- }
--
--function isChatPath(pathname: string): boolean {
--  return pathname === "/home" || pathname.startsWith("/chat/");
--}

package/src/templates/builder-code-starter/app/root.tsx.patch

@@ -1,7 +1,7 @@
 ===================================================================
 --- a/app/root.tsx
 +++ b/app/root.tsx
-@@ -1,70 +1,50 @@
+@@ -1,76 +1,50 @@
  import { configureTracking } from "@agent-native/core/client/analytics";
  import { appPath } from "@agent-native/core/client/api-path";
  import { useDbSync } from "@agent-native/core/client/hooks";
@@ -33,6 +33,12 @@
  import { AppToolkitProvider } from "@/components/ui/toolkit-provider";
  import { useNavigationState } from "@/hooks/use-navigation-state";
 -import { APP_TITLE } from "@/lib/app-config";
+-import {
+-  HOME_PATH,
+-  isChatPathname,
+-  NEW_CHAT_PATH,
+-  threadIdFromPath,
+-} from "@/lib/chat-paths";
 +import { APP_NAME, APP_TITLE } from "@/lib/app-config";
  import { TAB_ID } from "@/lib/tab-id";
  
@@ -79,7 +85,7 @@
          <meta name="mobile-web-app-capable" content="yes" />
          <meta
            name="apple-mobile-web-app-status-bar-style"
-@@ -94,91 +74,19 @@
+@@ -100,96 +74,19 @@
    });
    return null;
  }
@@ -104,7 +110,7 @@
 -  const navigate = useNavigate();
 -  const t = useT();
 -  const location = useLocation();
--  const isChatThread = location.pathname.startsWith("/chat/");
+-  const isChatThread = threadIdFromPath(location.pathname) !== null;
 -  useCommandMenuShortcut(useCallback(() => setCmdkOpen(true), []));
 -  return (
 -    <>
@@ -123,8 +129,13 @@
 -              {t("chat.newChat")}
 -            </CommandMenu.Item>
 -          ) : null}
--          {!isChatThread && location.pathname !== "/home" ? (
--            <CommandMenu.Item onSelect={() => navigate("/home")}>
+-          {location.pathname !== HOME_PATH ? (
+-            <CommandMenu.Item onSelect={() => navigate(HOME_PATH)}>
+-              {t("navigation.home")}
+-            </CommandMenu.Item>
+-          ) : null}
+-          {!isChatPathname(location.pathname) ? (
+-            <CommandMenu.Item onSelect={() => navigate(NEW_CHAT_PATH)}>
 -              {t("navigation.chat")}
 -            </CommandMenu.Item>
 -          ) : null}

package/src/templates/builder-code-starter/template-layer.json

@@ -5,16 +5,20 @@
     "CHANGELOG.md",
     "actions/navigate.spec.ts",
     "app/components/chat",
+    "app/components/home",
     "app/components/layout/AgentInspector.test.tsx",
     "app/components/layout/AgentInspector.tsx",
     "app/components/layout/Header.tsx",
     "app/components/layout/Sidebar.tsx",
     "app/i18n",
     "app/i18n-data.ts",
+    "app/lib/chat-paths.spec.ts",
+    "app/lib/chat-paths.ts",
     "app/lib/sidebar-thread-state.spec.ts",
     "app/lib/sidebar-thread-state.ts",
     "app/routes/agent.tsx",
     "app/routes/chat.$threadId.tsx",
+    "app/routes/chat._index.tsx",
     "app/routes/database.tsx",
     "app/routes/extensions.$id.$slug.tsx",
     "app/routes/extensions.$id.tsx",

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

@@ -25,8 +25,12 @@ never copy a value into app code or client-visible state.
 3. If the app truly needs its own API key, register it with the shared secrets
    surface. Do not build a parallel key form or storage table.
 4. Use deployment configuration only for a secret owned by the deployed app,
-   such as a webhook verification secret. A deployment key must not stand in
-   for a user's or customer's provider credential.
+   such as a webhook verification secret. LLM inference keys are an app-owned
+   exception: self-hosted apps may use provider keys from deployment env as a
+   shared fallback, while scoped user or organization keys take precedence.
+   Hosted-workspace deployments backed by a shared database must not share
+   those env keys across apps or tenants. This exception does not authorize
+   using env credentials to access user-owned provider data.
 
 ## Register an app-local API key
 

package/src/templates/chat/AGENTS.md

@@ -1,6 +1,6 @@
 # Chat — Agent Guide
 
-Chat is the minimal chat-first agent-native app. `/` redirects to shared sign-in; authenticated chat starts at `/home`. Actions carry capabilities; screens exist only for durable workflows.
+Chat is the minimal chat-first agent-native app. `/` redirects to shared sign-in, then `/home`, the editable Get started page. Chat lives at `/chat`; new chats start there. Actions carry capabilities; screens exist only for durable workflows.
 
 ## Skills
 
@@ -19,12 +19,12 @@ For custom branding, keep `server/plugins/agent-native-email-branding.ts` aligne
 
 ## Application state
 
-- `navigation` describes the view and selected ids. Chat is `chat` at `/home`; `/` opens shared sign-in/signup.
+- `navigation` describes the view and selected ids. Chat is `chat` at `/chat` and `/chat/<threadId>`; the Get started page is `home` at `/home`; `/` opens shared sign-in/signup.
 - Use `navigate` when supported and `view-screen` for a fresh read of visible details; basic navigation is already in `<current-screen>`.
 
 ## Building a domain app
 
-Choose the primary workflow and route before editing. Add a domain route under `app/routes/` and set `app.homePath` in `server/plugins/agent-native-email-branding.ts` with `defineAppConfig`. Keep `/home` as Chat. Add a static link in `app/components/layout/Sidebar.tsx` before `ChatThreadsSection`; `Header.tsx` maps `/home` to Chat and uses `APP_TITLE` elsewhere. Shared sidebar and AgentInspector remain.
+Choose the primary workflow and route before editing. Add a domain route under `app/routes/` and set `app.homePath` in `server/plugins/agent-native-email-branding.ts` with `defineAppConfig`. The default Get started page lives at `/home`, and Chat stays at `/chat`; edit `app/routes/home.tsx` when replacing that page with a domain-specific home. Add a static link in `app/components/layout/Sidebar.tsx` before `ChatThreadsSection`; `Header.tsx` uses `APP_TITLE` elsewhere. Shared sidebar and AgentInspector remain.
 
 Use `adding-a-feature` for functional parity and `frontend-design` for a user-facing screen. Keep feature guidance here; do not rewrite `README.md` or `DESIGN.md`. After all edits, run one typecheck, one doctor check, and one browser smoke of the primary workflow, including overlap rejection, cancellation freeing the slot, and authenticated landing. Skip production build and extra test suites.
 

package/src/templates/chat/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable user-facing changes to this app are documented here.
 
+## 2026-10-10
+
+### Fixed
+
+- Large prompts with full context remain available to retry when sending fails.
+
 ## 2026-09-30
 
 ### Improved