@agent-native/core 0.22.4 → 0.22.7

package/docs/content/database.md

@@ -74,6 +74,35 @@ For cases where you need raw SQL outside of Drizzle queries:
 - `isPostgres()` — runtime dialect check
 - `intType()` — returns the correct integer type for the current dialect
 
+## Migrations and Schema Updates {#migrations}
+
+In hosted environments, multiple deployment previews, branches, and the production server share the same underlying database. Therefore, database schema updates must follow strict constraints to avoid data loss and service disruption.
+
+### The "Zero Destructive Changes" Rule
+
+All database schema updates must be **strictly additive**.
+
+- **Do not drop tables or columns.**
+- **Do not rename tables or columns.** Renaming a column or table looks like a drop + create sequence to Drizzle, which will permanently delete your existing production data.
+- If a column needs to be renamed or replaced, add the new column alongside the old one, update your application code to read from/write to both, migrate the data, and only retire the old column in a later release once no active deployments are referencing it.
+
+> [!WARNING]
+> **Never run `drizzle-kit push` against a production database.**
+> Template database schemas only define app-specific domain tables; they do not define central framework tables (`user`, `session`, `application_state`, etc.). If you run `drizzle-kit push` against production, Drizzle will detect these framework tables as "not in schema" and attempt to drop them, causing immediate system-wide failure and data loss.
+
+### Safe Migration Path
+
+Instead of pushing directly, schema changes should be applied via SQL migrations executed at application startup. Implement additive migrations within a server plugin (e.g., `server/plugins/db.ts`) by invoking the framework's `runMigrations()` helper:
+
+```ts
+import { runMigrations } from "@agent-native/core/db";
+
+export default defineNitroPlugin(async () => {
+  // Executes pending SQL migrations safely at startup
+  await runMigrations();
+});
+```
+
 ## Environment Variables {#environment-variables}
 
 | Variable           | Purpose                                           |

package/docs/content/dispatch.md

@@ -25,7 +25,7 @@ If you're running a single template standalone, you don't need Dispatch — each
 
 ## What Dispatch does {#what-it-does}
 
-Five capabilities, all sitting on top of the same workspace database the other apps use.
+Six capabilities, all sitting on top of the same workspace database the other apps use.
 
 ### Central inbox
 
@@ -45,6 +45,12 @@ Dispatch auto-discovers the other apps in your workspace as A2A peers — no man
 
 The behavioral rule lives in the dispatch agent's instructions: domain work belongs to the domain app. Dispatch is the orchestrator, not the specialist.
 
+### Unified MCP gateway
+
+Dispatch can also be the single MCP URL for external agents. Connect Claude, ChatGPT, Codex, Cursor, or another MCP host to `https://dispatch.agent-native.com/_agent-native/mcp` once, then manage which apps that gateway can reach from Dispatch's **Agents** page. The gateway exposes `list_apps`, `ask_app`, and `open_app`, filtered by the selected app grants, so external agents can route work to Mail, Calendar, Analytics, Brain, and workspace apps without a separate browser authorization for every app.
+
+Direct per-app MCP URLs still exist when you intentionally want one isolated app surface. For most workspace use, the Dispatch gateway is the lower-friction path.
+
 ### Workspace resources
 
 Skills, guardrail instructions, agent profiles, and reference resources can be authored once in Dispatch and inherited by the rest of the workspace. Resources with **All apps** scope are global: Dispatch stores them once at workspace scope, and every app agent reads them at runtime. They are not copied into each app, and there is no manual workspace-resource sync step. App shared resources and personal resources can override or narrow the workspace defaults locally. Selected resources use explicit per-app grants for app-specific exceptions.

package/docs/content/external-agents.md

@@ -14,12 +14,21 @@ The external-agent bridge closes the loop. First you connect your own agent to a
 
 Add the hosted app as a remote MCP connector in your chat host, sign in, and enable it in a chat.
 
