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

package/docs/content/template-forms-integrations.mdx

@@ -0,0 +1,40 @@
+---
+title: "Forms in a Multi-App Workspace"
+description: "How Forms connects to Dispatch and other apps, and the two real mechanisms other apps use to act on a form or send data into it."
+---
+
+# Forms in a Multi-App Workspace
+
+Forms is one app among many in a [Dispatch](/docs/template-dispatch) workspace. This page covers what that actually means in practice: how the connection works, and concrete ways other apps can act on a form or send data into it. See [Forms](/docs/template-forms) for the overview.
+
+## How Forms connects to Dispatch
+
+Whether this is automatic depends on how Forms and Dispatch were set up together, not on whether either one is hosted or running locally.
+
+### Same workspace: automatic
+
+If Forms and Dispatch were generated or added together into one Agent-Native workspace (via `create` or `add-app`) and deployed as one unit, they already share one `.env`, one `A2A_SECRET`, and one workspace registry. Discovery and authenticated A2A calling both just work, with nothing to set up, whether that workspace is running on your machine or in production. This is the expected setup for a real multi-app product built on Forms.
+
+### Separate deployments: one manual step
+
+If Forms and Dispatch are two independently created Agent-Native projects, they don't share a secret and can't call each other yet. Connecting them takes one manual step on each side: add a `remote-agents/<id>.json` resource with a shared secret, from Settings → Connected Agents, the Agent page's Connections tab, or Dispatch → Agents → Add external agent. See [A2A Protocol](/docs/a2a-protocol) for the full walkthrough.
+
+To check which situation you're in, ask either app's agent "what apps can you see?" If Forms is missing from Dispatch's answer, you're in the second case.
+
+## Integration strategies
+
+**Natural-language delegation through Dispatch.** A sibling app doesn't need a special integration to work with Forms. It can hand Forms' agent a plain-English request, like "how many responses does the beta signup form have," the same way you would in chat, and Forms answers or acts on it directly. This is the real mechanism behind something like a question that arrives in Slack or Mail turning into a real answer from Forms: Dispatch (or the app that received the message) delegates the request to Forms' agent, and Forms handles it like any other prompt.
+
+**Other apps submitting into a form directly.** Forms doesn't need A2A or Dispatch at all for another app to send it data. Any app can send a plain web request to a form's public submit address, the same way an anonymous respondent filling out the public page does. The framework's own feedback button works exactly this way. It sends a submission to a deployed Forms app from inside another app's sidebar, along with which page and which app the feedback came from, and Forms records it as a normal response. This means any app in your workspace can send structured data into a form without an A2A connection at all, just a plain web request.
+
+**Staying decoupled.** Whether Forms is answering a delegated question or receiving a direct submission, it never needs to know the calling app's credentials, and the calling app never needs to know anything about how Forms stores its data. Delegation goes through the agent like any other prompt, and a direct submission goes through the same public address a human respondent would use.
+
+## What's next
+
+- [**Forms**](/docs/template-forms) — the overview and what it replaces
+- [**Features**](/docs/template-forms-features) — every feature area, with setup steps for each
+- [**Talk to the Agent**](/docs/template-forms-agent) — every prompt by task and how the agent sees your screen
+- [**Developer Guide**](/docs/template-forms-developers) — every action and the data model behind these features
+- [**Dispatch**](/docs/template-dispatch) — the workspace control plane these patterns run under
+- [**A2A Protocol**](/docs/a2a-protocol) — how apps discover, authenticate with, and call each other
+- [**Multi-App Workspace**](/docs/multi-app-workspace) — the general pattern of composing first-party apps instead of nesting them

package/docs/content/template-forms.mdx

@@ -1,26 +1,31 @@
 ---
 title: "Forms"
-description: "Agent-Native form builder — describe the form you want in chat, fine-tune it visually, publish a public link, and watch responses roll in."
+description: "An agent-powered form builder that replaces Typeform and Google Forms with one app you own. Describe the form you want in chat, publish a protected link, and watch responses get routed, exported, and summarized automatically."
 ---
 
 # Forms
 
-<!-- i18n-copy-ignore: Agent-Native is a proper name; punctuation is locale-invariant. -->
+Forms is a form builder for anyone who needs to collect information without writing code. Use it for signups, feedback, registrations, or surveys. Describe the form you want to the agent, fine-tune it visually when you want more direct control, and publish a link that anyone can fill out.
 
