@agent-native/core 0.121.2 → 0.122.0

package/docs/content/actions.mdx

@@ -225,7 +225,7 @@ export default defineAction({
 
 For a `GET` action, `leadId` is passed as a query param: `/_agent-native/actions/get-lead?leadId=abc`.
 
-<Endpoint id="doc-block-uhuudd" title="The auto-mounted action endpoint" method="GET" path="/_agent-native/actions/get-lead" summary={"Every action is mounted here automatically — the filename is the action name."} auth={"Session cookie; frontend calls carry `X-Agent-Native-Frontend: 1`"} params={[
+<Endpoint id="doc-block-uhuudd" title="The auto-mounted action endpoint" method="GET" path="/_agent-native/actions/get-lead" summary={"Every action is mounted here automatically — the filename is the action name."} auth={"Session cookie (frontend calls carry `X-Agent-Native-Frontend: 1`), or `Authorization: Bearer <token>` for external callers"} params={[
   {
     "name": "leadId",
     "in": "query",
@@ -244,7 +244,7 @@ For a `GET` action, `leadId` is passed as a query param: `/_agent-native/actions
   }
 ]}>
 
-POST by default; `http: { method: "GET" }` makes it a GET. The React hooks and `callAction` always call this path by name, regardless of any `http.path` override.
+POST by default; `http: { method: "GET" }` makes it a GET. The React hooks and `callAction` always call this path by name, regardless of any `http.path` override. External systems can call the same route with a long-lived bearer token — see [HTTP API](/docs/http-api).
 
 </Endpoint>
 

package/docs/content/agent-surfaces.mdx

@@ -220,7 +220,7 @@ One action is then callable as:
   }
 ]}>
 
-Every `defineAction` is auto-mounted at `/_agent-native/actions/<name>`. The JSON body is validated against the action's zod schema before `run` executes.
+Every `defineAction` is auto-mounted at `/_agent-native/actions/<name>`. The JSON body is validated against the action's zod schema before `run` executes. To call it from an external system with a long-lived bearer token, see [HTTP API](/docs/http-api).
 
 </Endpoint>
 

package/docs/content/authentication.mdx

@@ -404,6 +404,8 @@ function SignInCta() {
 
 Normal app pages use one impersonal, public-cacheable SSR shell for every visitor. `AppProviders` checks the session on the client; on a private path such as `/dashboard`, it redirects an anonymous visitor to `/_agent-native/sign-in?return=%2Fdashboard` before mounting private app UI. After sign-in, the visitor returns to `/dashboard`. Pass `isPublicPath` for public/SEO routes, or `sessionBypass` for a surface that authenticates through another scoped mechanism such as an MCP embed token.
 
+How long that shell is cached is a deployment-wide setting — see [SSR Caching](/docs/deployment#ssr-caching) for `AGENT_NATIVE_SSR_CACHE`. Shortening or disabling the cache changes duration only; SSR still renders the anonymous branch with cookies stripped.
+
 ### Behind the scenes: Google OAuth
 
 Both flows (the explicit `/_agent-native/sign-in` entrypoint and the bookmarked-path case) thread the return URL through the OAuth state. The state is HMAC-signed, so it can't be forged in transit. On the callback, the return URL is re-validated as same-origin before the redirect — so a leaked signing key still can't be turned into an open-redirect oracle.

package/docs/content/deployment.mdx

@@ -457,6 +457,41 @@ export default defineConfig({
 });
 ```
 
+## SSR Caching {#ssr-caching}
+
+Every SSR HTML response and every React Router `.data` response is one impersonal, public shell: `createH3SSRHandler` strips cookies before rendering, so the same bytes are correct for every visitor and all personalization happens on the client after load. That is what makes it safe to stamp a single hard-cache policy on those responses by default:
+
+```txt
+cache-control: public, max-age=600, stale-while-revalidate=604800, stale-if-error=3600
+```
+
+The same value is mirrored onto `cdn-cache-control` and `netlify-cdn-cache-control`. One shared CDN entry then serves the whole site instead of a per-request render, which is the single biggest lever on first-response latency — leave it on unless one of the cases below applies to your deployment.
+
+### Overriding with `AGENT_NATIVE_SSR_CACHE` {#ssr-cache-env}
+
+Set `AGENT_NATIVE_SSR_CACHE` in the deploy environment to change the policy for the whole deployment:
+
+| Value                                               | Result                                                                               |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| unset, `on`, `default`, `true`, `1`                 | The default policy above, unchanged. Recommended — best performance.                 |
+| `off`, `false`, `0`, `none`, `no-store`, `disabled` | `no-store` on `cache-control`, `cdn-cache-control`, and `netlify-cdn-cache-control`. |
+| A duration: `30`, `30s`, `5m`, `2h`                 | `public, max-age=<n>, stale-while-revalidate=<n>, stale-if-error=3600`.              |
+
+Bare numbers are seconds. `stale-while-revalidate` deliberately mirrors `max-age` for a custom duration: a short freshness window paired with the default seven-day stale window would hand back exactly the staleness you opted out of. An unrecognized value logs a warning and falls back to the default, so a typo can never silently disable the CDN.
+
+Turn it down or off when either of these is true:
+
+1. **Your host does not purge its CDN on deploy.** Netlify and Vercel do; some self-managed setups do not. Without a purge, a shipped build can keep serving the previous shell for `max-age` plus `stale-while-revalidate`.
+2. **Your loaders return mutable public data.** After a successful mutation, a `useRevalidator()` or redirect-after-action re-fetch can read the browser's cached `.data` copy instead of fresh loader output.
+
+The setting applies to every public-shell surface: React Router SSR HTML and `.data`, the login HTML shell, the `/_agent-native/speculation-rules.json` route, the docs site, and the public-form SSR in the forms template. The generated Cloudflare Worker resolves it at build time, so set it in the deploy environment before the build runs.
+
+Three things to keep in mind:
+
+- **Turning caching off does not make SSR personalized.** Cookies are still stripped before render and SSR loaders still see the anonymous branch. Per-user data must still be resolved client-side. This variable controls cache _duration_ only.
+- **It is deployment-wide, not per-route, by design.** A per-route or per-request cache override is how one visitor's payload ends up in another visitor's shared CDN entry, so the framework does not offer one — `guard:ssr-cache-shell` enforces it.
+- **For mutation-fresh data, prefer actions over disabling the cache.** App data belongs in [actions](/docs/actions), read from the client with `useActionQuery` / `useActionMutation` and kept live by `useDbSync()` polling; none of that goes through the SSR shell cache. Keep SSR loaders rendering the public shell, and reach for this variable only when you genuinely want loader data fresher.
+
 ## Environment Variables {#environment-variables}
 
 ### Build / Runtime {#env-runtime}
@@ -467,6 +502,7 @@ export default defineConfig({
 | `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.                                                                                                                                                                                                                                   |
 | `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.                                                                                                                         |
 | `AGENT_NATIVE_BUILDER_RELAY_TARGET_ORIGINS` | Corporate callback-only, comma-separated allowlist of exact trusted preview origins (for example, `https://0123456789abcdef01234567--content.netlify.app`). Set it only on the corporate callback deployment. Netlify origins must use an immutable, deploy-specific 24-hex permalink; mutable `deploy-preview-*` aliases, wildcards, and domain suffixes are rejected. |
 

package/docs/content/http-api.mdx

@@ -0,0 +1,266 @@
+---
+title: "HTTP API: Call Actions from Anything"
+description: "Call an agent-native app's actions over plain HTTP with a long-lived bearer token — from a support-desk bot, a CI job, a cron script, or any backend service, no browser session required."
+search: "HTTP API bearer token service token connect CLI curl action endpoint server-to-server webhook CI backend integration Authorization header revoke rotate"
+---
+
+# HTTP API
+
+**This page: call an app's actions from an external system over HTTP.** Use it when a support-desk bot, a CI job, a cron script, a Lambda, or any backend service needs to invoke your app without a browser and without an MCP client.
+
+| If you want to…                                      | Read                                     |
+| ---------------------------------------------------- | ---------------------------------------- |
+| Call one action from a script or backend service     | **This page** — HTTP API                 |
+| Let an AI host discover and call every action        | [MCP Server](/docs/mcp-protocol)         |
+| Connect Claude, ChatGPT, Codex, Cursor to your app   | [External Agents](/docs/external-agents) |
+| Have another agent-native app delegate work to yours | [A2A Protocol](/docs/a2a-protocol)       |
+| Define the operation in the first place              | [Actions](/docs/actions)                 |
+
+Every `defineAction` in `actions/` is already an HTTP endpoint. The frontend calls it through `useActionQuery` / `useActionMutation` with a session cookie, but the same route accepts an `Authorization: Bearer` token, so anything that can make an HTTPS request can call it. There is no separate "public API" to build and no REST wrapper to maintain — the action you wrote for the agent and the UI is the API.
+
+## When to use this surface {#when}
+
+Pick HTTP when the caller is code and already knows exactly which operation it wants:
+
+| Caller                                                 | Use                                    |
+| ------------------------------------------------------ | -------------------------------------- |
+| A script, backend service, CI job, or webhook consumer | **HTTP** — this page                   |
+| An LLM host that should discover tools and choose      | [MCP](/docs/mcp-protocol)              |
+| Another agent-native app delegating a fuzzy task       | [A2A](/docs/a2a-protocol)              |
+| A browser page in your own app                         | `useActionQuery` / `useActionMutation` |
+
+HTTP is the cheapest of the three: one request, one JSON body, one JSON response, no handshake, no session, no model in the loop. MCP and A2A both sit on top of the same actions — reach for them when the caller needs a tool catalog or the whole agent loop, not a single known operation.
+
+## Mint a token {#mint-token}
+
+Tokens come from the `connect` CLI. There are two kinds, and the choice matters.
+
+**Personal token** — bound to the person who runs the command. Use it for your own scripts and local development.
+
+```bash
+npx @agent-native/core@latest connect https://clips.example.com
+```
+
+This opens a browser sign-in, then writes the token into your local MCP client configs. Rows the token creates are owned by you.
+
+**Org service token** — bound to a synthetic, organization-owned identity rather than a person. Use it for anything that must keep running after people change teams: CI, a support-desk bot, a scheduled integration.
+
+```bash
+npx @agent-native/core@latest connect https://clips.example.com \
+  --service-token support-desk --ttl-days 90
+```
+
+The command still authenticates you in the browser first — minting requires org **owner or admin** — but the resulting token's subject is `svc-support-desk@service.<orgId>`. It survives you leaving the org or revoking your own personal tokens, and the rows it creates are org-scoped, so every org member can see them. The token value is printed exactly once and is never written to a local config file; copy it straight into your secret store.
+
+|                              | Personal token              | Org service token                |
+| ---------------------------- | --------------------------- | -------------------------------- |
+| Identity                     | The person who minted it    | `svc-<name>@service.<orgId>`     |
+| Survives that person leaving | No                          | Yes                              |
+| Rows it creates              | Owned by that person        | Org-scoped                       |
+| Who can mint                 | Any signed-in user          | Org owner/admin only             |
+| Best for                     | Your own scripts, local dev | CI, bots, scheduled integrations |
+
+Both default to a 365-day lifetime and accept `--ttl-days` between 1 and 365. If a machine cannot open a browser, the app's connect page at `https://<app>/mcp/connect` is the fallback: sign in there, copy the token, and pass it with `connect <url> --token <token>` or paste it directly into your secret store.
+
+For a self-hosted, single-tenant app where per-person identity does not matter, the static `ACCESS_TOKEN` / `ACCESS_TOKENS` environment variables are the simplest option — see [Authentication — Static MCP Bearer Tokens](/docs/authentication#access-tokens).
+
+## Call an action {#call}
+
+The route is `POST /_agent-native/actions/<action-id>`. The action id defaults to the action's filename, so `actions/import-loom-recording.ts` mounts at `/_agent-native/actions/import-loom-recording`.
+
+The request body is the raw JSON of the action's zod schema — no envelope, no `{ args: ... }` wrapper. The response is the action's return value serialized bare at the top level, not wrapped in `{ result: ... }`.
+
+```bash
+curl -sS -X POST \
+  https://clips.example.com/_agent-native/actions/import-loom-recording \
+  -H "Authorization: Bearer $AGENT_NATIVE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://www.loom.com/share/EXAMPLE_SHARE_ID"}'
+```
+
+```json
+{
+  "recordingId": "rec_8f2a91",
+  "title": "Checkout fails on Safari 17",
+  "status": "imported"
+}
+```
+
+<Endpoint id="doc-block-http-api-action" title="Call an action over HTTP" method="POST" path="/_agent-native/actions/import-loom-recording" summary={"Invoke any action by id with a bearer token — no browser session required."} auth={"Authorization: Bearer <connect-minted personal or org service token>, or a session cookie for same-origin browser calls"} params={[
+  {
+    "name": "Authorization",
+    "in": "header",
+    "type": "string",
+    "required": true,
+    "description": "Bearer <token> from `connect` or `connect --service-token`. Omit only for same-origin browser calls that carry the session cookie."
+  },
+  {
+    "name": "Content-Type",
+    "in": "header",
+    "type": "string",
+    "required": true,
+    "description": "application/json for POST actions."
+  }
+]} request={{
+  "contentType": "application/json",
+  "example": "{\n  \"url\": \"https://www.loom.com/share/EXAMPLE_SHARE_ID\"\n}"
+}} responses={[
+  {
+    "status": "200",
+    "description": "The action's return value, serialized bare at the top level.",
+    "example": "{\n  \"recordingId\": \"rec_8f2a91\",\n  \"title\": \"Checkout fails on Safari 17\",\n  \"status\": \"imported\"\n}"
+  },
+  {
+    "status": "400",
+    "description": "Input failed the action's zod schema before run() fired.",
+    "example": "{ \"error\": \"Invalid action parameters: url: Required\" }"
+  },
+  {
+    "status": "401",
+    "description": "Missing, expired, revoked, or wrong-audience token."
+  },
+  {
+    "status": "405",
+    "description": "Wrong HTTP method for this action.",
+    "example": "{ \"error\": \"Method not allowed. Use POST.\" }"
+  },
+  {
+    "status": "500",
+    "description": "The action threw. The real message stays server-side.",
+    "example": "{ \"error\": \"Internal server error\" }"
+  }
+]}>
+
+The body is validated against the action's zod schema before `run` executes. The token is verified the same way the app's MCP endpoint verifies it: same signature check, same audience binding to `{appUrl}/mcp`, same revocation gate. The caller's organization comes from the token's signed `org_id` claim — never from an ambient browser cookie that happens to ride along on the request.
+
+</Endpoint>
+
+### GET actions and query params {#get-actions}
+
+An action that declares an `http` override is reachable with the method it names, and `GET` args arrive as query params instead of a JSON body:
+
+```ts filename="actions/get-lead.ts"
+export default defineAction({
+  description: "Get details for a lead.",
+  schema: z.object({ leadId: z.string() }),
+  http: { method: "GET" },
+  run: async ({ leadId }) => {
+    /* ... */
+  },
+});
+```
+
+```bash
+curl -sS \
+  "https://crm.example.com/_agent-native/actions/get-lead?leadId=lead_123" \
+  -H "Authorization: Bearer $AGENT_NATIVE_TOKEN"
+```
+
+`http: { path: "..." }` changes the mounted URL for direct HTTP callers only, and `http: false` removes the endpoint entirely. See [Actions — HTTP config](/docs/actions#http) for the full option set.
+
+### Errors {#errors}
+
+Every failure returns `{ "error": string }` with an appropriate status:
+
+| Status | Meaning                                                                                                                                             |
+| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400`  | Input failed the action's zod schema. The message names the offending field.                                                                        |
+| `401`  | Missing, expired, revoked, or wrong-audience bearer token.                                                                                          |
+| `403`  | Authenticated, but not allowed to touch this data — see [When it 403s](#troubleshooting).                                                           |
+| `405`  | Wrong method. The message tells you which one the action declares.                                                                                  |
+| `409`  | Only for browser clients running a stale build; server-to-server callers never see it.                                                              |
+| `500`  | The action threw. The response message is always `Internal server error` — the real detail is logged server-side with a capture id, never returned. |
+
+Treat a `500` as "check the app's logs", not "read the error text". Actions that want to return a specific, user-facing failure should throw with an explicit `statusCode` below 500; those messages do come back verbatim.
+
+### CSRF and CORS {#csrf-cors}
+
+A cookieless server-to-server call skips CSRF entirely — there is no session cookie to confuse, so there is nothing to protect against. You do not need to fetch a CSRF token, and you should not send cookies.
+
+Cross-origin calls _from a browser_ are different: they need an allowlisted origin. If you are calling from browser JavaScript on another domain, configure the app's CORS allowlist first. Server-side callers are unaffected.
+
+## Worked example: a support-desk bot {#worked-example}
+
+A support-desk bot watches inbound tickets. When a customer attaches a Loom share link to a bug report, the bot imports it into Clips so the support team can comment on the recording, clip the relevant 20 seconds, and attach it to the engineering issue.
+
+**1. Mint a token the bot owns.** Run this once, as an org owner or admin:
+
+```bash
+npx @agent-native/core@latest connect https://clips.example.com \
+  --service-token support-desk --ttl-days 365
+```
+
+Copy the printed value into the bot's secret store as `AGENT_NATIVE_TOKEN`. It is shown once and never stored by the app.
+
+**2. Call the action when a ticket arrives.**
+
+```ts
+const res = await fetch(
+  "https://clips.example.com/_agent-native/actions/import-loom-recording",
+  {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.AGENT_NATIVE_TOKEN}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ url: shareUrl }),
+  },
+);
+
+if (!res.ok) {
+  const { error } = await res.json();
+  throw new Error(`Clips import failed (${res.status}): ${error}`);
+}
+
+const { recordingId } = await res.json();
+```
+
+**3. Link back to the recording.** Post `https://clips.example.com/r/${recordingId}` into the ticket thread. Because the bot used an org service token, the recording is org-scoped: every teammate who opens that link sees it, and it does not disappear when the person who set up the bot changes teams.
+
+The action ran exactly as it would have from chat or the UI — same validation, same access checks, same app state write that focuses the new recording for anyone who has the app open.
+
+## Lifetime, rotation, and revocation {#lifecycle}
+
+Tokens are JWTs signed by the app and bound to that app's audience. A token minted for one app cannot call another.
+
+- **Lifetime** — 365 days by default, `--ttl-days` between 1 and 365. Shorter is better for anything that runs unattended.
+- **Rotation** — mint the new token, deploy it to the caller, confirm traffic is flowing, then revoke the old one. There is no in-place rotation; the two tokens are independent and can overlap.
+- **Revocation** — every token carries a `jti`, and revocation is a `jti` check on every request, so a revoked token stops working immediately. Use the `list-org-service-tokens` action to see names, who minted them, and last-used timestamps, then `revoke-org-service-token` with the id. Both are owner/admin-gated for writes; any org member can list.
+- **Recovery** — the token value is never stored, only its `jti`. If you lose it, mint a new one and revoke the old.
+
+Because `list-org-service-tokens` reports `lastUsedAt`, it doubles as a cleanup tool: anything that has not been used in months is a candidate for revocation.
+
+<Callout id="doc-block-http-api-security" tone="warning">
+
+**Treat the token exactly like a password.** It authenticates as a real identity in your organization, and it is long-lived by default.
+
+- Put it in a secret manager or CI secret, never in source, a Dockerfile, a log line, or a client-side bundle.
+- Give each caller its own named service token (`--service-token support-desk`, `--service-token ci`) so you can revoke one without breaking the others, and so `lastUsedAt` tells you who is actually calling.
+- Prefer the shortest `--ttl-days` the caller can live with.
+- A service token acts as an org **`member`, and only ever `member`.** The synthetic `svc-*@service.<orgId>` identity is never inserted into `org_members`; it resolves an implicit member role for the org it was minted against, and nothing higher. So it can read and write that org's data like any member, but it cannot mint further tokens, revoke existing ones, or manage org members and settings — every one of those is admin-gated. It can still do everything a normal member can do with the org's data, so scope it deliberately.
+- Actions you never want reachable this way should set `http: false` (agent and CLI only) or `toolCallable: false`. See [Actions — Exposure flags](/docs/actions#exposure-flags).
+
+</Callout>
+
+## When it 403s {#troubleshooting}
+
+A `401` means the token was not accepted at all. A `403` means the token _was_ accepted and the request then failed an access check — a different problem with a different fix.
+
+| Symptom                                                          | Likely cause                                                                                                                                                                      |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `401` on every call, immediately after minting                   | Token minted against a different app URL. It is audience-bound to `{appUrl}/mcp`; mint it against the app you are calling.                                                        |
+| `401` that started working and then stopped                      | Expired (check `--ttl-days`) or revoked. Check `list-org-service-tokens` with `includeRevoked: true`.                                                                             |
+| `403` on a data action                                           | The identity is not scoped to the org that owns the row. Confirm the token was minted with an active org, and that the row is org-scoped rather than owned by a person.           |
+| `403` on a data action from a service token only                 | The app authorizes with its own `org_members` role lookup and has not adopted `implicitServiceOrgRole` from `@agent-native/core/org`, so the synthetic identity resolves no role. |
+| `403` on `create-org-service-token` / `revoke-org-service-token` | The caller is an org `member`, or is a service token. Minting and revoking require a human owner/admin.                                                                           |
+| `403` from browser JavaScript, but curl works                    | Cross-origin browser call from an origin that is not allowlisted. See [CSRF and CORS](#csrf-cors).                                                                                |
+| `405` with a method you did not expect                           | The action declares `http: { method: "GET" }`. Send args as query params, not a JSON body.                                                                                        |
+| `404`                                                            | Wrong action id, an `http: { path: "..." }` override, or `http: false`.                                                                                                           |
+
+## What's next {#related-docs}
+
+- [**Actions**](/docs/actions) — define the operation once; HTTP, MCP, A2A, CLI, and the UI all call the same one
+- [**Authentication**](/docs/authentication) — session auth, orgs, and static `ACCESS_TOKEN` bearers
+- [**MCP Server**](/docs/mcp-protocol) — the tool-catalog surface these tokens are audience-bound to
+- [**A2A Protocol**](/docs/a2a-protocol) — agent-to-agent delegation between agent-native apps
+- [**Security**](/docs/security) — data scoping, access guards, and secret handling

package/docs/content/syncing-template-changes.mdx

@@ -0,0 +1,159 @@
+---
+title: "Syncing Template Changes"
+description: "agent-native template pulls later upstream first-party template changes into an app that was generated from a template, using a real per-file three-way merge against a pristine baseline."
+---
+
+# Syncing Template Changes
+
+`agent-native create` copies a first-party template into your app and then makes it yours — substituting the app name, renaming `_gitignore`, rewriting `package.json`, pinning `workspace:*` and `catalog:` dependencies to concrete versions, and (in a workspace) swapping in inherited auth and chat plugins. From that moment the app is a fork. Fixes and improvements that land in the template upstream do not reach it.
+
+`agent-native upgrade` does not close that gap. It moves package versions, runs import codemods, and refreshes skill directories — it never touches a file that was copied out of a template.
+
+`agent-native template` is the missing half. It re-fetches the template at a newer version, re-applies the exact transforms `create` applied, and merges the result into your app file by file.
+
+## Quick start {#quick-start}
+
+```bash
+agent-native upgrade
+agent-native template sync
+```
+
+`sync` defaults to the template version matching your installed `@agent-native/core`, so running it after `upgrade` keeps code and packages on the same version.
+
+Look before you merge:
+
+```bash
+agent-native template status
+agent-native template diff
+```
+
+## How the merge works {#how-the-merge-works}
+
+A useful merge needs three trees, not two:
+
+- **base** — the pristine template as it was when your app was generated.
+- **theirs** — the same template at the version you are syncing to, put through the same transform pipeline.
+- **ours** — your app as it stands now.
+
+With those, every file falls into a clear case. Upstream did not touch it, so it is left alone. You never touched it, so it fast-forwards. Both of you changed it, so it gets conflict markers. Nothing is overwritten just because it differs.
+
+Without a base, "sync" can only mean overwrite, which silently discards your work or reverts upstream's.
+
+## The baseline {#the-baseline}
+
+The base tree is stored as a git ref in your own repo:
+
+```txt
+refs/agent-native/template-baseline/apps/slides
+```
+
+It is written with git plumbing against a throwaway index file. Your `HEAD`, your branch, your index, and your working tree are never touched — running `template baseline` mid-edit is safe, and `git status` reads identically before and after.
+
+On first write, the fetch and push refspecs for `refs/agent-native/*` are added to your remote so the baseline survives a clone. If the app is not in a git repo, the baseline falls back to a tarball under `.agent-native/`.
+
+Apps generated before provenance existed have no baseline. Create one, then sync:
+
+```bash
+agent-native template baseline
+agent-native template sync
+```
+
+## Provenance {#provenance}
+
+`create` records what a later merge needs in the app's `package.json`:
+
+```json
+{
+  "agent-native": {
+    "scaffold": {
+      "template": "slides",
+      "frameworkSkills": "default",
+      "templateRef": "@agent-native/core@0.120.3",
+      "templateSource": "github",
+      "coreVersion": "0.120.3",
+      "shape": "workspace"
+    }
+  }
+}
+```
+
+`templateRef` is the immutable tag the template was actually fetched from, which is what makes the base reproducible. `shape` decides whether the workspace transforms are replayed during materialization.
+
+## Commands {#commands}
+
+### status {#status}
+
+```bash
+agent-native template status [app]
+```
+
+Reports the recorded ref, the latest available ref, whether a baseline exists, how many files upstream changed, and how many you have modified locally.
+
+### diff {#diff}
+
+```bash
+agent-native template diff [app] [--to <ref>]
+```
+
+A read-only unified diff of what changed upstream between your baseline and the target. Writes nothing.
+
+### sync {#sync}
+
+```bash
+agent-native template sync [app] [--to <ref>] [--dry-run] [--force]
+```
+
+Performs the merge. `--to` defaults to the ref matching the installed core. `--dry-run` prints the plan without writing.
+
+`sync` refuses to run when the app directory has uncommitted changes, so a bad merge is always recoverable with `git checkout`. `--force` overrides this; prefer committing first.
+
+When the merge is clean, the baseline advances automatically. When there are conflicts it deliberately does not — see `accept`.
+
+### accept {#accept}
+
+```bash
+agent-native template accept [app]
+```
+
+Advances the baseline after you resolve conflict markers. It refuses while any `<<<<<<<` remains, so the baseline can never move past an unresolved merge and quietly bake conflict markers into your next base.
+
+### baseline {#baseline}
+
+```bash
+agent-native template baseline [app] [--ref <ref>] [--template <name>]
+```
+
+Records a baseline for an app that predates scaffold provenance. Pass `--ref` when you know which version the app actually came from; the closer it is to the truth, the fewer phantom conflicts the first sync produces.
+
+## What is never merged {#what-is-never-merged}
+
+Some files are yours by definition, and some cannot be merged meaningfully:
+
+- Secrets and local config: `.env`, `.env.local`
+- Lockfiles: `pnpm-lock.yaml`
+- Generated output: `node_modules`, `.output`, `.react-router`, `dist`, `build`
+- App-owned content: `learnings.md`, pending entries under `changelog/`
+
+Binary files are never marker-merged. If both sides changed one, your copy is kept and the file is reported for manual handling. Symlinks are reported rather than clobbered.
+
+## Contributing changes back {#contributing-changes-back}
+
+Syncing is one-directional by design: upstream is the source of truth for template content, and the transforms `create` applies are not perfectly reversible. Recovering `{{APP_NAME}}` from a concrete app name is a guess, and files that `create` rewrote wholesale — `package.json`, `netlify.toml`, `app/root.tsx`, `server/plugins/auth.ts` — have no faithful inverse at all.
+
+If you are working inside the framework monorepo and want to push an app-side improvement back into a template, the `contribute:template` script does the reverse pass with those limits made explicit:
+
+```bash
+pnpm contribute:template --app <path-to-app> --dry-run
+```
+
+It diffs your app against its baseline so only your own changes are candidates, inverts the placeholder substitution on just those files, three-way merges them into `templates/<name>/` as unstaged edits on the current branch, and prints everything it refused to touch so you can port the intent by hand.
+
+## Relationship to other commands {#relationship-to-other-commands}
+
+| Command                      | Moves                                                          |
+| ---------------------------- | -------------------------------------------------------------- |
+| `agent-native upgrade`       | `@agent-native/*` package versions, imports, skill directories |
+| `agent-native template sync` | files copied out of a template at scaffold time                |
+| `agent-native eject`         | a framework component into app-owned source, with provenance   |
+
+`upgrade` and `template sync` are complementary and safe to run together. `eject` is the opposite move — it takes ownership of a file deliberately, and ejected files are tracked separately in `agent-native.ejections.json`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.121.2",
+  "version": "0.122.0",
   "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": {
@@ -139,6 +139,7 @@
     "./client/AgentPanel": "./dist/client/AgentPanel.js",
     "./client/application-state": "./dist/client/application-state.js",
     "./client/api-path": "./dist/client/api-path.js",
+    "./client/clipboard": "./dist/client/clipboard.js",
     "./client/route-state": "./dist/client/route-state.js",
     "./client/observability": "./dist/client/observability/index.js",
     "./client/onboarding": "./dist/client/onboarding/index.js",
@@ -389,8 +390,8 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/recap-cli": "0.5.1",
-    "@agent-native/toolkit": "^0.10.6"
+    "@agent-native/toolkit": "^0.10.6",
+    "@agent-native/recap-cli": "0.5.1"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",