@agent-native/core 0.122.4 → 0.123.0

package/docs/content/creating-templates.mdx

@@ -40,7 +40,7 @@ npx @agent-native/core@latest create my-platform
 
 Chat gives you auth, durable chat threads, SQL-backed resources, tools, application state, actions, and polling sync. You add the domain model and product UI.
 
-If you are not building a reusable UI template yet, use the headless on-ramp in [Getting Started](/docs/getting-started#1-create-your-app): define one action, run it with `pnpm agent`, and add UI later when the workflow needs a durable surface.
+If you are not building a reusable UI template yet, use the headless on-ramp in [Getting Started](/docs/getting-started#create-your-app): define one action, run it with `pnpm agent`, and add UI later when the workflow needs a durable surface.
 
 ## Project Structure {#project-structure}
 
@@ -317,6 +317,10 @@ useQuery({
 
 Common sources: `"action"` (every successful agent action — the reliable fallback), `"app-state"`, `"settings"`, plus any custom resource source your store emits via `recordChange`. See the `real-time-sync` skill for the full pattern.
 
+Templates render with the default shadcn-style UI. If your company already has
+its own React design system, see [Custom Design Systems](/docs/custom-design-system)
+to register it as a typed adapter instead of adopting the default primitives.
+
 ## Add Application State {#application-state}
 
 Application state is how the agent knows what the user is seeing. At minimum, add:
@@ -527,7 +531,11 @@ workspace pointed at current build output.
   keep `AGENTS.md` and skills skimmable as the template grows.
 - [**Agent-Native Toolkit**](/docs/agent-native-toolkit) — reusable sharing,
   settings, history, and review surfaces instead of rebuilding them per app.
+- [**Custom Design Systems**](/docs/custom-design-system) — render the UI with
+  your company's own React components instead of the default shadcn-style UI.
 - [**Multi-App Workspace**](/docs/multi-app-workspace) — make the template fit
   naturally alongside sibling apps and Dispatch.
+- [**Syncing Template Changes**](/docs/syncing-template-changes) — pull later
+  upstream template fixes into an app that already forked from it.
 - [**Templates**](/docs/cloneable-saas) — turn a template into a
   publishable product you can share and deploy.

package/docs/content/custom-design-system.mdx

@@ -5,6 +5,14 @@ description: "Use your company’s React design system across Agent Native apps
 
 # Custom Design Systems
 
+<Callout id="doc-block-cds1who" tone="info">
+
+**Who is this for:** host authors and design-system owners who want Agent
+Native to render with a company's own React components instead of the
+default shadcn-style UI. Most apps use the default UI and don't need this.
+
+</Callout>
+
 Agent Native can render app-owned screens and shared Toolkit experiences with
 your company’s React components. Register an explicit, typed adapter once; the
 same feature controllers continue to own actions, state, accessibility

package/docs/content/data-programs.mdx

@@ -6,6 +6,12 @@ search: "data program emit rows schema providerFetch dashboard panel program sou
 
 # Data Programs
 
+<Callout tone="info">
+
+**Developer page.** This page is for developers who want to understand or extend how the agent turns an ad-hoc analysis into a live dashboard panel. End users just ask the agent for a live view and see the resulting chart or table — no code required.
+
+</Callout>
+
 A **data program** is a named, stored, agent-authored JS script that fetches, joins, filters, or aggregates data — provider APIs via `providerFetch` / `providerFetchAll` / `providerSearchAll`, app data via `appAction`, or Resources-backed workspace files — and calls `emit(rows, schema)` exactly once with the result. The result is cached in SQL and any chart/table component can render it, refreshed on a policy you choose instead of on every page view.
 
 It ships automatically wherever [`run-code`](/docs/actions) is available — there is nothing to mount or configure per app. If your app already has run-code enabled, `save-data-program`, `preview-data-program`, `run-data-program`, `list-data-programs`, `get-data-program`, and `delete-data-program` are already registered actions.

package/docs/content/deployment.mdx

@@ -501,6 +501,7 @@ Three things to keep in mind:
 | `PORT`                                      | Server port (Node.js only)                                                                                                                                                                                                                                                                                                                                              |
 | `NITRO_PRESET`                              | Override build preset at build time                                                                                                                                                                                                                                                                                                                                     |
 | `APP_BASE_PATH`                             | Mount the app under a prefix (e.g. `/mail`). Set automatically by `npx @agent-native/core@latest deploy`; leave unset for standalone.                                                                                                                                                                                                                                   |
+| `APP_URL`                                   | Optional canonical public origin. Checked ahead of `BETTER_AUTH_URL` when resolving the A2A JWT audience, the OAuth public origin, self-dispatch webhook targets, and generated resource links. Set it explicitly on preview/staging deploys where the request host is unreliable.                                                                                      |
 | `AGENT_PROD_CODE_EXECUTION`                 | Optional production code-execution mode: `off` (default), `sandboxed`, or `trusted`. See [Production Code Execution](#production-code-execution).                                                                                                                                                                                                                       |
 | `AGENT_NATIVE_SSR_CACHE`                    | Deployment-wide SSR shell cache policy: unset/`on` keeps the default hard-cache, `off` sends `no-store`, or a duration such as `30s` / `5m` sets a shorter freshness. See [SSR Caching](#ssr-caching).                                                                                                                                                                  |
 | `AGENT_NATIVE_BUILDER_RELAY_SECRET`         | Dedicated 32+ char shared HMAC secret for preview-safe Builder authorization relay. Set the same value on the approved corporate callback deployment and preview deployments only when authorization must land in an isolated preview database.                                                                                                                         |
@@ -625,3 +626,4 @@ Agent-native apps store all state in SQL via Drizzle and sync the UI via [pollin
 - [**Authentication**](/docs/authentication) — OAuth credentials and env vars for the auth mode you choose
 - [**Multi-App Workspace**](/docs/multi-app-workspace) — the workspace model behind `deploy`'s one-origin build
 - [**Frames**](/docs/frames) — the embedded agent panel vs. Builder.io's cloud frame for production UI edits
+- [**Public Agent Web**](/docs/agent-web-surfaces) — the `robots.txt`, `llms.txt`, and markdown-mirror files a Vite build writes into the deploy output for public routes

package/docs/content/doctor.mdx

@@ -23,7 +23,7 @@ A clean run:
 
 ```
 agent-native doctor: /path/to/app
-Guards run: no-drizzle-push, no-unscoped-credentials, no-unscoped-queries, no-env-credentials, db-tool-scoping, no-env-mutation, no-localhost-fallback, migration-manifest
+Guards run: no-drizzle-push, no-unscoped-credentials, no-unscoped-queries, no-env-credentials, db-tool-scoping, no-env-mutation, no-localhost-fallback, explicit-collab-access, migration-manifest
 Clean — no findings.
 ```
 
@@ -37,9 +37,9 @@ A run with findings prints one line per finding and exits `1`:
 agent-native doctor found issues above. Fix them, or add a `// guard:allow-<check> — reason` opt-out with reviewer approval.
 ```
 
-## The eight guards {#guards}
+## The nine guards {#guards}
 
-v1 ships 8 guards. Each is a pure scan over the app's source tree — `node_modules`, `.git`, `dist`, `build`, and other build-output directories are always skipped.
+v1 ships 9 guards. Each is a pure scan over the app's source tree — `node_modules`, `.git`, `dist`, `build`, and other build-output directories are always skipped.
 
 | Guard                     | What it catches                                                                                                                                                                                                                            | Why it matters                                                                                                                                                                                                                                                                             |
 | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -50,6 +50,7 @@ v1 ships 8 guards. Each is a pure scan over the app's source tree — `node_modu
 | `db-tool-scoping`         | A table in `server/db/schema.ts` with no `owner_email` / `org_id` column and no matching entry in `agent-native.json`'s `doctor.dbToolScopingDenylist`                                                                                     | The agent's raw `db-query` / `db-exec` / `db-patch` tools can only safely expose tenant-scoped tables; an unscoped table needs an explicit, reviewed exception.                                                                                                                            |
 | `no-env-mutation`         | Production code assigning to, or `delete`-ing, `process.env.KEY`                                                                                                                                                                           | `process.env` is process-scoped, not request-scoped. A warm serverless container handles many concurrent requests in one process, so mutating `process.env` in a request handler leaks state across users. Use `runWithRequestContext` instead.                                            |
 | `no-localhost-fallback`   | The literal `"local@localhost"`, or `?? DEV_MODE_USER_EMAIL` / `\|\| DEV_MODE_USER_EMAIL`, used as a fallback identity                                                                                                                     | Falling back to a sentinel identity when there's no session pools every unauthenticated request onto one shared tenant. Throw or return 401 instead.                                                                                                                                       |
+| `explicit-collab-access`  | A `createCollabPlugin(...)` call with no explicit `access` — must declare `access: { mode: "resource", resourceType }` or `access: { mode: "all-authenticated" }` (legacy `resourceType` is still accepted during migration)               | An implicit config can silently scope real-time collaboration delivery wrong — for example broadcasting deployment-wide when only one resource's viewers should see the edits.                                                                                                             |
 | `migration-manifest`      | Imports listed in an installed package's `migration-manifest.json`                                                                                                                                                                         | The import is scheduled to move or disappear. Preview and apply the supported codemod before the upgrade makes it a hard error.                                                                                                                                                            |
 
 Guard names are stable identifiers — the same strings work in `--only`, `agent-native.json`'s `doctor.disabledGuards`, and every finding's `guard` field.
@@ -163,6 +164,7 @@ The actual `--json` payload also carries a `strict` field reflecting whether `--
     "db-tool-scoping",
     "no-env-mutation",
     "no-localhost-fallback",
+    "explicit-collab-access",
     "migration-manifest"
   ],
   "strict": false

package/docs/content/extensions.mdx

@@ -133,6 +133,17 @@ A user is reading an email from `priya@acme.com`. What kind of widget would help
 - **CRM enrichment** — pulls the contact's company size, last meeting date, or open deals from your CRM.
 - **Meeting scheduler shortcut** — turns "find a time next week" into a one-click "send these slots" widget.
 
+Once installed into Mail's `mail.contact-sidebar.bottom` slot, the Contact notes widget sits right under the contact card on every thread:
+
+<WireframeBlock id="doc-block-ext1">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:flex;min-height:420px;box-sizing:border-box'><div style='flex:1;display:flex;flex-direction:column;gap:10px;padding:16px;border-right:1.4px solid var(--wf-line)'><strong>Re: Q3 renewal</strong><small class='wf-muted'>priya@acme.com &middot; 9:14 AM</small><div class='wf-card'><p style='margin:0'>Hi &mdash; following up on the renewal terms we discussed on the call...</p></div></div><div style='width:220px;display:flex;flex-direction:column;gap:10px;padding:16px'><div class='wf-card'><strong>priya@acme.com</strong><small class='wf-muted' style='display:block'>Acme Inc.</small></div><div class='wf-card' style='display:flex;flex-direction:column;gap:6px'><span class='wf-pill accent'>Extension &middot; Contact notes</span><small class='wf-muted'>Notes about this contact&hellip;</small><div style='border:1.4px solid var(--wf-line);border-radius:var(--wf-radius);padding:8px;min-height:56px'>Renewal call went well. Wants annual billing.</div></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
 Sketch — Contact notes (saves a note tied to whoever you're emailing):
 
 ```html
@@ -238,6 +249,10 @@ saved versions, inspect the diff from the previous version, and restore an
 older name/description/icon/content snapshot without changing ownership or
 sharing.
 
+## For developers {#for-developers}
+
+Everything from here through [Local File Extensions](#local-file-extensions) is the bridge/data-API reference for template developers — the exact helpers, endpoints, and slot contract an extension can use. Skip ahead to [Sharing](#sharing) if you just want to build and share widgets as an end user.
+
 ## What an extension can do {#capabilities}
 
 Inside the iframe sandbox, every extension has these helpers on `window`:
@@ -451,6 +466,17 @@ Deletes the matching item from the selected scope. The default scope is `user`,
 
 </Endpoint>
 
+### Agent tools for extension data {#agent-data-tools}
+
+Two agent-facing actions read and write an extension's data store from outside the iframe — for seeding an extension with data, inspecting what it has stored, or updating it without opening the widget:
+
+| Action               | Purpose                                                                                                              | Access required |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------- |
+| `extension-data-set` | Write (upsert) one item to an extension's data store. Refreshes any mounted iframe showing that extension afterward. | Editor          |
+| `extension-data-get` | Read one item, or list a collection, from an extension's data store.                                                 | Viewer          |
+
+These are distinct from the `extensionData.*` bridge helpers above (called from inside the sandboxed iframe) and from the [Authenticated Extension Data API](#authenticated-extension-data-api) (called by another logged-in client over HTTP) — same underlying store (`tool_data`), three different callers.
+
 External APIs go through `extensionFetch`, which proxies the call server-side and substitutes secrets via the `${keys.NAME}` template:
 
 ```html