-**Shortcut:** every hosted agent-native app serves a one-page connect helper at `https://<app>/_agent-native/mcp/connect` (for example [mail.agent-native.com/\_agent-native/mcp/connect](https://mail.agent-native.com/_agent-native/mcp/connect), [analytics.agent-native.com/\_agent-native/mcp/connect](https://analytics.agent-native.com/_agent-native/mcp/connect)). It shows the MCP URL with a one-click copy button and a tab strip — Claude · ChatGPT · Cursor · Claude Code · Codex · Other — each with the exact steps or copy-able command for that host. Bookmark it and share with non-developer teammates; everything below is also reachable from that page.
+**Recommended for cross-app work:** connect Dispatch once:
+
+```text
+https://dispatch.agent-native.com/_agent-native/mcp
+```
+
+Dispatch exposes a unified MCP gateway with `list_apps`, `ask_app`, and `open_app`. In Dispatch's **Agents** page, choose whether that gateway can reach all apps or only selected apps. This avoids adding Mail, Calendar, Analytics, Brain, and every workspace app as separate MCP resources.
+
+**Shortcut:** every hosted agent-native app serves a one-page connect helper at `https://<app>/_agent-native/mcp/connect` (for example [dispatch.agent-native.com/\_agent-native/mcp/connect](https://dispatch.agent-native.com/_agent-native/mcp/connect), [mail.agent-native.com/\_agent-native/mcp/connect](https://mail.agent-native.com/_agent-native/mcp/connect), [analytics.agent-native.com/\_agent-native/mcp/connect](https://analytics.agent-native.com/_agent-native/mcp/connect), or `https://<your-app>/_agent-native/mcp/connect`). It shows the MCP URL with a one-click copy button and a tab strip — Claude · ChatGPT · Cursor · Claude Code · Codex · Other — each with the exact steps or copy-able command for that host. Bookmark it and share with non-developer teammates; everything below is also reachable from that page.
 
 Use the hosted app's MCP URL:
 
 | App       | Remote MCP URL                                         |
 | --------- | ------------------------------------------------------ |
+| Dispatch  | `https://dispatch.agent-native.com/_agent-native/mcp`  |
 | Mail      | `https://mail.agent-native.com/_agent-native/mcp`      |
 | Analytics | `https://analytics.agent-native.com/_agent-native/mcp` |
 | Any app   | `https://<app-host>/_agent-native/mcp`                 |
@@ -61,6 +70,17 @@ ChatGPT's full MCP connector flow is currently workspace/admin gated. Use ChatGP
 
 If the ChatGPT workspace does not expose custom MCP connectors, ask a workspace admin to enable them first.
 
+#### Recovering "Connector name already exists" {#chatgpt-drafts}
+
+ChatGPT creates a **draft** the moment you click **Create app** — even if you closed the OAuth popup before approving the scopes. The draft is not visible under **Enabled apps**, but it still owns the name, so retrying with the same name surfaces a `"Connector name already exists"` toast. Recovery is fully self-service in the ChatGPT UI:
+
+1. Open **Settings → Apps**.
+2. Scroll past **Enabled apps** and **Advanced settings** to the **Drafts** section (labeled _"Private apps you've created in developer mode"_).
+3. Click the draft with the conflicting name.
+4. Either press **Connect** to finish OAuth in place (no rename needed), or open the **⋯** overflow menu and choose **Delete** and re-add via **Advanced settings → Create app**.
+
+There is no "Drafts" tab on the **Add more / app directory** dialog, so non-admins sometimes miss the section entirely — it lives further down the same Settings → Apps page that lists enabled apps.
+
 ### Cursor {#cursor}
 
 1. Open Cursor → **Settings → MCP**.
@@ -91,13 +111,13 @@ Use this flow for local agent clients on your machine — Claude Code, Claude Co
 If you have the Agent-Native CLI installed, run:
 
 ```bash
-agent-native connect https://mail.agent-native.com
+agent-native connect https://dispatch.agent-native.com
 ```
 
 Or run the same command through npm without installing anything globally:
 
 ```bash
-npx @agent-native/core connect https://mail.agent-native.com
+npx @agent-native/core connect https://dispatch.agent-native.com
 ```
 
 The command asks which local agent clients should receive MCP config. All clients are preselected the first time; after you choose, the selection is saved to `~/.agent-native/connect.json` so the next run can reuse it with Enter, or you can edit the checked items.
@@ -116,7 +136,7 @@ Restart the agent client after connecting so it picks up the new MCP server; OAu
 
 Use `--client codex` (or `--client claude-code`, `--client claude-code-cli`, `--client cowork`, `--client all`) to skip the picker for scripts or one-off installs.
 
-Connect every first-party hosted app at once with:
+When you truly need isolated per-app MCP resources, connect every first-party hosted app at once with:
 
 ```bash
 npx @agent-native/core connect --all
@@ -156,7 +176,7 @@ claude mcp add --transport http agent-native-mail \
   https://mail.agent-native.com/_agent-native/mcp
 ```
 
-This is the same URL-only entry that `agent-native connect https://mail.agent-native.com --client claude-code` writes for you. Then run `/mcp` in Claude Code and choose **Authenticate**. The client discovers auth from the MCP server's `401 WWW-Authenticate` challenge, fetches `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, dynamically registers a public OAuth client, opens the app's authorization page, and stores the resulting token securely. ChatGPT developer-mode connectors use the same server URL:
+This is the same URL-only entry that `agent-native connect https://dispatch.agent-native.com --client claude-code` writes for you. Then run `/mcp` in Claude Code and choose **Authenticate**. The client discovers auth from the MCP server's `401 WWW-Authenticate` challenge, fetches `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, dynamically registers a public OAuth client, opens the app's authorization page, and stores the resulting token securely. ChatGPT developer-mode connectors use the same server URL:
 
 ```text
 https://mail.agent-native.com/_agent-native/mcp
@@ -199,13 +219,13 @@ Claude Code and other CLI-first clients still receive the same resources and met
 
 On top of the per-action tools the MCP server exposes a stable verb set, so an external agent has a predictable surface without guessing per-app action names:
 
-| Tool                                       | Side effects | Returns                                                                              |
-| ------------------------------------------ | ------------ | ------------------------------------------------------------------------------------ |
-| `list_apps`                                | none         | workspace apps + their URLs / running state                                          |
-| `open_app({ app, view, params? })`         | none         | a `buildDeepLink` URL (surfaces as an "Open …" link)                                 |
-| `ask_app({ app, message })`                | agent loop   | routes a natural-language task to that app's in-app agent (delegates to `ask-agent`) |
-| `create_workspace_app({ name, template })` | scaffolds    | a new app booted via the workspace path, plus its running URL + deep link            |
-| `list_templates`                           | none         | the allow-listed templates only                                                      |
+| Tool                                               | Side effects | Returns                                                                                     |
+| -------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- |
+| `list_apps`                                        | none         | workspace apps + their URLs / running state                                                 |
+| `open_app({ app, view?, path?, params?, embed? })` | none         | a deep link or same-origin route; `embed: true` renders the full app inline where supported |
+| `ask_app({ app, message })`                        | agent loop   | routes a natural-language task to that app's in-app agent (delegates to `ask-agent`)        |
+| `create_workspace_app({ name, template })`         | scaffolds    | a new app booted via the workspace path, plus its running URL + deep link                   |
+| `list_templates`                                   | none         | the allow-listed templates only                                                             |
 
 `create_workspace_app` rejects any non-allow-listed template — the public template allow-list in `packages/shared-app-config/templates.ts` is authoritative and CI-guarded; an external agent cannot widen it. A same-named template action overrides a builtin (template-over-core precedence). Disable the whole set with `MCPConfig.builtinCrossAppTools: false`.
 
@@ -281,7 +301,9 @@ export default defineAction({
 
 The MCP server advertises extension `io.modelcontextprotocol/ui`, adds `_meta.ui.resourceUri` plus `_meta["ui/resourceUri"]` to `tools/list`, and exposes the HTML through `resources/list` + `resources/read` using MIME `text/html;profile=mcp-app`. The stdio proxy forwards those resource handlers from the live app, so desktop and CLI clients see the same resources as HTTP clients.
 
-Keep the existing `link` builder even when adding `mcpApp`. CLI-only clients, older hosts, and any host that does not render MCP Apps will ignore the UI metadata and still need the `"Open in … →"` link. Treat `mcpApp.resource.html` like `link`: synchronous, deterministic, and self-contained; declare external origins in `csp`. Use the full app deep link for heavyweight authenticated workflows that do not fit cleanly in an embedded iframe.
+Keep the existing `link` builder even when adding `mcpApp`. CLI-only clients, older hosts, and any host that does not render MCP Apps will ignore the UI metadata and still need the `"Open in … →"` link. Treat `mcpApp.resource.html` like `link`: synchronous, deterministic, and self-contained; declare external origins in `csp`.
+
+For heavyweight authenticated workflows, reuse the real React app instead of rebuilding a plain-HTML mini UI. Core exports `embedApp()` from `@agent-native/core/mcp` and `@agent-native/core`; attach it to an action that already has a `link` builder. The embedded MCP App calls the app-only `create_embed_session` helper, exchanges a one-time SQL ticket at `/_agent-native/embed/start`, and loads the target route in an iframe with a short-lived browser session plus a bearer fallback for same-origin fetches. `open_app({ app, path, embed: true })` is the generic escape hatch for routes such as dashboards, filtered inboxes, calendar draft views, and extension pages.
 
 ### The `link` contract {#link-contract}
 
@@ -403,6 +425,8 @@ If `connect dev` cannot infer your local owner identity from an existing connect
 
 The standard OAuth path never exposes tokens to MCP Apps: the host stores OAuth access/refresh tokens and mediates tool calls and `resources/read` over the authenticated MCP connection. Embedded iframes receive app data and tool results, not bearer secrets.
 
+Full-app embeds also avoid handing the MCP bearer token to the browser. The MCP caller mints a one-time embed ticket in SQL; the iframe launch route consumes it and sets a short-lived, iframe-safe browser session cookie. The landing URL carries a temporary `__an_embed_token` query param only long enough for the client to capture it, remove it from the address bar, and attach it to same-origin `fetch` calls when third-party cookies are blocked. Embed sessions are route-scoped; app fetches include the current embedded target, and the server rejects token reuse outside the minted route. Production `X-Frame-Options: DENY` stays in place for normal page loads and is omitted only when that embed session marker is present.
+
 The fallback hosted `connect` flow never copies the deployment's shared secret. Instead:
 
 - A logged-in browser session mints a **per-user, scoped, revocable** token — an `A2A_SECRET`-signed JWT carrying the caller's `sub` + `org_domain` and a unique `jti`, so every tool run stays tenant-scoped via `runWithRequestContext`.

package/docs/content/key-concepts.md

@@ -84,9 +84,9 @@ Core SQL stores are auto-created and available in every template:
 
 ```ts
 // Drizzle schema for domain data
-import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { table, text, integer } from "@agent-native/core/db/schema";
 
-export const forms = sqliteTable("forms", {
+export const forms = table("forms", {
   id: text("id").primaryKey(),
   title: text("title").notNull(),
   schema: text("schema").notNull(), // JSON
@@ -239,7 +239,7 @@ The framework supports every Drizzle-supported database. Never write SQL that on
 Use the framework helpers for dialect-agnostic SQL:
 
 ```ts
-import { getDbExec, isPostgres, intType } from "@agent-native/core/db/client";
+import { getDbExec, isPostgres, intType } from "@agent-native/core/db";
 
 // getDbExec() auto-converts ? params to $1 for Postgres
 const client = getDbExec();

package/docs/content/messaging.md

@@ -349,7 +349,7 @@ This means a multi-app workspace fronted by Dispatch is more resilient than a si
 ### Common pitfalls {#pitfalls}
 
 - **Don't double-read the request body.** h3 v2's body stream is consume-once: if you call `readBody(event)` after the framework has already parsed `event.node.req.body` (or vice versa), the second read hangs the request indefinitely. This shows up most often with Resend and SendGrid — both stream the inbound payload and the dangling read never resolves, the platform times out, and the webhook gets retried until it dedups. If you wrap the framework's webhook handler in your own middleware, pass the already-parsed `IncomingMessage` via the `incoming` option rather than letting the handler re-parse.
-- **Don't run agent loops inside the webhook handler.** The handler must enqueue and return — the agent loop runs in the processor's fresh execution. Putting it inline guarantees serverless freeze kills the run.
+- **Don't run agent loops inside the webhook handler.** The handler must enqueue and return — the agent loop runs in the processor's fresh execution. Putting it inline guarantees serverless freeze kills the run. Furthermore, public-facing gateway integrations (such as Netlify or Vercel) enforce strict HTTP timeout limits (e.g., Netlify's 10-second request limit). Because agent runs and tools often take longer than this window, trying to run the loop synchronously within the webhook request will cause the gateway to terminate the connection, resulting in aborted execution and dropped replies. The HMAC-signed self-webhook `/process-task` queue pattern is the only way to satisfy gateway limits while executing the full agent loop safely.
 - **Don't rely on dedup memory across cold starts.** The dedup key lives in the SQL `(platform, external_event_key)` unique index, not an in-process Map. If you replace the queue, keep the SQL-level dedup or duplicate Slack retries will trigger duplicate agent runs.
 - **Keep the self-webhook URL reachable.** The processor URL is built from `APP_URL` / `URL` / `DEPLOY_URL` / `BETTER_AUTH_URL`, falling back to the inbound request headers. On preview deploys with rewritten hostnames, set one of these explicitly or the dispatch will hit a 404.
 

package/docs/content/onboarding.md

@@ -132,6 +132,32 @@ export default defineNitroPlugin(() => {
 });
 ```
 
+### Checking Workspace Connections in Onboarding
+
+When building templates that interact with external services (like Slack, Google Workspace, GitHub, or HubSpot), you should check if the workspace has already connected and granted that provider connection to your application. This prevents users from having to duplicate credentials (like API keys or refresh tokens) in their local environment variables when a central, managed connection exists.
+
+You can check connection readiness in your `isComplete` callback using the connection catalog APIs:
+
+```ts
+import { listWorkspaceConnectionProviderCatalogForApp } from "@agent-native/core/workspace-connections";
+
+// Inside registerOnboardingStep:
+isComplete: async () => {
+  // Check if a managed workspace connection exists and is ready
+  const catalog = await listWorkspaceConnectionProviderCatalogForApp("gmail");
+  const connection = catalog.find((p) => p.providerId === "google-gmail");
+
+  if (connection?.status === "ready" && connection.granted) {
+    return true;
+  }
+
+  // Fall back to local environment variable check
+  return !!process.env.GMAIL_REFRESH_TOKEN;
+};
+```
+
+Refer to the [Workspace Connections](/docs/workspace-connections) documentation for the full list of connection provider catalog methods.
+
 ### Method kinds
 
 | Kind               | Payload                                               | Use for                                   |

package/docs/content/template-content.md

@@ -155,7 +155,7 @@ The four places to look when changing behavior:
 - **`app/components/editor/`** — the Tiptap editor. Add a new node type under `extensions/` and register it in `DocumentEditor.tsx`. The bubble toolbar, slash menu, and hover previews are all component files you can edit.
 - **`.agents/skills/`** — guidance the agent reads before acting. If you add a new capability (say, a CMS publishing pipeline), drop a `SKILL.md` in a new skill folder so the agent uses it correctly. Existing skills: `document-editing`, `notion-integration`, `real-time-sync`, `delegate-to-agent`, `storing-data`, `self-modifying-code`, `security`, `frontend-design`, `create-skill`, `capture-learnings`.
 - **`AGENTS.md`** — the top-level agent guide with the action cheatsheet and common-tasks table. Update it whenever you add a major feature so the agent discovers it without exploring.
-- **`server/db/schema.ts`** — data model. Add a column or table here, run `pnpm db:push`, and it's available to every action.
+- **`server/db/schema.ts`** — data model. Add a column or table here. For local development, you can sync your database schema using `pnpm db:push`. In hosted production environments, **never** run `db:push` (doing so will attempt to drop core framework tables not defined in the template's schema); instead, apply schema updates via strictly additive migration scripts executed at startup (see [Database](/docs/database#migrations) for guidelines).
 - **`shared/notion-markdown.ts`** — markdown-to-Notion-blocks conversion. Extend this if you add new block types that need to round-trip through Notion.
 
 The agent can make all of these changes itself — ask it to "add a tags column to documents and expose it in the sidebar" and it will update the schema, migrate, wire the UI, and write the action.

package/docs/content/template-dispatch.md

@@ -83,6 +83,15 @@ When Dispatch approval policy is enabled, applying a shared or team-wide dream p
 
 Use Dreams when you want to answer questions like "what did agents keep getting wrong this week?", "what should we remember?", or "which repeated lesson deserves a skill?" Inbound Slack, email, Telegram, WhatsApp, and web-derived evidence is treated as untrusted input, so proposals from those sources require review and provenance before they affect shared memory. Workspace-instruction proposals require durable evidence spanning at least two threads or two source apps; eval-only noise, account setup issues, quota limits, and single-app UI wording corrections stay out of global instructions.
 
+### Dream Input Validation Boundaries
+
+Because evidence is collected from external, untrusted sources (such as chat transcripts, webhooks, and third-party integrations), the Dream processor enforces strict input validation boundaries to prevent prompt injection and payload-size attacks:
+
+- **Byte Size Limits:** Individual thread payloads are capped at a maximum of 10KB of text content per message, and candidate scans are truncated if they exceed 100KB in total to prevent context exhaustion.
+- **Sanitization:** All text inputs are sanitized to strip control characters, binary payloads, and non-printable Unicode ranges.
+- **Schema Validation:** Inbound debug data and thread history are parsed against strict Zod schemas before being compiled into LLM prompts. Any candidate structure that fails schema validation is immediately discarded from the processing batch.
+- **Escaping:** All user-provided text chunks are dynamically escaped when formatted into the prompt templates to prevent prompt injections (e.g., trying to hijack the Dream loop to write arbitrary instructions).
+
 In the Dispatch UI, open **Dreams** to run a manual pass, review candidate threads, inspect the report, and open each proposal's review sheet before applying or rejecting it. Use **Settings** to edit the recurring cron schedule, source scope, timeout/concurrency limits, candidate limit, and minimum candidate threshold; use **Ensure schedule** after saving when you want the `jobs/dispatch-dream.md` recurring job materialized from those settings. The review sheet shows approval behavior, the current target content, proposed content, and source evidence. Agents use the same workflow through actions:
 
 - `list-dream-candidates` finds recent threads with grounded signals such as explicit user corrections, failed runs, tool errors, feedback, eval failures, and successful checkpointed workflows. Pass `sourceId: "all"` or `sourceIds` to scan multiple thread-debug sources; `sourceTimeoutMs`, `sourceConcurrency`, `sourceStartStaggerMs`, `threadConcurrency`, and `threadTimeoutMs` keep production scans partial and bounded, and the response includes per-source health.

package/docs/content/template-starter.md

@@ -10,14 +10,14 @@ Starter is the minimum viable agent-native app. You get the six-rules architectu
 <!-- screenshot:
   app: starter
   view: /
-  shows: Blank-slate app with sidebar (Starter brand, Home / New App / Observability), centered "Blank app" card with Start building prompt button + 3 quick-action tiles (New app / Documentation / Theme), agent chat panel on the right
+  shows: Blank-slate app with sidebar (Blank app brand, Home / Observability), centered "Blank app" card with Start building prompt button + quick-action tiles for Documentation and Theme, agent chat panel on the right
   account: screenshot-account (no domain data needed — starter ships with no seed schema)
   capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
 -->
 
 ![Starter scaffold with the agent sidebar and a clean blank-slate UI](/screenshots/starter.png)
 
-Pick Starter when you're not sure which domain template fits, or when you want to learn the framework by doing — there's almost nothing to delete.
+Pick Starter when you're not sure which domain template fits, or when you want to learn the framework by doing. It is scaffolding for your app, not a launcher for more apps, so starter-derived apps should be renamed and reshaped into the actual product.
 
 ## What's in it {#whats-in-it}
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.22.4",
+  "version": "0.22.7",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",

package/src/templates/workspace-core/AGENTS.md

@@ -55,11 +55,14 @@ available to every workspace app. Only create or request per-app vault grants
 when Dispatch's vault access setting is switched to manual mode.
 
 Workspace apps are discovered from `apps/<app-name>/package.json`. There is no
-separate workspace app registry to edit for Dispatch to list the app. Use
-relative workspace links like `/<app-name>` and never hardcode `localhost`,
-`127.0.0.1`, `8080`, `8100`, or any dev port in app cards, instructions,
-redirects, or navigation; the active workspace gateway/browser origin owns the
-port. React Router apps must preserve `APP_BASE_PATH` / `VITE_APP_BASE_PATH` in
+separate workspace app registry to edit for Dispatch to list the app. Always
+save a concise, human-readable `description` there; Dispatch lists and A2A
+connected-agent context use the app name plus description so agents know what
+the app does. Use relative workspace links like `/<app-name>` and never
+hardcode `localhost`, `127.0.0.1`, `8080`, `8100`, or any dev port in app
+cards, instructions, redirects, or navigation; the active workspace
+gateway/browser origin owns the port. React Router apps must preserve
+`APP_BASE_PATH` / `VITE_APP_BASE_PATH` in
 `app/entry.client.tsx` via `appBasePath()` so the app hydrates correctly when
 mounted at `/<app-name>`. Use the framework/template UI stack for standard UI:
 shadcn/ui components and `@tabler/icons-react`. Do not add `lucide-react` or
@@ -80,3 +83,9 @@ workspace root. In production, Dispatch posts new-app requests to Builder
 branch creation; Builder should still scaffold the separate workspace app. The
 workspace dev gateway (`pnpm dev`) detects new `apps/<app-name>` directories
 automatically.
+
+When using the starter template, treat it as scaffolding only. The finished app
+must be branded as the requested app, with its own home screen, navigation,
+package metadata, manifest, and domain workflow. Do not leave visible
+`Starter`, `Blank app`, `Start building`, or `New app` UI in a starter-derived
+app.

package/src/templates/workspace-root/AGENTS.md

@@ -108,6 +108,11 @@ coding agents can discover the same workspace-wide guidance from the root.
   should still create the separate workspace app, not patch starter. The local
   workspace gateway detects new app directories automatically and starts each
   app server lazily on first visit.
+- When using the starter template, treat it as scaffolding only. The finished
+  app must be branded as the requested app, with its own home screen,
+  navigation, package metadata, manifest, and domain workflow. Do not leave
+  visible `Starter`, `Blank app`, `Start building`, or `New app` UI in a
+  starter-derived app.
 
 ## Workspace Identity
 

package/src/templates/workspace-root/README.md

@@ -106,6 +106,9 @@ pnpm exec agent-native create crm --template=starter
 The CLI detects the workspace root and scaffolds a minimal app that already
 depends on `@{{APP_NAME}}/shared`. Edit only the routes you care about;
 auth, org switching, skills, and instructions come from the shared package.
+Starter is only the source scaffold: the finished app should use its own name,
+home screen, navigation, package metadata, and manifest rather than leaving
+starter or new-app UI in place.
 If the request starts from Dispatch in production, Dispatch sends it to Builder
 branch creation; that branch should still add a new `apps/<app-id>` workspace
 app rather than adding files to `apps/starter`.