@agent-native/core 0.91.2 → 0.92.0

package/docs/content/notifications.mdx

@@ -108,12 +108,18 @@ Severity drives the badge styling in the dropdown and is passed through to chann
 
 ## Built-in channels {#channels}
 
-| Channel   | Delivery                                                  | Requires                                            |
-| --------- | --------------------------------------------------------- | --------------------------------------------------- |
-| `inbox`   | Persists to the `notifications` table; drives the bell UI | Always on — part of the primitive.                  |
-| `webhook` | POST JSON to a configured URL                             | `NOTIFICATIONS_WEBHOOK_URL` env var set at startup. |
-
-The webhook channel resolves `${keys.NAME}` references in both the URL and `NOTIFICATIONS_WEBHOOK_AUTH` against the owner's ad-hoc [secrets](/docs/security), so the raw value never enters the agent's context. Per-key URL allowlists are enforced — same rule the automations `web-request` tool uses.
+| Channel   | Delivery                                                  | Requires                                                                              |
+| --------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `inbox`   | Persists to the `notifications` table; drives the bell UI | Always on — part of the primitive.                                                    |
+| `email`   | Sends email via Resend/SendGrid                           | Per-notification `metadata.emailRecipients` and/or `NOTIFICATIONS_EMAIL_RECIPIENTS`.  |
+| `slack`   | POST Slack Block Kit JSON to an incoming webhook          | Per-notification `metadata.slackWebhookUrl` and/or `NOTIFICATIONS_SLACK_WEBHOOK_URL`. |
+| `webhook` | POST JSON to a configured URL                             | Per-notification `metadata.webhookUrl` and/or `NOTIFICATIONS_WEBHOOK_URL`.            |
+
+Slack and webhook are always registered. Delivery prefers the per-notification
+metadata URL, then falls back to the matching env var. If neither is set, that
+channel no-ops for the emission.
+
+The webhook and Slack channels resolve `${keys.NAME}` references in both the URL and `NOTIFICATIONS_*_AUTH` against the owner's ad-hoc [secrets](/docs/security), so the raw value never enters the agent's context. Per-key URL allowlists are enforced — same rule the automations `web-request` tool uses.
 
 <Diagram id="doc-block-1lduyog" title="Channels and severity" summary={"inbox is always on; webhook needs an env var; custom channels register at startup. Severity drives badge styling and is passed through to every channel."}>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.91.2",