-Forms is a form builder for anyone who needs to collect information — signups, feedback, registrations, surveys — without writing code. Describe the form you want to the agent, fine-tune it visually when you want direct control, and publish a link anyone can fill out.
+<Cards columns={1}>
 
-<WireframeBlock id="doc-block-forms1">
-  <Screen
-    surface="desktop"
-    html={
-      "<div style='min-height:560px;box-sizing:border-box;display:flex;align-items:center;justify-content:center;padding:56px 40px'><div style='display:flex;flex-direction:column;align-items:center;justify-content:center;gap:24px;width:min(700px,92%);min-height:420px'><div style='text-align:center'><h1 style='margin:0'>Ask Forms</h1><p class='wf-muted' style='margin:10px 0 0'>Describe the form you want. Fine-tune it visually once it exists.</p></div><div class='wf-card' style='width:100%;min-height:140px;display:flex;flex-direction:column;gap:18px'><span class='wf-muted'>Create a beta signup form with role, team size, and priority use case</span><div style='flex:1'></div><div style='display:flex;align-items:center;gap:10px'><div style='flex:1'></div><button class='primary'>↑</button></div></div><div style='display:flex;gap:8px;flex-wrap:wrap;justify-content:center'><span class='wf-pill'>Post responses to Slack</span><span class='wf-pill'>Summarize this week's submissions</span><span class='wf-pill'>Make this form shorter</span></div></div></div>"
-    }
-  />
-</WireframeBlock>
+### [Try it out now →](https://forms.agent-native.com)
 
-Every new session opens on **Ask Forms**, a chat where you describe what you want. The agent creates the form, and you move into the visual editor whenever you want to adjust fields, validation, or publishing settings by hand — both paths edit the same SQL-backed form definition, so nothing gets out of sync.
+See Forms live and publish a real form.
 
