@agent-native/core 0.59.0 → 0.60.0

package/src/templates/workspace-core/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, or advanced features.
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options.
+
+If the action runner is unavailable, search the package docs directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`.
+
+## Useful Slugs
+
+| Need | Slugs |
+| --- | --- |
+| Actions and typed client calls | `actions`, `client` |
+| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
+| UI state visible to the agent | `context-awareness` |
+| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
+| Automations and schedules | `automations`, `recurring-jobs` |
+| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.

package/src/templates/workspace-core/.agents/skills/client-side-routing/SKILL.md

@@ -66,6 +66,15 @@ export default function Settings() {
 
 If a page needs per-route data (e.g. sidebar highlighting the active document), derive it inside the layout from `useParams()` / `useLocation()` — don't pass it as a prop through every route file.
 
+## Chat-First Routes
+
+If `/` is a full-page chat such as `AgentChatHome`, keep the app shell mounted
+around it when possible so `AgentSidebar` URL sync and route warmup stay active.
+If the chat route intentionally lives outside the shell, add a tiny app-owned
+prewarm for the routes agents commonly open from that chat. In local dev,
+React Router can update the address bar before a cold Vite route chunk commits,
+which makes navigation look broken even when the URL is correct.
+
 ## Adding a New Route
 
 - **Pattern #1** (AppLayout in `root.tsx`): just render page content — nothing else.

package/src/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: composable-mini-apps
+description: >-
+  Build many focused workspace apps that compose through agent discovery and
+  A2A. Use when designing headless mini-apps or cross-app workflows.
+---
+
+# Composable Mini-Apps
+
+## Rule
+
+Prefer many one-job apps in a workspace over one oversized app. A headless app
+can own a provider, dataset, workflow, or specialist action surface without a
+full UI; the main agent composes those apps through discovery and A2A.
+
+## Shape
+
+- Give each mini-app one clear job, a concise `package.json` description, and
+  action names that describe the job it owns.
+- Keep provider credentials and upstream API details in the app that owns that
+  provider or workflow. Other apps should delegate to it instead of copying its
+  integration code.
+- Use a tiny status/config screen only when users need to inspect state. A
+  pure headless app is fine when its job is invoked by agents, automations, or
+  sibling apps.
+- If two workflows only share a helper, put the helper in `packages/shared`;
+  keep the workflow actions in separate apps.
+
+## Discovery And Invocation
+
+The main agent should discover available siblings before assuming capability:
+
+- Runtime agents receive an `<available-apps>` block built from
+  `discoverAgents()`. Workspace siblings are layered in by
+  `discoverWorkspaceAgents()`.
+- UI shells, headless surfaces, and scripts can read the same registry through
+  `GET /_agent-native/agents?selfAppId=<app-id>`.
+- Code or CLI callers should use the first-class A2A invocation path
+  (`invokeAgent()` / `agent-native invoke`) when they need to call an app by
+  id, name, or URL.
+- In the agent loop, use `call-agent` with the sibling app id when another app
+  owns the work or data. Never call the current app through `call-agent`; use
+  local actions instead.
+
+Send narrow prompts to siblings: name the exact question, relevant ids, date
+ranges, and expected output shape. Preserve returned ids and URLs verbatim.
+
+## Provider APIs
+
+Provider-specific actions are shortcuts, not limits. When the upstream API can
+answer the question better than a first-class shortcut, call
+`provider-api-catalog` and `provider-api-docs` as needed, then
+`provider-api-request` against the real provider endpoint. For broad joins,
+searches, or absence claims, stage the bounded corpus with `stageAs` and reduce
+it with `query-staged-dataset` or code.
+
+When composing apps, make the provider-owning mini-app do those
+`provider-api-request` calls. The orchestrator should delegate a bounded job;
+it should not reimplement every provider endpoint locally.
+
+## Example
+
+For a sales-intelligence workspace, split the job into small apps:
+
+| App | Owns | Calls |
+| --- | --- | --- |
+| `hubspot-pipeline` | CRM deals, contacts, companies, associations | `provider-api-request` with provider `hubspot` |
+| `gong-evidence` | Calls, transcripts, snippets, speaker evidence | `provider-api-request` with provider `gong` |
+| `knowledge-base` | Internal docs, pricing rules, playbooks | local search/read actions |
+| `deal-brief` | Orchestration and final brief | `invokeAgent()` or `call-agent` to the three apps |
+
+Flow: `deal-brief` asks `hubspot-pipeline` for the target account and open
+deals, asks `gong-evidence` for recent transcript evidence about those deals,
+asks `knowledge-base` for relevant playbook guidance, then synthesizes the
+answer. That is a HubSpot→Gong→knowledge-base chain made of focused apps,
+not a single app that clones every provider integration.
+
+## Don't
+
+- Do not clone Mail, Calendar, Analytics, Brain, Assets, or another first-party
+  app just to reuse its data. Delegate or link to the existing app.
+- Do not hide a multi-provider workflow inside a giant "misc tools" app.
+- Do not add one-off provider endpoints when `provider-api-request` can express
+  the upstream API safely.
+- Do not create wrapper routes that only re-export another app's action or A2A
+  result.
+
+## Related Skills
+
+- **a2a-protocol** - How apps expose and call A2A endpoints.
+- **actions** - How each mini-app exposes its own operation surface.
+- **external-agents** - How external MCP hosts route through workspace apps.
+- **storing-data** - How app-owned data stays SQL-backed and portable.

package/src/templates/workspace-core/.agents/skills/context-awareness/SKILL.md

@@ -125,6 +125,15 @@ await writeAppState("navigate", { view: "inbox", threadId: "abc123" });
 **UI side** — use `useAgentRouteState`, shown above. It polls command keys,
 dedupes `_writeId`, deletes consumed commands, and applies app-local routing.
 
+When a destination has a real URL, let the `navigate` command carry that local
+`path` (plus semantic fields when useful) and have the UI prefer `path` before
+falling back to semantic routing. Keep app navigation single-channel: do not
+also write `__set_url__` for the same navigation. `__set_url__` belongs to the
+framework URL tools (`set-url-path`, `set-search-params`) and URL-only filter
+changes. If a command can arrive while a chat stream is rendering, prefer
+`navigate(path, { replace: true, flushSync: true })` over a view-transition
+wrapper so the URL and visible route commit together.
+
 ## Jitter Prevention
 
 When the agent writes to application-state via script helpers (`writeAppState`), the write is tagged with `requestSource: "agent"`. The UI uses the `ignoreSource` option on `useDbSync()` with a per-tab ID so it ignores its own writes while still picking up changes from agents, other tabs, and scripts.
@@ -171,7 +180,7 @@ The mail template demonstrates these patterns working together:
 - Keep shareable filters in URL query params so `<current-url>` and `set-search-params` work
 - Update `view-screen` when adding new features — it should return data for every view
 - Use `useAgentRouteState` or `useSemanticNavigationState` for UI-side navigation sync and command consumption
-- Use the one-shot `navigate` command pattern for semantic agent-initiated navigation
+- Use the one-shot `navigate` command pattern for app navigation; include a same-origin `path` when the target URL is known
 - Tag agent writes with `requestSource: "agent"` (the script helpers do this automatically)
 
 ## Don't
@@ -179,6 +188,7 @@ The mail template demonstrates these patterns working together:
 - Don't assume the user is on a specific page — always check navigation state
 - Don't hardcode navigation paths in scripts — read the current state and branch
 - Don't write to the `navigation` key from the agent — it belongs to the UI. Use `navigate` instead.
+- Don't write both `navigate` and `__set_url__` for one app navigation; competing consumers can make the browser URL change before React Router commits the page.
 - Don't ignore the `<current-screen>` block — it tells you where the user is
 - Don't duplicate whole URL query strings into `navigation` when `<current-url>` already exposes them
 - Don't store fetched data in navigation state — it holds IDs and semantic UI state only. The `view-screen` script fetches the actual data.

package/src/templates/workspace-core/.agents/skills/secrets/SKILL.md

@@ -111,7 +111,7 @@ row is written — status is derived from `hasOAuthTokens("google")`.
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { readAppSecret } from "@agent-native/core/secrets";
 import { getRequestUserEmail } from "@agent-native/core/server";
 

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

@@ -4,6 +4,23 @@ These instructions apply to every app in the {{APP_TITLE}} workspace. Keep
 only rules that should be shared across all apps here. App-specific behavior
 belongs in that app's own `AGENTS.md` or `.agents/skills/` directory.
 
+## Framework Docs Lookup
+
+Version-matched Agent Native docs ship with `@agent-native/core` in
+`node_modules/@agent-native/core/docs`.
+
+- From an app directory, use `pnpm action docs-search --query "<topic>"`,
+  `pnpm action docs-search --slug <slug>`, or `pnpm action docs-search --list`.
+- If the action runner is unavailable, read
+  `node_modules/@agent-native/core/docs/AGENTS.md` and search
+  `node_modules/@agent-native/core/docs/content/` directly with `rg`.
+- For advanced workspace features, start with `workspace`, `multi-app-workspace`,
+  `a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
+  `external-agents`, `mcp-protocol`, `sharing`, and `security`.
+
+Use package docs for framework APIs, and use this `AGENTS.md` plus
+`.agents/skills/` for workspace-specific conventions.
+
 ## Shared Context
 
 Add company, product, compliance, or support-context notes that every app