+  "version": "0.92.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": {
@@ -315,7 +315,7 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
-    "@agent-native/toolkit": "0.4.3"
+    "@agent-native/toolkit": "0.4.4"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/templates/default/.agents/skills/self-modifying-code/SKILL.md

@@ -28,7 +28,19 @@ Not all modifications are equal. Use this to decide what level of care is needed
 | 1: Data       | Files in `data/`      | JSON state, generated content, markdown          | Nothing — these are routine       |
 | 2: Source     | App code              | Components, routes, styles, scripts              | Run `pnpm typecheck && pnpm lint` |
 | 3: Config     | Project config        | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first   |
-| 4: Off limits | Secrets and framework | `.env`, `@agent-native/core` internals           | Never modify these                |
+| 4: Off limits | Secrets and framework | `.env`, `@agent-native/*` packages & overrides   | Never modify these                |
+
+Tier 4 includes **all** of the following — not only editing package source:
+
+- Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
+- `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
+  target any `@agent-native/*` package
+- Local patches, vendored copies, or invented "dispatch/core behavior"
+  shims meant to paper over a version skew or failed upgrade
+
+When an older branch needs current packages, use **`agent-native upgrade`**
+(see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
+**app** code or stop and ask — do not patch the framework.
 
 ## Git Checkpoint Pattern
 
@@ -74,13 +86,19 @@ inline strings in components.
 ## Don't
 
 - Don't modify `.env` files or files containing secrets
-- Don't modify `@agent-native/core` package internals
+- Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
+  `@agent-native/*` package internals (including under `node_modules`)
+- Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
+  `@agent-native/*` to "make the app run" after a version bump
+- Don't invent local dispatch/core behavior overrides when upgrade fails —
+  run `npx @agent-native/core@latest upgrade`, then fix app-level errors only
 - Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
 - Don't skip the typecheck/lint step after editing source code
 - Don't make source changes without a git checkpoint to roll back to
 
 ## Related Skills
 
+- **upgrade-agent-native** — supported path to bring an older app/workspace current
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat

package/src/templates/default/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/src/templates/default/AGENTS.md

@@ -38,9 +38,15 @@ Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` and `.agents/skills/` for
 app-specific rules, then use the corpus for reusable framework/template
 patterns.
-After updating `@agent-native/core`, run `pnpm skills:update` or
-`npx @agent-native/core@latest skills update scaffold --project` from the app
-root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
+To bring an older app current, run `pnpm upgrade:agent-native` or
+`npx @agent-native/core@latest upgrade` from the app root. That bumps
+`@agent-native/*` deps, installs, refreshes scaffold skills, and typechecks.
+Do **not** add `pnpm.overrides` / patches against `@agent-native/*` or edit
+`node_modules/@agent-native/*` when an upgrade fails — fix app code or ask.
+See the `upgrade-agent-native` and `self-modifying-code` skills.
+After a manual core bump only, `pnpm skills:update` (or
+`npx @agent-native/core@latest skills update scaffold --project`) still
+refreshes framework-provided `.agents/skills` and repairs `CLAUDE.md` /
 `.claude/skills` compatibility links.
 
 ### Database Code
@@ -150,6 +156,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 | `delegate-to-agent`    | Before adding LLM calls or AI delegation                                          |
 | `actions`              | Before creating or modifying actions                                              |
 | `self-modifying-code`  | Before editing source, components, or styles                                      |
+| `upgrade-agent-native` | Before updating an older app/branch or when tempted to patch `@agent-native/*`    |
 | `capture-learnings`    | Before recording user preferences or corrections                                  |
 | `frontend-design`      | Before building or restyling any UI component, page, or layout                    |
 | `shadcn-ui`            | Before adding, updating, or debugging shadcn/ui components                        |

package/src/templates/default/package.json

@@ -9,7 +9,8 @@
     "typecheck": "agent-native typecheck",
     "action": "agent-native action",
     "script": "agent-native script",
-    "skills:update": "agent-native skills update scaffold --project"
+    "skills:update": "agent-native skills update scaffold --project",
+    "upgrade:agent-native": "agent-native upgrade"
   },
   "dependencies": {
     "@agent-native/core": "latest",

package/src/templates/headless/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/src/templates/headless/AGENTS.md

@@ -38,9 +38,15 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` for app-specific rules, then use
 the corpus for reusable framework/template patterns.
-After updating `@agent-native/core`, run `pnpm skills:update` or
-`npx @agent-native/core@latest skills update scaffold --project` from the app
-root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
+To bring an older app current, run `pnpm upgrade:agent-native` or
+`npx @agent-native/core@latest upgrade` from the app root. That bumps
+`@agent-native/*` deps, installs, refreshes scaffold skills, and typechecks.
+Do **not** add `pnpm.overrides` / patches against `@agent-native/*` or edit
+`node_modules/@agent-native/*` when an upgrade fails — fix app code or ask.
+See the `upgrade-agent-native` and `self-modifying-code` skills.
+After a manual core bump only, `pnpm skills:update` (or
+`npx @agent-native/core@latest skills update scaffold --project`) still
+refreshes framework-provided `.agents/skills` and repairs `CLAUDE.md` /
 `.claude/skills` compatibility links.
 
 ## Actions

package/src/templates/headless/package.json

@@ -7,6 +7,7 @@
     "agent": "agent-native agent",
     "script": "agent-native script",
     "skills:update": "agent-native skills update scaffold --project",
+    "upgrade:agent-native": "agent-native upgrade",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/src/templates/workspace-core/.agents/skills/self-modifying-code/SKILL.md

@@ -28,7 +28,19 @@ Not all modifications are equal. Use this to decide what level of care is needed
 | 1: Data       | Files in `data/`      | JSON state, generated content, markdown          | Nothing — these are routine       |
 | 2: Source     | App code              | Components, routes, styles, scripts              | Run `pnpm typecheck && pnpm lint` |
 | 3: Config     | Project config        | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first   |
-| 4: Off limits | Secrets and framework | `.env`, `@agent-native/core` internals           | Never modify these                |
+| 4: Off limits | Secrets and framework | `.env`, `@agent-native/*` packages & overrides   | Never modify these                |
+
+Tier 4 includes **all** of the following — not only editing package source:
+
+- Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
+- `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
+  target any `@agent-native/*` package
+- Local patches, vendored copies, or invented "dispatch/core behavior"
+  shims meant to paper over a version skew or failed upgrade
+
+When an older branch needs current packages, use **`agent-native upgrade`**
+(see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
+**app** code or stop and ask — do not patch the framework.
 
 ## Git Checkpoint Pattern
 
@@ -74,13 +86,19 @@ inline strings in components.
 ## Don't
 
 - Don't modify `.env` files or files containing secrets
-- Don't modify `@agent-native/core` package internals
+- Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
+  `@agent-native/*` package internals (including under `node_modules`)
+- Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
+  `@agent-native/*` to "make the app run" after a version bump
+- Don't invent local dispatch/core behavior overrides when upgrade fails —
+  run `npx @agent-native/core@latest upgrade`, then fix app-level errors only
 - Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
 - Don't skip the typecheck/lint step after editing source code
 - Don't make source changes without a git checkpoint to roll back to
 
 ## Related Skills
 
+- **upgrade-agent-native** — supported path to bring an older app/workspace current
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat

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

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

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

@@ -27,10 +27,16 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Use package docs for framework APIs, the package corpus for reusable
 framework/template patterns, and `packages/shared/AGENTS.md` plus
 `packages/shared/.agents/skills/` for workspace-specific conventions.
-After updating `@agent-native/core`, run `pnpm skills:update` or
-`npx @agent-native/core@latest skills update scaffold --project` from the
-workspace root to refresh framework-provided shared skills and repair
-`CLAUDE.md` / `.claude/skills` compatibility links.
+To bring an older workspace current, run `pnpm upgrade:agent-native` or
+`npx @agent-native/core@latest upgrade` from the workspace root. That bumps
+`@agent-native/*` deps, installs, refreshes scaffold skills, and typechecks.
+Do **not** add `pnpm.overrides` / patches against `@agent-native/*` or edit
+`node_modules/@agent-native/*` when an upgrade fails — fix app code or ask.
+See the `upgrade-agent-native` and `self-modifying-code` skills.
+After a manual core bump only, `pnpm skills:update` (or
+`npx @agent-native/core@latest skills update scaffold --project`) still
+refreshes framework-provided shared skills and repairs `CLAUDE.md` /
+`.claude/skills` compatibility links.
 
 ## Core Agent Rule
 

package/src/templates/workspace-root/package.json

@@ -8,6 +8,7 @@
     "typecheck": "pnpm -r typecheck",
     "repair:workspace-org": "tsx scripts/repair-workspace-org.ts",
     "skills:update": "agent-native skills update scaffold --project",
+    "upgrade:agent-native": "agent-native upgrade",
     "fmt:check": "oxfmt --check .",
     "lint": "pnpm fmt:check"
   },

package/corpus/templates/analytics/changelog/2026-07-08-session-replay-clamps-ultra-wide-viewports-while-keeping-the.md

@@ -1,6 +0,0 @@
----
-type: improved
-date: 2026-07-08
----
-
-Session replay clamps ultra-wide viewports while keeping the recorded page height instead of forcing a default size