-<Diagram id="doc-block-forms2" title="Build, publish, collect" summary={"The agent and the visual editor edit one SQL-backed form definition. The public fill page is unauthenticated, and submissions route server-side to your destinations."}>
+</Cards>
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2F70338a3cf0cc402580858a409dd5bd6a?alt=media&token=f2c7c8e9-6cf3-4e03-865d-abc499d87ff6&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="A brief tour of the forms application."
+  caption="A brief tour of the forms application."
+  autoplay={true}
+  loop={true}
+/>
+
+Every new session opens on **Ask Forms**, a chat where you describe what you want. The agent creates the form for you. You can then move into the visual editor any time you want to adjust fields, validation, or publishing settings by hand. Both ways of editing update the same form, so nothing gets out of sync.
+
+<Diagram id="doc-block-forms2" title="Build, publish, collect" summary={"The agent and the visual editor edit the same form. Anyone can open the public fill page without signing in, and new submissions are sent to your destinations automatically."}>
 
 ```html
 <div class="diagram-flow">
@@ -85,38 +90,46 @@ Every new session opens on **Ask Forms**, a chat where you describe what you wan
 
 </Diagram>
 
-## What you can do with it
+## What it replaces
+
+<Comparison>
 
-- **Build forms conversationally.** "Create a contact form," "add an NPS score question," "make the email field required." See [field types and JSON schema](/docs/template-forms-building-publishing#field-types).
-- **Fine-tune visually.** Edit labels, placeholders, required state, options, and field order from the builder UI when you want direct control.
-- **Publish and protect a public form.** Share a public link, and turn on captcha protection or fully anonymous responses when you need them — see [Building and publishing a form](/docs/template-forms-building-publishing).
-- **Review responses and ask for insights.** "Summarize this week's submissions," "chart submissions by day" — see [Responses, insights, and destinations](/docs/template-forms-responses).
-- **Route submissions automatically.** Send new responses to Slack, Discord, Google Sheets, or a webhook the moment they arrive.
+### Before
 
-## Getting started
+- Typeform, Google Forms, or a form built by hand for collecting responses
+- Copying new submissions into Slack or a spreadsheet by hand
+- A separate tool just to summarize what came back
+- Setting up a Zapier automation to get responses into Sheets or a webhook
 
-Live demo: [forms.agent-native.com](https://forms.agent-native.com).
+### After
 
-1. **Ask for the form you want.** Ask Forms is the landing chat — describe the audience and what should happen after submission.
-2. **Refine in the editor.** Adjust labels, validation, choices, and order in the visual builder when direct editing is faster.
-3. **Publish and share.** Use the public form URL for respondents, then watch results arrive in the Responses view.
-4. **Connect destinations.** Route new submissions to Slack, Discord, Google Sheets, webhooks, or your own extension point.
+- One form that the agent and the visual editor both update
+- New responses are sent to Slack, Discord, Sheets, or a webhook the moment they arrive
+- Ask for a summary and get a chart, a table, or both, without a separate tool
+- Conditional fields, spam protection, and anonymous mode are all built into the same builder
 
-### Useful prompts
+</Comparison>
+
+## Forms in a multi-app workspace
+
+If you run Forms alongside other apps in [Dispatch](/docs/template-dispatch), a form is no longer just a page you open by hand. The Forms agent can pass along questions that belong to another app, and other apps can send responses into your form directly, the same way the framework's own feedback button does. See [Forms in a Multi-App Workspace](/docs/template-forms-integrations) for how this works.
+
+## What you can do with it
 
-- "Create a beta signup form with role, team size, and priority use case."
-- "Add a required NPS question and a free-text follow-up."
-- "Create an anonymous customer feedback form and give me the public link."
-- "Post every new response to the product Slack channel."
-- "What's the setup for my beta signup form?"
-- "Summarize this week's submissions and group them by customer segment."
-- "Make this form shorter without losing the fields we need for routing."
+- **Build forms conversationally.** Try prompts like "Create a contact form," "add an NPS score question," or "make the email field required." See [the available field types](/docs/template-forms-features#field-types).
+- **Fine-tune visually.** Edit labels, placeholders, required fields, options, and field order right in the form builder when you want more direct control.
+- **Publish and protect a public form.** Share a public link, and turn on spam protection or fully anonymous responses when you need them. See [Features](/docs/template-forms-features).
+- **Review responses and ask for insights.** Try prompts like "Summarize this week's submissions" or "Chart submissions by day." See [Features](/docs/template-forms-features#response-insights).
+- **Route submissions automatically.** Paste in a Slack, Discord, Google Sheets, or generic webhook URL, and new responses are sent there the moment they arrive.
 
 ## What's next
 
-- [**Building and publishing a form**](/docs/template-forms-building-publishing) — field types, conditional logic, and public-form protections
-- [**Responses, insights, and destinations**](/docs/template-forms-responses) — analyzing, exporting, and routing submissions
-- [**Forms — data model and actions**](/docs/template-forms-developers) — the SQL schema and action reference, for developers
+- [**Features**](/docs/template-forms-features) — field types, conditional logic, publishing, protections, responses, insights, and routing, with setup steps for each
+- [**Talk to the Agent**](/docs/template-forms-agent) — prompts by task and how the agent sees your screen
+- [**Forms in a Multi-App Workspace**](/docs/template-forms-integrations) — delegation and the public submit endpoint other apps use
+- [**Developer Guide**](/docs/template-forms-developers) — the SQL schema, action reference, and routes, for developers
 - [**Templates**](/docs/cloneable-saas) — the Cloneable SaaS model
+- [**Getting Started**](/docs/getting-started) — the framework fundamentals: actions, application state, and live sync
 - [**Actions**](/docs/actions-overview) — the action system powering the builder
 - [**Messaging**](/docs/messaging) — Slack and other submission destinations
+- [**Sharing**](/docs/sharing) — the share-grant model form shares build on

package/docs/content/template-mail-developers.mdx

@@ -69,7 +69,7 @@ Every operation is a TypeScript file in `templates/mail/actions/`, auto-mounted
 
 **Automations & Gmail filters**
 
-- `manage-automations` / `trigger-automations` — agent-facing natural-language triage rules
+- `manage-email-rules` / `trigger-automations` — agent-facing natural-language triage rules
 - `create-automation` / `list-automations` / `update-automation` / `delete-automation` — UI-only, back the Settings automations list (same `automation_rules` table)
 - `get-automation-settings` / `update-automation-settings` — UI-only, the engine/model used to evaluate rules
 - `manage-gmail-filters` — native Gmail filters (list/create/replace/delete); Gmail has no update endpoint, so `replace` creates a new filter and deletes the old one
@@ -329,7 +329,7 @@ Emails flowing through the API have the shape `{ id, threadId, from, to, cc, sub
 
 Mail is yours to change. Everything important lives in a handful of places — start there.
 
-**Adding an agent capability.** Add a new file under `templates/mail/actions/` using `defineAction`. Your action becomes an agent tool, a CLI command (`pnpm action <name>`), and a typed frontend hook surface through `useActionQuery` / `useActionMutation`. Look at `templates/mail/actions/star-email.ts` for a short example or `templates/mail/actions/manage-automations.ts` for one with multiple sub-actions. See the [actions](/docs/actions-overview) docs for the full pattern.
+**Adding an agent capability.** Add a new file under `templates/mail/actions/` using `defineAction`. Your action becomes an agent tool, a CLI command (`pnpm action <name>`), and a typed frontend hook surface through `useActionQuery` / `useActionMutation`. Look at `templates/mail/actions/star-email.ts` for a short example or `templates/mail/actions/manage-email-rules.ts` for one with multiple sub-actions. See the [actions](/docs/actions-overview) docs for the full pattern.
 
 **Changing the UI.** Routes are in `templates/mail/app/routes/` and components in `templates/mail/app/components/email/` and `templates/mail/app/components/layout/`. The app uses shadcn/ui primitives from `app/components/ui/` and Tabler Icons — stick to those.
 
@@ -337,7 +337,7 @@ Mail is yours to change. Everything important lives in a handful of places — s
 
 **Changing data or settings.** Mail's own schema is in `templates/mail/server/db/schema.ts`. Settings reads and writes go through `readSetting`/`writeSetting` (or the per-user `getUserSetting`/`putUserSetting`) from `@agent-native/core/settings`. Application state (navigation, drafts, one-shot commands) uses `readAppState`/`writeAppState` from `@agent-native/core/application-state`.
 
-**Adding a new automation action type.** Extend the action schema in `templates/mail/actions/manage-automations.ts` and the executor in `templates/mail/actions/trigger-automations.ts`.
+**Adding a new automation action type.** Extend the action schema in `templates/mail/actions/manage-email-rules.ts` and the executor in `templates/mail/actions/trigger-automations.ts`.
 
 **Adding a sidebar CRM integration.** Follow the pattern in `server/handlers/gong.ts`, `pylon.ts`, or `apollo.ts` for a read-only sidebar panel, or register a new provider in `MAIL_PROVIDER_API_IDS` (`server/lib/provider-api.ts`) to make it reachable through `provider-api-request` as well.
 

package/docs/content/toolkit-settings.mdx

@@ -33,7 +33,7 @@ free the moment an app adopts the shared page.
 | `useAgentSettingsTabs()` | Framework-provided agent, model, key, automation, and voice tabs that apps can mount.              |
 | `SettingsSearchEntry`    | A deep-link target (label, keywords, tab, and hash) that makes a control findable.                 |
 | `<LanguagePicker>`       | Standard language selector for app settings.                                                       |
-| `openAgentSettings()`    | Compatibility escape hatch for opening the sidebar settings tab when needed.                       |
+| `openAgentSettings()`    | Opens the canonical `/settings` page at the requested section.                                     |
 | Deep links               | Stable links such as `/settings/integrations/secrets/OPENAI_API_KEY` and `/settings/integrations`. |
 
 ## Page Contract {#page-contract}
@@ -111,8 +111,8 @@ on so settings stay findable everywhere.
   control so users can find settings by name instead of scanning tabs.
 - Link to tabs by hash so setup prompts can send users to the exact missing
   credential.
-- Use the agent sidebar settings only as a compact access point, not as the
-  primary home for every setting.
+- Keep settings in the canonical `/settings` pages. Agent chat should remain
+  focused on conversation and never render settings inline.
 
 ## What's next
 

package/docs/content/webmcp.mdx

@@ -1,6 +1,6 @@
 ---
 title: "WebMCP"
-description: "Expose explicit Agent-Native client actions to browser agents and consume page-local WebMCP tools from Agent-Native chat."
+description: "Automatically expose Agent-Native actions to browser agents, register explicit client actions, and consume page-local WebMCP tools from Agent-Native chat."
 search: "WebMCP browser tools modelContext registerTool getTools executeTool browser session"
 ---
 
@@ -15,24 +15,42 @@ discover them, and the browser mediates execution.
 
 The framework supports both directions:
 
-<!-- i18n-copy-ignore: oxfmt-only table alignment; no translated prose changed. -->
-
 | You want to...                                                           | Use                                                                                                      |
 | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
-| Make selected actions in your app available to a browser agent           | `createAgentNativeWebMcpRegistration`                                                                    |
+| Make backend actions available to a browser agent                        | Automatic on authenticated pages through `AppProviders`                                                  |
+| Make page-local client actions available to a browser agent              | `createAgentNativeWebMcpRegistration`                                                                    |
 | Let Agent-Native chat discover and call WebMCP tools in the current page | `createAgentNativeWebMcpClient` plus `webmcp` on `AgentNativeEmbedded` or `AgentNativeFrame`             |
 | Connect a headless or remote agent to an app                             | [MCP Server](/docs/mcp-protocol), [External Agents](/docs/external-agents), or [A2A](/docs/a2a-protocol) |
 
 WebMCP is not a network MCP server and does not make a closed app globally
 discoverable. A consuming agent needs an open, connected browser page and the
-page must explicitly opt into the tools it exposes.
+page must expose tools to it.
 
 The browser API is experimental and may change. See the [Chrome WebMCP
 Imperative API](https://developer.chrome.com/docs/ai/webmcp/imperative-api) and
 the [WebMCP specification](https://webmachinelearning.github.io/webmcp/) for
 the current browser contract.
 
-## Produce WebMCP tools
+## Automatic backend actions
+
+On an authenticated app page, `AppProviders` automatically registers eligible
+backend actions with `document.modelContext`. The tools are derived from the
+same action registry used by the in-app agent and execute through the same
+validated, authenticated server dispatcher. This includes agent-only actions
+declared with `http: false`; WebMCP does not turn those actions into public HTTP
+APIs.
+
+An action is eligible when `agentTool` is not `false` and `needsApproval` is
+not declared. The latter is a fail-closed boundary: the server action approval
+contract belongs to the agent loop and cannot be delegated to a browser hint.
+Public paths, signed-out pages, and `sessionBypass` surfaces do not register
+backend action tools. Browsers without `document.modelContext` simply keep the
+normal app behavior.
+
+No per-app WebMCP list or new `defineAction` metadata is required. Change the
+existing action definition when its exposure should change.
+
+## Explicit page-local actions
 
 Register only the actions that should be available to a page agent. The
 framework removes the action's local `run` function from the descriptor and
@@ -181,10 +199,10 @@ remote or headless tool calls, and use A2A when another app's agent should
 receive work and reason over it. WebMCP is an opt-in browser bridge, not a
 replacement for either network protocol.
 
-The framework does not auto-register every backend action as a WebMCP tool.
-Choose a small explicit producer list, keep side effects behind approval, and
-retain normal MCP or A2A exposure for capabilities that must work without an
-open browser page.
+The framework automatically projects eligible backend actions and still lets a
+page register explicit client-only capabilities. Keep server-side approval
+actions on the agent loop, and retain normal MCP or A2A exposure for
+capabilities that must work without an open browser page.
 
 ## Compatibility and safety
 
@@ -195,7 +213,8 @@ open browser page.
 - Treat descriptions, schemas, annotations, and results as page-provided
   data. The framework validates and bounds them, but agents should still treat
   `untrustedContentHint` results as untrusted content.
-- Use `stop()` when the owning page or component unmounts so stale tools do not
-  remain available.
+- Automatic registrations are aborted when the private app shell unmounts. Use
+  `stop()` for explicit page-local registrations so stale tools do not remain
+  available.
 - Keep server MCP and A2A endpoints for remote access. WebMCP only reaches the
   tools registered in a connected browser context.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.176.1",
+  "version": "0.176.2-nightly-20260831184159",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -435,8 +435,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.32",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.20",
-    "@agent-native/toolkit": "^0.17.6"
+    "@agent-native/recap-cli": "0.5.21",
+    "@agent-native/toolkit": "^0.19.0-nightly-20260831184159"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/chat/.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/chat/.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/chat/AGENTS.md

@@ -1,8 +1,9 @@
 # Chat — Agent Guide
 
-Chat is the minimal chat-first agent-native app. Chat is the primary surface;
-actions carry the real capabilities, and screens exist only where a workflow
-needs durable UI around the conversation.
+Chat is the minimal chat-first agent-native app. The public root is a marketing
+surface; the authenticated chat app starts at `/home`. Actions carry the real
+capabilities, and screens exist only where a workflow needs durable UI around
+the conversation.
 
 ## Skills
 
@@ -46,7 +47,7 @@ brand. Its `app.name` is used in transactional emails, and its optional
 ## Application State
 
 - `navigation` describes the current view and selected entity ids. The default
-  chat view is `chat` at `/`.
+  chat view is `chat` at `/home`; `/` is the public SSR marketing page.
 - `navigate` moves the UI when the app supports it.
 - `view-screen` is the first tool to call when the user's visible context
   matters.

package/src/templates/chat/app/components/layout/Header.tsx

@@ -10,7 +10,7 @@ import { useLocation } from "react-router";
 import { APP_TITLE } from "@/lib/app-config";
 
 const pageTitleKeys: Record<string, string> = {
-  "/": "navigation.chat",
+  "/home": "navigation.chat",
   "/observability": "navigation.observability",
   "/agent": "settings.agentTitle",
   "/settings": "navigation.settings",

package/src/templates/chat/app/components/layout/Layout.tsx

@@ -38,7 +38,7 @@ const SIDEBAR_COLLAPSE_KEY = "chat.sidebar.collapsed";
  */
 function routeOwnsToolbar(pathname: string): boolean {
   return (
-    pathname === "/" ||
+    pathname === "/home" ||
     pathname.startsWith("/chat/") ||
     pathname === "/database" ||
     pathname.startsWith("/extensions")
@@ -52,7 +52,7 @@ export function Layout({ children }: LayoutProps) {
   const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
   const [sidebarCollapsed, setSidebarCollapsed] = useState(true);
   const isChatRoute =
-    location.pathname === "/" || location.pathname.startsWith("/chat/");
+    location.pathname === "/home" || location.pathname.startsWith("/chat/");
   const chatHomeHandoffActive = useAgentChatHomeHandoff({
     storageKey: "chat",
     activePath: location.pathname,
@@ -61,7 +61,8 @@ export function Layout({ children }: LayoutProps) {
   const chatHomeHandoffPending = isAgentChatHomeHandoffActive("chat");
   useAgentChatHomeHandoffLinks({
     storageKey: "chat",
-    isChatPath: (pathname) => pathname === "/" || pathname.startsWith("/chat/"),
+    isChatPath: (pathname) =>
+      pathname === "/home" || pathname.startsWith("/chat/"),
     requireActiveHandoff: true,
   });
 
@@ -100,7 +101,7 @@ export function Layout({ children }: LayoutProps) {
   const ownsToolbar = routeOwnsToolbar(location.pathname);
   function openAskAgentFullscreen() {
     focusAgentChat();
-    navigateWithAgentChatViewTransition(navigate, "/");
+    navigateWithAgentChatViewTransition(navigate, "/home");
   }
 
   const contentFrame = (

package/src/templates/chat/app/components/layout/Sidebar.tsx

@@ -3,11 +3,10 @@ import {
   useChatThreads,
   type ChatThreadSummary,
 } from "@agent-native/core/client/agent-chat";
-import { appPath } from "@agent-native/core/client/api-path";
 import { useT } from "@agent-native/core/client/i18n";
 import { openCommandMenu } from "@agent-native/core/client/navigation";
 import { OrgSwitcher } from "@agent-native/core/client/org";
-import { FeedbackButton } from "@agent-native/core/client/ui";
+import { AgentNativeIcon, FeedbackButton } from "@agent-native/core/client/ui";
 import { SidebarFooterActions } from "@agent-native/toolkit/app-shell";
 import {
   ChatHistoryRail,
@@ -36,7 +35,7 @@ const navItems = [
   {
     icon: IconMessageCircle,
     labelKey: "navigation.chat",
-    href: "/",
+    href: "/home",
     view: "chat",
   },
 ];
@@ -150,7 +149,7 @@ function ChatThreadsSection({ open }: { open: boolean }) {
   );
   const displayedActiveThreadId =
     threadIdFromPath(location.pathname) ??
-    (location.pathname === "/" ? null : activeThreadId);
+    (location.pathname === "/home" ? null : activeThreadId);
   const chatItems = useMemo<ChatHistoryItem[]>(
     () =>
       visibleThreads.map((thread) => ({
@@ -190,7 +189,7 @@ function ChatThreadsSection({ open }: { open: boolean }) {
     persistActiveThreadId(threadId);
     navigateWithAgentChatViewTransition(
       navigate,
-      options?.isNew ? "/" : chatThreadPath(threadId),
+      options?.isNew ? "/home" : chatThreadPath(threadId),
     );
     window.requestAnimationFrame(() => {
       window.dispatchEvent(
@@ -275,7 +274,7 @@ export function Sidebar({
   const navigate = useNavigate();
   const t = useT();
   const isChatRoute =
-    location.pathname === "/" || location.pathname.startsWith("/chat/");
+    location.pathname === "/home" || location.pathname.startsWith("/chat/");
   const ToggleIcon = collapsed
     ? IconLayoutSidebarLeftExpand
     : IconLayoutSidebarLeftCollapse;
@@ -357,7 +356,7 @@ export function Sidebar({
         )}
       >
         <Link
-          to="/"
+          to="/home"
           onClick={(event) => {
             if (
               !collapsible ||
@@ -387,21 +386,9 @@ export function Sidebar({
                 : undefined
           }
         >
-          <img
-            src={appPath("/agent-native-icon-light.svg")}
-            alt=""
+          <AgentNativeIcon
             aria-hidden="true"
-            width={28}
-            height={16}
-            className="block h-4 w-7 shrink-0 object-contain object-center dark:hidden"
-          />
-          <img
-            src={appPath("/agent-native-icon-dark.svg")}
-            alt=""
-            aria-hidden="true"
-            width={28}
-            height={16}
-            className="hidden h-4 w-7 shrink-0 object-contain object-center dark:block"
+            className="h-3.5 w-6 shrink-0 text-sidebar-accent-foreground"
           />
           <div className={cn("min-w-0", collapsed && "sr-only")}>
             <p className="truncate text-sm font-semibold text-sidebar-accent-foreground">
@@ -421,7 +408,7 @@ export function Sidebar({
           {navItems.map((item) => {
             const Icon = item.icon;
             const isActive =
-              item.href === "/"
+              item.href === "/home"
                 ? isChatRoute
                 : location.pathname.startsWith(item.href);
             const link = (
@@ -429,7 +416,7 @@ export function Sidebar({
                 to={item.href}
                 onClick={(event) => {
                   if (
-                    item.href === "/" &&
+                    item.href === "/home" &&
                     !isChatRoute &&
                     !event.metaKey &&
                     !event.ctrlKey &&
@@ -437,7 +424,7 @@ export function Sidebar({
                     !event.altKey
                   ) {
                     event.preventDefault();
-                    navigateWithAgentChatViewTransition(navigate, "/");
+                    navigateWithAgentChatViewTransition(navigate, "/home");
                   }
                 }}
                 className={navClass({ isActive })}
@@ -505,7 +492,11 @@ export function Sidebar({
           })}
         </nav>
 
-        <div className={cn(collapsed ? "px-1 py-1" : "px-3 py-2")}>
+        <div
+          className={cn(
+            collapsed ? "px-1 py-1 empty:hidden" : "px-3 py-2 empty:hidden",
+          )}
+        >
           <OrgSwitcher
             reserveSpace
             className={

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

@@ -55,7 +55,7 @@ function pathForView(view?: string): string {
     case "chat":
     case "home":
     case "ask":
-      return "/";
+      return "/home";
     case "database":
       return "/database";
     case "extensions":
@@ -69,16 +69,16 @@ function pathForView(view?: string): string {
     case "team":
       return "/settings/organization";
     default:
-      return "/";
+      return "/home";
   }
 }
 
 function pathForCommand(command: any): string {
   const path = pathForView(command?.view);
-  if (path !== "/") return path;
+  if (path !== "/home") return path;
   const threadId =
     typeof command?.threadId === "string" ? command.threadId.trim() : "";
-  return threadId ? `/chat/${encodeURIComponent(threadId)}` : "/";
+  return threadId ? `/chat/${encodeURIComponent(threadId)}` : path;
 }
 
 function routerPath(path: string): string {
@@ -92,5 +92,5 @@ function routerPath(path: string): string {
 }
 
 function isChatPath(pathname: string): boolean {
-  return pathname === "/" || pathname.startsWith("/chat/");
+  return pathname === "/home" || pathname.startsWith("/chat/");
 }