@@ -55,7 +72,7 @@ become a separate workspace app under `apps/<app-name>`, mounted at
 `/<app-name>`.
 
 Do not implement a new app by adding a route, page, component, or file to
-`apps/starter` or another existing app unless the user explicitly asks to modify
+`apps/chat` or another existing app unless the user explicitly asks to modify
 that existing app.
 
 Dispatch vault access is workspace-wide by default: every saved vault key is
@@ -101,8 +118,8 @@ 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
+When using the chat 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
+`Chat`, `Starter`, `Blank app`, `Start building`, or `New app` UI in a chat-derived
 app.

package/src/templates/workspace-core/src/server/index.ts

@@ -1,5 +1,5 @@
 // Export workspace-wide server plugin overrides here when you need them.
-// Starter apps inherit these exports, so provide explicit framework defaults
+// Chat-derived apps inherit these exports, so provide explicit framework defaults
 // to keep generated workspaces warning-free until a workspace customizes them.
 import {
   createAgentChatPlugin,

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

@@ -6,6 +6,22 @@ in `apps/<app>/AGENTS.md`; shared cross-app behavior belongs in
 The root `.agents/skills` path points at the shared package's skills so local
 coding agents can discover the same workspace-wide guidance from the root.
 
+## Framework Docs Lookup
+
+Version-matched Agent Native docs ship with `@agent-native/core` in
+`node_modules/@agent-native/core/docs`.
+
+- From an app directory, use `pnpm action docs-search --query "<topic>"`,
+  `pnpm action docs-search --slug <slug>`, or `pnpm action docs-search --list`.
+- From the workspace root, read `node_modules/@agent-native/core/docs/AGENTS.md`
+  and search `node_modules/@agent-native/core/docs/content/` directly with `rg`.
+- For advanced workspace features, start with `workspace`, `multi-app-workspace`,
+  `a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
+  `external-agents`, `mcp-protocol`, `sharing`, and `security`.
+
+Use package docs for framework APIs, and use `packages/shared/AGENTS.md` plus
+`packages/shared/.agents/skills/` for workspace-specific conventions.
+
 ## Core Agent Rule
 
 - All AI/LLM behavior goes through the app's agent chat. UI and server code
@@ -61,11 +77,15 @@ coding agents can discover the same workspace-wide guidance from the root.
   `/<app-id>`.
 - When a user explicitly asks for a new app or workspace app, create the
   separate workspace app.
+- For composable workflows, prefer many one-job headless or small-UI apps that
+  discover and call sibling apps over A2A. Read
+  `packages/shared/.agents/skills/composable-mini-apps/SKILL.md` before
+  designing cross-app orchestration.
 - Dispatch vault access is workspace-wide by default: every saved vault key is
   available to every workspace app. Only create or request per-app vault grants
   when Dispatch's vault access setting is switched to manual mode.
 - Do not satisfy a new-app request by adding a route, page, component, or file
-  to `apps/starter` or another existing app unless the user explicitly asks to
+  to `apps/chat` or another existing app unless the user explicitly asks to
   modify that existing app.
 - Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as
   existing hosted/connected neighbors available through links and A2A/default
@@ -121,14 +141,14 @@ coding agents can discover the same workspace-wide guidance from the root.
 - In local development, scaffold the app from the workspace root with
   `pnpm exec agent-native create <app-id> --template=<template>`. In production
   Dispatch posts the request to Builder branch creation; the Builder branch
-  should still create the separate workspace app, not patch starter. The local
+  should still create the separate workspace app, not patch chat. 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
+- When using the chat 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.
+  visible `Chat`, `Starter`, `Blank app`, `Start building`, or `New app` UI in
+  a chat-derived app.
 
 ## Workspace Identity
 

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

@@ -68,10 +68,10 @@ pnpm dev               # starts the workspace gateway; opens Dispatch when prese
 ```
 
 The dev gateway serves Dispatch at `/dispatch` when you keep the recommended
-Dispatch app selected, and every app at its own path such as `/starter`. It
+Dispatch app selected, and every app at its own path such as `/chat`. It
 watches `apps/`, so newly-created apps are detected without restarting
 `pnpm dev`. App servers start lazily the first time you visit their path. App
-links should stay relative, such as `/starter` or `/<app-id>`; do not hardcode
+links should stay relative, such as `/chat` or `/<app-id>`; do not hardcode
 localhost or dev ports because the active gateway origin owns the port.
 
 Dispatch vault keys are workspace-wide by default: every saved vault key is
@@ -100,18 +100,18 @@ authenticated org routes whenever possible.
 ## Adding a new app
 
 ```bash
-pnpm exec agent-native create crm --template=starter
+pnpm exec agent-native create crm --template=chat
 ```
 
-The CLI detects the workspace root and scaffolds a minimal app that already
+The CLI detects the workspace root and scaffolds a minimal chat 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,
+Chat 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.
+chat 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`.
+app rather than adding files to `apps/chat`.
 Dispatch discovers ready apps from `apps/<app-id>/package.json`; there is no
 separate workspace app registry to edit. React Router apps must preserve
 `APP_BASE_PATH` / `VITE_APP_BASE_PATH` in `app/entry.client.tsx` via

package/docs/content/template-starter.md

@@ -1,78 +0,0 @@
----
-title: "Starter"
-description: "The minimal agent-native scaffold — agent chat, actions, application state, live sync, auth — wired up, with no domain code. Build from scratch."
----
-
-# Starter
-
-Starter is the minimum viable agent-native app. You get the six-rules architecture, the agent sidebar, the workspace tab, live sync, auth, and exactly one example action. Nothing else. Build from there.
-
-<!-- screenshot:
-  app: starter
-  view: /
-  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. 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}
-
-- **Agent sidebar** (`<AgentSidebar>`) wired into `app/root.tsx`. Chat, CLI, workspace tabs all present.
-- **Agent chat plugin** pre-configured so the chat actually talks to Claude (once `ANTHROPIC_API_KEY` is set).
-- **Auth** via Better Auth — login, signup, sessions, organizations. The same flow runs locally and in production; in development email verification is skipped so signup is just an email + password.
-- **Actions directory** with one example (`actions/hello.ts`) and the `view-screen` / `navigate` standard actions wired up.
-- **The framework's core tables** (application_state, settings, oauth_tokens, sessions, resources) provided by `@agent-native/core` at runtime — there's no template-local schema file to maintain. Add your own Drizzle schema when you define domain tables.
-- **Live sync** (`useDbSync`) already wired so UI auto-refreshes when the agent writes to the database.
-- **AGENTS.md** with the framework-wide rules the agent reads on every turn.
-- **One example domain route** at `/` that says hi and renders the sidebar toggle, plus the framework-shared admin routes (Database, Team, Observability, Extensions).
-
-## What's _not_ in it {#not-in-it}
-
-- No domain tables (no emails, no events, no forms)
-- No fancy UI — no dashboards, no lists, no charts
-- No template-specific actions beyond the stubs
-- No integrations (Slack, SendGrid, etc.)
-
-That's the point. Ship whatever belongs to _your_ app, not someone else's.
-
-## When to pick it {#when-to-pick}
-
-- **Building a pure-agent app** — the kind where the UI is mostly "let me see what the agent did." See [Pure-Agent Apps](/docs/pure-agent-apps).
-- **Learning the framework** — this is the smallest surface to wrap your head around.
-- **An internal tool** with a unique domain that doesn't match any of the other templates.
-- **A prototype** — ship the agent now, add real UI later.
-
-Pick a domain template ([Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Content](/docs/template-content), [Forms](/docs/template-forms), [Analytics](/docs/template-analytics), etc.) when there's an existing product shape that fits.
-
-## Scaffolding {#scaffolding}
-
-```bash
-npx @agent-native/core@latest create my-app --standalone --template starter
-```
-
-Or, in a workspace:
-
-```bash
-npx @agent-native/core@latest create my-platform  # pick "Starter" (pre-selected by default) plus any others
-```
-
-## First edits {#first-edits}
-
-After scaffolding:
-
-1. Ask the agent: "Add a data model for `notes` — a note has an id, title, body, owner. Render a list of notes at `/notes` and let the user create one."
-2. The agent adds the Drizzle schema, the `create-note` and `list-notes` actions, and the new route. You watch it happen.
-3. `pnpm dev`, navigate to `/notes`, add a note through the UI. Ask the agent "draft a note summarizing yesterday's standup." Watch it use your new action.
-
-That's the loop.
-
-## What's next
-
-- [**Getting Started**](/docs) — the broader CLI + workspace flow
-- [**Key Concepts**](/docs/key-concepts) — the six rules and what you get for free
-- [**Actions**](/docs/actions) — the action system you'll add to
-- [**Adding a Feature**](/docs/key-concepts#four-area-checklist) — the four-area checklist every new feature should update